bufq(9) [netbsd man page]

BUFQ(9) 						   BSD Kernel Developer's Manual						   BUFQ(9)

NAME

     bufq, bufq_state, bufq_alloc, bufq_drain, bufq_free, bufq_getstrategyname, bufq_move, bufq_put, bufq_get, bufq_peek, bufq_cancel -- device
     buffer queues

SYNOPSIS

     #include <sys/bufq.h>

     int
     bufq_alloc(struct bufq_state **bufq, const char *strategy, int flags);

     void
     bufq_drain(struct bufq_state *bufq);

     void
     bufq_free(struct bufq_state *bufq);

     const char *
     bufq_getstrategyname(struct bufq_state *bufq);

     void
     bufq_move(struct bufq_state *dst, struct bufq_state *src);

     void
     bufq_put(struct bufq_state *bufq, struct buf *bp);

     struct buf *
     bufq_get(struct bufq_state *bufq);

     struct buf *
     bufq_peek(struct bufq_state *bufq);

     struct buf *
     bufq_cancel(struct bufq_state *bufq, struct buf *bp);

DESCRIPTION

     The bufq subsystem is a set of operations for the management of device buffer queues.

     The primary data type for using the operations is the bufq_state structure, which is opaque for users.

FUNCTIONS

     bufq_alloc(bufq, strategy, flags)
	      Allocate and initialize a bufq_state descriptor.

	      The argument strategy specifies a buffer queue strategy to be used for this buffer queue.  The following special values can be used:

		    BUFQ_STRAT_ANY	     Let bufq_alloc() select a strategy.
		    BUFQ_DISK_DEFAULT_STRAT  Let bufq_alloc() select a strategy, assuming it will be used for a normal disk device.

	      Valid bits for the flags are:

		    BUFQ_SORT_RAWBLOCK	sort by b_rawblkno
		    BUFQ_SORT_CYLINDER	sort by b_cylinder and then by b_rawblkno
		    BUFQ_EXACT		Fail if a strategy specified by strategy is not available.  In that case, bufq_alloc returns ENOENT.  If
					this flag is not specified, bufq_alloc() will silently use one of available strategies.

     bufq_drain(bufq)
	      Drain a bufq_state descriptor.

     bufq_free(bufq)
	      Destroy a bufq_state descriptor.

     bufq_getstrategyname(bufq)
	      Get a strategy identifier of a buffer queue, the string returned will be NUL-terminated and it always will be a valid strategy name.

     bufq_move(dst, src)
	      Move all requests from the buffer queue src to the buffer queue dst.

     bufq_put(bufq, bp)
	      Put the buf bp in the queue.

     bufq_get(bufq)
	      Get the next buf from the queue and remove it from the queue.  Returns NULL if the queue is empty.

     bufq_peek(bufq)
	      Get the next buf from the queue without removal.	The next buf will remain the same until bufq_get(), bufq_put(), or bufq_drain() is
	      called.  Returns NULL if the queue is empty.

     bufq_cancel(bufq, bp)
	      Cancel the buf bp issued earlier on the queue.  Returns NULL if the element can not be found on the queue or bp if it has been found
	      and removed.  This operation can be computationally expensive if there are a lot of buffers queued.

CODE REFERENCES

     The actual code implementing the device buffer queues can be found in the file sys/kern/subr_bufq.c.

HISTORY

     The bufq subsystem appeared in NetBSD 2.0.

AUTHORS

     The bufq subsystem was written by Jurgen Hannken-Illjes <hannken@NetBSD.org>.

BSD
								 January 24, 2009							       BSD

buf(9s) 																   buf(9s)

NAME

       buf - General: Describes arbitrary I/O

SYNOPSIS

       ----------------------------------
       Member Name   Data Type
       ----------------------------------
       b_flags	     int
       b_forw	     struct buf *
       b_back	     struct buf *
       av_forw	     struct buf *
       av_back	     struct buf *
       b_bcount      int
       b_error	     short
       b_dev	     dev_t
       b_un.b_addr   caddr_t
       b_lblkno      daddr_t
       b_blkno	     daddr_t
       b_resid	     int
       b_iodone      void (*b_iodone) ()
       b_proc	     struct proc *
       ----------------------------------

MEMBERS

       Specifies  binary  status  flags.  These flags indicate how a request is to be handled and the current status of the request. The following
       flags are applicable to kernel modules that are device drivers: B_READ, B_DONE, B_ERROR, B_BUSY, and B_PHYS. See  the  DESCRIPTION  section
       for more information on these flags.  Specifies a hash chain. Only the entity (driver, buffer cache) that owns the buf structure can use or
       reference this member. A driver receiving a buf structure from the buffer cache through the strategy routine  must  not	use  this  member.
       Specifies  a  hash  chain.  Only  the  entity (driver, buffer cache) that owns the buf structure can use or reference this member. A driver
       receiving a buf structure from the buffer cache through the strategy routine must not use this member.  Specifies the position on the  free
       list  if  the  b_flags  member  is  not set to B_BUSY.  Specifies the position on the free list if the b_flags member is not set to B_BUSY.
       Specifies the size of the requested transfer (in bytes).  Specifies that an error occurred on this data transfer. This member is set to	an
       error  code  if	the b_flags member bit was set.  Specifies the special device to which the transfer is directed.  Specifies the address at
       which to pull or push the data.	Specifies the logical block number.  Specifies the block number on the partition of a disk or on the  file
       system.	 Specifies  (in bytes) the data not transferred because of some error.	Specifies the routine called by iodone.  The device driver
       calls iodone at the completion of an I/O operation.  Specifies a pointer to the proc structure that represents the process  performing  the
       I/O.

DESCRIPTION

       The  buf data structure describes arbitrary I/O, but is usually associated with block I/O and physio.  A systemwide pool of buf data struc-
       tures exists for block I/O; however, many kernel modules that are device drivers also include locally defined buf data structures.

       Kernel modules can use the following flags with the b_flags member: This flag is set if the operation is read and cleared if the  operation
       is write.  This flag is cleared when a request is passed to a driver strategy routine. The writer must call iodone to mark a buffer as com-
       pleted.	This flag specifies that an error occurred on this data transfer.  Kernel modules set this flag if an  error  occurs.	This  flag
       indicates that the buffer is in use.  This flag indicates that the associated data is in user address space.

NOTES

       The  operating system does not define a B_CALL flag.  The iodone routine checks the b_iodone member to determine if you specified a comple-
       tion routine. If so, iodone clears b_iodone and then calls the specified completion routine. If you want to reuse this buf data	structure,
       you must reset the b_iodone member to a completion routine. In fact, it is good programming practice to reset all of the referenced members
       of a buf data structure that you plan to reuse.

FILES

																	   buf(9s)