Annotation of embedaddon/libpdel/sys/alog.3, revision 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