Linux Certif

Toute la documentation sur la certification Linux LPI

alq_write.9freebsd

BSD mandoc

NAME

alq alq_open alq_write alq_flush alq_close alq_get alq_post - Asynchronous Logging Queues

SYNOPSIS

In sys/alq.h Ft int Fo alq_open Fa struct alq **app Fa const char *file Fa struct ucred *cred Fa int cmode Fa int size Fa int count Fc Ft int Fn alq_write struct alq *alq void *data int waitok Ft void Fn alq_flush struct alq *alq Ft void Fn alq_close struct alq *alq Ft struct ale * Fn alq_get struct alq *alq int waitok Ft void Fn alq_post struct alq *alq struct ale *ale

DESCRIPTION

The facility provides an asynchronous fixed length recording mechanism, known as Asynchronous Logging Queues. It can record to any vnode(9), thus providing the ability to journal logs to character devices as well as regular files. All functions accept a Vt 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 Vt 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 interface should not modify this field. Behaviour is undefined if this field is modified.

FUNCTIONS

The Fn alq_open function creates a new logging queue. The Fa file argument is the name of the file to open for logging; if the file does not yet exist, Fn alq_open will attempt to create it. The Fa cmode argument will be passed to Fn vn_open as the requested creation mode, to be used if the file will be created by Fn alq_open . Consumers of this API may wish to pass ALQ_DEFAULT_CMODE a default creation mode suitable for most applications. The argument Fa 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 Fa size . The Fa count argument determines the number of items to be stored in the asynchronous queue over an approximate period of a disk write operation.

The Fn alq_write function writes Fa data to the designated queue, Fa alq . In the event that Fn alq_write could not write the entry immediately, and ALQ_WAITOK is passed to Fa waitok , then Fn alq_write will be allowed to tsleep(9).

The Fn alq_flush function is used for flushing Fa alq to the log medium that was passed to Fn alq_open .

The Fn alq_close function will close the asynchronous logging queue, Fa alq , and flush all pending write requests to the log medium. It will free all resources that were previously allocated.

The Fn alq_get function returns the next available asynchronous logging entry from the queue, Fa alq . This function leaves the queue in a locked state, until a subsequent Fn alq_post call is made. In the event that Fn alq_get could not retrieve an entry immediately, it will tsleep(9) with the ``alqget '' wait message.

The Fn alq_post function schedules the asynchronous logging entry, Fa ale , which is retrieved using the Fn alq_get function, for writing to the asynchronous logging queue, Fa alq . This function leaves the queue, Fa alq , in an unlocked state.

IMPLEMENTATION NOTES

The Fn alq_write function is a wrapper around the Fn alq_get and Fn alq_post functions; by using these functions separately, a call to Fn bcopy can be avoided for performance critical code paths.

LOCKING

Each asynchronous queue is protected by a spin mutex.

Functions Fn alq_flush , Fn alq_open and Fn 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 Fn alq_open function returns one of the error codes listed in open(2), if it fails to open Fa file , or else it returns 0.

The Fn alq_write function returns Er EWOULDBLOCK if ALQ_NOWAIT was provided as a value to Fa waitok and either the queue is full, or when the system is shutting down.

The Fn alq_get function returns NULL if ALQ_NOWAIT was provided as a value to Fa 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), kthread(9), ktr(9), tsleep(9), vnode(9)

HISTORY

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

AUTHORS

An -nosplit The facility was written by An Jeffrey Roberson Aq jeff@FreeBSD.org .

This manual page was written by An Hiten Pandya Aq hmp@FreeBSD.org .