libslack(msg) - message module
#include <slack/msg.h>
typedef struct Msg Msg;
void msg_release(Msg *msg); void *msg_destroy(Msg **msg); void msg_out(Msg *dst, const char *fmt, ...); void vmsg_out(Msg *dst, const char *fmt, va_list args); Msg *msg_create_fd(int fd); Msg *msg_create_fd_locked(Locker *locker, int fd); Msg *msg_create_stderr(void); Msg *msg_create_stderr_locked(Locker *locker); Msg *msg_create_stdout(void); Msg *msg_create_stdout_locked(Locker *locker); Msg *msg_create_file(const char *path); Msg *msg_create_file_locked(Locker *locker, const char *path); Msg *msg_create_syslog(const char *ident, int option, int facility); Msg *msg_create_syslog_locked(Locker *locker, const char *ident, int option, int facility); Msg *msg_create_plex(Msg *msg1, Msg *msg2); Msg *msg_create_plex_locked(Locker *locker, Msg *msg1, Msg *msg2); int msg_add_plex(Msg *msg, Msg *item); const char *msg_set_timestamp_format(const char *format); int msg_set_timestamp_format_locker(Locker *locker); int syslog_lookup_facility(const char *facility); int syslog_lookup_priority(const char *priority); const char *syslog_facility_str(int spec); const char *syslog_priority_str(int spec); int syslog_parse(const char *spec, int *facility, int *priority);
This module provides general messaging functions. Message channels can be
created that send messages to a file descriptor, a file, syslog or multiplex messages to any combination of the above. Messages sent to
files are timestamped using (by default) the strftime(3) format: "%Y%m%d
%H:%M:%S"
.
It also provides functions for parsing syslog targets, converting between syslog facility names and codes, and converting between syslog priority names and codes.
void msg_release(Msg *msg)
Releases (deallocates) msg
and its internal data.
void *msg_destroy(Msg **msg)
Destroys (deallocates and sets to NULL
) *msg
. Returns NULL
.
void msg_out(Msg *dst, const char *fmt, ...)
Sends a message to dst
. fmt
is a printf-like format string. Any remaining arguments are processed as in printf(3).
Warning: Do not under any circumstances ever pass a non-literal string as the fmt argument unless you know exactly how many conversions will take place. Being careless with this is a very good way to build potential security holes into your programs. The same is true for all functions that take a printf()-like format string as an argument.
msg_out(dst, buf); // EVIL msg_out(dst, "%s", buf); // GOOD
void vmsg_out(Msg *dst, const char *fmt, va_list ap)
Sends a message to dst
. fmt
is a printf-like format string.
args
is processed as in vprintf(3).
Msg *msg_create_fd(int fd)
Creates a Msg object that sends messages to file descriptor fd
. On success, returns the new Msg object. On error, returns NULL
.
Msg *msg_create_fd_locked(Locker *locker, int fd)
Creates a Msg object that sends messages to file descriptor fd
. Multiple threads accessing this Msg object will be synchronised by
locker
. On success, returns the new Msg object. On error, returns
NULL
.
Msg *msg_create_stderr(void)
Creates a Msg object that sends messages to standard error. On success, returns the new Msg object. On error, returns NULL
.
Msg *msg_create_stderr_locked(Locker *locker)
Creates a Msg object that sends messages to standard error. Multiple threads accessing
this Msg object will be synchronised by locker
. On success, returns the new Msg object. On error, returns NULL
.
Msg *msg_create_stdout(void)
Creates a Msg object that sends messages to standard output. On success, returns the new Msg object. On error, returns NULL
.
Msg *msg_create_stdout_locked(Locker *locker)
Creates a Msg object that sends messages to standard output. Multiple threads accessing
this Msg object will be synchronised by locker
. On success, returns the new Msg object. On error, returns NULL
.
Msg *msg_create_file(const char *path)
Creates a Msg object that sends messages to the file specified by
path
. On success, returns the new Msg object. On error, returns
NULL
.
Msg *msg_create_file_locked(Locker *locker, const char *path)
Creates a Msg object that sends messages to the file specified by
path
. Multiple threads accessing this Msg object will be synchronised by locker
. On success, returns the new Msg object. On error, returns
NULL
.
Msg *msg_create_syslog(const char *ident, int option, int facility)
Creates a Msg object that sends messages to syslog initialised with
ident
, option
and facility
. On success, returns the new Msg
object. On error, returns NULL
.
Msg *msg_create_syslog_locked(Locker *locker, const char *ident, int option, int facility)
Creates a Msg object that sends messages to syslog initialised with
ident
, option
and facility
. Multiple threads accessing this Msg
object will be synchronised by locker
. On success, returns the new Msg
object. On error, returns NULL
.
Msg *msg_create_plex(Msg *msg1, Msg *msg2)
Creates a Msg object that multiplexes messages to msg1
and msg2
. Further Msg objects may be added to its list using msg_add_plex(Msg
*msg). On success, returns the new Msg object. On error, returns
NULL
.
Msg *msg_create_plex_locked(Locker *locker, Msg *msg1, Msg *msg2)
Creates a Msg object that multiplexes messages to msg1
and msg2
. Further Msg objects may be added to its list using msg_add_plex(Msg
*msg). Multiple threads accessing this Msg object will be synchronised by locker
. On success, returns the new Msg object. On error, returns
NULL
.
int msg_add_plex(Msg *msg, Msg *item)
Adds item
to the list of Msg objects multiplexed by msg
. On success, returns 0. On error, returns -1.
const char *msg_set_timestamp_format(const char *format)
Sets the strftime(3) format string used when sending messages to a file. By default, it is "%Y%m%d %H:%M:%S"
. On success, returns the previous format string. On error (i.e. format
is NULL
), returns NULL
.
int msg_set_timestamp_format_locker(Locker *locker)
Sets the locking strategy for changing the timestamp format used when
sending messages to a file. This is only needed if the timestamp format
will be modified in multiple threads. On success, returns 0
. On error, returns
-1
.
int syslog_lookup_facility(const char *facility)
Returns the code corresponding to facility
. If not found, returns -1.
int syslog_lookup_priority(const char *priority)
Returns the code corresponding to priority
. If not found, returns -1.
const char *syslog_facility_str(int spec)
Returns the name corresponding to the facility part of spec
. If not found, returns NULL
.
const char *syslog_priority_str(int spec)
Returns the name corresponding to the priority part of spec
. If not found, returns NULL
.
int syslog_parse(const char *spec, int *facility, int *priority)
Parses spec
as a facility.priority string. If facility
is non-NULL
, the parsed facility is stored in the location pointed to by
facility
. If priority
is non-NULL
the parsed priority is stored in the location pointed to by priority
. On success, returns 0. On error, returns -1.
syslog facilities syslog priorities ---------------------- ----------------------- kern LOG_KERN emerg LOG_EMERG user LOG_USER alert LOG_ALERT mail LOG_MAIL crit LOG_CRIT daemon LOG_DAEMON err LOG_ERR auth LOG_AUTH warning LOG_WARNING syslog LOG_SYSLOG info LOG_INFO lpr LOG_LPR debug LOG_DEBUG news LOG_NEWS uucp LOG_UUCP cron LOG_CRON local0 LOG_LOCAL0 local1 LOG_LOCAL1 local2 LOG_LOCAL2 local3 LOG_LOCAL3 local4 LOG_LOCAL4 local5 LOG_LOCAL5 local6 LOG_LOCAL6 local7 LOG_LOCAL7
#include <syslog.h> #include <slack/msg.h>
int main(int ac, char **av) { int facility, priority; if (syslog_parse(av[1], &facility, &priority) != -1) syslog(facility | priority, "syslog(%s)", av[1]); return 0; }
MT-Disciplined - msg functions - man thread(3) for details
MT-Safe - syslog functions
libslack(3), err(3), prog(3), syslog(3), thread(3)
20010215 raf <raf@raf.org>