\begindata{text,538945640} \textdsversion{12} \template{help} \define{global } \chapter{\center{Errprintf: Send a formatted message to the Andrew console }} \section{\smaller{What errprintf is }}\leftindent{ The errprintf subroutine is the approved way of sending error messages to the console. It should be used for all printing on stderr by window manager applications, system demons, and any other program whose stderr is redirected to the console. } \section{\smaller{Syntax Summary }}\leftindent{ #include "errprintf.h" errprintf(application, type, log, id, formatstring, arg1, arg2, arg3, .....) int type; char * You need to link against $\{BASEDIR\}/lib/liberrors.a, where $\{BASEDIR\} == /usr/andrew or equivelent.} \section{\smaller{Description }}\leftindent{ errprintf prepares an Andrew-format error message and prints it on stderr. It should be used for all message printing that is destined for /dev/console or the console service. Basically, you can think of it as replacing "printf(stderr...", with four new arguments replacing the "stderr" argument. Those arguments have the following meanings: \leftindent{\italic{application} -- should be the name of the program generating the message. A zero here will cause the application name to be "UNKNOWN" \italic{type} -- should be either ERR_CRITICAL, ERR_WARNING, ERR_MONITOR, or ERR_DEBUG. ERR_CRITICAL is for extremely critical conditions (files lost, file servers crashing, etc.) ERR_WARNING is for other error conditions that novices must see. ERR_MONITOR is for informative and important messages that sophisticated users will want to know about but that need not be shown to novices. ERR_DEBUG is for information that most people won't want to see, but that will be useful to enable in the console when you're debugging. (Note that you should not use this facility TOO freely, as it is moderately expensive to send unnecessary messages to the console.) A zero for "type" is the same as ERR_CRITICAL. \italic{log} -- may be used to cause the message to be logged somewhere. If log begins with a slash ("/"), then the message will be appended to the named file. Otherwise, the message will be mailed to the named destination. A zero here will cause no logging to happen. \italic{id }-- The unique official Andrew ID of this message. If your message has not been assigned a unique ID, this field should be zero. Official IDs have been assigned only to a few error messages; for most, an ID of zero is appropriate. } The remaining parameters are simply the usual printf control string and arguments. Note that errprintf ALWAYS adds a newline to the end of your message, so you should probably omit the newline. } \smaller{\section{Reliability}} \leftindent{An added benefit of using errprintf is reliability. The routine always checks the status of stderr before writing to it; if for some reason stderr has become closed or blocked, so that writes to stderr are failing, errprintf will reopen stderr as /dev/console. This means that errprintf is likely to be more robust than a simple fprintf when the machine is very confused. (Such events are extremely rare, except for demons started at reboot time which must write to /dev/console; this condition is chronic for those demons, and their output will generally be lost unless they use errprintf or something like it.) The liberrors library includes a function safefprintf, which is called by errprintf, and behaves just like fprintf except that it reopens the file pointer you give it to be /dev/console if it turns out to be unwritable.} \section{\smaller{Examples}} \leftindent{The first example will cause an error message for the program "myprog" consisting of "foo bar" to be sent to console with CRITICAL priority, no logging, and no official ID: \programexample{errprintf("myprog", 0, 0, 0, "foo %s bar", s);} The next example will cause the same error message to print out only on the consoles of those users who monitor the "MONITOR" messages, and will also log the error by sending mail to Jim Morris: \programexample{errprintf("myprog", ERR_MONITOR, "jhm", 0, "foo %s bar", s);} } \section{\smaller{Bugs}} \leftindent{The message produced from your control string and arguments is limited to 500 characters at present. Reopening /dev/console isn't always right, but no better solution is obvious. errprintf and safeprintf do not understand more than 20 arguments following the control formatting string.} \section{\smaller{Related tools }} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" to see the help document for: \leftindent{ \italic{\helptopic{console} }} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,1119,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538945640}