trace.h File Reference

Tracing facility APIs. More...


Defines

#define TRACE_ALL   0x7F00
 Trace all types.
#define TRACE_LOG   0x8000
 Set if logging should be done.
#define TRACE_MASK   0xff00
 Extract TRACE_xx from LOG_xx.
#define TRACE_SHIFT   8
 Shift TRACE_xx down to low order.
#define TRACE_ALL_BITS   0xffffffff
#define TRACE_NSEC_PER_MSEC   1000
#define TRACE_LOG_DEBUG   (TRACE_ALL | TRACE_LOG | LOG_DEBUG)
#define TRACE_LOG_INFO   (TRACE_ALL | TRACE_LOG | LOG_INFO)
#define TRACE_LOG_NOTICE   (TRACE_ALL | TRACE_LOG | LOG_NOTICE)
#define TRACE_LOG_WARNING   (TRACE_ALL | TRACE_LOG | LOG_WARNING)
#define TRACE_LOG_ERR   (TRACE_ALL | TRACE_LOG | LOG_ERR)
#define TRACE_LOG_CRITICAL   (TRACE_ALL | TRACE_LOG | LOG_CRIT)
#define TRACE_LOG_EMERG   (TRACE_ALL | TRACE_LOG | LOG_EMERG)
#define TRACE_LOG_CONFLICT   (TRACE_ALL | TRACE_LOG | LOG_CONFLICT)
#define TRACE_AUX_FLAG_MSEC   (1<<0)
 Log milliseconds.
#define TRACE_AUX_FLAG_NOCOMPRESS   (1<<1)
 Do not compress log files.

Typedefs

typedef trace_file_s trace_file_t

Functions

trace_file_t * trace_file_open (trace_file_t *tp, const char *file_name, u_int32_t file_size, u_int32_t file_count)
 Opens a trace file.
trace_file_t * trace_file_open_buffered (trace_file_t *tp, const char *file_name, u_int32_t file_size, u_int32_t file_count, char *stream_buffer, int stream_buffer_size)
 Opens a fully buffered trace file.
void trace_file_close (trace_file_t *tp)
 Closes a trace file and free the trace_file_t.
void tracev (trace_file_t *tp, u_int32_t type, const char *fmt, va_list ap)
 Issues a trace message.
void tracev_event (trace_file_t *tp, u_int32_t type, const char *tag, const char **entry, const char *fmt, va_list ap)
 TODO.
void trace (trace_file_t *tp, u_int32_t type, const char *fmt,...)
 Possibly issue a trace message, depending on if the specified trace flag is enabled.
void trace_event (trace_file_t *tp, u_int32_t type, const char *tag, const char **entry, const char *fmt,...)
 TODO.
void trace_flag_set (trace_file_t *tp, u_int32_t flag)
 Enables the specified trace flag for tracing.
void trace_flag_clear (trace_file_t *tp, u_int32_t flag)
 Disables the specified trace flag.
void trace_aux_flags_set (trace_file_t *tp, u_int32_t flags)
 Sets the aux flags to the specified value.
u_int32_t trace_flag_is_set (trace_file_t *tp, u_int32_t flag)
 Determines if a particular trace flag is set.
bool trace_flags_are_set (trace_file_t *tp)
 Determines if any trace flag is set.
int trace_set_file_perms (trace_file_t *tp, mode_t mode)
 Sets the trace file permissions per mode.
int trace_fileno (trace_file_t *tp)
 Returns the descriptor for the trace file.
void trace_file_flush (trace_file_t *tp)
 Flushes buffered output to the trace file.
int trace_set_file_match (trace_file_t *tp, char *regex)
 Sets the match regex filter for the trace file.
char * trace_format_msg (trace_file_t *traceptr, int *msg_len, const char *fmt, va_list ap)
 Format the trace message.
char * trace_format_msg_r (trace_file_t *traceptr, char *trace_buffer, int *msg_len, const char *fmt, va_list ap)
 Format the trace message and return the pointer to the formatted string.


Detailed Description

Tracing facility APIs.


Function Documentation

void trace trace_file_t *  tp,
u_int32_t  type,
const char *  fmt,
  ...
 

Possibly issue a trace message, depending on if the specified trace flag is enabled.

The trace flag may be 'or'ed with TRACE_LOG if the message should be syslogged as well as traced. If this is set, the trace flag should also be 'or'ed with the desired LOG_xxx value. If the specified trace flag is enabled, the trace message is formatted with a timestamp prepended, and written to the file (if the file has been opened), and possibly written to the syslog (if TRACE_LOG is included).

Parameters:
[in] tp Pointer to a trace file
[in] type A TRACE_xxx constant
[in] fmt A printf-like format string

void trace_aux_flags_set trace_file_t *  tp,
u_int32_t  flags
 

Sets the aux flags to the specified value.

Note that we don't use set/clear primitives here; the caller needs to define all the flags desired.

Parameters:
[in] tp Pointer to a trace file
[in] flags The new trace flag value

void trace_event trace_file_t *  tp,
u_int32_t  type,
const char *  tag,
const char **  entry,
const char *  fmt,
  ...
 

TODO.

Parameters:
[in] tp Pointer to a trace file
[in] type A TRACE_xxx constant
[in] tag 
[in] entry 
[in] fmt Format string

void trace_file_close trace_file_t *  tp  ) 
 

Closes a trace file and free the trace_file_t.

Parameters:
[in] tp Pointer to a trace file

void trace_file_flush trace_file_t *  tp  ) 
 

Flushes buffered output to the trace file.

Parameters:
[in] tp Pointer to a trace file

trace_file_t* trace_file_open trace_file_t *  tp,
const char *  file_name,
u_int32_t  file_size,
u_int32_t  file_count
 

Opens a trace file.

The max file size is specified by file_size, and the max number of files by file_count. As the file fills, it is rotated out; file.0 is the second newest, file.1 is the next older, etc.

If no file is opened, tracing can still be done to syslog but will not be saved in a file.

The trace_file_t * returned by trace_file_open must be passed to all other trace functions that log to this file.

If tp is NULL, file_name will be used for the trace file. Otherwise, if file_name is NULL but tp is non-null, trace_file_open() will reuse the file name in tp (after closing and freeing the current trace file).

Parameters:
[in] tp Pointer to the previous trace file
[in] file_name The name of the new trace file to open
[in] file_size Maximum size of the trace file
[in] file_count 
Returns:
A pointer to a new trace file structure. If both tp and file_name are NULL, this function returns NULL.

trace_file_t* trace_file_open_buffered trace_file_t *  tp,
const char *  file_name,
u_int32_t  file_size,
u_int32_t  file_count,
char *  stream_buffer,
int  stream_buffer_size
 

Opens a fully buffered trace file.

This function behave exactly like trace_file_open(), with the exception that when a buffer is supplied to it, it is used to fully buffer the trace file stream

Parameters:
[in] tp Pointer to the previous trace file
[in] file_name The name of the new trace file to open
[in] file_size Maximum size of the trace file
[in] file_count 
[in] stream_buffer The buffer to be used as a stream buffer for the trace file
[in] stream_buffer_size The size of the supplied stream buffer
Returns:
A pointer to a new trace file structure. If both tp and file_name are NULL, this function returns NULL.

int trace_fileno trace_file_t *  tp  ) 
 

Returns the descriptor for the trace file.

Parameters:
[in] tp Pointer to a trace file

void trace_flag_clear trace_file_t *  tp,
u_int32_t  flag
 

Disables the specified trace flag.

Clearing TRACE_ALL will disable all trace flags.

Parameters:
[in] tp Pointer to a trace file
[in] flag The trace flag to clear

u_int32_t trace_flag_is_set trace_file_t *  tp,
u_int32_t  flag
 

Determines if a particular trace flag is set.

Parameters:
[in] tp Pointer to a trace file
[in] flag Flag to check the status of
Returns:
TRUE if the specified trace flag is enabled.

void trace_flag_set trace_file_t *  tp,
u_int32_t  flag
 

Enables the specified trace flag for tracing.

Setting TRACE_ALL will enable all trace flags.

Parameters:
[in] tp Pointer to a trace file
[in] flag The trace flag to set

bool trace_flags_are_set trace_file_t *  tp  ) 
 

Determines if any trace flag is set.

Parameters:
[in] tp Pointer to a trace file
Returns:
true if any trace flag is enabled; false otherwise.

char* trace_format_msg trace_file_t *  traceptr,
int *  msg_len,
const char *  fmt,
va_list  ap
 

Format the trace message.

Format the trace message and return the pointer to the formatted string

Note:
This API is not reentrant.
Parameters:
[in] tp Pointer to a trace file
[in] msg_len Stores the length of the returned string here
[in] fmt Format string
[in] ap Variable-length argument list
Returns:
The pointer to the formatted string
See also:
trace_format_msg_r

char* trace_format_msg_r trace_file_t *  traceptr,
char *  trace_buffer,
int *  msg_len,
const char *  fmt,
va_list  ap
 

Format the trace message and return the pointer to the formatted string.

Parameters:
[in] traceptr Pointer to a trace file
[in] trace_buffer Pointer to a trace buffer. The caller has to provide a buffer.
[in] msg_len Stores the length of the returned string here
[in] fmt Format string
[in] ap Variable-length argument list
Returns:
The pointer to the formatted string
See also:
trace_format_msg

int trace_set_file_match trace_file_t *  tp,
char *  regex
 

Sets the match regex filter for the trace file.

The trace function will log message only if it matches this regular-expression.

Parameters:
[in] tp Pointer to a trace file
[in] regex Regular expression to match
Returns:
The return value of this function is 0.

int trace_set_file_perms trace_file_t *  tp,
mode_t  mode
 

Sets the trace file permissions per mode.

mode indicates the permissions to be used (a la creat(2)/chmod(2)).

Parameters:
[in] tp Pointer to a trace file
[in] mode Permission mode to be used
Returns:
0 on success; -1 on failure

void tracev trace_file_t *  tp,
u_int32_t  type,
const char *  fmt,
va_list  ap
 

Issues a trace message.

If a logging level is set in type the message is sent to syslog as well.

If called with tp set to NULL, trace() will log the message to syslog if TRACE_LOG is included in type.

Parameters:
[in] tp Pointer to a trace file
[in] type A TRACE_xxx constant
[in] fmt Format string
[in] ap Variable-length argument list

void tracev_event trace_file_t *  tp,
u_int32_t  type,
const char *  tag,
const char **  entry,
const char *  fmt,
va_list  ap
 

TODO.

Parameters:
[in] tp Pointer to a trace file
[in] type A TRACE_xxx constant
[in] tag 
[in] entry 
[in] fmt Format string
[in] ap Variable-length argument list


2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:23:40 2010 for libjuniper by Doxygen 1.4.5