|  | Home | Documentation | Debugging and logging updated Sat Apr 25 2026 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Macros | Functions
Debugging and logging

This module describes 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, enables `DEBUG` mode for runtime debug logs, but without enabling `SOAP_MEM_DEBUG` memory debugging. 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 `SOAP_DEBUG` 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 describes compile-time flags and functions for run-time debugging and logging.

This module describes 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, enables `DEBUG` mode for runtime debug logs, but without enabling `SOAP_MEM_DEBUG` memory debugging.

This macro can 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 `SOAP_DEBUG` 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