diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 2 | ||||
| -rw-r--r-- | man/einfo.3 | 210 |
2 files changed, 211 insertions, 1 deletions
diff --git a/man/Makefile b/man/Makefile index 6a106e7c..4110c8f7 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,4 +1,4 @@ -MAN3= \ +MAN3= einfo.3 \ rc_config.3 rc_deptree.3 rc_find_pids.3 rc_plugin_hook.3 \ rc_runlevel.3 rc_service.3 rc_stringlist.3 MAN8= rc-service.8 rc-status.8 rc-update.8 rc.8 runscript.8 \ diff --git a/man/einfo.3 b/man/einfo.3 new file mode 100644 index 00000000..f7b1fd26 --- /dev/null +++ b/man/einfo.3 @@ -0,0 +1,210 @@ +.\" Copyright (c) 2007-2008 Roy Marples +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd Mar 16, 2008 +.Dt EINFO 3 SMM +.Os OpenRC +.Sh NAME +.Nm einfo , ewarn , eerror , ebegin , +.Nm einfon , ewarnn , eerrorn , ebeginn , +.Nm einfov , ewarnv , ebeginv , +.Nm einfovn , ewarnvn , ebeginvn , +.Nm ewarnx , eerrorx , +.Nm eend , ewend , +.Nm eendv , ewendv , +.Nm ebracket , +.Nm eindent , eoutdent , +.Nm eindentv , eoutdentv , +.Nm eprefix +.Nd colorful informational output +.Sh LIBRARY +Enhanced Information output library (libeinfo, -leinfo) +.Sh SYNOPSIS +.In einfo.h +.Ft int Fn einfo "const char * restrict format" ... +.Ft int Fn ewarn "const char * restrict format" ... +.Ft int Fn eerror "const char * restrict format" ... +.Ft int Fn ebegin "const char * restrict format" ... +.Ft int Fn einfon "const char * restrict format" ... +.Ft int Fn ewarnn "const char * restrict format" ... +.Ft int Fn eerrorn "const char * restrict format" ... +.Ft int Fn ebeginn "const char * restrict format" ... +.Ft int Fn einfov "const char * restrict format" ... +.Ft int Fn ewarnv "const char * restrict format" ... +.Ft int Fn ebeginv "const char * restrict format" ... +.Ft int Fn einfovn "const char * restrict format" ... +.Ft int Fn ewarnvn "const char * restrict format" ... +.Ft int Fn ebeginvn "const char * restrict format" ... +.Ft int Fn ewarnx "const char * restrict format" ... +.Ft int Fn eerrorx "const char * restrict format" ... +.Ft int Fn eend "int retval" "const char * restrict format" ... +.Ft int Fn ewend "int retval" "const char * restrict format" ... +.Ft int Fn eendv "int retval" "const char * restrict format" ... +.Ft int Fn ewendv "int retval" "const char * restrict format" ... +.Ft void Fn ebracket "int col" "ECOLOR color" "const char * restrict msg" +.Ft void Fn eindent void +.Ft void Fn eoutdent void +.Ft void Fn eindentv void +.Ft void Fn eoutdentv void +.Ft void Fn eprefix "const char * prefix" +.Sh DESCRIPTION +The +.Fn einfo +family of functions provide a simple informational output that is colorised. +Basically +.Fn einfo , +.Fn ewarn +and +.Fn eerror +behave exactly like +.Fn printf +but prefix the output with a colored *. The function called denotes the color +used with +.Fn einfo +being green, +.Fn ewarn +being yellow and +.Fn eerror +being red. +einfo goes to stdout and the others go to stderr. +The number of real characters printed is returned. +.Fn ebegin +is identical to +.Fn einfo +except that 3 dots are appended to the output. +.Pp +.Fn einfov , +.Fn ewarnv +and +.Fn ebeginv +work the same way to +.Fn einfo , +.Fn ewarn , +and +.Fn ebegin +respectively, but only work when +.Va EINFO_VERBOSE +is true. You can also make the +.Fn einfo , +.Fn ewarn , +and +.Fn ebegin +functions silent by setting +.Va EINFO_QUIET +to true. +.Pp +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 +.Fn einfon , +.Fn ewarnn , +.Fn eerrorn , +.Fn einfovn , +.Fn ewarnvn , +and +.Fn ebeginvn . +.Pp +.Fn eend , +.Fn ewend , +.Fn eendv +and +.Fn ewendv +are the counterparts to the above functions. If +.Fa 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 +.Fn error +(or +.Fn ewarn +if +.Fn ewend +is called) !! in red (or yellow if +.Fn ewend +is called) is printed in a bracket at the end of the line. +The value of +.Fa retval +is returned. +.Pp +.Fn ebracket +does the same as +.Fn eend +but prints +.Fa msg +instead of ok or !! in the color +.Fa color +at the column +.Fa col . +.Pp +.Fn eindent +indents subsequent calls to the above functions by 3 characters. +.Fn eoutdent +removes an +.Fn eindent . +.Fn eindentv +and +.Fn eoutdentv +only work when +.Va EINFO_VERBOSE +is true. +.Pp +.Fn eprefix +prefixes the string +.Fa prefix +to the above functions. +.Sh IMPLEMENTATION NOTES +einfo can optionally be linked against the +.Lb 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. +.Sh ENVIRONMENT +.Va EINFO_QUIET +when set to true makes the +.Fn einfo +and +.Fn einfon +family of functions quiet, so nothing is printed. +.Va EERROR_QUIET +when set to true makes the +.Fn eerror +and +.Fn eerrorn +family of functions quiet, so nothing is printed. +.Pp +.Va EINFO_VERBOSE +when set to true makes the +.Fn einfov +and +.Fn einfovn +family of functions work, so they do print. +.Sh FILES +.Pa /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. +.Sh SEE ALSO +.Xr printf 3 , +.Sh AUTHORS +.An Roy Marples <roy@marples.name> |