211 lines
5.9 KiB
Groff
211 lines
5.9 KiB
Groff
|
.\" 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>
|