\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 *<everything else>


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 <contents of string s> 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}
