Lely core libraries 2.3.4
diag.c File Reference

This file is part of the utilities library; it contains the diagnostic function definitions. More...

#include "util.h"
#include <lely/libc/stdio.h>
#include <lely/util/diag.h>
#include <assert.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <syslog.h>
Include dependency graph for diag.c:

Go to the source code of this file.

Functions

size_t floc_lex (struct floc *at, const char *begin, const char *end)
 Increments a file location by reading characters from a memory buffer.
 
int snprintf_floc (char *s, size_t n, const struct floc *at)
 Prints a file location to a string buffer.
 
void diag_get_handler (diag_handler_t **phandler, void **phandle)
 Retrieves the handler function for diag().
 
void diag_set_handler (diag_handler_t *handler, void *handle)
 Sets the handler function for diag().
 
void diag_at_get_handler (diag_at_handler_t **phandler, void **phandle)
 Retrieves the handler function for diag_at().
 
void diag_at_set_handler (diag_at_handler_t *handler, void *handle)
 Sets the handler function for diag_at().
 
void diag (enum diag_severity severity, int errc, const char *format,...)
 Emits a diagnostic message.
 
void vdiag (enum diag_severity severity, int errc, const char *format, va_list ap)
 Emits a diagnostic message.
 
void diag_at (enum diag_severity severity, int errc, const struct floc *at, const char *format,...)
 Emits a diagnostic message occurring at a location in a text file.
 
void vdiag_at (enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 Emits a diagnostic message occurring at a location in a text file.
 
void diag_if (enum diag_severity severity, int errc, const struct floc *at, const char *format,...)
 Emits a diagnostic message occurring at a location in a text file.
 
void vdiag_if (enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 Emits a diagnostic message occurring at a location in a text file.
 
void default_diag_handler (void *handle, enum diag_severity severity, int errc, const char *format, va_list ap)
 The default diag() handler.
 
void default_diag_at_handler (void *handle, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 The default diag_at() handler.
 
void cmd_diag_handler (void *handle, enum diag_severity severity, int errc, const char *format, va_list ap)
 The diag() handler used for command-line programs.
 
void daemon_diag_handler (void *handle, enum diag_severity severity, int errc, const char *format, va_list ap)
 The diag() handler for daemons.
 
void daemon_diag_at_handler (void *handle, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 The diag_at() handler for daemons.
 
void log_diag_handler (void *handle, enum diag_severity severity, int errc, const char *format, va_list ap)
 The diag() handler for log files.
 
void log_diag_at_handler (void *handle, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 The diag_at() handler used for log-files.
 
void syslog_diag_handler (void *handle, enum diag_severity severity, int errc, const char *format, va_list ap)
 The diag() handler used for the system logging facilities.
 
void syslog_diag_at_handler (void *handle, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 The diag_at() handler used for the system logging facilities.
 
int vsnprintf_diag (char *s, size_t n, enum diag_severity severity, int errc, const char *format, va_list ap)
 Prints a diagnostic message to a string buffer.
 
int vasprintf_diag (char **ps, enum diag_severity severity, int errc, const char *format, va_list ap)
 Equivalent to vsnprintf_diag(), except that it allocates a string large enough to hold the output, including the terminating null byte.
 
int vsnprintf_diag_at (char *s, size_t n, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 Prints a diagnostic message occurring at a location in a text file to a string buffer.
 
int vasprintf_diag_at (char **ps, enum diag_severity severity, int errc, const struct floc *at, const char *format, va_list ap)
 Equivalent to vsnprintf_diag_at(), except that it allocates a string large enough to hold the output, including the terminating null byte.
 
const char * cmdname (const char *path)
 Extracts the command name from a path.
 

Detailed Description

This file is part of the utilities library; it contains the diagnostic function definitions.

See also
lely/util/diag.h
Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file diag.c.

Function Documentation

◆ floc_lex()

size_t floc_lex ( struct floc at,
const char *  begin,
const char *  end 
)

Increments a file location by reading characters from a memory buffer.

This function assumes a tab stop of 8 spaces.

Parameters
ata pointer to a file location (can be NULL).
begina pointer to the start of the buffer.
enda pointer to one past the last character in the buffer (can be NULL if the buffer is null-terminated).
Returns
the number of characters read (excluding the termination character).

Definition at line 65 of file diag.c.

◆ snprintf_floc()

int snprintf_floc ( char *  s,
size_t  n,
const struct floc at 
)

Prints a file location to a string buffer.

The filename, line and column are separated by a colon. If the line or column is zero, it is omitted from the output. This allows the user to print a partial location if, for example, the column is unknown or meaningless.

Parameters
sthe address of the output buffer. If s is not NULL, at most n - 1 characters are written, plus a terminating null byte.
nthe size (in bytes) of the buffer at s. If n is zero, nothing is written.
ata pointer the location in a text file.
Returns
the number of characters that would have been written had the buffer been sufficiently large, not counting the terminating null byte, or a negative number on error. In the latter case, the error number is stored in errno.

Definition at line 97 of file diag.c.

◆ diag_get_handler()

void diag_get_handler ( diag_handler_t **  phandler,
void **  phandle 
)

Retrieves the handler function for diag().

Parameters
phandlerthe address at which to store a pointer to the handler function (can be NULL).
phandlethe address at which to store the pointer to the extra argument for the handler function (can be NULL).
See also
diag_set_handler()

Definition at line 139 of file diag.c.

◆ diag_set_handler()

void diag_set_handler ( diag_handler_t handler,
void *  handle 
)

Sets the handler function for diag().

Parameters
handlera pointer to the new handler function.
handlean optional pointer to an extra argument for the handler function (can be NULL).
See also
diag_get_handler()

Definition at line 148 of file diag.c.

◆ diag_at_get_handler()

void diag_at_get_handler ( diag_at_handler_t **  phandler,
void **  phandle 
)

Retrieves the handler function for diag_at().

Parameters
phandlerthe address at which to store a pointer to the handler function (can be NULL).
phandlethe address at which to store the pointer to the extra argument for the handler function (can be NULL).
See also
diag_at_set_handler()

Definition at line 155 of file diag.c.

◆ diag_at_set_handler()

void diag_at_set_handler ( diag_at_handler_t handler,
void *  handle 
)

Sets the handler function for diag_at().

Parameters
handlera pointer to the new handler function.
handlean optional pointer to an extra argument for the handler function (can be NULL).
See also
diag_at_get_handler()

Definition at line 164 of file diag.c.

◆ diag()

void diag ( enum diag_severity  severity,
int  errc,
const char *  format,
  ... 
)
inline

Emits a diagnostic message.

This function SHOULD print the severity of the diagnostic followed by the user-specified message. If the specified severity is DIAG_FATAL, the program SHOULD be terminated after printing the message.

The default error handler can be changed with diag_set_handler(), in which case the new handler is responsible for terminating the program in case of an error with severity DIAG_FATAL.

Parameters
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error SHOULD be printed after the user-specified message.
formata printf-style format string.
...an optional list of arguments to be printed according to format.
See also
diag_set_handler(), diag_at()

Definition at line 171 of file diag.c.

◆ vdiag()

void vdiag ( enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

Emits a diagnostic message.

This function is equivalent to diag(), except that it accepts a va_list instead of a variable number of arguments.

Definition at line 180 of file diag.c.

◆ diag_at()

void diag_at ( enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
  ... 
)
inline

Emits a diagnostic message occurring at a location in a text file.

This function SHOULD print the location in a text file, where the diagnostic presumably occurred, followed by the severity and a user-specified message. If the specified severity is DIAG_FATAL, the program SHOULD be terminated after printing the message.

The default error handler can be changed with diag_at_set_handler(), in which case the new handler is responsible for terminating the program in case of an error with severity DIAG_FATAL.

Parameters
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error will be printed after the user-specified message.
ata pointer the location in a text file (can be NULL). If at is not NULL, the location SHOULD be printed before the severity.
formata printf-style format string.
...an optional list of arguments to be printed according to format.
See also
diag_at_set_handler(), diag()

Definition at line 187 of file diag.c.

◆ vdiag_at()

void vdiag_at ( enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

Emits a diagnostic message occurring at a location in a text file.

This function is equivalent to diag_at(), except that it accepts a va_list instead of a variable number of arguments.

Definition at line 197 of file diag.c.

◆ diag_if()

void diag_if ( enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
  ... 
)
inline

Emits a diagnostic message occurring at a location in a text file.

This function is equivalent to diag_at(), except that it only invokes the error handler if at is not NULL. It therefore MUST NOT be used with severity DIAG_FATAL unless at is guaranteed to be non-NULL.

Definition at line 205 of file diag.c.

◆ vdiag_if()

void vdiag_if ( enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

Emits a diagnostic message occurring at a location in a text file.

This function is equivalent to vdiag_at(), except that it only invokes the error handler if at is not NULL. It therefore MUST NOT be used with severity DIAG_FATAL unless at is guaranteed to be non-NULL.

Definition at line 215 of file diag.c.

◆ default_diag_handler()

void default_diag_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

The default diag() handler.

This function prints the string generated by vsnprintf_diag() to stderr. If severity equals DIAG_FATAL, this function calls exit(EXIT_FAILURE) instead of returning.

Definition at line 223 of file diag.c.

◆ default_diag_at_handler()

void default_diag_at_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

The default diag_at() handler.

This function is similar to default_diag_handler(), except that it prints the string generated by vsnprintf_diag_at().

Definition at line 230 of file diag.c.

◆ cmd_diag_handler()

void cmd_diag_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

The diag() handler used for command-line programs.

This function prints the string at handle, which SHOULD point to the name of the program (see cmdname()), and then calls default_diag_handler().

Definition at line 258 of file diag.c.

◆ daemon_diag_handler()

void daemon_diag_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

The diag() handler for daemons.

On Windows this function is equivalent to dialog_diag_handler(), on other platforms to syslog_diag_handler().

Definition at line 273 of file diag.c.

◆ daemon_diag_at_handler()

void daemon_diag_at_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

The diag_at() handler for daemons.

This function is similar to daemon_diag_handler(), except that it prints the string generated by vsnprintf_diag_at().

Definition at line 280 of file diag.c.

◆ log_diag_handler()

void log_diag_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

The diag() handler for log files.

This function is similar to default_diag_handler(), except that it prepends each message with a RFC-2822-compliant timestamp.

Definition at line 335 of file diag.c.

◆ log_diag_at_handler()

void log_diag_at_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

The diag_at() handler used for log-files.

This function is similar to default_diag_at_handler(), except that it prepends each message with a RFC-2822-compliant timestamp.

Definition at line 342 of file diag.c.

◆ syslog_diag_handler()

void syslog_diag_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

The diag() handler used for the system logging facilities.

On POSIX platforms this function invokes syslog(); on other platforms this function is equivalent to log_diag_handler().

Definition at line 377 of file diag.c.

◆ syslog_diag_at_handler()

void syslog_diag_at_handler ( void *  handle,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

The diag_at() handler used for the system logging facilities.

On POSIX platforms this function invokes syslog(); on other platforms this function is equivalent to log_diag_at_handler().

Definition at line 384 of file diag.c.

◆ vsnprintf_diag()

int vsnprintf_diag ( char *  s,
size_t  n,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

Prints a diagnostic message to a string buffer.

This function prints the severity of the message (except in the case of DIAG_INFO), followed by a colon and the user-specified message. If errc is non-zero, the message is followed by another colon and the result of errc2str().

Parameters
sthe address of the output buffer. If s is not NULL, at most n - 1 characters are written, plus a terminating null byte.
nthe size (in bytes) of the buffer at s. If n is zero, nothing is written.
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error will be printed after the user-specified message.
formata printf-style format string.
apthe list of arguments to be printed according to format.
Returns
the number of characters that would have been written had the buffer been sufficiently large, not counting the terminating null byte, or a negative number on error. In the latter case, the error number is stored in errno.
See also
vsnprintf_diag_at()

Definition at line 414 of file diag.c.

◆ vasprintf_diag()

int vasprintf_diag ( char **  ps,
enum diag_severity  severity,
int  errc,
const char *  format,
va_list  ap 
)

Equivalent to vsnprintf_diag(), except that it allocates a string large enough to hold the output, including the terminating null byte.

Parameters
psthe address of a value which, on success, contains a pointer to the allocated string. This pointer SHOULD be passed to free() to release the allocated storage.
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error will be printed after the user-specified message.
formata printf-style format string.
apthe list of arguments to be printed according to format.
Returns
the number of characters written, not counting the terminating null byte, or a negative number on error. In the latter case, the error number is stored in errno.
See also
vasprintf_diag_at()

Definition at line 421 of file diag.c.

◆ vsnprintf_diag_at()

int vsnprintf_diag_at ( char *  s,
size_t  n,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

Prints a diagnostic message occurring at a location in a text file to a string buffer.

This function prints the location in a text file, where the diagnostic presumably occurred, followed a colon and the severity of the message (except in the case of DIAG_INFO), followed by a colon and the user-specified message. If errc is non-zero, the message is followed by another colon and the result of errc2str().

Parameters
sthe address of the output buffer. If s is not NULL, at most n - 1 characters are written, plus a terminating null byte.
nthe size (in bytes) of the buffer at s. If n is zero, nothing is written.
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error will be printed after the user-specified message.
ata pointer the location in a text file (can be NULL). If at is not NULL, the location will be printed before the severity according to snprintf_floc().
formata printf-style format string.
apthe list of arguments to be printed according to format.
Returns
the number of characters that would have been written had the buffer been sufficiently large, not counting the terminating null byte, or a negative number on error. In the latter case, the error number is stored in errno.
See also
vsnprintf_diag()

Definition at line 428 of file diag.c.

◆ vasprintf_diag_at()

int vasprintf_diag_at ( char **  ps,
enum diag_severity  severity,
int  errc,
const struct floc at,
const char *  format,
va_list  ap 
)

Equivalent to vsnprintf_diag_at(), except that it allocates a string large enough to hold the output, including the terminating null byte.

Parameters
psthe address of a value which, on success, contains a pointer to the allocated string. This pointer SHOULD be passed to free() to release the allocated storage.
severitythe severity of the message.
errcthe native error code generated by a system call or library function, given by get_errc(). If errc is non-zero, a text string describing the error will be printed after the user-specified message.
ata pointer the location in a text file (can be NULL). If at is not NULL, the location will be printed before the severity according to snprintf_floc().
formata printf-style format string.
apthe list of arguments to be printed according to format.
Returns
the number of characters written, not counting the terminating null byte, or a negative number on error. In the latter case, the error number is stored in errno.
See also
vasprintf_diag()

Definition at line 502 of file diag.c.

◆ cmdname()

const char * cmdname ( const char *  path)

Extracts the command name from a path.

This function returns a pointer to the first character after the last separator ('/' or '\') in path.

Definition at line 537 of file diag.c.