## NAME

ACE_Log_Msg - Provides a variable length argument message logging abstraction.

## SYNOPSIS

    #include <ace/Log_Msg.h>

    class ACE_Log_Msg
    {
      public:
            enum{ STDERR = 1,
            LOGGER = 2,
            OSTREAM = 4,
            MSG_CALLBACK = 8,
            VERBOSE = 16,
            VERBOSE_LITE = 32,
            SILENT = 64 };

        static ACE_Log_Msg *instance (void);
        static int exists (void);
        static void disable_debug_messages (
            ACE_Log_Priority priority = LM_DEBUG
            );
        static void enable_debug_messages (
            ACE_Log_Priority priority = LM_DEBUG
            );
        ACE_Log_Msg (void);
        ~ACE_Log_Msg (void);
        int open (
            const ASYS_TCHAR *prog_name,
            u_long options_flags = ACE_Log_Msg::STDERR,
            LPCTSTR logger_key = 0
            );
        void set_flags (u_long f);
        void clr_flags (u_long f);
        u_long flags (void);
        int acquire (void);
        int release (void);
        void sync (const ASYS_TCHAR *program_name);
        void op_status (int status);
        int op_status (void);
        void errnum (int);
        int errnum (void);
        void linenum (int);
        int linenum (void);
        void file (const ASYS_TCHAR *);
        const ASYS_TCHAR *file (void);
        void msg (const ASYS_TCHAR *);
        const ASYS_TCHAR *msg (void);
        void restart (int);
        int restart (void);
        void msg_ostream (ostream *);
        ostream *msg_ostream (void) const;
        void msg_callback (ACE_Log_Msg_Callback *c);
        ACE_Log_Msg_Callback *msg_callback (void) const;
        int inc (void);
        int dec (void);
        int trace_depth (void);
        void trace_depth (int);
        int trace_active (void);
        void trace_active (int value);
        ACE_Thread_Descriptor *thr_desc (void) const;
        void thr_desc (ACE_Thread_Descriptor *td);
        ACE_SEH_EXCEPT_HANDLER seh_except_selector (void);
        ACE_SEH_EXCEPT_HANDLER seh_except_selector (
            ACE_SEH_EXCEPT_HANDLER
            );
        ACE_SEH_EXCEPT_HANDLER seh_except_handler (void);
        ACE_SEH_EXCEPT_HANDLER seh_except_handler (
            ACE_SEH_EXCEPT_HANDLER
            );
        void stop_tracing (void);
        void start_tracing (void);
        int tracing_enabled (void);
        typedef enum { THREAD, PROCESS } MASK_TYPE;
        u_long priority_mask (MASK_TYPE = THREAD);
        u_long priority_mask (u_long, MASK_TYPE = THREAD);
        int log_priority_enabled (ACE_Log_Priority log_priority);
        pid_t getpid (void) const;
        const ASYS_TCHAR *local_host (void) const;
        void local_host (const ASYS_TCHAR *);
        void set (
            const ASYS_TCHAR *file,
            int line,
            int op_status = -1,
            int errnum = 0,
            int restart = 1,
            ostream *os = 0,
            ACE_Log_Msg_Callback *c = 0
            );
        ssize_t log (
            ACE_Log_Priority priority,
            const ASYS_TCHAR *format,
            ...
            );
        ssize_t log (
            const ASYS_TCHAR *format,
            ACE_Log_Priority priority,
            va_list argp
            );
        ssize_t log (ACE_Log_Record &log_record, int suppress_stderr = 0);
        int log_hexdump (
            ACE_Log_Priority log_priority,
            const char *buffer,
            int size,
            const ASYS_TCHAR *text = 0
            );
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      private:
        int status_;
        int errnum_;
        int linenum_;
        ASYS_TCHAR file_[MAXPATHLEN + 1];
        ASYS_TCHAR msg_[ACE_Log_Record::MAXLOGMSGLEN];
        int restart_;
        ostream *ostream_;
        ACE_Log_Msg_Callback *msg_callback_;
        int trace_depth_;
        int trace_active_;
        int tracing_enabled_;
        ACE_Thread_Descriptor *thr_desc_;
        ACE_SEH_EXCEPT_HANDLER seh_except_selector_;
        ACE_SEH_EXCEPT_HANDLER seh_except_handler_;
        u_long priority_mask_;
        static u_long process_priority_mask_;
        static const ASYS_TCHAR *program_name_;
        static const ASYS_TCHAR *local_host_;
        static pid_t pid_;
        static u_long flags_;
        static int msg_off_;
        static int instance_count_;
        static u_long default_priority_mask_;
        static void close (void);
        friend void ACE_OS::cleanup_tss (const u_int);
        ACE_Log_Msg &operator= (const ACE_Log_Msg &);
        ACE_Log_Msg (const ACE_Log_Msg &);
    };

## DESCRIPTION

This class is very flexible since it allows formatted error messages to be printed in a thread-safe manner to stderr or a distributed logger. Moreover, the message is kept in a thread-specific storage location, which can be used to communicate errors between framework methods and callers.

## Initialization and termination routines.

    static ACE_Log_Msg *instance (void);

Returns a pointer to the Singleton.

    static int exists (void);

Returns non-null if an ACE_Log_Msg exists for the calling thread.

    static void disable_debug_messages (
        ACE_Log_Priority priority = LM_DEBUG
        );

Clears the flag from the default priority mask used to initialize ACE_Log_Msg instances.

    static void enable_debug_messages (
        ACE_Log_Priority priority = LM_DEBUG
        );

Sets the flag in the default priority mask used to initialize ACE_Log_Msg instances.

    ACE_Log_Msg (void);

Initialize logger.

    ~ACE_Log_Msg (void);

cleanup logger.

    int open (
        const ASYS_TCHAR *prog_name,
        u_long options_flags = ACE_Log_Msg::STDERR,
        LPCTSTR logger_key = 0
        );

Initialize the ACE error handling facility. `prog_name` is the name of the executable program. `flags` are a bitwise-or of options flags passed to the Logger (see the enum above for the valid values). If the `LOGGER` bit in `flags` is enabled then `logger_key` is the name of ACE_FIFO rendezvous point where the local client logger daemon is listening for logging messages.

## Set/get the options flags.

    void set_flags (u_long f);

Enable the bits in the logger's options flags.

    void clr_flags (u_long f);

Disable the bits in the logger's options flags.

    u_long flags (void);

Return the bits in the logger's options flags.

## Allow apps to acquire and release internal synchronization lock.

This lock is used internally by the `ACE_Log_Msg` implementation. By exporting the lock, applications can hold the lock atomically over a number of calls to `ACE_Log_Msg`.

    int acquire (void);

Acquire the internal lock.

    int release (void);

Release the internal lock.

    void sync (const ASYS_TCHAR *program_name);

Call after doing a `fork` to resynchronize the process id and `program_name` variables. @@ Does this function mean anything on Windows?

## Set/get methods. Note that these are non-static and thus will

be thread-specific.

    void op_status (int status);

Set the result of the operation status (by convention, -1 means error).

    int op_status (void);

Get the result of the operation status (by convention, -1 means error).

    void errnum (int);

Set the value of the errnum (by convention this corresponds to errno).

    int errnum (void);

Get the value of the errnum (by convention this corresponds to errno).

    void linenum (int);

Set the line number where an error occurred.

    int linenum (void);

Get the line number where an error occurred.

    void file (const ASYS_TCHAR *);

Set the file name where an error occurred.

    const ASYS_TCHAR *file (void);

Get the file name where an error occurred.

    void msg (const ASYS_TCHAR *);

Set the message that describes what type of error occurred.

    const ASYS_TCHAR *msg (void);

Get the message that describes what type of error occurred.

    void restart (int);

Set the field that indicates whether interrupted calls should be restarted.

    int restart (void);

Get the field that indicates whether interrupted calls should be restarted.

## Notice that the following two function is equivalent to

"void msg_ostream (HANDLE)" and "HANDLE msg_ostream (void)" on Windows CE. There is no `iostream.h` support on CE.

    void msg_ostream (ostream *);

    ostream *msg_ostream (void) const;

Set/Get the ostream that is used to print error messages.

    void msg_callback (ACE_Log_Msg_Callback *c);

    ACE_Log_Msg_Callback *msg_callback (void) const;

Set/Get the callback object.

## Nesting depth increment and decrement.

    int inc (void);

    int dec (void);

## Get/set trace depth.

    int trace_depth (void);

    void trace_depth (int);

## Get/set trace active status.

    int trace_active (void);

    void trace_active (int value);

    ACE_Thread_Descriptor *thr_desc (void) const;

Get the TSS thread descriptor.

    void thr_desc (ACE_Thread_Descriptor *td);

Set the TSS thread descriptor. This method will call td-acquire_release to block execution until this call return.

    ACE_SEH_EXCEPT_HANDLER seh_except_selector (void);

    ACE_SEH_EXCEPT_HANDLER seh_except_selector (ACE_SEH_EXCEPT_HANDLER);

Get/Set TSS exception action.

    ACE_SEH_EXCEPT_HANDLER seh_except_handler (void);

    ACE_SEH_EXCEPT_HANDLER seh_except_handler (ACE_SEH_EXCEPT_HANDLER);

Get/Set TSS exception handler.

## Stop/start/query tracing status on a per-thread basis...

    void stop_tracing (void);

    void start_tracing (void);

    int tracing_enabled (void);

    typedef enum { THREAD, PROCESS } MASK_TYPE;

## Get/set the priority mask.

    u_long priority_mask (MASK_TYPE = THREAD);

Get the current `ACE_Log_Priority` mask.

    u_long priority_mask (u_long, MASK_TYPE = THREAD);

Set the `ACE_Log_Priority` mask, returns original mask.

    int log_priority_enabled (ACE_Log_Priority log_priority);

Return true if the requested priority is enabled.

    pid_t getpid (void) const;

Optimize reading of the pid (avoids a system call if the value is cached...).

## Set/get the name of the local host.

    const ASYS_TCHAR *local_host (void) const;

    void local_host (const ASYS_TCHAR *);

    void set (
        const ASYS_TCHAR *file,
        int line,
        int op_status = -1,
        int errnum = 0,
        int restart = 1,
        ostream *os = 0,
        ACE_Log_Msg_Callback *c = 0
        );

Set the line number, file name, operational status, error number, restart flag, ostream and the callback object. This combines all the other set methods into a single method.

    ssize_t log (
        ACE_Log_Priority priority,
        const ASYS_TCHAR *format,
        ...
        );

Format a message to the thread-safe ACE logging mechanism. Valid options (prefixed by '%', as in printf format strings) include: 'A': print an ACE_timer_t value (which could be either double or ACE_UINT32.) 'a': exit the program at this point (var-argument is the exit status!) 'c': print a character 'i', 'd': print a decimal number 'I', indent according to nesting depth 'e', 'E', 'f', 'F', 'g', 'G': print a double 'l', print line number where an error occurred. 'N': print file name where the error occurred. 'n': print the name of the program (or "`unknown`" if not set) 'o': print as an octal number 'P': print out the current process id 'p': print out the appropriate errno value from sys_errlist 'Q': print out the uint64 number 'r': call the function pointed to by the corresponding argument 'R': print return status 'S': print out the appropriate _sys_siglist entry corresponding to var-argument. 's': print out a character string 'T': print timestamp in hour:minute:sec:usec format. 'D': print timestamp in month/day/year hour:minute:sec:usec format. 't': print thread id (1 if single-threaded) 'u': print as unsigned int 'W': print out a wide (Unicode) character string (currently Win32 only). 'X', 'x': print as a hex number '%': print out a single percent sign, '%'

    ssize_t log (
        const ASYS_TCHAR *format,
        ACE_Log_Priority priority,
        va_list argp
        );

An alternative logging mechanism that makes it possible to integrate variable argument lists from other logging mechanisms into the ACE mechanism.

    ssize_t log (ACE_Log_Record &log_record, int suppress_stderr = 0);

Log a custom built log record to the currently enabled logging sinks.

    int log_hexdump (
        ACE_Log_Priority log_priority,
        const char *buffer,
        int size,
        const ASYS_TCHAR *text = 0
        );

Method to log hex dump. This is useful for debugging. Calls `log` to do the actual print, but formats first to make the chars printable.

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## The following fields are *not* kept in thread-specific storage.

We only want one instance for the entire process!

    static u_long process_priority_mask_;

Keeps track of all the per-process `ACE_Log_Priority` values that are currently enabled. Default is for all logging priorities to be enabled.

    static const ASYS_TCHAR *program_name_;

Records the program name.

    static const ASYS_TCHAR *local_host_;

Name of the local host (used when printing messages).

    static pid_t pid_;

Process id of the current process.

    static u_long flags_;

Options flags.

    static int msg_off_;

Offset of msg_[].

    static int instance_count_;

Number of existing Log_Msg instances; when 0, delete program/host names

    static u_long default_priority_mask_;

Priority mask to use for each new instance

    static void close (void);

For cleanup, at program termination.

    friend void ACE_OS::cleanup_tss (const u_int);

## Disallow these operations.

    ACE_Log_Msg &operator= (const ACE_Log_Msg &);

    ACE_Log_Msg (const ACE_Log_Msg &);

## AUTHOR

Doug Schmidt

## LIBRARY

ace