Copyright (c) 2003 Hiten M. Pandya <hmp@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the following disclaimer,
without modification, immediately at the beginning of the file.
2. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

$FreeBSD: head/share/man/man9/alq.9 131736 2004-07-07 07:56:58Z ru $

.Dd May 16, 2003 .Dt ALQ 9 .Os .Sh NAME .Nm alq , .Nm alq_open , .Nm alq_write , .Nm alq_flush , .Nm alq_close , .Nm alq_get , .Nm alq_post .Nd Asynchronous Logging Queues .Sh SYNOPSIS n sys/alq.h .Ft int .Fn alq_open "struct alq **app" "const char *file" "int size" "int count" .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" .Sh DESCRIPTION The .Nm facility provides an asynchronous fixed length recording mechanism, known as Asynchronous Logging Queues. It can record to any .Xr 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.

p An .Dq asynchronous log entry is defined as .Vt "struct ale" , which has the following members: d -literal -offset indent struct ale { struct ale *ae_next; /* Next Entry */ char *ae_data; /* Entry buffer */ int ae_flags; /* Entry flags */ }; .Ed

p The .Va ae_flags field is for internal use, clients of the .Nm interface should not modify this field. Behaviour is undefined if this field is modified. .Sh FUNCTIONS The .Fn alq_open function creates a new logging queue.

p The .Fa file argument is the name of the file to open for logging. 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.

p 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 .Dv ALQ_WAITOK is passed to .Fa waitok , then .Fn alq_write will be allowed to .Xr tsleep 9 .

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

p 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.

p 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 .Xr tsleep 9 with the .Dq Li alqget wait message.

p 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. .Sh IMPLEMENTATION NOTES The .Fn alq_open function uses the credentials of the invoking thread for opening files. 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. .Sh RETURN VALUES The .Fn alq_open function returns one of the error codes listed in .Xr open 2 , if it fails to open .Fa file , or else it returns 0.

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

p The .Fn alq_get function returns .Dv NULL , if .Dv ALQ_NOWAIT was provided as a value to .Fa waitok and either the queue is full, or when the system is shutting down.

p NOTE: invalid arguments to non-void functions will result in undefined behaviour. .Sh SEE ALSO .Xr syslog 3 , .Xr kthread 9 , .Xr ktr 9 , .Xr tsleep 9 , .Xr vnode 9 .Sh HISTORY The Asynchronous Logging Queues (ALQ) facility first appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Jeffrey Roberson Aq jeff@FreeBSD.org .

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