1.\" 2.\" Copyright (c) 2003 Hiten M. Pandya <hmp@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions, and the following disclaimer, 10.\" without modification, immediately at the beginning of the file. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 18.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd May 16, 2003 29.Dt ALQ 9 30.Os 31.Sh NAME 32.Nm alq , 33.Nm alq_open , 34.Nm alq_write , 35.Nm alq_flush , 36.Nm alq_close , 37.Nm alq_get , 38.Nm alq_post 39.Nd Asynchronous Logging Queues 40.Sh SYNOPSIS 41.In sys/alq.h 42.Ft int 43.Fo alq_open 44.Fa "struct alq **app" 45.Fa "const char *file" 46.Fa "struct ucred *cred" 47.Fa "int size" 48.Fa "int count" 49.Fc 50.Ft int 51.Fn alq_write "struct alq *alq" "void *data" "int waitok" 52.Ft void 53.Fn alq_flush "struct alq *alq" 54.Ft void 55.Fn alq_close "struct alq *alq" 56.Ft struct ale * 57.Fn alq_get "struct alq *alq" "int waitok" 58.Ft void 59.Fn alq_post "struct alq *alq" "struct ale *ale" 60.Sh DESCRIPTION 61The 62.Nm 63facility provides an asynchronous fixed length recording 64mechanism, known as Asynchronous Logging Queues. 65It can record to any 66.Xr vnode 9 , 67thus providing the ability to journal logs to character 68devices as well as regular files. 69All functions accept a 70.Vt "struct alq" 71argument, which is an opaque type that maintains state information 72for an Asynchronous Logging Queue. 73The logging facility runs in a separate kernel thread, which services 74all log entry requests. 75.Pp 76An 77.Dq asynchronous log entry 78is defined as 79.Vt "struct ale" , 80which has the following members: 81.Bd -literal -offset indent 82struct ale { 83 struct ale *ae_next; /* Next Entry */ 84 char *ae_data; /* Entry buffer */ 85 int ae_flags; /* Entry flags */ 86}; 87.Ed 88.Pp 89The 90.Va ae_flags 91field is for internal use, clients of the 92.Nm 93interface should not modify this field. 94Behaviour is undefined if this field is modified. 95.Sh FUNCTIONS 96The 97.Fn alq_open 98function creates a new logging queue. 99The 100.Fa file 101argument is the name of the file to open for logging. 102The argument 103.Fa cred 104specifies the credentials to use when opening the file. 105The size of each entry in the queue is determined by 106.Fa size . 107The 108.Fa count 109argument determines the number of items to be stored in the 110asynchronous queue over an approximate period of a disk 111write operation. 112.Pp 113The 114.Fn alq_write 115function writes 116.Fa data 117to the designated queue, 118.Fa alq . 119In the event that 120.Fn alq_write 121could not write the entry immediately, and 122.Dv ALQ_WAITOK 123is passed to 124.Fa waitok , 125then 126.Fn alq_write 127will be allowed to 128.Xr tsleep 9 . 129.Pp 130The 131.Fn alq_flush 132function is used for flushing 133.Fa alq 134to the log medium that was passed to 135.Fn alq_open . 136.Pp 137The 138.Fn alq_close 139function will close the asynchronous logging queue, 140.Fa alq , 141and flush all pending write requests to the log medium. 142It will free all resources that were previously allocated. 143.Pp 144The 145.Fn alq_get 146function returns the next available asynchronous logging entry 147from the queue, 148.Fa alq . 149This function leaves the queue in a locked state, until a subsequent 150.Fn alq_post 151call is made. 152In the event that 153.Fn alq_get 154could not retrieve an entry immediately, it will 155.Xr tsleep 9 156with the 157.Dq Li alqget 158wait message. 159.Pp 160The 161.Fn alq_post 162function schedules the asynchronous logging entry, 163.Fa ale , 164which is retrieved using the 165.Fn alq_get 166function, 167for writing to the asynchronous logging queue, 168.Fa alq . 169This function leaves the queue, 170.Fa alq , 171in an unlocked state. 172.Sh IMPLEMENTATION NOTES 173The 174.Fn alq_open 175function uses the credentials of the invoking thread 176for opening files. 177The 178.Fn alq_write 179function is a wrapper around the 180.Fn alq_get 181and 182.Fn alq_post 183functions; by using these functions separately, a call 184to 185.Fn bcopy 186can be avoided for performance critical code paths. 187.Sh LOCKING 188Each asynchronous queue is protected by a spin mutex. 189.Pp 190Functions 191.Fn alq_flush , 192.Fn alq_open 193and 194.Fn alq_post 195may attempt to acquire an internal sleep mutex, and should 196consequently not be used in contexts where sleeping is 197not allowed. 198.Sh RETURN VALUES 199The 200.Fn alq_open 201function returns one of the error codes listed in 202.Xr open 2 , 203if it fails to open 204.Fa file , 205or else it returns 0. 206.Pp 207The 208.Fn alq_write 209function returns 210.Er EWOULDBLOCK 211if 212.Dv ALQ_NOWAIT 213was provided as a value to 214.Fa waitok 215and either the queue is full, or when the system is shutting down. 216.Pp 217The 218.Fn alq_get 219function returns 220.Dv NULL , 221if 222.Dv ALQ_NOWAIT 223was provided as a value to 224.Fa waitok 225and either the queue is full, or when the system is shutting down. 226.Pp 227NOTE: invalid arguments to non-void functions will result in 228undefined behaviour. 229.Sh SEE ALSO 230.Xr syslog 3 , 231.Xr kthread 9 , 232.Xr ktr 9 , 233.Xr tsleep 9 , 234.Xr vnode 9 235.Sh HISTORY 236The 237Asynchronous Logging Queues (ALQ) facility first appeared in 238.Fx 5.0 . 239.Sh AUTHORS 240.An -nosplit 241The 242.Nm 243facility was written by 244.An Jeffrey Roberson Aq jeff@FreeBSD.org . 245.Pp 246This manual page was written by 247.An Hiten M. Pandya Aq hmp@FreeBSD.org . 248