g_bio man page on FreeBSD

Man page or keyword search:  
man Server   9747 pages
apropos Keyword Search (all sections)
Output format
FreeBSD logo
[printable version]

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

NAME
     g_new_bio, g_clone_bio, g_destroy_bio, g_print_bio — GEOM bio controlling
     functions

SYNOPSIS
     #include <sys/bio.h>
     #include <geom/geom.h>

     struct bio *
     g_new_bio(void);

     struct bio *
     g_alloc_bio(void);

     struct bio *
     g_clone_bio(struct bio *bp);

     struct bio *
     g_duplicate_bio(struct bio *bp);

     void
     g_destroy_bio(struct bio *bp);

     void
     g_print_bio(struct bio *bp);

DESCRIPTION
     A struct bio is used by GEOM to describe I/O requests, its most important
     fields are described below:

     bio_cmd	    I/O request command.  There are four I/O requests avail‐
		    able in GEOM:

		    BIO_READ	 A read request.

		    BIO_WRITE	 A write request.

		    BIO_DELETE	 Indicates that a certain range of data is no
				 longer used and that it can be erased or
				 freed as the underlying technology supports.
				 Technologies like flash adaptation layers can
				 arrange to erase the relevant blocks before
				 they will become reassigned and cryptographic
				 devices may want to fill random bits into the
				 range to reduce the amount of data available
				 for attack.

		    BIO_GETATTR	 Inspect and manipulate out-of-band attributes
				 on a particular provider or path.  Attributes
				 are named by ascii strings and are stored in
				 the bio_attribute field.

		    BIO_FLUSH	 Tells underlying providers to flush their
				 write caches.

     bio_flags	    Available flags:

		    BIO_ERROR  Request failed (error value is stored in
			       bio_error field).

		    BIO_DONE   Request finished.

     bio_cflags	    Private use by the consumer.

     bio_pflags	    Private use by the provider.

     bio_offset	    Offset into provider.

     bio_data	    Pointer to data buffer.

     bio_error	    Error value when BIO_ERROR is set.

     bio_done	    Pointer to function which will be called when the request
		    is finished.

     bio_driver1    Private use by the provider.

     bio_driver2    Private use by the provider.

     bio_caller1    Private use by the consumer.

     bio_caller2    Private use by the consumer.

     bio_attribute  Attribute string for BIO_GETATTR request.

     bio_from	    Consumer to use for request (attached to provider stored
		    in bio_to field) (typically read-only for a class).

     bio_to	    Destination provider (typically read-only for a class).

     bio_length	    Request length in bytes.

     bio_completed  Number of bytes completed, but they may not be completed
		    from the front of the request.

     bio_children   Number of bio clones (typically read-only for a class).

     bio_inbed	    Number of finished bio clones.

     bio_parent	    Pointer to parent bio.

     The g_new_bio() function allocates a new, empty bio structure.

     g_alloc_bio() - same as g_new_bio(), but always succeeds (allocates bio
     with the M_WAITOK malloc flag).

     The g_clone_bio() function allocates a new bio structure and copies the
     following fields from the bio given as an argument to clone: bio_cmd,
     bio_length, bio_offset, bio_data, bio_attribute.  The field bio_parent in
     the clone points to the passed bio and the field bio_children in the
     passed bio is incremented.

     This function should be used for every request which enters through the
     provider of a particular geom and needs to be scheduled down.  Proper
     order is:

     1.	  Clone the received struct bio.
     2.	  Modify the clone.
     3.	  Schedule the clone on its own consumer.

     g_duplicate_bio() - same as g_clone_bio(), but always succeeds (allocates
     bio with the M_WAITOK malloc flag).

     The g_destroy_bio() function deallocates and destroys the given bio
     structure.

     The g_print_bio() function prints information about the given bio struc‐
     ture (for debugging purposes).

RETURN VALUES
     The g_new_bio() and g_clone_bio() functions return a pointer to the allo‐
     cated bio, or NULL if an error occurred.

EXAMPLES
     Implementation of “NULL-transformation”, meaning that an I/O request is
     cloned and scheduled down without any modifications.  Let us assume that
     field ex_consumer in structure example_softc contains a consumer attached
     to the provider we want to operate on.

	   void
	   example_start(struct bio *bp)
	   {
		   struct example_softc *sc;
		   struct bio *cbp;

		   printf("Request received: ");
		   g_print_bio(bp);
		   printf("\n");

		   sc = bp->bio_to->geom->softc;
		   if (sc == NULL) {
			   g_io_deliver(bp, ENXIO);
			   return;
		   }

		   /* Let's clone our bio request. */
		   cbp = g_clone_bio(bp);
		   if (cbp == NULL) {
			   g_io_deliver(bp, ENOMEM);
			   return;
		   }
		   cbp->bio_done = g_std_done;	   /* Standard 'done' function. */

		   /* Ok, schedule it down. */
		   /*
		    * The consumer can be obtained from
		    * LIST_FIRST(&bp->bio_to->geom->consumers) as well,
		    * if there is only one in our geom.
		    */
		   g_io_request(cbp, sc->ex_consumer);
	   }

SEE ALSO
     geom(4), DECLARE_GEOM_CLASS(9), g_access(9), g_attach(9), g_consumer(9),
     g_data(9), g_event(9), g_geom(9), g_provider(9), g_provider_by_name(9),
     g_wither_geom(9)

AUTHORS
     This manual page was written by Pawel Jakub Dawidek ⟨pjd@FreeBSD.org⟩.

BSD			       November 1, 2006				   BSD
[top]

List of man pages available for FreeBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net