Cosm API - Log File Functions

[Cosm Logo]

Log File Functions

v3LogOpen
v3Log
v3LogClose

v3LogOpen

Syntax

#include "log.h"
s32 v3LogOpen( v3_LOG * log, ascii * filename, u32 max_level,
  u32 mode );

Description

Initialize the log, setting the filename, max_level, and mode. If V3_LOG_MODE_NUMBER then log any message with an equal or lower level than max_level. If V3_LOG_MODE_BITS then log any message with it's level matching a bit in max_level. Initializing a log with a NULL filename or invalid mode causes failure.

Log modes:

V3_LOG_MODE_NUMBER: Log any message with an equal or lower level than max_level.
V3_LOG_MODE_BITS: Log any message with it's level matching a bit in max_level.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_LOG_ERROR_MODE: The specified mode is invalid.
V3_LOG_ERROR_NAME: The specified filename is invalid.
V3_LOG_ERROR_INIT: log is invalid.
V3_LOG_ERROR_ACCESS: Unable to get write access to the log file.

Example

  v3_LOG log;
  s32 result;

  v3MemSet( &log, v3u64u32( sizeof( v3_LOG ) ), 0 );

  result = v3LogOpen( &log, "/var/log/cosmlog", 5,
    V3_LOG_MODE_NUMBER );

  if ( result == V3_PASS )
  {
    v3PrintA( "Log file /var/log/cosmlog initialized.\n" );
  }
  else
  {
    v3PrintA( "Unable to open /var/log/cosmlog.\n" );
  }

v3Log

Syntax

#include "log.h"
s32 v3Log( v3_LOG * log, u32 level, u32 echo,
  const ascii * format, ... );

Description

Write the formatted string to the log. See v3PrintA for format info. The string will be logged only if the level is acceptable to the open log. Level 0 will always be logged. If echo is V3_LOG_ECHO and the level passes then the string will also be printed to the standard output device. Otherwise if level does not pass or echo is V3_LOG_NOECHO nothing will be printed.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_LOG_ERROR_INIT: The log file wasn't initialized using v3LogOpen.
V3_LOG_ERROR_ACCESS: Unable to get write access to the log file.

Example

  v3_LOG log;

  v3MemSet( &log, v3u64u32( sizeof( v3_LOG ) ), 0 );

  v3LogOpen( &log, (ascii *) "file.log", 5, V3_LOG_MODE_NUMBER );
  /* check for errors */

  v3Log( &log, 3, V3_LOG_NOECHO, (ascii *)
    "This is logged. 3 is less than 5.\n" );
  v3Log( &log, 8, V3_LOG_NOECHO, (ascii *)
    "This is not logged. 8 is greater than 5.\n" );

  v3LogClose( &log );

  v3LogOpen( &log, (ascii *) "file.log", 0x55, V3_LOG_MODE_BITS );
  /* check for errors */

  v3Log( &log, 0x03, V3_LOG_NOECHO, (ascii *)
    "This is logged. ( 0x03 & 0x55 ) != 0.\n" );
  v3Log( &log, 0x08, V3_LOG_NOECHO, (ascii *)
    "This is not logged. ( 0x08 & 0x55 ) == 0.\n" );
  v3Log( &log, 0x00, V3_LOG_NOECHO, (ascii *)
    "This is logged. Level 0 is ALWAYS logged.\n" );

  v3LogClose( &log );

v3LogClose

Syntax

#include "log.h"
s32 v3LogClose( v3_LOG * log );

Description

Close the log.

Return Values

V3_PASS on success.

Errors

None.

Example

  v3_LOG log;

  v3MemSet( &log, v3u64u32( sizeof( v3_LOG ) ), 0 );

  /* ... */

  v3LogClose( &log );