debug.h File Reference

General purpose debugging routines. More...

`#include "int_sizes.h"`
`#include <unistd.h>`
`#include <sys/types.h>`
`#include <stdarg.h>`
`#include <stdio.h>`

Go to the source code of this file.

## Macros

#define | D_INFO (0LL)
| Indicates a message that is of general interest to the user.
#define | D_FATAL (1LL<<0)
| Indicates a message that is fatal.
#define | D_ERROR (1LL<<1)
| Indicates a message that is a warning/error.
#define | D_NOTICE (1LL<<2)
| Indicates a message that is always shown.
#define | D_DEBUG (1LL<<3)
| Indicates a general debugging message.
#define | D_SYSCALL (1LL<<4)
| Debug system calls in Parrot.
#define | D_CHANNEL (1LL<<5)
| Debug the I/O channel in Parrot.
#define | D_PROCESS (1LL<<6)
| Debug jobs and process.
#define | D_RESOLVE (1LL<<7)
| Debug the file name resolver in Parrot.
#define | D_LIBCALL (1LL<<8)
| Debug I/O library calls in Parrot.
#define | D_LOCAL (1LL<<9)
| Debug the local I/O module in Parrot.
#define | D_DNS (1LL<<10)
| Debug domain name lookups.
#define | D_TCP (1LL<<11)
| Debug TCP connections and disconnections.
#define | D_AUTH (1LL<<12)
| Debug authentication and authorization actions.
#define | D_IRODS (1LL<<13)
| Debug the iRODS module in Parrot.
#define | D_CVMFS (1LL<<14)
| Debug CVMFS module in Parrot.
#define | D_HTTP (1LL<<15)
| Debug HTTP queries.
#define | D_FTP (1LL<<16)
| Debug FTP operations.
#define | D_NEST (1LL<<17)
| Debug the NEST module in Parrot.
#define | D_GROW (1LL<<18)
| Debug the GROW filesystem in Parrot.
#define | D_CHIRP (1LL<<19)
| Debug Chirp protocol operations.
#define | D_DCAP (1LL<<20)
| Debug the DCAP module in Parrot.
#define | D_RFIO (1LL<<21)
| Debug the RFIO module in Parrot.
#define | D_GLITE (1LL<<22)
| Debug the gLite module in Parrot.
#define | D_MULTI (1LL<<23)
| Debug Chirp Multi filesystems.
#define | D_PSTREE (1LL<<24)
| Debug process trees in Parrot.
#define | D_ALLOC (1LL<<25)
| Debug space allocations in the Chirp server.
#define | D_LFC (1LL<<26)
| Debug LFC file lookups in Parrot.
#define | D_GFAL (1LL<<27)
| Debug the GFAL module in Parrot.
#define | D_SUMMARY (1LL<<28)
| Show I/O summary stats in Parrot.
#define | D_LOGIN (1LL<<29)
| Debug logins on the Chirp server.
#define | D_CACHE (1LL<<30)
| Debug cache operations in Parrot.
#define | D_POLL (1LL<<31)
| Debug FD polling in Parrot.
#define | D_HDFS (1LL<<32)
| Debug the HDFS module in Parrot.
#define | D_WQ (1LL<<33)
| Debug the Work Queue operations.
#define | D_BXGRID (1LL<<34)
| Debug the BXGRID Module in Parrot.
#define | D_USER (1LL<<35)
| Debug custom user application.
#define | D_XROOTD (1LL<<36)
| Debug Xrootd module in Parrot.
#define | D_MPI (1LL<<37)
| Debug MPI module for Makeflow.
#define | D_BATCH (1LL<<38)
| Debug batch_job modules.
#define | D_RMON (1LL<<39)
| Debug resource monitor.
#define | D_MAKEFLOW_RUN (1LL<<40)
| Debug makeflow's dag run.
#define | D_MAKEFLOW_LEXER (1LL<<41)
| Debug makeflow's lexer.
#define | D_MAKEFLOW_PARSER (1LL<<42)
| Debug makeflow's parser.
#define | D_MAKEFLOW_ALLOC (1LL<<43)
| Debug makeflow's alloc.
#define | D_CONFUGA (1LL<<44)
| Debug Confuga Storage Cluster.
#define | D_JX (1LL<<45)
| Debug JX.
#define | D_MAKEFLOW_HOOK (1LL<<46)
| Debug makeflow's hook system.
#define | D_EXT (1LL<<47)
| Debug the ext module in Parrot.
#define | D_VINE (1LL<<48)
| Debug the taskvine service.
#define | D_TLQ (1LL<<49)
| Debug the TLQ service's interactions with CCTools.
#define | D_SSL (1LL<<50)
| Debug the TLQ service's interactions with CCTools.
#define | D_BUCKETING (1LL<<51)
| Debug bucketing algorithms.
#define | D_REMOTE (D_HTTP|D_FTP|D_NEST|D_CHIRP|D_DCAP|D_RFIO|D_LFC|D_GFAL|D_MULTI|D_GROW|D_IRODS|D_HDFS|D_BXGRID|D_XROOTD|D_CVMFS)
| Debug all remote I/O operations.
#define | D_MAKEFLOW (D_MAKEFLOW_RUN|D_MAKEFLOW_LEXER|D_MAKEFLOW_PARSER)
| Debug all makeflow's operations.
#define | D_ALL (~(0LL))
| Show all debugging info.

## Functions

void | debug (int64_t flags, const char *fmt,...) __attribute__((format(printf
| Emit a debugging message.
void void | vdebug (int64_t flags, const char *fmt, va_list args)
| Emit a debugging message.
void | warn (int64_t flags, const char *fmt,...)
| Emit a warning message.
void | fatal (const char *fmt,...)
| Emit a fatal debugging message and terminate with SIGTERM.
void | notice (int64_t flags, const char *fmt,...)
| Emit a notice message.
void | debug_config (const char *name)
| Initialize the debugging system.
void | debug_config_file (const char *file)
| Direct debug output to a file.
void | debug_config_file_size (off_t size)
| Set the maximum debug file size.
int | debug_flags_set (const char *flagname)
| Set debugging flags to enable output.
void | debug_flags_print (FILE *stream)
| Display the available debug flags.
int64_t | debug_flags_clear (void)
| Clear all debugging flags.
void | debug_set_flag_name (int64_t flag, const char *name)
| Set name of flag combination Sets the string value associated with flag.
void | debug_flags_restore (int64_t flags)
| Restore debug flags.
void | debug_rename (const char *suffix)
| Rename debug file with given suffix.
void | debug_reopen (void)
| Reopen the debug stream.
void | debug_close (void)
| Close the debug stream (only for disk files, no stderr or stdout).

## Detailed Description

General purpose debugging routines.

The cctools debugging system is built into all software components. Any code may invoke debug with a printf-style message to log relevant information. Each debug call uses a flag to indicate which subsystem is doing the logging, so that various subsystems may be easily turned on and off. For example, the Chirp subsystem has many statements like this:

    debug(D_CHIRP,"reading file %s from host %s:%d",filename,hostname,port);

The main routine of a program is responsible for calling debug_config, debug_config_file and debug_flags_set to choose what to display and where to send it. By default, nothing is displayed, unless it has the flags D_NOTICE or D_FATAL. For example, a main program might do this:

      debug_config("superprogram");
      debug_config_file("/tmp/myoutputfile");
      debug_flags_set("tcp");
      debug_flags_set("chirp");

## Macro Definition Documentation

## D_INFO

#define D_INFO (0LL)

Indicates a message that is of general interest to the user.

(the default)

## D_FATAL

#define D_FATAL (1LL<<0)

Indicates a message that is fatal.

## D_ERROR

#define D_ERROR (1LL<<1)

Indicates a message that is a warning/error.

## D_NOTICE

#define D_NOTICE (1LL<<2)

Indicates a message that is always shown.

## D_DEBUG

#define D_DEBUG (1LL<<3)

Indicates a general debugging message.

## D_SYSCALL

#define D_SYSCALL (1LL<<4)

Debug system calls in Parrot.

## D_CHANNEL

#define D_CHANNEL (1LL<<5)

Debug the I/O channel in Parrot.

## D_PROCESS

#define D_PROCESS (1LL<<6)

Debug jobs and process.

## D_RESOLVE

#define D_RESOLVE (1LL<<7)

Debug the file name resolver in Parrot.

## D_LIBCALL

#define D_LIBCALL (1LL<<8)

Debug I/O library calls in Parrot.

## D_LOCAL

#define D_LOCAL (1LL<<9)

Debug the local I/O module in Parrot.

## D_DNS

#define D_DNS (1LL<<10)

Debug domain name lookups.

## D_TCP

#define D_TCP (1LL<<11)

Debug TCP connections and disconnections.

## D_AUTH

#define D_AUTH (1LL<<12)

Debug authentication and authorization actions.

## D_IRODS

#define D_IRODS (1LL<<13)

Debug the iRODS module in Parrot.

## D_CVMFS

#define D_CVMFS (1LL<<14)

Debug CVMFS module in Parrot.

## D_HTTP

#define D_HTTP (1LL<<15)

Debug HTTP queries.

## D_FTP

#define D_FTP (1LL<<16)

Debug FTP operations.

## D_NEST

#define D_NEST (1LL<<17)

Debug the NEST module in Parrot.

## D_GROW

#define D_GROW (1LL<<18)

Debug the GROW filesystem in Parrot.

## D_CHIRP

#define D_CHIRP (1LL<<19)

Debug Chirp protocol operations.

## D_DCAP

#define D_DCAP (1LL<<20)

Debug the DCAP module in Parrot.

## D_RFIO

#define D_RFIO (1LL<<21)

Debug the RFIO module in Parrot.

## D_GLITE

#define D_GLITE (1LL<<22)

Debug the gLite module in Parrot.

## D_MULTI

#define D_MULTI (1LL<<23)

Debug Chirp Multi filesystems.

## D_PSTREE

#define D_PSTREE (1LL<<24)

Debug process trees in Parrot.

## D_ALLOC

#define D_ALLOC (1LL<<25)

Debug space allocations in the Chirp server.

## D_LFC

#define D_LFC (1LL<<26)

Debug LFC file lookups in Parrot.

## D_GFAL

#define D_GFAL (1LL<<27)

Debug the GFAL module in Parrot.

## D_SUMMARY

#define D_SUMMARY (1LL<<28)

Show I/O summary stats in Parrot.

## D_LOGIN

#define D_LOGIN (1LL<<29)

Debug logins on the Chirp server.

## D_CACHE

#define D_CACHE (1LL<<30)

Debug cache operations in Parrot.

## D_POLL

#define D_POLL (1LL<<31)

Debug FD polling in Parrot.

## D_HDFS

#define D_HDFS (1LL<<32)

Debug the HDFS module in Parrot.

## D_WQ

#define D_WQ (1LL<<33)

Debug the Work Queue operations.

## D_BXGRID

#define D_BXGRID (1LL<<34)

Debug the BXGRID Module in Parrot.

## D_USER

#define D_USER (1LL<<35)

Debug custom user application.

## D_XROOTD

#define D_XROOTD (1LL<<36)

Debug Xrootd module in Parrot.

## D_MPI

#define D_MPI (1LL<<37)

Debug MPI module for Makeflow.

## D_BATCH

#define D_BATCH (1LL<<38)

Debug batch_job modules.

## D_RMON

#define D_RMON (1LL<<39)

Debug resource monitor.

## D_MAKEFLOW_RUN

#define D_MAKEFLOW_RUN (1LL<<40)

Debug makeflow's dag run.

## D_MAKEFLOW_LEXER

#define D_MAKEFLOW_LEXER (1LL<<41)

Debug makeflow's lexer.

## D_MAKEFLOW_PARSER

#define D_MAKEFLOW_PARSER (1LL<<42)

Debug makeflow's parser.

## D_MAKEFLOW_ALLOC

#define D_MAKEFLOW_ALLOC (1LL<<43)

Debug makeflow's alloc.

## D_CONFUGA

#define D_CONFUGA (1LL<<44)

Debug Confuga Storage Cluster.

## D_JX

#define D_JX (1LL<<45)

Debug JX.

## D_MAKEFLOW_HOOK

#define D_MAKEFLOW_HOOK (1LL<<46)

Debug makeflow's hook system.

## D_EXT

#define D_EXT (1LL<<47)

Debug the ext module in Parrot.

## D_VINE

#define D_VINE (1LL<<48)

Debug the taskvine service.

## D_TLQ

#define D_TLQ (1LL<<49)

Debug the TLQ service's interactions with CCTools.

## D_SSL

#define D_SSL (1LL<<50)

Debug the TLQ service's interactions with CCTools.

## D_BUCKETING

#define D_BUCKETING (1LL<<51)

Debug bucketing algorithms.

## D_REMOTE

#define D_REMOTE (D_HTTP|D_FTP|D_NEST|D_CHIRP|D_DCAP|D_RFIO|D_LFC|D_GFAL|D_MULTI|D_GROW|D_IRODS|D_HDFS|D_BXGRID|D_XROOTD|D_CVMFS)

Debug all remote I/O operations.

## D_MAKEFLOW

#define D_MAKEFLOW (D_MAKEFLOW_RUN|D_MAKEFLOW_LEXER|D_MAKEFLOW_PARSER)

Debug all makeflow's operations.

## D_ALL

#define D_ALL (~(0LL))

Show all debugging info.

## Function Documentation

## debug()

void debug | ( | int64_t | flags,
|  | const char * | fmt,
|  |  | ... )

Emit a debugging message.

Logs a debugging message, if the given flags are active.

Parameters

  flags | Any of the standard debugging flags OR-ed together.
  fmt | A printf-style formatting string, followed by the necessary arguments.

## vdebug()

void void vdebug | ( | int64_t | flags,
|  | const char * | fmt,
|  | va_list | args )

Emit a debugging message.

Logs a debugging message, if the given flags are active, using a va_list instead of a list of arguments.

Parameters

  flags | Any of the standard debugging flags OR-ed together.
  fmt | A printf-style formatting string.
  args | A va_list containing the arguments.

## warn()

void warn | ( | int64_t | flags,
|  | const char * | fmt,
|  |  | ... )

Emit a warning message.

Logs a warning message, regardless of if given flags are active.

Parameters

  flags | Any of the standard debugging flags OR-ed together.
  fmt | A printf-style formatting string, followed by the necessary arguments.

## fatal()

void fatal | ( | const char * | fmt,
|  |  | ... )

Emit a fatal debugging message and terminate with SIGTERM.

Displays a printf-style message, and then forcibly exits the program.

Parameters

  fmt | A printf-style formatting string, followed by the necessary arguments.

## notice()

void notice | ( | int64_t | flags,
|  | const char * | fmt,
|  |  | ... )

Emit a notice message.

Logs a warning message, regardless of if given flags are active.

Parameters

  flags | Any of the standard debugging flags OR-ed together.
  fmt | A printf-style formatting string, followed by the necessary arguments.

## debug_config()

void debug_config | ( | const char * | name | ) |

Initialize the debugging system.

Must be called before any other calls take place.

Parameters

  name | The name of the program to use in debug output.

## debug_config_file()

void debug_config_file | ( | const char * | file | ) |

Direct debug output to a file.

All enabled debugging statements will be sent to this file.

Parameters

  file | The pathname of the file for output.

See also
  debug_config_file_size

## debug_config_file_size()

void debug_config_file_size | ( | off_t | size | ) |

Set the maximum debug file size.

Debugging files can very quickly become large and fill up your available disk space. This functions sets the maximum size of a debug file. When it exceeds this size, it will be renamed to (file).old, and a new file will be started.

Parameters

  size | Maximum size in bytes of the debugging file.

## debug_flags_set()

int debug_flags_set | ( | const char * | flagname | ) |

Set debugging flags to enable output.

Accepts a debug flag in ASCII form, and enables that subsystem. For example: debug_flags_set("chirp"); Typically used in command-line processing in main.

Parameters

  flagname | The name of the debugging flag to enable.

Returns
  One if the flag is valid, zero otherwise.

See also
  debug_flags_print, debug_flags_clear

## debug_flags_print()

void debug_flags_print | ( | FILE * | stream | ) |

Display the available debug flags.

Prints on the standard output all possible debug flag names that can be passed to debug_flags_set. Useful for constructing a program help text.

Parameters

  stream | Standard I/O stream on which to print the output.

## debug_flags_clear()

int64_t debug_flags_clear | ( | void |  | ) |

Clear all debugging flags.

Clear all currently set flags, so that no output will occur.

See also
  debug_flags_set

## debug_set_flag_name()

void debug_set_flag_name | ( | int64_t | flag,
|  | const char * | name )

Set name of flag combination Sets the string value associated with flag.

This is normally used to set the D_USER user flag as so: debug_set_flag_name(D_USER, "my-application");.

Parameters

  flag | Any of the standard debugging flags.
  name | New name to associate with flag.

## debug_flags_restore()

void debug_flags_restore | ( | int64_t | flags | ) |

Restore debug flags.

Parameters

  flags | flags to set

## debug_rename()

void debug_rename | ( | const char * | suffix | ) |

Rename debug file with given suffix.

Parameters

  suffix | Suffix of saved log.

## debug_reopen()

void debug_reopen | ( | void |  | ) |

Reopen the debug stream.

## debug_close()

void debug_close | ( | void |  | ) |

Close the debug stream (only for disk files, no stderr or stdout).