NAME

       uderrmsg,  uderrmode, uderrname, uderror, udadvise, udtime_stamp - Unidata error-messaging
       package

SYNOPSIS

       #include "uderrmsg.h"

       int        uderrmode(const int mode);
       char*      uderrname(const char *name);
       void       uderror(const char *fmt, ...);
       void       udadvise(const char *fmt, ...);
       char*      udtime_stamp(void);

       #define    UD_FATAL
       #define    UD_VERBOSE

DESCRIPTION

       These routines implement the Unidata error-messaging mechanism and should be used  by  all
       Unidata-conforming software.

       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.

           UD_FATAL
                   uderror()  and  udadvise()  will  abort  the  program after printing any error
                   message.

           UD_VERBOSE
                   uderror() and udadvise() will print all messages.

       The default is UD_FATAL | UD_VERBOSE.

       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,
       argv[0] for the argument.  (the udres(3) function udinit() does this for you).

       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 perror(3) 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 uderror(), the system error message, and the system
       error number.  The argument syntax is the same as for printf(3).  If  the  error-messaging
       package  has  the  UD_FATAL  mode-bit set, then this routine will abort after printing the
       message.

       "errno" is cleared before returning.

       If "stderr" is not a "tty", then the error message will be prefixed by a time-stamp.

       udadvise() prints on stderr an error message consisting of fmt and any other arguments if,
       and only if, the UD_VERBOSE mode-bit is set.  The syntax is the same as for printf(3).  If
       the error-messaging package has the UD_FATAL mode-bit set, then this  routine  will  abort
       after printing the message.

       If "stderr" is not a "tty", then the error message will be prefixed by a time-stamp.

       udtime_stamp()  returns  a  pointer to a static buffer containing a 0-terminated string of
       the current time in the Unidata-standard format.

EXAMPLE

       If "uderrname" has been called with argument "foobar", then the following code

           #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 {
           ...

       will print the following error message if "allowed" is false:

           foobar: output: Writing to output file not allowed

       and might print the following error message if the write(2) fails:

           foobar: output: no space left on device (errno=28)
           foobar: output: Couldn't write 100000 bytes to output file

SEE ALSO

       udres(3), udape(3).