|  | Home | Documentation | Debugging and logging updated Sat Sep 23 2023 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Macros | Functions
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:

- `DEBUG`
- `SOAP_DEBUG`
- `DEBUG_STAMP`
- `SOAP_MEM_DEBUG`
- `soap_set_recv_logfile`
- `soap_set_sent_logfile`
- `soap_set_test_logfile`

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

- `soap_set_logging_inbound`
- `soap_set_logging_outbound`
- `soap_logging_stats`
- `soap_reset_logging_stats`

## 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();
soap_register_plugin(soap, logging);
... // send and receive messages
size_t sent, recv;
soap_logging_stats(soap, &sent, &recv);
printf("Bytes sent = %zu bytes received = %zu\n", sent, recv);
soap_reset_logging_stats(soap);

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

  soap | `soap` context
  sent | pointer to variable to assign
  recv | pointer 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

  soap | `soap` 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");
soap_register_plugin(soap, logging);
soap_set_logging_inbound(soap, fd);
... // send and receive messages
soap_set_logging_inbound(soap, NULL);
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

  soap | `soap` context
  fd | file 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");
soap_register_plugin(soap, logging);
soap_set_logging_outbound(soap, fd);
... // send and receive messages
soap_set_logging_outbound(soap, NULL);
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

  soap | `soap` context
  fd | file 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

  soap | `soap` context
  logfile | path 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

  soap | `soap` context
  logfile | path 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

  soap | `soap` context
  logfile | path name of the log file or NULL to disable logging