S-Lang Run-Time Library Reference: Version 2.0.4: Message and Error Functions

Next Previous Contents

## 10. Message and Error Functions

## 10.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:

  > `

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

  > `

Example

  The `mkdir` function will attempt to create a directory. If that directory already exists, the function will fail and set `errno` to `EEXIST`.

  > `

  >         define create_dir (dir)
  >         {
  >            if (0 == mkdir (dir)) return;
  >            if (errno != EEXIST)
  >              throw IOError, sprintf ("mkdir %s failed: %s",
  >                                       dir, errno_string (errno));
  >         }

  > `

See Also

  `errno_string, error, mkdir`

## 10.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`

## 10.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`

## 10.4 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`

## 10.5 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`

## 10.6 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`

## 10.7 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`

## 10.8 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