1.\" 2.\" Copyright (c) 2003 Hiten 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 cmode" 48.Fa "int size" 49.Fa "int count" 50.Fc 51.Ft int 52.Fn alq_write "struct alq *alq" "void *data" "int waitok" 53.Ft void 54.Fn alq_flush "struct alq *alq" 55.Ft void 56.Fn alq_close "struct alq *alq" 57.Ft struct ale * 58.Fn alq_get "struct alq *alq" "int waitok" 59.Ft void 60.Fn alq_post "struct alq *alq" "struct ale *ale" 61.Sh DESCRIPTION 62The 63.Nm 64facility provides an asynchronous fixed length recording 65mechanism, known as Asynchronous Logging Queues. 66It can record to any 67.Xr vnode 9 , 68thus providing the ability to journal logs to character 69devices as well as regular files. 70All functions accept a 71.Vt "struct alq" 72argument, which is an opaque type that maintains state information 73for an Asynchronous Logging Queue. 74The logging facility runs in a separate kernel thread, which services 75all log entry requests. 76.Pp 77An 78.Dq asynchronous log entry 79is defined as 80.Vt "struct ale" , 81which has the following members: 82.Bd -literal -offset indent 83struct ale { 84 struct ale *ae_next; /* Next Entry */ 85 char *ae_data; /* Entry buffer */ 86 int ae_flags; /* Entry flags */ 87}; 88.Ed 89.Pp 90The 91.Va ae_flags 92field is for internal use, clients of the 93.Nm 94interface should not modify this field. 95Behaviour is undefined if this field is modified. 96.Sh FUNCTIONS 97The 98.Fn alq_open 99function creates a new logging queue. 100The 101.Fa file 102argument is the name of the file to open for logging; if the file does not 103yet exist, 104.Fn alq_open 105will attempt to create it. 106The 107.Fa cmode 108argument will be passed to 109.Fn vn_open 110as the requested creation mode, to be used if the file will be created by 111.Fn alq_open . 112Consumers of this API may wish to pass 113.Dv ALQ_DEFAULT_CMODE , 114a default creation mode suitable for most applications. 115The argument 116.Fa cred 117specifies the credentials to use when opening and performing I/O on the file. 118The size of each entry in the queue is determined by 119.Fa size . 120The 121.Fa count 122argument determines the number of items to be stored in the 123asynchronous queue over an approximate period of a disk 124write operation. 125.Pp 126The 127.Fn alq_write 128function writes 129.Fa data 130to the designated queue, 131.Fa alq . 132In the event that 133.Fn alq_write 134could not write the entry immediately, and 135.Dv ALQ_WAITOK 136is passed to 137.Fa waitok , 138then 139.Fn alq_write 140will be allowed to 141.Xr tsleep 9 . 142.Pp 143The 144.Fn alq_flush 145function is used for flushing 146.Fa alq 147to the log medium that was passed to 148.Fn alq_open . 149.Pp 150The 151.Fn alq_close 152function will close the asynchronous logging queue, 153.Fa alq , 154and flush all pending write requests to the log medium. 155It will free all resources that were previously allocated. 156.Pp 157The 158.Fn alq_get 159function returns the next available asynchronous logging entry 160from the queue, 161.Fa alq . 162This function leaves the queue in a locked state, until a subsequent 163.Fn alq_post 164call is made. 165In the event that 166.Fn alq_get 167could not retrieve an entry immediately, it will 168.Xr tsleep 9 169with the 170.Dq Li alqget 171wait message. 172.Pp 173The 174.Fn alq_post 175function schedules the asynchronous logging entry, 176.Fa ale , 177which is retrieved using the 178.Fn alq_get 179function, 180for writing to the asynchronous logging queue, 181.Fa alq . 182This function leaves the queue, 183.Fa alq , 184in an unlocked state. 185.Sh IMPLEMENTATION NOTES 186The 187.Fn alq_write 188function is a wrapper around the 189.Fn alq_get 190and 191.Fn alq_post 192functions; by using these functions separately, a call 193to 194.Fn bcopy 195can be avoided for performance critical code paths. 196.Sh LOCKING 197Each asynchronous queue is protected by a spin mutex. 198.Pp 199Functions 200.Fn alq_flush , 201.Fn alq_open 202and 203.Fn alq_post 204may attempt to acquire an internal sleep mutex, and should 205consequently not be used in contexts where sleeping is 206not allowed. 207.Sh RETURN VALUES 208The 209.Fn alq_open 210function returns one of the error codes listed in 211.Xr open 2 , 212if it fails to open 213.Fa file , 214or else it returns 0. 215.Pp 216The 217.Fn alq_write 218function returns 219.Er EWOULDBLOCK 220if 221.Dv ALQ_NOWAIT 222was provided as a value to 223.Fa waitok 224and either the queue is full, or when the system is shutting down. 225.Pp 226The 227.Fn alq_get 228function returns 229.Dv NULL , 230if 231.Dv ALQ_NOWAIT 232was provided as a value to 233.Fa waitok 234and either the queue is full, or when the system is shutting down. 235.Pp 236NOTE: invalid arguments to non-void functions will result in 237undefined behaviour. 238.Sh SEE ALSO 239.Xr syslog 3 , 240.Xr kthread 9 , 241.Xr ktr 9 , 242.Xr tsleep 9 , 243.Xr vnode 9 244.Sh HISTORY 245The 246Asynchronous Logging Queues (ALQ) facility first appeared in 247.Fx 5.0 . 248.Sh AUTHORS 249.An -nosplit 250The 251.Nm 252facility was written by 253.An Jeffrey Roberson Aq jeff@FreeBSD.org . 254.Pp 255This manual page was written by 256.An Hiten Pandya Aq hmp@FreeBSD.org . 257