EINFO(3)

NAME
einfo, ewarn, eerror, ebegin, einfon, ewarnn, eerrorn, ebeginn, einfov, ewarnv, ebeginv, einfovn, ewarnvn, ebeginvn, ewarnx, eerrorx, eend, ewend, eendv, ewendv, ebracket, eindent, eoutdent, eindentv, eoutdentv, eprefix - colorful informational output

LIBRARY
Enhanced Information output library (libeinfo, -leinfo)

SYNOPSIS
#include <einfo.h>
int einfo(const char * restrict format, ...);
int ewarn(const char * restrict format, ...);
int eerror(const char * restrict format, ...);
int ebegin(const char * restrict format, ...);
int einfon(const char * restrict format, ...);
int ewarnn(const char * restrict format, ...);
int eerrorn(const char * restrict format, ...);
int ebeginn(const char * restrict format, ...);
int einfov(const char * restrict format, ...);
int ewarnv(const char * restrict format, ...);
int ebeginv(const char * restrict format, ...);
int einfovn(const char * restrict format, ...);
int ewarnvn(const char * restrict format, ...);
int ebeginvn(const char * restrict format, ...);
int ewarnx(const char * restrict format, ...);
int eerrorx(const char * restrict format, ...);
int eend(int retval, const char * restrict format, ...);
int ewend(int retval, const char * restrict format, ...);
int eendv(int retval, const char * restrict format, ...);
int ewendv(int retval, const char * restrict format, ...);
void ebracket(int col, ECOLOR color, const char * restrict msg);
void eindent(void);
void eoutdent(void);
void eindentv(void);
void eoutdentv(void);
void eprefix(const char * prefix);

DESCRIPTION
The einfo() family of functions provide a simple informational output that is colorised. Basically einfo(), ewarn() and eerror() behave exactly like printf() but prefix the output with a colored *. The function called denotes the color used with einfo() being green, ewarn() being yellow and eerror() being red. einfo goes to stdout and the others go to stderr. The number of real characters printed is returned. ebegin() is identical to einfo() except that 3 dots are appended to the output.

einfov(), ewarnv() and ebeginv() work the same way to einfo(), ewarn(), and ebegin() respectively, but only work when EINFO_VERBOSE is true. You can also make the einfo(), ewarn(), and ebegin() functions silent by setting EINFO_QUIET to true.

These functions are designed to output a whole line, so they also append a newline to the string. To stop this behaviour, you can use the functions einfon(), ewarnn(), eerrorn(), einfovn(), ewarnvn(), and ebeginvn().

eend(), ewend(), eendv() and ewendv() are the counterparts to the above functions. If retval is zero then ok in green is printed in a bracket at the end of the prior line. Otherwise we print the formatted string using error() (or ewarn() if ewend() is called) !! in red (or yellow if ewend() is called) is printed in a bracket at the end of the line. The value of retval is returned.

ebracket() does the same as eend() but prints msg instead of ok or !! in the color color at the column col.

eindent() indents subsequent calls to the above functions by 3 characters. eoutdent() removes an eindent(). eindentv() and eoutdentv() only work when EINFO_VERBOSE is true.

eprefix() prefixes the string prefix to the above functions.

IMPLEMENTATION NOTES
einfo can optionally be linked against the libtermcap so that we can correctly query the connected console for our color and cursor escape codes. If not, then we have a hard coded list of terminals we know about that support the commonly used codes for color and cursor position.

ENVIRONMENT
EINFO_QUIET when set to true makes the einfo() and einfon() family of functions quiet, so nothing is printed. EERROR_QUIET when set to true makes the eerror() and eerrorn() family of functions quiet, so nothing is printed.

EINFO_VERBOSE when set to true makes the einfov() and einfovn() family of functions work, so they do print.

FILES
/etc/init.d/functions.sh is provided by OpenRC, which allows shell scripts to use the above functions. For historical reasons our verbose functions are prefixed with v instead of suffixed. So einfov becomes veinfo, einfovn becomes veinfon. Rinse and repeat for the other verbose functions.

SEE ALSO
printf(3),

AUTHORS
Roy Marples <roy@marples.name>