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