/share/man/man9/alq.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 441 lines · 441 code · 0 blank · 0 comment · 0 complexity · 0783f54888571c7cacdd0be1ffc583cf MD5 · raw file

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