Next Previous Contents

11. Message and Error Functions

11.1 errno

Synopsis

Error code set by system functions

Usage

Int_Type errno

Description

A system function can fail for a variety of reasons. For example, a file operation may fail because lack of disk space, or the process does not have permission to perform the operation. Such functions will return -1 and set the variable errno to an error code describing the reason for failure.

Particular values of errno may be specified by the following symbolic constants (read-only variables) and the corresponding errno_string value:

     E2BIG            "Arg list too long"
     EACCES           "Permission denied"
     EBADF            "Bad file number"
     EBUSY            "Mount device busy"
     ECHILD           "No children"
     EEXIST           "File exists"
     EFAULT           "Bad address"
     EFBIG            "File too large"
     EINTR            "Interrupted system call"
     EINVAL           "Invalid argument"
     EIO              "I/O error"
     EISDIR           "Is a directory"
     ELOOP            "Too many levels of symbolic links"
     EMFILE           "Too many open files"
     EMLINK           "Too many links"
     ENAMETOOLONG     "File name too long"
     ENFILE           "File table overflow"
     ENODEV           "No such device"
     ENOENT           "No such file or directory"
     ENOEXEC          "Exec format error"
     ENOMEM           "Not enough core"
     ENOSPC           "No space left on device"
     ENOTBLK          "Block device required"
     ENOTDIR          "Not a directory"
     ENOTEMPTY        "Directory not empty"
     ENOTTY           "Not a typewriter"
     ENXIO            "No such device or address"
     EPERM            "Operation not permitted"
     EPIPE            "Broken pipe"
     EROFS            "Read-only file system"
     ESPIPE           "Illegal seek"
     ESRCH            "No such process"
     ETXTBSY          "Text file busy"
     EXDEV            "Cross-device link"

Example

The mkdir function will attempt to create a directory. If it fails, the function will throw an IOError exception with a message containing the string representation of the errno value.

    if (-1 == mkdir (dir))
       throw IOError, sprintf ("mkdir %s failed: %s",
                               dir, errno_string (errno));

See Also

errno_string, error, mkdir

11.2 errno_string

Synopsis

Return a string describing an errno.

Usage

String_Type errno_string ( [Int_Type err ])

Description

The errno_string function returns a string describing the integer errno code err. If the err parameter is omitted, the current value of errno will be used. See the description for errno for more information.

Example

The errno_string function may be used as follows:

    define sizeof_file (file)
    {
       variable st = stat_file (file);
       if (st == NULL)
         throw IOError, sprintf ("%s: %s", file, errno_string (errno));
       return st.st_size;
    }

See Also

errno, stat_file

11.3 error

Synopsis

Generate an error condition (deprecated)

Usage

error (String_Type msg)

Description

This function has been deprecated in favor of throw.

The error function generates a S-Lang RunTimeError exception. It takes a single string parameter which is displayed on the stderr output device.

Example

    define add_txt_extension (file)
    {
       if (typeof (file) != String_Type)
         error ("add_extension: parameter must be a string");
       file += ".txt";
       return file;
    }

See Also

verror, message

11.4 __get_exception_info

Synopsis

Get information about the current exception

Usage

Struct_Type __get_exception_info ()

Description

This function returns information about the currently active exception in the form as a structure with the following fields:

    error            The current exception, e.g., RunTimeError
    descr            A description of the exception
    file             Name of the file generating the exception
    line             Line number where the exception originated
    function         Function where the exception originated
    object           A user-defined object thrown by the exception
    message          A user-defined message
    traceback        Traceback messages
If no exception is active, NULL will be returned.

This same information may also be obtained via the optional argument to the try statement:

     variable e = NULL;
     try (e)
       {
          do_something ();
       }
     finally
       {
          if (e != NULL)
            vmessage ("An error occurred: %s", e.message);
       }

See Also

error

11.5 message

Synopsis

Print a string onto the message device

Usage

message (String_Type s)

Description

The message function will print the string specified by s onto the message device.

Example

     define print_current_time ()
     {
       message (time ());
     }

Notes

The message device will depend upon the application. For example, the output message device for the jed editor corresponds to the line at the bottom of the display window. The default message device is the standard output device.

See Also

vmessage, sprintf, error

11.6 new_exception

Synopsis

Create a new exception

Usage

new_exception (String_Type name, Int_Type baseclass, String_Type descr)

Description

This function creates a new exception called name subclassed upon baseclass. The description of the exception is specified by descr.

Example

  new_exception ("MyError", RunTimeError, "My very own error");
  try
    {
       if (something_is_wrong ())
         throw MyError;
    }
  catch RunTimeError;
In this case, catching RunTimeError will also catch MyError since it is a subclass of RunTimeError.

See Also

error, verror

11.7 usage

Synopsis

Generate a usage error

Usage

usage (String_Type msg)

Description

The usage function generates a UsageError exception and displays msg to the message device.

Example

Suppose that a function called plot plots an array of x and y values. Then such a function could be written to issue a usage message if the wrong number of arguments was passed:

    define plot ()
    {
       variable x, y;

       if (_NARGS != 2)
         usage ("plot (x, y)");

       (x, y) = ();
       % Now do the hard part
          .
          .
    }

See Also

error, message

11.8 verror

Synopsis

Generate an error condition (deprecated)

Usage

verror (String_Type fmt, ...)

Description

This function has been deprecated in favor or throw.

The verror function performs the same role as the error function. The only difference is that instead of a single string argument, verror takes a sprintf style argument list.

Example

    define open_file (file)
    {
       variable fp;

       fp = fopen (file, "r");
       if (fp == NULL) verror ("Unable to open %s", file);
       return fp;
    }

Notes

In the current implementation, the verror function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of sprintf and error.

To generate a specific exception, a throw statement should be used. In fact, a throw statement such as:

     if (fp == NULL)
       throw OpenError, "Unable to open $file"$;
is preferable to the use of verror in the above example.

See Also

error, Sprintf, vmessage

11.9 vmessage

Synopsis

Print a formatted string onto the message device

Usage

vmessage (String_Type fmt, ...)

Description

The vmessage function formats a sprintf style argument list and displays the resulting string onto the message device.

Notes

In the current implementation, the vmessage function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of Sprintf and message.

See Also

message, sprintf, Sprintf, verror


Next Previous Contents