Genivia Home Documentation
Debugging and logging

updated Fri Oct 16 2020 by Robert van Engelen
 
Debugging and logging

This module defines compile-time flags and functions for run-time debugging and logging. More...

Macros

#define DEBUG
 User-definable macro to enable debugging and logging. More...
 
#define SOAP_DEBUG
 User-definable macro, identical behavior as DEBUG but more portable. More...
 
#define DEBUG_STAMP
 User-definable macro to enable debugging and logging with time stamps. More...
 
#define SOAP_MEM_DEBUG
 User-definable macro to enable memory debugging without logging. More...
 

Functions

void soap_set_recv_logfile (struct soap *soap, const char *logfile)
 Specify a file name to save messages received. More...
 
void soap_set_sent_logfile (struct soap *soap, const char *logfile)
 Specify a file name to save messages sent. More...
 
void soap_set_test_logfile (struct soap *soap, const char *logfile)
 Specify a file name to save debugging info. More...
 
void soap_set_logging_inbound (struct soap *soap, FILE *fd)
 Specify inbound message logging with the logging plugin. More...
 
void soap_set_logging_outbound (struct soap *soap, FILE *fd)
 Specify outbound message logging with the logging plugin. More...
 
void soap_logging_stats (struct soap *soap, size_t *sent, size_t *recv)
 Collect messaging statistics with the logging plugin. More...
 
void soap_reset_logging_stats (struct soap *soap)
 Reset messaging statistics with the logging plugin. More...
 
int logging (struct soap *, struct soap_plugin *, void *)
 The logging plugin registration function. More...
 

Detailed Description

This module defines compile-time flags and functions for run-time debugging and logging.

This module defines the following compile-time flags and functions to specify log files:

Alternatively, the logging plugin can be used without setting DEBUG to efficiently log messages and collect statistics:

Macro Definition Documentation

#define DEBUG

User-definable macro to enable debugging and logging.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to produce RECV.log, SENT.log, and TEST.log files for debugging purposes:

  • RECV.log contains messages received, concatenated
  • SENT.log contains messages sent, concatenated
  • TEST.log contains debugging information to identify issues Debugging with DEBUG incurs significant run-time overhead and should only be used for debugging purposes.
Example:
c++ -D DEBUG -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
RECV.log SENT.log TEST.log
See also
SOAP_DEBUG, DEBUG_STAMP, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.
Note
The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with DEBUG, because these libraries are built by default without debugging enabled. Use ./configure --enable-debug to rebuild the libraries with -D DEBUG.
#define DEBUG_STAMP

User-definable macro to enable debugging and logging with time stamps.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to produce RECV.log, SENT.log, and TEST.log files with time stamps for debugging purposes:

  • RECV.log contains messages received, concatenated
  • SENT.log contains messages sent, concatenated
  • TEST.log contains debugging information with time stamps to identify issues This incurs significant run-time overhead and should only be used for debugging purposes.
Example:
c++ -D DEBUG_STAMP -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
RECV.log SENT.log TEST.log
See also
DEBUG, SOAP_DEBUG, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.
Note
The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with DEBUG_STAMP, because these libraries are built by default without debugging enabled.
#define SOAP_DEBUG

User-definable macro, identical behavior as DEBUG but more portable.

This macro should be used when the DEBUG macro is reserved by the IDE for other purposes.

See also
DEBUG, DEBUG_STAMP, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile.
#define SOAP_MEM_DEBUG

User-definable macro to enable memory debugging without logging.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to detect memory corruption errors but does not produce RECV.log, SENT.log and TEST.log files and avoids the significant run-time overhead of logging. Use this macro when memory debugging is required without logging overhead.

Example:
c++ -D SOAP_MEM_DEBUG -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
ls: No match.
See also
DEBUG, SOAP_DEBUG, DEBUG_STAMP.
Note
The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with SOAP_MEM_DEBUG, because these libraries are built by default without debugging enabled.

Function Documentation

int logging ( struct soap ,
struct soap_plugin *  ,
void *   
)

The logging plugin registration function.

The logging plugin API is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c.

See also
soap_set_logging_inbound, soap_set_logging_outbound, soap_logging_stats, soap_reset_logging_stats.
void soap_logging_stats ( struct soap soap,
size_t *  sent,
size_t *  recv 
)

Collect messaging statistics with the logging plugin.

This function collects the recorded messaging statistics, namely the number of bytes received from inbound messages and the number of bytes sent to outbound messages.

Example:
#include "soapH.h"
#include "plugin/logging.h"
struct soap *soap = soap_new();
... // send and receive messages
size_t sent, recv;
soap_logging_stats(soap, &sent, &recv);
printf("Bytes sent = %zu bytes received = %zu\n", sent, recv);
Note
This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.
See also
soap_set_logging_inbound, soap_set_logging_outbound, soap_reset_logging_stats.
Parameters
soapsoap context
sentpointer to variable to assign
recvpointer to variable to assign
void soap_reset_logging_stats ( struct soap soap)

Reset messaging statistics with the logging plugin.

This function resets the recorded messaging statistics.

Note
This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.
See also
soap_set_logging_inbound, soap_set_logging_outbound, soap_logging_stats.
Parameters
soapsoap context
void soap_set_logging_inbound ( struct soap soap,
FILE *  fd 
)

Specify inbound message logging with the logging plugin.

This function enables inbound message logging. Inbound messages are recorded to the specified file descriptor. Logging is disabled by passing a NULL file descriptor parameter.

Example:
#include "soapH.h"
#include "plugin/logging.h"
struct soap *soap = soap_new();
FILE *fd = fopen("logs/recv.log", "w");
... // send and receive messages
fclose(fd);
Note
This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.
See also
soap_set_logging_outbound, soap_logging_stats, soap_reset_logging_stats.
Parameters
soapsoap context
fdfile descriptor to record inbound messages
void soap_set_logging_outbound ( struct soap soap,
FILE *  fd 
)

Specify outbound message logging with the logging plugin.

This function enables outbound message logging. Outbound messages are recorded to the specified file descriptor. Logging is disabled by passing a NULL file descriptor parameter.

Example:
#include "soapH.h"
#include "plugin/logging.h"
struct soap *soap = soap_new();
FILE *fd = fopen("logs/sent.log", "w");
... // send and receive messages
fclose(fd);
Note
This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.
See also
soap_set_logging_inbound, soap_logging_stats, soap_reset_logging_stats.
Parameters
soapsoap context
fdfile descriptor to record outbound messages
void soap_set_recv_logfile ( struct soap soap,
const char *  logfile 
)

Specify a file name to save messages received.

This function sets the specified file path name logfile to save all messages received. Messages are appended to the specified file. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:
#include "soapH.h"
struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");
Note
Requires compilation with DEBUG.
See also
soap_set_sent_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.
Parameters
soapsoap context
logfilepath name of the log file or NULL to disable logging
void soap_set_sent_logfile ( struct soap soap,
const char *  logfile 
)

Specify a file name to save messages sent.

This function sets the specified file path name logfile to save the messages sent. Messages are appended to the specified file. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:
#include "soapH.h"
struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");
Note
Requires compilation with DEBUG.
See also
soap_set_recv_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.
Parameters
soapsoap context
logfilepath name of the log file or NULL to disable logging
void soap_set_test_logfile ( struct soap soap,
const char *  logfile 
)

Specify a file name to save debugging info.

This function sets the specified file path name logfile to save debugging info generated by the engine and by the generated code. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:
#include "soapH.h"
struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");
Note
Requires compilation with DEBUG.
Parameters
soapsoap context
logfilepath name of the log file or NULL to disable logging