slog2_register()

#include <slog2.h>

int slog2_register( slog2_buffer_set_config_t *config,
                    slog2_buffer_t *handles,
                    uint32_t flags );

Since:

BlackBerry 10.0.0

Arguments:

config

A pointer to a slog2 buffer configuration object; see below.

handles

An array that the function fills with opaque handles for the buffers it allocates. The number of entries must be at least the value of the num_buffers member of the config structure.

flags

A bitwise OR of options for buffer management. No flags are currently defined; pass 0 for this argument.

Library:

libslog2

Use the -l slog2 option to qcc to link against this library.

Description:

The slog2_register() function register a new instance of a slog2 buffer set. Each buffer set contains one or more buffers; specify the size of each buffer as a multiple of 4 KB pages. The maximum number of buffers is specified by SLOG2_MAX_BUFFERS.

slog2_buffer_set_config_t and slog2_buffer_config_t structures

The slog2_buffer_config_t structure contains the configuration data for a single slog2 buffer:

typedef struct
{
    const char    *buffer_name;
    int            num_pages;
} slog2_buffer_config_t;

The fields include:

buffer_name

The name you want to use for the buffer.

num_pages

The number of 4 KB pages this buffer contains.

The slog2_buffer_set_config_t structure contains the configuration data for a slog2 buffer set. Each buffer set contains one or more buffers; the maximum number of buffers is specified by SLOG2_MAX_BUFFERS.

typedef struct
{
    int                   num_buffers;
    const char           *buffer_set_name;
    _Uint8t               verbosity_level;
    slog2_buffer_config_t buffer_config[ SLOG2_MAX_BUFFERS ];
} slog2_buffer_set_config_t;

num_buffers

The number of buffers to configure.

buffer_set_name

The process name, or other descriptor. We recommend that you use the name of your process for this.

verbosity_level

The minimum severity to log; one of:

• SLOG2_SHUTDOWN — shut down the system now (e.g., for OEM use).
• SLOG2_CRITICAL — unexpected unrecoverable error (e.g., hard disk error).
• SLOG2_ERROR — unexpected recoverable error (e.g., you need to reset a hardware controller).
• SLOG2_WARNING — expected error (e.g., parity error on a serial port).
• SLOG2_NOTICE — warning (e.g., out of paper).
• SLOG2_INFO — information (e.g., printing page 3).
• SLOG2_DEBUG1 — debug messages (e.g., normal detail).
• SLOG2_DEBUG2 — debug messages (e.g., fine detail).

All buffers in the set have the same level of verbosity.

buffer_config

An array of slog2_buffer_config_t structures that define the buffers.

Returns:

0

Success.

-1

An error occurred. The handle data isn't guaranteed.

#include <stdio.h>
#include <stdlib.h>
#include <slog2.h>
 
/* Pull in the executable name.  argv[0] causes problems, so don't use it! */
extern char *__progname;
 
int main(int argc, char **argv)
{
    slog2_buffer_set_config_t   buffer_config;
    slog2_buffer_t              buffer_handle[2];
 
    /* A local variable used to demonstrate the slog2fa() API call below. */
    int                         some_number = 5108;
 
    /* You should use the name of your process to name the buffer set. */
    buffer_config.buffer_set_name = __progname;
 
    /* These two buffers are configured below. */
    buffer_config.num_buffers = 2;
 
    /* Request an initial verbosity level.
      
       We recommend that all components use SLOG2_INFO as the default verbosity level, then
       use SLOG2_DEBUG1 and SLOG2_DEBUG2 for higher levels of verbosity for in-depth investigations
       performed by developers or testers.
      
       All buffers within the set share the same verbosity level.
    */
      
    buffer_config.verbosity_level = SLOG2_INFO;
 
    /* !! NOTE: Please use a maximum of 32KB for the total of all your individual buffers !! */
 
    /* Configure the first buffer, using 7 x 4KB pages.  This larger buffer will be used for
       very chatty logging.  Our goal is to have 30-60 seconds of history at any given time,
       so we will want to log at a rate of around one log line with a string of 16 bytes
       long every 150 milliseconds.
    */

    buffer_config.buffer_config[0].buffer_name = "hi_rate_logging";
    buffer_config.buffer_config[0].num_pages = 7;
 
    /* Configure the second buffer, which we will use for high level info logging that is very
       infrequent, but we want a longer history (hours or maybe even over a day or two).  This
       buffer uses 1 x 4KB.
    */

    buffer_config.buffer_config[1].buffer_name = "lo_rate_logging";
    buffer_config.buffer_config[1].num_pages = 1;
 
    /* Register the buffer set. */

    if( -1 == slog2_register( &buffer_config, buffer_handle, 0 ) ) {
        fprintf( stderr, "Error registering slogger2 buffer!\n" );
        return -1;
    }
 
    /* slog2f()
       - is the SLOWEST (though most convenient) of the slog2 APIs
       - CANNOT be used with interrupts off because va_args handling could use interrupts
    */

    slog2f( buffer_handle[0], 0, SLOG2_INFO,
        "Writing a formatted string into the buffer: %s", argv[0] );
 
    /* slog2c()
       - is the FASTEST slog2 API
       - is interrupt safe
    */

    slog2c( buffer_handle[0], 0, SLOG2_INFO,
        "Writing a constant string into the buffer." );
 
   /* slog2fa()
      - provides a VERY FAST and INTERRUPT SAFE alternative to slog2f()
      - uses special formatting macros to ensure that va_args does NOT trigger interrupt use
   */

   slog2fa( buffer_handle[0], 0, SLOG2_WARNING, "string:%s, some_number:%d",
                                              SLOG2_FA_STRING( "Hello world" ),
                                              SLOG2_FA_SIGNED( some_number ),
                                              SLOG2_FA_END );
 
    /* Write something to the 'lo rate' buffer (i.e., buffer 1). */
    slog2c( buffer_handle[1], 0, SLOG2_NOTICE,
        "This string will be logged." );
 
    /* The verbosity level will prevent this from being written to the slog2 buffer
       (severity > verbosity_level). */

    slog2c( buffer_handle[0], 0, SLOG2_DEBUG1,
        "This string should not be logged." );
 
    return 0;
}

Classification:

QNX Neutrino