--- name: "explain_output" section: "3" platform: "linux" package: "libexplain-dev" version: "1.4.D001-16" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/explain_output" --- # explain\_output(3) output error messages ## NAME explain\_output - output error messages ## SYNOPSIS `#include ` ## DESCRIPTION These functions may be used to write error messages. ### explain\_output\_message `void explain_output_message(const char *text);` The explain\_output\_message function is used to print text. It is printed via the registered output class, see *explain\_output\_register*(3) for how. - *text* The text of the message to be printed. It has not been wrapped (yet). ### explain\_output\_error `void explain_output_error(const char *fmt, ...);` The explain\_output\_error function is used to print a formatted error message. The printing is done via the *explain\_output\_message*(3) function. - *fmt* The format text of the message to be printed. See [*printf*(3)](/printf/3.md) for more information. ### explain\_output\_error\_and\_die `void explain_output_error_and_die(const char *fmt, ...);` The explain\_output\_error\_and\_die function is used to print text, and then terminate immediately. The printing is done via the *explain\_output\_message*(3) function, process termination is via the *explain\_output\_exit\_failure*(3) function. - *fmt* The format text of the message to be printed. See [printf(3)](/printf/3.md) for more information. ### explain\_output\_warning `void explain_output_warning(const char *fmt, ...);` The explain\_output\_warning function is used to print a formatted error message, including the word “warning”. The printing is done via the *explain\_output\_message*(3) function. - *fmt* The format text of the message to be printed. See [*printf*(3)](/printf/3.md) for more information. ### explain\_output\_exit `void explain_output_exit(int status);` The explain\_output\_exit function is used to terminate execution. It is executed via the registered output class, *explain\_output\_register*(3) for how. - *status* The exist status requested. ### explain\_output\_exit\_failure `void explain_output_exit_failure(void);` The explain\_output\_exit\_failure function is used to terminate execution, with exit status EXIT\_FAILURE. It is executed via the registered output class, see *explain\_output\_register*(3) for how. ### explain\_option\_hanging\_indent\_set `void explain_option_hanging_indent_set(int columns);` The explain\_option\_hanging\_indent\_set function is used to cause the output wrapping to use hanging indents. By default no hanging indent is used, but this can sometimes obfuscate the end of one error message and the beginning of another. A hanging indent results in continuation lines starting with white space, similar to RFC822 headers. This can be set using the “`hanging‐indent=`*n*” string in the EXPLAIN\_OPTIONS environment variable. See [*explain*(3)](/explain/3.md) for more information. Using this function will override any environment variable setting. - *columns* The number of columns of hanging indent to be used. A value of 0 means no hanging indent (all lines flush with left margin). A common value to use is 4: it doesn't consume too much of each line, and it is a clear indent. ## OUTPUT REDIRECTION It is possible to change how and where libexplain sends its output, and even how it calls the [*exit*(2)](/exit/2.md) function. This functionality is used by the `explain_*_or_die` and `explain_*_on_error` functions. By default, libexplain will wrap and print error messages on stderr, and call the [*exit*(2)](/exit/2.md) system call to terminate execution. Clients of the libexplain library may choose to use some message handling facilities provided by libexplain, or they may choose to implement their own. - **syslog** To cause all output to be sent to syslog, use `explain_output_register(explain_output_syslog_new());` This is useful for servers and daemons. - **stderr and syslog** The “tee” output class can be used to duplicate output. To cause all output to be sent to both stderr and syslog, use ``` explain_output_register ( explain_output_tee_new ( explain_output_stderr_new(), explain_output_syslog_new() ) ); ``` If you need more than two, use several instances of “tee”, cascaded. - **stderr and a file** To cause all output to be sent to both stderr and a regular file, use ``` explain_output_register ( explain_output_tee_new ( explain_output_stderr_new(), explain_output_file_new(filename, 0) ) ); ``` See the `` file for extensive documentation. ### explain\_output\_new `explain_output_t *explain_output_new(const explain_output_vtable_t *vtable);` The explain\_output\_new function may be used to create a new dynamically allocated instance of explain\_output\_t. - *vtable* The struct containing the pointers to the methods of the derived class. - *returns* NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the class. ### explain\_output\_stderr\_new `explain_output_t *explain_output_stderr_new(void);` The explain\_output\_stderr\_new function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to stderr, and exits via [*exit*(2)](/exit/2.md); This is the default output handler. - *returns* NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the stderr class. ### explain\_output\_syslog\_new `explain_output_t *explain_output_syslog_new(void);` The explain\_output\_syslog\_new function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to syslog, and exits via [*exit*(2)](/exit/2.md); The following values are used: ``` option = 0 facility = LOG_USER level = LOG_ERR ``` See [*syslog*(3)](/syslog/3.md) for more information. - *returns* NULL on error (i.e. [*malloc*(3)](/malloc/3.md) failed), or a pointer to a new dynamically allocated instance of the syslog class. ### explain\_output\_syslog\_new1 `explain_output_t *explain_output_syslog_new1(int level);` The explain\_output\_syslog\_new1 function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to syslog, and exits via [*exit*(2)](/exit/2.md); The following values are used: ``` option = 0 facility = LOG_USER ``` See [*syslog*(3)](/syslog/3.md) for more information. - *level* The syslog level to be used, see [syslog(3)](/syslog/3.md) for a definition. - *returns* NULL on error (i.e. [*malloc*(3)](/malloc/3.md) failed), or a pointer to a new dynamically allocated instance of the syslog class. ### explain\_output\_syslog\_new3 `explain_output_t *explain_output_syslog_new3(int option, int facility,` `int level);` The explain\_output\_syslog\_new3 function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to syslog, and exits via [*exit*(2)](/exit/2.md); If you want different facilities or levels, create multiple instances. - *option* The syslog option to be used, see [syslog(3)](/syslog/3.md) for a definition. - *facility* The syslog facility to be used, see [syslog(3)](/syslog/3.md) for a definition. - *level* The syslog level to be used, see [syslog(3)](/syslog/3.md) for a definition. - *returns* NULL on error (i.e. [*malloc*(3)](/malloc/3.md) failed), or a pointer to a new dynamically allocated instance of the syslog class. ### explain\_output\_file\_new `explain_output_t *explain_output_file_new(const char *filename, int append);` The explain\_output\_file\_new function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to a file, and exits via [*exit*(2)](/exit/2.md). - *filename* The file to be opened and written to. - *append* true (non‐zero) if messages are to be appended to the file, false (zero) if the file is to be replaced with new contents. - *returns* NULL on error (i.e. [*malloc*(3)](/malloc/3.md) or [*open*(2)](/open/2.md) failed), or a pointer to a new dynamically allocated instance of the syslog class. ### explain\_output\_tee\_new `explain_output_t *explain_output_tee_new(explain_output_t *first,` `explain_output_t *second);` The explain\_output\_tee\_new function may be used to create a new dynamically allocated instance of an explain\_output\_t class that writes to **two** other output classes. - *first* *The first output class to write to.* - *second* *The second output class to write to.* - *returns* *NULL on error (i.e. [malloc(3)](/malloc/3.md) failed), or a pointer to a new* *dynamically allocated instance of the syslog class.* *The output subsystem will “own” the first and* *second objects after this call. You may not make any reference* *to these pointers ever again. The output subsystem will destroy these* *objects and free the memory when it feels like it.* ### explain\_output\_register `void explain_output_register(explain_output_t *op);` The explain\_output\_register function is used to change libexplain's default output handling facilities with something else. The NULL pointer restores libexplain's default processing. If no output class is registered, the default is to wrap and print to stderr, and to exit via the [*exit*(2)](/exit/2.md) system call. - *op* Pointer to the explain\_output\_t instance to be operated on. The output subsystem will “own” the pointer after this call. You may not make any reference to this pointer ever again. The output subsystem will destroy the object and free the memory when it feels like it. ## COPYRIGHT libexplain version 1.4\ Copyright (C) 2010 Peter Miller ## AUTHOR Written by Peter Miller \