--- name: "log_open" section: "3debug" platform: "linux" package: "libdebug0-dev" version: "0.5.3-8+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/log_open/3debug" --- # log\_open(3debug) log routines for debugging ## NAME log\_open, log\_close, log\_reset, log\_flush, log\_printf, log\_vprintf, log\_putc, log\_puts - log routines for debugging ## LIBRARIES Debug Library (-ldebug) ## SYNOPSIS ``` #include int log_open(const char *logfile, int level, int flags); void log_close(void); int log_reset(void); int log_flush(void); int log_printf(int level, const char *fmt, ...); int log_vprintf(int level, const char *fmt, va_list ap); int log_putc(int level, int c); int log_puts(int level, const char *str); ``` ## DESCRIPTION **log\_open()** initializes the logging system. The filename of the file to which messages are logged should be specified by *logfile*, or **NULL** if messages should be printed to the console. The values for *level* and *flags* are given in the next section. From version 0.4.1 onwards the debug library also supports logging to syslog instead of a file. Instead of specifying a file, just specify a string in the form *ident.facility*, where *ident* is a string which will be prepended to each syslog message and is usually the program name. The *facility* should be the facility to which messages should be logged. **log\_close()** flushes all pending messages, and closes the file descriptor of the log file (if any). **log\_reset()** reinitializes the logging system. If any files are currently opened for writing, it will be closed and reopened. This is useful if you need to rotate log files. **log\_flush()** flushes all pending messages (if any). **log\_printf()** and **log\_vprintf()** are replacements for [**printf**(3)](/printf/3.md) and [**vprintf**(3)](/vprintf/3.md) respectively. **log\_putc()** will log a single character. This is the equivalent of [**putchar**(3)](/putchar/3.md). **log\_puts()** will log a string. It is the equivalent of [**puts**(3)](/puts/3.md), except that is does not append a trailing newline. ## PARAMETERS This section lists the parameters used to set the values of *level* and *flags*. ### level This determines the importance of the message. The levels are, in order of decreasing verbosity: - **LOG\_NOISY** verbose debug messages - **LOG\_DEBUG** debug messages - **LOG\_VERBOSE** informational messages - **LOG\_NORMAL** normal, but significant, conditions - **LOG\_WARNING** warning conditions - **LOG\_ERROR** error conditions - **LOG\_QUIET** no messages are printed The *level* argument to **log\_printf()**, **log\_vprintf()**, **log\_putc()**, and **log\_puts()** specify the level at which the message should be printed. It does not make sense to specify **LOG\_QUIET** to these functions. The *level* argument to **log\_open()** sets the verbosity of the program. Any messages printed with a *level* higher (more verbose) than that specified to the **log\_open()** function, will be discarded. ### flags The *flags* argument to **log\_open()** is an OR of any of these: - **LOG\_HAVE\_COLORS** If this flag is specified and messages are printed to the console (i.e. no log file is specified), messages will be printed in different colors, depending on their log level. - **LOG\_PRINT\_FUNCTION** If this flag is specified, the function in which the print function was called would be printed in addition to the filename and line number. - **LOG\_DEBUG\_PREFIX\_ONLY** If this flag is specified, only messages with a level higher or equal to (i.e. more or as verbose) **LOG\_DEBUG** will be printed in color and with file, line number, and (if necessary), the function. - **LOG\_DETECT\_DUPLICATES** If this flag is specified, messages would be buffered and duplicate lines would not be printed. Instead, the first message would be printed, followed by a line describing the number of times the message repeated. This is a great way to prevent flooding, but unfortunately it has the side effect of always being one statement behind. - **LOG\_DETECT\_FLOODING** If specified, the rate at which messages are printed would be limited in order to avoid flooding. This feature have not been implemented yet, and is currently ignored. ## RETURN VALUE All functions except **log\_close()** return 0 if successful, -1 if some error occurred. Check errno to see which error occurred. If **log\_reset()** or **log\_open()** fails, behaviour is undefined and it should be assumed that no logging is possible. The **log\_close()** function returns no value. ## NOTES If this routines are combined with the memory routines, care should be taken to call open and close functions in the right order. The correct order is as follows: ``` mem_open (NULL); log_open (NULL,LOG_NORMAL,LOG_HAVE_COLORS | LOG_PRINT_FUNCTION); atexit (mem_close); atexit (log_close); ``` Of course, [**atexit**(3)](/atexit/3.md) should only be used if the program will not forked. None of the libdebug routines are thread-safe. I'm not planning to change this either! For more information, please see http://threading.2038bug.com/ ## SEE ALSO mem\_open(3), [errno(3)](/errno/3.md), [atexit(3)](/atexit/3.md), [printf(3)](/printf/3.md), [vprintf(3)](/vprintf/3.md), [putchar(3)](/putchar/3.md), [puts(3)](/puts/3.md)\ [logrotate(8)](/logrotate/8.md), [syslog(3)](/syslog/3.md), [logger(1)](/logger/1.md) ## AUTHOR Written by Abraham vd Merwe \