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

Functions

void debug (INT64_T flags, const char *fmt,...) __attribute__((format(printf
 Emit a debugging message. More...
 
void void vdebug (INT64_T flags, const char *fmt, va_list args)
 Emit a debugging message. More...
 
void warn (INT64_T flags, const char *fmt,...)
 Emit a warning message. More...
 
void fatal (const char *fmt,...)
 Emit a fatal debugging message and terminate with SIGTERM. More...
 
void notice (INT64_T flags, const char *fmt,...)
 Emit a notice message. More...
 
void debug_config (const char *name)
 Initialize the debugging system. More...
 
void debug_config_file (const char *file)
 Direct debug output to a file. More...
 
void debug_config_file_size (off_t size)
 Set the maximum debug file size. More...
 
int debug_flags_set (const char *flagname)
 Set debugging flags to enable output. More...
 
void debug_flags_print (FILE *stream)
 Display the available debug flags. More...
 
INT64_T debug_flags_clear (void)
 Clear all debugging flags. More...
 
void debug_set_flag_name (INT64_T flag, const char *name)
 
Set name of flag combination

Sets the string value associated with flag. More...

 
void debug_flags_restore (INT64_T flags)
 Restore debug flags. More...
 
void debug_rename (const char *suffix)
 Rename debug file with given suffix. More...
 
void debug_reopen (void)
 Reopen the debug stream. More...
 

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

#define D_INFO   (0LL)

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

(the default)

#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.

Debug all remote I/O operations.

Debug all makeflow's operations.

#define D_ALL   (~(0LL))

Show all debugging info.

Function Documentation

void debug ( INT64_T  flags,
const char *  fmt,
  ... 
)

Emit a debugging message.

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

Parameters
flagsAny of the standard debugging flags OR-ed together.
fmtA printf-style formatting string, followed by the necessary arguments.
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
flagsAny of the standard debugging flags OR-ed together.
fmtA printf-style formatting string.
argsA va_list containing the arguments.
void warn ( INT64_T  flags,
const char *  fmt,
  ... 
)

Emit a warning message.

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

Parameters
flagsAny of the standard debugging flags OR-ed together.
fmtA printf-style formatting string, followed by the necessary arguments.
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
fmtA printf-style formatting string, followed by the necessary arguments.
void notice ( INT64_T  flags,
const char *  fmt,
  ... 
)

Emit a notice message.

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

Parameters
flagsAny of the standard debugging flags OR-ed together.
fmtA printf-style formatting string, followed by the necessary arguments.
void debug_config ( const char *  name)

Initialize the debugging system.

Must be called before any other calls take place.

Parameters
nameThe name of the program to use in debug output.
void debug_config_file ( const char *  file)

Direct debug output to a file.

All enabled debugging statements will be sent to this file.

Parameters
fileThe pathname of the file for output.
See Also
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
sizeMaximum size in bytes of the debugging file.
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
flagnameThe name of the debugging flag to enable.
Returns
One if the flag is valid, zero otherwise.
See Also
debug_flags_print, debug_flags_clear
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
streamStandard I/O stream on which to print the output.
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
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
flagAny of the standard debugging flags.
nameNew name to associate with flag.
void debug_flags_restore ( INT64_T  flags)

Restore debug flags.

Parameters
flagsflags to set
void debug_rename ( const char *  suffix)

Rename debug file with given suffix.

Parameters
suffixSuffix of saved log.
void debug_reopen ( void  )

Reopen the debug stream.