uderror(3) Unidata error-messaging package

Other Alias

uderrmsg, uderrmode, uderrname, udadvise, udtime_stamp

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