---
name: "g_consumer"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/g_consumer"
---

# g\_consumer(9)

GEOM consumers management

## NAME

**g\_new\_consumer**, **g\_destroy\_consumer** – GEOM consumers management

## SYNOPSIS

**#include \<geom/geom.h\>**

*struct g\_consumer \**\

**g\_new\_consumer**(*struct g\_geom \*gp*);

*void*\

**g\_destroy\_consumer**(*struct g\_consumer \*cp*);

## DESCRIPTION

A GEOM consumer is the backdoor through which a geom connects to another GEOM provider and through which I/O requests are sent.

The **g\_new\_consumer**() function creates a new consumer on geom *gp*. Before using the new consumer, it has to be attached to a provider with [g\_attach(9)](/g_attach/9.md) and opened with [g\_access(9)](/g_access/9.md).

The **g\_destroy\_consumer**() function destroys the given consumer and cancels all related pending events. This function is the last stage of killing an unwanted consumer.

## RESTRICTIONS/CONDITIONS

**g\_new\_consumer**():

-

  The geom *gp* has to have *start* and *access* methods defined.

-

  The topology lock has to be held.

**g\_destroy\_consumer**():

-

  The consumer must not be attached to a provider.

-

  The access count has to be 0.

-

  The topology lock has to be held.

## RETURN VALUES

The **g\_new\_consumer**() function returns a pointer to the newly created consumer.

## EXAMPLES

Create consumer, attach it to given provider, gain read access and clean up.

```
void
some_function(struct g_geom *mygeom, struct g_provider *pp)
{
	struct g_consumer *cp;
	g_topology_assert();
	/* Create new consumer on 'mygeom' geom. */
	cp = g_new_consumer(mygeom);
	/* Attach newly created consumer to given provider. */
	if (g_attach(cp, pp) != 0) {
		g_destroy_consumer(cp);
		return;
	}
	/* Open provider for reading through our consumer. */
	if (g_access(cp, 1, 0, 0) != 0) {
		g_detach(cp);
		g_destroy_consumer(cp);
		return;
	}
	g_topology_unlock();
	/*
	 * Read data from provider.
	 */
	g_topology_lock();
	/* Disconnect from provider (release access count). */
	g_access(cp, -1, 0, 0);
	/* Detach from provider. */
	g_detach(cp);
	/* Destroy consumer. */
	g_destroy_consumer(cp);
}
```

## 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\_bio(9)](/g_bio/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⟩.