diff options
author | hmp <hmp@FreeBSD.org> | 2003-11-10 22:45:09 +0000 |
---|---|---|
committer | hmp <hmp@FreeBSD.org> | 2003-11-10 22:45:09 +0000 |
commit | 3b1d84afe440bb6a3b51602929717b6f74fa4007 (patch) | |
tree | fd00c699c8f23b78b01d516e13ae9485235639f0 /share/man/man9/alq.9 | |
parent | 23058182407fb7fb4e47e5b3d9c3cd9a1baee996 (diff) | |
download | FreeBSD-src-3b1d84afe440bb6a3b51602929717b6f74fa4007.zip FreeBSD-src-3b1d84afe440bb6a3b51602929717b6f74fa4007.tar.gz |
Manual page for Asynchronous Logging Queues (ALQ) facility.
The manual page contains enough information to get someone started
with ALQ.
MLINKS have been added appropriately.
Approved by: jeff, des
Reviewed by: des, jeff, sam, brooks, rwatson, mtm
Diffstat (limited to 'share/man/man9/alq.9')
-rw-r--r-- | share/man/man9/alq.9 | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/share/man/man9/alq.9 b/share/man/man9/alq.9 new file mode 100644 index 0000000..c42422f --- /dev/null +++ b/share/man/man9/alq.9 @@ -0,0 +1,228 @@ +.\" +.\" 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$ +.\" +.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 +.In 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. +.Pp +An +.Dq asynchronous log entry , +is defined as +.Vt "struct ale" , +which has the following members: +.Bd -literal + struct ale { + struct ale *ae_next; /* Next Entry */ + char *ae_data; /* Entry buffer */ + int ae_flags; /* Entry flags */ + }; +.Ed +.Pp +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. +.Pp +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. +.Pp +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 . +.Pp +The +.Fn alq_flush +function is used for flushing +.Fa alq +to the log medium that was passed to +.Fn alq_open . +.Pp +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. +.Pp +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 2 +with the +.Dq alqget +wait message. +.Pp +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. +.Pp +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. +.Pp +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. +.Pp +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 . +.Pp +This manual page was written by +.An Hiten M. Pandya Aq hmp@FreeBSD.org . |