.\"$Id: uderrmsg.3,v 1.1 2000/08/07 23:15:04 emmerson Exp $
.\"
.\" $__Header$
.\"
.TH UDERRMSG 3 "20 September 1990" "Printed: \n(yr.\n(mo.\n(dy" "UNIDATA LIBRARY FUNCTIONS"
.SH NAME
uderrmsg, uderrmode, uderrname, uderror, udadvise, udtime_stamp \- Unidata error-messaging package
.SH SYNOPSIS
.nf
.ft B
.ta \w'extern int 'u +\w'udtime_stamp 'u
#include "uderrmsg.h"
.sp
int	uderrmode(const int mode);
char*	uderrname(const char *name);
void	uderror(const char *fmt, ...);
void	udadvise(const char *fmt, ...);
char*	udtime_stamp(void);
.sp
#define	UD_FATAL
#define	UD_VERBOSE
.ft
.fi
.SH DESCRIPTION
.LP
These routines implement the Unidata error-messaging mechanism and
should be used by all Unidata-conforming software.
.LP
.B uderrmode(\|)
sets the mode of the error-messaging package and
returns the previous mode.
The mode is the bitwise or of zero or more of the following
bit-set macro-constants.
Setting a mode-bit enables the action and vice versa.
.sp
.RS +4
.IP \fBUD_FATAL\fP +8
\fBuderror()\fP and \fBudadvise()\fP will abort the program after printing
any error message.
.IP \fBUD_VERBOSE\fP
\fBuderror()\fP and \fBudadvise()\fP will print all messages.
.RE
.sp
The default is \fBUD_FATAL | UD_VERBOSE\fP.
.LP
.B uderrname(\|)
sets the program name to be used in all messages and returns the previous
name.
It should be called once at the beginning of each program using, for
example, \fBargv[0]\fP for the argument.
(the \fBudres\fP(3) function \fBudinit()\fP does this for you).
.LP
.B uderror(\|)
prints a system error message on stderr if, and only if, the UD_VERBOSE
mode-bit is set.
This routine is used in place of \fBperror(3)\fP and should be called 
when a system function returns an error status.
The error message will consist of the program name, the error message
supplied as arguments to \fBuderror()\fP, the system error message, and
the system error number.
The argument syntax is the same as for \fBprintf\fP(3).
If the error-messaging package has the UD_FATAL mode-bit set,
then this routine will abort after printing the message.
.sp
"\fBerrno\fP" is cleared before returning.
.sp
If "\fBstderr\fP" is not a "\fBtty\fP", then the error message
will be prefixed by a time-stamp.
.LP
.B udadvise(\|)
prints on stderr an error message consisting of \fIfmt\fP and any other
arguments if, and only if, the UD_VERBOSE mode-bit is set.
The syntax is the same as for \fBprintf\fP(3).
If the error-messaging package has the UD_FATAL mode-bit set,
then this routine will abort after printing the message.
.sp
If "\fBstderr\fP" is not a "\fBtty\fP", then the error message
will be prefixed by a time-stamp.
.LP
.B udtime_stamp(\|)
returns a pointer to a static buffer containing a 0-terminated string
of the current time in the Unidata-standard format.
.SH EXAMPLE
.LP
If "\fBuderrname\fP" has been called with argument "\fBfoobar\fP", then
the following code
.sp
.RS +4
.nf
.ta 4n +4n
#include "guise.h"
#include "uderrmsg.h"
\&...
output()
{
	static char me[] = "output"; /* This routine's name */
\&...
uderrmode(UD_VERBOSE);
if (!allowed) {
	udadvise("%s: Writing to output file not allowed", me);
} else if (write(fd, buf, nbyte) == -1) {
	uderror(me);
	udadvise("%s: Couldn't write %d bytes to output file", me, nbyte);
} else {
\&...
.fi
.RE
.sp
will print the following error message if "\fBallowed\fP" is false:
.sp
.RS +4
foobar: output: Writing to output file not allowed
.RE
.sp
and might print the following error message if the \fBwrite(2)\fP fails:
.sp
.RS +4
.nf
foobar: output: no space left on device (errno=28)
foobar: output: Couldn't write 100000 bytes to output file
.fi
.RE
.SH "SEE ALSO"
.BR udres (3),
.BR udape (3).