Annotation of embedaddon/libpdel/sys/alog.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: alog.3,v 1.15 2004/06/02 17:24:38 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt ALOG 3
42: .Os
43: .Sh NAME
44: .Nm alog
45: .Nd logging library
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In netinet/in.h
51: .In pdel/structs/structs.h
52: .In pdel/structs/type/array.h
53: .In pdel/sys/alog.h
54: .Ft int
55: .Fn alog_configure "int channel" "const struct alog_config *conf"
56: .Ft int
57: .Fn alog_shutdown "int channel"
58: .Ft int
59: .Fn alog_set_channel "int channel"
60: .Ft void
61: .Fn alog "int sev" "const char *fmt" "..."
62: .Ft void
63: .Fn valog "int sev" "const char *fmt" "va_list args"
64: .Ft int
65: .Fn alog_get_history "int channel" "int min_severity" "int max_entries" "time_t max_age" "const regex_t *preg" "struct alog_history *list"
66: .Ft int
67: .Fn alog_clear_history "int channel"
68: .Ft int
69: .Fn alog_facility "const char *name"
70: .Ft "const char *"
71: .Fn alog_facility_name "int facility"
72: .Ft int
73: .Fn alog_severity "const char *name"
74: .Ft "const char *"
75: .Fn alog_severity_name "int severity"
76: .Ft void
77: .Fn alog_set_debug "int channel" "int enabled"
78: .Ft void
79: .Fn alog_expand "const char *fmt" "int errnum" "char *buf" "size_t bufsize"
80: .Vt extern const struct structs_type alog_facility_type ;
81: .Vt extern const struct structs_type alog_severity_type ;
82: .Vt extern const struct structs_type alog_config_type ;
83: .Vt extern const struct structs_type alog_history_type ;
84: .Sh DESCRIPTION
85: These functions provide support for storing and retrieving log messages.
86: Up to
87: .Dv ALOG_MAX_CHANNELS
88: independent log channels are supported.
89: Log entries may be printed to standard error, stored in a searchable
90: circular log history file, and sent to a local or remote
91: .Xr syslog 3
92: server.
93: .Pp
94: .Fn alog_configure
95: configures a log channel;
96: .Fa channel
97: must be between zero and
98: .Dv "ALOG_MAX_CHANNELS - 1" ,
99: inclusive.
100: The channel's configuration is pointed to by
101: .Fa conf ,
102: which is a pointer to a
103: .Li "struct alog_config" :
104: .Pp
105: .Bd -literal -compact -offset 3n
106: struct alog_config {
107: const char *path; /* logfile filename, or NULL */
108: const char *name; /* syslog id, or NULL to disable */
109: const char *facility; /* syslog facility, NULL=stderr */
110: struct in_addr remote_server; /* remote server, or 0.0.0.0 local */
111: int min_severity; /* min severity to actually log */
112: int histlen; /* how much history to save */
113: };
114: .Ed
115: .Pp
116: If
117: .Fa path
118: is not
119: .Dv NULL
120: it specifies the pathname of a circular
121: .Xr logfile 3
122: used to store log entries, and
123: .Fa histlen
124: specifies the maximum number of entries to store in the file.
125: .Pp
126: If
127: .Fa facility
128: is
129: .Dv NULL ,
130: log messages will be sent to standard error.
131: Otherwise, if
132: .Fa name
133: is not
134: .Dv NULL ,
135: .Xr syslog 3
136: logging is performed:
137: .Fa name
138: is the
139: .Xr syslog 3
140: identifier,
141: .Fa remote_server
142: specifies the IP address of a remote
143: .Xr syslog 3
144: server to send log entries to (or
145: .Li "0.0.0.0"
146: for the local
147: .Xr syslogd 8
148: listening on
149: .Pa "/var/run/log)" ,
150: and
151: .Fa facility
152: specifies a
153: .Xr syslog 3
154: facility, which must be a valid facility name as returned by
155: .Fn alog_facility_name
156: (see below), e.g., "daemon".
157: If
158: .Fa name
159: is
160: .Dv NULL ,
161: log messages are not output at all (but will still be stored in the log file).
162: .Pp
163: .Fa min_severity
164: specifies a minimum
165: .Xr syslog 3
166: severity level (actually a maximum, numerically speaking) for
167: logged entries; less severe entries are filtered out.
168: .Pp
169: After a channel has been configured successfully via
170: .Fn alog_configure ,
171: access to that channel via
172: .Fn alog ,
173: .Fn valog ,
174: .Fn alog_get_history ,
175: and
176: .Fn alog_clear_history
177: by multiple threads is safe.
178: .Pp
179: .Fn alog_shutdown
180: shuts down an
181: .Fa alog
182: channel, returning it to its uninitialized, thread-unsafe state.
183: Logging to an uninitialized channel is permitted; the output is
184: written to standard error.
185: This allows applications to log errors before they've configured
186: .Nm alog .
187: .Pp
188: .Fn alog_set_channel
189: sets the log channel for newly logged messages.
190: This setting persists until another call to
191: .Fn alog_set_channel .
192: A separate "current channel" variable is kept for each thread.
193: .Pp
194: .Fn alog
195: and
196: .Fn valog
197: log a message.
198: .Fa sev
199: is a
200: .Xr syslog 3
201: severity level such as
202: .Dv LOG_ERROR .
203: The message is formatted using
204: .Fa fmt
205: as a
206: .Xr printf 3
207: like format string.
208: As a special case, "%m" is replaced with
209: .Fn strerror errno .
210: The value of
211: .Va errno
212: is not modified by these functions.
213: Note that when a channel is configured to log to syslog or standard error,
214: these functions become thread cancellation points.
215: .Pp
216: .Fn alog_get_history
217: retrieves previously logged entries from the circular log file
218: associated with channel
219: .Fa channel .
220: Only entries with severity greater than
221: .Fa min_severity
222: are returned;
223: only entries logged no earlier than
224: .Fa max_age
225: seconds ago are returned;
226: if
227: .Fa preg
228: is not
229: .Dv NULL ,
230: log entries not matching the regular expression are filtered out;
231: and finally, at most
232: .Fa max_entries
233: total entries are returned.
234: .Pp
235: The returned entries are described by an array of pointers to
236: .Li "struct alog_entry" :
237: .Pp
238: .Bd -literal -compact -offset 3n
239: struct alog_entry {
240: time_t when; /* when event was logged */
241: int sev; /* entry log severity */
242: char msg[0]; /* entry contents (including '\\0') */
243: };
244:
245: DEFINE_STRUCTS_ARRAY(alog_history, struct alog_entry *);
246: .Ed
247: .Pp
248: This array is stored in
249: .Fa "*list" ,
250: which will then contain a data structure with
251: .Xr structs 3
252: type
253: .Fa alog_history_type
254: and which must eventually be freed by the caller via
255: .Xr structs_free 3 .
256: .Pp
257: .Fn alog_clear_history
258: resets a log history file to empty.
259: .Pp
260: .Fn alog_facility
261: takes a
262: .Xr syslog 3
263: facility name and returns its numeric value.
264: .Pp
265: .Fn alog_facility_name
266: returns the
267: .Xr syslog 3
268: facility name for
269: .Fa facility .
270: .Pp
271: .Fn alog_severity
272: takes a
273: .Xr syslog 3
274: severity name and returns its numeric value.
275: .Pp
276: .Fn alog_severity_name
277: returns the
278: .Xr syslog 3
279: severity name for
280: .Fa severity .
281: .Pp
282: .Fn alog_expand
283: expands the last occurence of "%m" (if any) in the string
284: .Fa fmt
285: into
286: .Fn strerror errnum
287: and writes the result into the buffer pointed to by
288: .Fa buf ,
289: which has size
290: .Fa bufsize .
291: .Pp
292: .Fn alog_set_debug
293: causes the next call to
294: .Fn alog_configure
295: to act as if
296: .Fa facility
297: were equal to
298: .Dv NULL .
299: .Pp
300: The following
301: .Xr structs 3
302: types are pre-defined:
303: .Pp
304: .Bl -hang -width 2n -offset 3n
305: .It Va alog_facility_type
306: .Pp
307: Same as
308: .Xr structs_type_string 3
309: but may only take values that are valid
310: .Xr syslog 3
311: facility names.
312: The default value is
313: .Dq daemon.
314: .It Va alog_severity_type
315: .Pp
316: Same as
317: .Xr structs_type_int 3
318: but the ASCII representation is the severity name from
319: .Fn alog_severity_name
320: instead of a number.
321: .It Va alog_config_type
322: .Pp
323: Describes a
324: .Li "struct alog_config" .
325: .It Va alog_history_type
326: .Pp
327: Describes a
328: .Li "struct alog_history" ,
329: which is a
330: .Xr structs 3
331: array of
332: .Li "struct alog_entry *"
333: pointers.
334: This type is used for accessing and freeing the log history returned by
335: .Fn alog_get_history .
336: .El
337: .Sh RETURN VALUES
338: The above functions return -1 or
339: .Dv NULL
340: to indicate an error, setting
341: .Va errno
342: accordingly.
343: .Sh SEE ALSO
344: .Xr libpdel 3 ,
345: .Xr regex 3 ,
346: .Xr structs 3 ,
347: .Xr structs_type_array 3 ,
348: .Xr syslog 3 ,
349: .Xr typed_mem 3
350: .Sh HISTORY
351: The PDEL library was developed at Packet Design, LLC.
352: .Dv "http://www.packetdesign.com/"
353: .Sh AUTHORS
354: .An Archie Cobbs Aq archie@freebsd.org
355: .Sh BUGS
356: If multiple channels are configured to write to local syslog,
357: messages can get written with the wrong identifier or facility.
358: This is an unavoidable consequence of the implementation of
359: .Xr openlog 3
360: and
361: .Xr syslog 3 ,
362: which doesn't support threading.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to alog.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / sys