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

# alq\_write(9)

Asynchronous Logging Queues

## NAME

**alq**, **alq\_open**, **alq\_write**, **alq\_flush**, **alq\_close**, **alq\_get**, **alq\_post** – Asynchronous Logging Queues

## SYNOPSIS

**#include \<sys/alq.h\>**

*int*\

**alq\_open**(*struct alq \*\*app*, *const char \*file*, *struct ucred \*cred*, *int cmode*, *int size*, *int count*);

*int*\

**alq\_write**(*struct alq \*alq*, *void \*data*, *int waitok*);

*void*\

**alq\_flush**(*struct alq \*alq*);

*void*\

**alq\_close**(*struct alq \*alq*);

*struct* *ale* *\**\

**alq\_get**(*struct alq \*alq*, *int waitok*);

*void*\

**alq\_post**(*struct alq \*alq*, *struct ale \*ale*);

## DESCRIPTION

The **alq** facility provides an asynchronous fixed length recording mechanism, known as Asynchronous Logging Queues. It can record to any [vnode(9)](/vnode/9.md), thus providing the ability to journal logs to character devices as well as regular files. All functions accept a *struct alq* argument, which is an opaque type that maintains state information for an Asynchronous Logging Queue. The logging facility runs in a separate kernel thread, which services all log entry requests.

An “asynchronous log entry” is defined as *struct ale*, which has the following members:

```
struct ale {
	struct ale	*ae_next;	/* Next Entry */
	char		*ae_data;	/* Entry buffer */
	int		ae_flags;	/* Entry flags */
};
```

The *ae\_flags* field is for internal use, clients of the **alq** interface should not modify this field. Behaviour is undefined if this field is modified.

## FUNCTIONS

The **alq\_open**() function creates a new logging queue. The *file* argument is the name of the file to open for logging; if the file does not yet exist, **alq\_open**() will attempt to create it. The *cmode* argument will be passed to **vn\_open**() as the requested creation mode, to be used if the file will be created by **alq\_open**(). Consumers of this API may wish to pass ALQ\_DEFAULT\_CMODE, a default creation mode suitable for most applications. The argument *cred* specifies the credentials to use when opening and performing I/O on the file. The size of each entry in the queue is determined by *size*. The *count* argument determines the number of items to be stored in the asynchronous queue over an approximate period of a disk write operation.

The **alq\_write**() function writes *data* to the designated queue, *alq*. In the event that **alq\_write**() could not write the entry immediately, and ALQ\_WAITOK is passed to *waitok*, then **alq\_write**() will be allowed to [tsleep(9)](/tsleep/9.md).

The **alq\_flush**() function is used for flushing *alq* to the log medium that was passed to **alq\_open**().

The **alq\_close**() function will close the asynchronous logging queue, *alq*, and flush all pending write requests to the log medium. It will free all resources that were previously allocated.

The **alq\_get**() function returns the next available asynchronous logging entry from the queue, *alq*. This function leaves the queue in a locked state, until a subsequent **alq\_post**() call is made. In the event that **alq\_get**() could not retrieve an entry immediately, it will [tsleep(9)](/tsleep/9.md) with the “alqget” wait message.

The **alq\_post**() function schedules the asynchronous logging entry, *ale*, which is retrieved using the **alq\_get**() function, for writing to the asynchronous logging queue, *alq*. This function leaves the queue, *alq*, in an unlocked state.

## IMPLEMENTATION NOTES

The **alq\_write**() function is a wrapper around the **alq\_get**() and **alq\_post**() functions; by using these functions separately, a call to **bcopy**() can be avoided for performance critical code paths.

## LOCKING

Each asynchronous queue is protected by a spin mutex.

Functions **alq\_flush**(), **alq\_open**() and **alq\_post**() may attempt to acquire an internal sleep mutex, and should consequently not be used in contexts where sleeping is not allowed.

## RETURN VALUES

The **alq\_open**() function returns one of the error codes listed in [open(2)](/open/2.md), if it fails to open *file*, or else it returns 0.

The **alq\_write**() function returns EWOULDBLOCK if ALQ\_NOWAIT was provided as a value to *waitok* and either the queue is full, or when the system is shutting down.

The **alq\_get**() function returns NULL, if ALQ\_NOWAIT was provided as a value to *waitok* and either the queue is full, or when the system is shutting down.

NOTE: invalid arguments to non-void functions will result in undefined behaviour.

## SEE ALSO

[syslog(3)](/syslog/3.md), [kthread(9)](/kthread/9.md), [ktr(9)](/ktr/9.md), [tsleep(9)](/tsleep/9.md), [vnode(9)](/vnode/9.md)

## HISTORY

The Asynchronous Logging Queues (ALQ) facility first appeared in FreeBSD 5.0.

## AUTHORS

The **alq** facility was written by Jeffrey Roberson ⟨jeff@FreeBSD.org⟩.

This manual page was written by Hiten Pandya ⟨hmp@FreeBSD.org⟩.