---
name: "g_bio"
section: "9freebsd"
platform: "linux"
package: "freebsd-manpages"
version: "12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/g_alloc_bio/9freebsd"
---

# g\_bio(9freebsd)

GEOM bio controlling functions

Part of [g\_alloc\_bio(9freebsd)](/g_alloc_bio/9freebsd.md).

## NAME

**g\_new\_bio**, **g\_clone\_bio**, **g\_destroy\_bio**, **g\_print\_bio**, **g\_reset\_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*);

*void*\

**g\_reset\_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 five I/O requests available 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* structure (for debugging purposes).

The **g\_reset\_bio**() function resets the given *bio* structure back to its initial state. **g\_reset\_bio**() preserves internal data structures, while setting all user visible fields to their initial values. When reusing a *bio* obtained from **g\_new\_bio**(), **g\_alloc\_bio**(), **g\_clone\_bio**(), or **g\_duplicate\_bio**() for multiple transactions, **g\_reset\_bio**() must be called between the transactions in lieu of **bzero**(). While not strictly required for a *bio* structure created by other means, **g\_reset\_bio**() should be used to initialize it and between transactions.

## RETURN VALUES

The **g\_new\_bio**() and **g\_clone\_bio**() functions return a pointer to the allocated *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->consumer) as well,
	 * if there is only one in our geom.
	 */
	g_io_request(cbp, sc->ex_consumer);
}
```

## SEE ALSO

[geom(4)](/geom/4.md), [DECLARE\_GEOM\_CLASS(9)](/DECLARE_GEOM_CLASS/9.md), [g\_access(9)](/g_access/9.md), [g\_attach(9)](/g_attach/9.md), [g\_consumer(9)](/g_consumer/9.md), [g\_data(9)](/g_data/9.md), [g\_event(9)](/g_event/9.md), [g\_geom(9)](/g_geom/9.md), [g\_provider(9)](/g_provider/9.md), [g\_provider\_by\_name(9)](/g_provider_by_name/9.md), [g\_wither\_geom(9)](/g_wither_geom/9.md)

## AUTHORS

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