1.\" 2.\" Copyright (c) 2003 Hiten Pandya <hmp@FreeBSD.org> 3.\" Copyright (c) 2009-2010 The FreeBSD Foundation 4.\" All rights reserved. 5.\" 6.\" Portions of this software were developed at the Centre for Advanced 7.\" Internet Architectures, Swinburne University of Technology, Melbourne, 8.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD 9.\" Foundation. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions, and the following disclaimer, 16.\" without modification, immediately at the beginning of the file. 17.\" 2. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 24.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd April 26, 2010 33.Dt ALQ 9 34.Os 35.Sh NAME 36.Nm alq , 37.Nm alq_open_flags , 38.Nm alq_open , 39.Nm alq_writen , 40.Nm alq_write , 41.Nm alq_flush , 42.Nm alq_close , 43.Nm alq_getn , 44.Nm alq_get , 45.Nm alq_post_flags , 46.Nm alq_post 47.Nd Asynchronous Logging Queues 48.Sh SYNOPSIS 49.In sys/alq.h 50.Ft int 51.Fo alq_open_flags 52.Fa "struct alq **app" 53.Fa "const char *file" 54.Fa "struct ucred *cred" 55.Fa "int cmode" 56.Fa "int size" 57.Fa "int flags" 58.Fc 59.Ft int 60.Fo alq_open 61.Fa "struct alq **app" 62.Fa "const char *file" 63.Fa "struct ucred *cred" 64.Fa "int cmode" 65.Fa "int size" 66.Fa "int count" 67.Fc 68.Ft int 69.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags" 70.Ft int 71.Fn alq_write "struct alq *alq" "void *data" "int flags" 72.Ft void 73.Fn alq_flush "struct alq *alq" 74.Ft void 75.Fn alq_close "struct alq *alq" 76.Ft struct ale * 77.Fn alq_getn "struct alq *alq" "int len" "int flags" 78.Ft struct ale * 79.Fn alq_get "struct alq *alq" "int flags" 80.Ft void 81.Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags" 82.Ft void 83.Fn alq_post "struct alq *alq" "struct ale *ale" 84.Sh DESCRIPTION 85The 86.Nm 87facility provides an asynchronous fixed or variable length recording 88mechanism, known as Asynchronous Logging Queues. 89It can record to any 90.Xr vnode 9 , 91thus providing the ability to journal logs to character 92devices as well as regular files. 93All functions accept a 94.Vt "struct alq" 95argument, which is an opaque type that maintains state information 96for an Asynchronous Logging Queue. 97The logging facility runs in a separate kernel thread, which services 98all log entry requests. 99.Pp 100An 101.Dq asynchronous log entry 102is defined as 103.Vt "struct ale" , 104which has the following members: 105.Bd -literal -offset indent 106struct ale { 107 intptr_t ae_bytesused; /* # bytes written to ALE. */ 108 char *ae_data; /* Write ptr. */ 109 int ae_pad; /* Unused, compat. */ 110}; 111.Ed 112.Pp 113An 114.Nm 115can be created in either fixed or variable length mode. 116A variable length 117.Nm 118accommodates writes of varying length using 119.Fn alq_writen 120and 121.Fn alq_getn . 122A fixed length 123.Nm 124accommodates a fixed number of writes using 125.Fn alq_write 126and 127.Fn alq_get , 128each of fixed size (set at queue creation time). 129Fixed length mode is deprecated in favour of variable length mode. 130.Sh FUNCTIONS 131The 132.Fn alq_open_flags 133function creates a new variable length asynchronous logging queue. 134The 135.Fa file 136argument is the name of the file to open for logging. 137If the file does not yet exist, 138.Fn alq_open 139will attempt to create it. 140The 141.Fa cmode 142argument will be passed to 143.Fn vn_open 144as the requested creation mode, to be used if the file will be created by 145.Fn alq_open . 146Consumers of this API may wish to pass 147.Dv ALQ_DEFAULT_CMODE , 148a default creation mode suitable for most applications. 149The 150.Fa cred 151argument specifies the credentials to use when opening and performing I/O on the file. 152The 153.Fa size 154argument sets the size (in bytes) of the underlying queue. 155The ALQ_ORDERED flag may be passed in via 156.Fa flags 157to indicate that the ordering of writer threads waiting for a busy 158.Nm 159to free up resources should be preserved. 160.Pp 161The deprecated 162.Fn alq_open 163function is implemented as a wrapper around 164.Fn alq_open_flags 165to provide backwards compatibility to consumers that have not been updated to 166utilise the newer 167.Fn alq_open_flags 168function. 169It passes all arguments through to 170.Fn alq_open_flags 171untouched except for 172.Fa size 173and 174.Fa count , 175and sets 176.Fa flags 177to 0. 178To create a variable length mode 179.Nm , 180the 181.Fa size 182argument should be set to the size (in bytes) of the underlying queue and the 183.Fa count 184argument should be set to 0. 185To create a fixed length mode 186.Nm , 187the 188.Fa size 189argument should be set to the size (in bytes) of each write and the 190.Fa count 191argument should be set to the number of 192.Fa size 193byte chunks to reserve capacity for. 194.Pp 195The 196.Fn alq_writen 197function writes 198.Fa len 199bytes from 200.Fa data 201to the designated variable length mode queue 202.Fa alq . 203If 204.Fn alq_writen 205could not write the entry immediately and 206.Dv ALQ_WAITOK 207is set in 208.Fa flags , 209the function will be allowed to 210.Xr msleep_spin 9 211with the 212.Dq Li alqwnord 213or 214.Dq Li alqwnres 215wait message. 216A write will automatically schedule the queue 217.Fa alq 218to be flushed to disk. 219This behaviour can be controlled by passing ALQ_NOACTIVATE via 220.Fa flags 221to indicate that the write should not schedule 222.Fa alq 223to be flushed to disk. 224.Pp 225The deprecated 226.Fn alq_write 227function is implemented as a wrapper around 228.Fn alq_writen 229to provide backwards compatibility to consumers that have not been updated to 230utilise variable length mode queues. 231The function will write 232.Fa size 233bytes of data (where 234.Fa size 235was specified at queue creation time) from the 236.Fa data 237buffer to the 238.Fa alq . 239Note that it is an error to call 240.Fn alq_write 241on a variable length mode queue. 242.Pp 243The 244.Fn alq_flush 245function is used for flushing 246.Fa alq 247to the log medium that was passed to 248.Fn alq_open . 249If 250.Fa alq 251has data to flush and is not already in the process of being flushed, the 252function will block doing IO. 253Otherwise, the function will return immediately. 254.Pp 255The 256.Fn alq_close 257function will close the asynchronous logging queue 258.Fa alq 259and flush all pending write requests to the log medium. 260It will free all resources that were previously allocated. 261.Pp 262The 263.Fn alq_getn 264function returns an asynchronous log entry from 265.Fa alq , 266initialised to point at a buffer capable of receiving 267.Fa len 268bytes of data. 269This function leaves 270.Fa alq 271in a locked state, until a subsequent 272.Fn alq_post 273or 274.Fn alq_post_flags 275call is made. 276If 277.Fn alq_getn 278could not obtain 279.Fa len 280bytes of buffer immediately and 281.Dv ALQ_WAITOK 282is set in 283.Fa flags , 284the function will be allowed to 285.Xr msleep_spin 9 286with the 287.Dq Li alqgnord 288or 289.Dq Li alqgnres 290wait message. 291The caller can choose to write less than 292.Fa len 293bytes of data to the returned asynchronous log entry by setting the entry's 294ae_bytesused field to the number of bytes actually written. 295This must be done prior to calling 296.Fn alq_post . 297.Pp 298The deprecated 299.Fn alq_get 300function is implemented as a wrapper around 301.Fn alq_getn 302to provide backwards compatibility to consumers that have not been updated to 303utilise variable length mode queues. 304The asynchronous log entry returned will be initialised to point at a buffer 305capable of receiving 306.Fa size 307bytes of data (where 308.Fa size 309was specified at queue creation time). 310Note that it is an error to call 311.Fn alq_get 312on a variable length mode queue. 313.Pp 314The 315.Fn alq_post_flags 316function schedules the asynchronous log entry 317.Fa ale 318(obtained from 319.Fn alq_getn 320or 321.Fn alq_get ) 322for writing to 323.Fa alq . 324The ALQ_NOACTIVATE flag may be passed in via 325.Fa flags 326to indicate that the queue should not be immediately scheduled to be flushed to 327disk. 328This function leaves 329.Fa alq 330in an unlocked state. 331.Pp 332The 333.Fn alq_post 334function is implemented as a wrapper around 335.Fn alq_post_flags 336to provide backwards compatibility to consumers that have not been updated to 337utilise the newer 338.Fn alq_post_flags 339function. 340It simply passes all arguments through to 341.Fn alq_post_flags 342untouched, and sets 343.Fa flags 344to 0. 345.Sh IMPLEMENTATION NOTES 346The 347.Fn alq_writen 348and 349.Fn alq_write 350functions both perform a 351.Xr bcopy 3 352from the supplied 353.Fa data 354buffer into the underlying 355.Nm 356buffer. 357Performance critical code paths may wish to consider using 358.Fn alq_getn 359(variable length queues) or 360.Fn alq_get 361(fixed length queues) to avoid the extra memory copy. 362Note that a queue remains locked between calls to 363.Fn alq_getn 364or 365.Fn alq_get 366and 367.Fn alq_post 368or 369.Fn alq_post_flags , 370so this method of writing to a queue is unsuitable for situations where the 371time between calls may be substantial. 372.Sh LOCKING 373Each asynchronous logging queue is protected by a spin mutex. 374.Pp 375Functions 376.Fn alq_flush 377and 378.Fn alq_open 379may attempt to acquire an internal sleep mutex, and should 380consequently not be used in contexts where sleeping is 381not allowed. 382.Sh RETURN VALUES 383The 384.Fn alq_open 385function returns one of the error codes listed in 386.Xr open 2 , 387if it fails to open 388.Fa file , 389or else it returns 0. 390.Pp 391The 392.Fn alq_writen 393and 394.Fn alq_write 395functions return 396.Er EWOULDBLOCK 397if 398.Dv ALQ_NOWAIT 399was set in 400.Fa flags 401and either the queue is full or the system is shutting down. 402.Pp 403The 404.Fn alq_getn 405and 406.Fn alq_get 407functions return 408.Dv NULL 409if 410.Dv ALQ_NOWAIT 411was set in 412.Fa flags 413and either the queue is full or the system is shutting down. 414.Pp 415NOTE: invalid arguments to non-void functions will result in 416undefined behaviour. 417.Sh SEE ALSO 418.Xr syslog 3 , 419.Xr kproc 9 , 420.Xr ktr 9 , 421.Xr msleep_spin 9 , 422.Xr vnode 9 423.Sh HISTORY 424The 425Asynchronous Logging Queues (ALQ) facility first appeared in 426.Fx 5.0 . 427.Sh AUTHORS 428.An -nosplit 429The 430.Nm 431facility was written by 432.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org 433and extended by 434.An Lawrence Stewart Aq Mt lstewart@freebsd.org . 435.Pp 436This manual page was written by 437.An Hiten Pandya Aq Mt hmp@FreeBSD.org 438and revised by 439.An Lawrence Stewart Aq Mt lstewart@freebsd.org . 440