share/man/man9/alq.9

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