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

# alq(9freebsd)

Asynchronous Logging Queues

Part of [ALQ(9freebsd)](/ALQ/9freebsd.md).

## NAME

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

## SYNOPSIS

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

*int*\

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

*int*\

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

*int*\

**alq\_writen**(*struct alq \*alq*, *void \*data*, *int len*, *int flags*);

*int*\

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

*void*\

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

*void*\

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

*struct* *ale* *\**\

**alq\_getn**(*struct alq \*alq*, *int len*, *int flags*);

*struct* *ale* *\**\

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

*void*\

**alq\_post\_flags**(*struct alq \*alq*, *struct ale \*ale*, *int flags*);

*void*\

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

## DESCRIPTION

The **alq** facility provides an asynchronous fixed or variable 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 {
	intptr_t	ae_bytesused;	/* # bytes written to ALE. */
	char		*ae_data;	/* Write ptr. */
	int		ae_pad;		/* Unused, compat. */
};
```

An **alq** can be created in either fixed or variable length mode. A variable length **alq** accommodates writes of varying length using **alq\_writen**() and **alq\_getn**(). A fixed length **alq** accommodates a fixed number of writes using **alq\_write**() and **alq\_get**(), each of fixed size (set at queue creation time). Fixed length mode is deprecated in favour of variable length mode.

## FUNCTIONS

The **alq\_open\_flags**() function creates a new variable length asynchronous 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 *cred* argument specifies the credentials to use when opening and performing I/O on the file. The *size* argument sets the size (in bytes) of the underlying queue. The ALQ\_ORDERED flag may be passed in via *flags* to indicate that the ordering of writer threads waiting for a busy **alq** to free up resources should be preserved.

The deprecated **alq\_open**() function is implemented as a wrapper around **alq\_open\_flags**() to provide backwards compatibility to consumers that have not been updated to utilise the newer **alq\_open\_flags**() function. It passes all arguments through to **alq\_open\_flags**() untouched except for *size* and *count*, and sets *flags* to 0. To create a variable length mode **alq**, the *size* argument should be set to the size (in bytes) of the underlying queue and the *count* argument should be set to 0. To create a fixed length mode **alq**, the *size* argument should be set to the size (in bytes) of each write and the *count* argument should be set to the number of *size* byte chunks to reserve capacity for.

The **alq\_writen**() function writes *len* bytes from *data* to the designated variable length mode queue *alq*. If **alq\_writen**() could not write the entry immediately and ALQ\_WAITOK is set in *flags*, the function will be allowed to [msleep\_spin(9)](/msleep_spin/9.md) with the “alqwnord” or “alqwnres” wait message. A write will automatically schedule the queue *alq* to be flushed to disk. This behaviour can be controlled by passing ALQ\_NOACTIVATE via *flags* to indicate that the write should not schedule *alq* to be flushed to disk.

The deprecated **alq\_write**() function is implemented as a wrapper around **alq\_writen**() to provide backwards compatibility to consumers that have not been updated to utilise variable length mode queues. The function will write *size* bytes of data (where *size* was specified at queue creation time) from the *data* buffer to the *alq*. Note that it is an error to call **alq\_write**() on a variable length mode queue.

The **alq\_flush**() function is used for flushing *alq* to the log medium that was passed to **alq\_open**(). If *alq* has data to flush and is not already in the process of being flushed, the function will block doing IO. Otherwise, the function will return immediately.

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\_getn**() function returns an asynchronous log entry from *alq*, initialised to point at a buffer capable of receiving *len* bytes of data. This function leaves *alq* in a locked state, until a subsequent **alq\_post**() or **alq\_post\_flags**() call is made. If **alq\_getn**() could not obtain *len* bytes of buffer immediately and ALQ\_WAITOK is set in *flags*, the function will be allowed to [msleep\_spin(9)](/msleep_spin/9.md) with the “alqgnord” or “alqgnres” wait message. The caller can choose to write less than *len* bytes of data to the returned asynchronous log entry by setting the entry's ae\_bytesused field to the number of bytes actually written. This must be done prior to calling **alq\_post**().

The deprecated **alq\_get**() function is implemented as a wrapper around **alq\_getn**() to provide backwards compatibility to consumers that have not been updated to utilise variable length mode queues. The asynchronous log entry returned will be initialised to point at a buffer capable of receiving *size* bytes of data (where *size* was specified at queue creation time). Note that it is an error to call **alq\_get**() on a variable length mode queue.

The **alq\_post\_flags**() function schedules the asynchronous log entry *ale* (obtained from **alq\_getn**() or **alq\_get**()) for writing to *alq*. The ALQ\_NOACTIVATE flag may be passed in via *flags* to indicate that the queue should not be immediately scheduled to be flushed to disk. This function leaves *alq* in an unlocked state.

The **alq\_post**() function is implemented as a wrapper around **alq\_post\_flags**() to provide backwards compatibility to consumers that have not been updated to utilise the newer **alq\_post\_flags**() function. It simply passes all arguments through to **alq\_post\_flags**() untouched, and sets *flags* to 0.

## IMPLEMENTATION NOTES

The **alq\_writen**() and **alq\_write**() functions both perform a [bcopy(3)](/bcopy/3.md) from the supplied *data* buffer into the underlying **alq** buffer. Performance critical code paths may wish to consider using **alq\_getn**() (variable length queues) or **alq\_get**() (fixed length queues) to avoid the extra memory copy. Note that a queue remains locked between calls to **alq\_getn**() or **alq\_get**() and **alq\_post**() or **alq\_post\_flags**(), so this method of writing to a queue is unsuitable for situations where the time between calls may be substantial.

## LOCKING

Each asynchronous logging queue is protected by a spin mutex.

Functions **alq\_flush**() and **alq\_open**() 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\_writen**() and **alq\_write**() functions return EWOULDBLOCK if ALQ\_NOWAIT was set in *flags* and either the queue is full or the system is shutting down.

The **alq\_getn**() and **alq\_get**() functions return NULL if ALQ\_NOWAIT was set in *flags* and either the queue is full or the system is shutting down.

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

## SEE ALSO

[syslog(3)](/syslog/3.md), [kproc(9)](/kproc/9.md), [ktr(9)](/ktr/9.md), [msleep\_spin(9)](/msleep_spin/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*⟩ and extended by Lawrence Stewart ⟨*lstewart@freebsd.org*⟩.

This manual page was written by Hiten Pandya ⟨*hmp@FreeBSD.org*⟩ and revised by Lawrence Stewart ⟨*lstewart@freebsd.org*⟩.