oracular (3) uderrmsg.3.gz

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).