Error code set by system functions
Int_Type errno
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"
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));
Return a string describing an errno.
String_Type errno_string ( [Int_Type err ])
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.
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;
}
Generate an error condition (deprecated)
error (String_Type msg)
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.
define add_txt_extension (file)
{
if (typeof (file) != String_Type)
error ("add_extension: parameter must be a string");
file += ".txt";
return file;
}
Get information about the current exception
Struct_Type __get_exception_info ()
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
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);
}
Print a string onto the message device
message (String_Type s)
The message function will print the string specified by
s onto the message device.
define print_current_time ()
{
message (time ());
}
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.
Create a new exception
new_exception (String_Type name, Int_Type baseclass, String_Type descr)
This function creates a new exception called name subclassed
upon baseclass. The description of the exception is
specified by descr.
new_exception ("MyError", RunTimeError, "My very own error");
try
{
if (something_is_wrong ())
throw MyError;
}
catch RunTimeError;
RunTimeError will also catch
MyError since it is a subclass of RunTimeError.
Generate a usage error
usage (String_Type msg)
The usage function generates a UsageError exception and
displays msg to the message device.
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
.
.
}
Generate an error condition (deprecated)
verror (String_Type fmt, ...)
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.
define open_file (file)
{
variable fp;
fp = fopen (file, "r");
if (fp == NULL) verror ("Unable to open %s", file);
return fp;
}
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"$;
verror in the above example.
Print a formatted string onto the message device
vmessage (String_Type fmt, ...)
The vmessage function formats a sprintf style argument list
and displays the resulting string onto the message device.
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.