diff options
Diffstat (limited to 'share/man/man9/alq.9')
| -rw-r--r-- | share/man/man9/alq.9 | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/share/man/man9/alq.9 b/share/man/man9/alq.9 new file mode 100644 index 000000000000..ec6ef2688c3a --- /dev/null +++ b/share/man/man9/alq.9 @@ -0,0 +1,256 @@ +.\" +.\" Copyright (c) 2003 Hiten 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 +.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" +.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 -offset indent +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. +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 +.Dv 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. +.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 9 +with the +.Dq Li 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_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 LOCKING +Each asynchronous queue is protected by a spin mutex. +.Pp +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. +.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 Pandya Aq hmp@FreeBSD.org . |