NAME

libslack(msg) - message module


SYNOPSIS

    #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);


DESCRIPTION

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


EXAMPLE

    #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-Level

MT-Disciplined - msg functions - man thread(3) for details

MT-Safe - syslog functions


SEE ALSO

libslack(3), err(3), prog(3), syslog(3), thread(3)


AUTHOR

20010215 raf <raf@raf.org>