<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: System Call Functions</TITLE>
<LINK HREF="slangfun-15.html" REL=next>
<LINK HREF="slangfun-13.html" REL=previous>
<LINK HREF="slangfun.html#toc14" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-15.html">Next</A>
<A HREF="slangfun-13.html">Previous</A>
<A HREF="slangfun.html#toc14">Contents</A>
<HR>
<H2><A NAME="s14">14. System Call Functions</A></H2>
<P>
<H2><A NAME="errno"></A> <A NAME="ss14.1">14.1 <B>errno</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Error code set by system functions.
<DT><B> Usage </B><DD><P><CODE>Integer_Type errno</CODE>
<DT><B> Description </B><DD><P>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 <CODE>-1</CODE> and set the variable <CODE>errno</CODE> to an error
code describing the reason for failure.
<P>Particular values of <CODE>errno</CODE> may be specified by the following
symbolic constants (read-only variables) and the corresponding
<CODE>errno_string</CODE> value:
<BLOCKQUOTE><CODE>
<PRE>
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"
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Example </B><DD><P>The <CODE>mkdir</CODE> function will attempt to create a directory. If
that directory already exists, the function will fail and set
<CODE>errno</CODE> to <CODE>EEXIST</CODE>.
<BLOCKQUOTE><CODE>
<PRE>
define create_dir (dir)
{
if (0 == mkdir (dir)) return;
if (errno != EEXIST)
error ("mkdir %s failied: %s", dir, errno_string);
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>errno_string, error, mkdir</CODE>
</DL>
<P>
<P>
<H2><A NAME="errno_string"></A> <A NAME="ss14.2">14.2 <B>errno_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Return a string describing an errno.
<DT><B> Usage </B><DD><P><CODE>String_Type errno_string (Integer_Type err)</CODE>
<DT><B> Description </B><DD><P>The <CODE>errno_string</CODE> function returns a string describing the
integer error code <CODE>err</CODE>. The variable <CODE>err</CODE> usually
corresponds to the <CODE>errno</CODE> intrinsic function. See the
description for <CODE>errno</CODE> for more information.
<DT><B> Example </B><DD><P>The <CODE>errno_string</CODE> function may be used as follows:
<BLOCKQUOTE><CODE>
<PRE>
define sizeof_file (file)
{
variable st = stat (file);
if (st == NULL)
verror ("%s: %s", file, errno_string (errno);
return st.st_size;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>errno, stat, verror</CODE>
</DL>
<P>
<P>
<H2><A NAME="getegid"></A> <A NAME="ss14.3">14.3 <B>getegid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the effective group id
<DT><B> Usage </B><DD><P><CODE>Int_Type getegid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getegid</CODE> function returns the effective group ID of the
current process.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getgid, geteuid, setgid</CODE>
</DL>
<P>
<P>
<H2><A NAME="geteuid"></A> <A NAME="ss14.4">14.4 <B>geteuid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the effective user-id of the current process
<DT><B> Usage </B><DD><P><CODE>Int_Type geteuid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>geteuid</CODE> function returns the effective user-id of the
current process.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getuid, setuid, setgid</CODE>
</DL>
<P>
<P>
<H2><A NAME="getgid"></A> <A NAME="ss14.5">14.5 <B>getgid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the group id
<DT><B> Usage </B><DD><P><CODE>Integer_Type getgid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getgid</CODE> function returns the real group id of the current
process.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getpid, getppid</CODE>
</DL>
<P>
<P>
<H2><A NAME="getpid"></A> <A NAME="ss14.6">14.6 <B>getpid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the current process id
<DT><B> Usage </B><DD><P><CODE>Integer_Type getpid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getpid</CODE> function returns the current process identification
number.
<DT><B> See Also </B><DD><P><CODE>getppid, getgid</CODE>
</DL>
<P>
<P>
<H2><A NAME="getppid"></A> <A NAME="ss14.7">14.7 <B>getppid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the parent process id
<DT><B> Usage </B><DD><P><CODE>Integer_Type getppid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getpid</CODE> function returns the process identification
number of the parent process.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getpid, getgid</CODE>
</DL>
<P>
<P>
<H2><A NAME="getuid"></A> <A NAME="ss14.8">14.8 <B>getuid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the user-id of the current process
<DT><B> Usage </B><DD><P><CODE>Int_Type getuid ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getuid</CODE> function returns the user-id of the current
process.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getuid, getegid</CODE>
</DL>
<P>
<P>
<H2><A NAME="kill"></A> <A NAME="ss14.9">14.9 <B>kill</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Send a signal to a process
<DT><B> Usage </B><DD><P><CODE>Integer_Type kill (Integer_Type pid, Integer_Type sig)</CODE>
<DT><B> Description </B><DD><P>This function may be used to send a signal given by the integer <CODE>sig</CODE>
to the process specified by <CODE>pid</CODE>. The function returns zero upon
sucess and <CODE>-1</CODE> upon failure setting errno accordingly.
<DT><B> Example </B><DD><P>The <CODE>kill</CODE> function may be used to determine whether or not
a specific process exists:
<BLOCKQUOTE><CODE>
<PRE>
define process_exists (pid)
{
if (-1 == kill (pid, 0))
return 0; % Process does not exist
return 1;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getpid</CODE>
</DL>
<P>
<P>
<H2><A NAME="mkfifo"></A> <A NAME="ss14.10">14.10 <B>mkfifo</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Create a named pipe
<DT><B> Usage </B><DD><P><CODE>Int_Type mkfifo (String_Type name, Int_Type mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>mkfifo</CODE> attempts to create a named pipe with the specified
name and mode (modified by the process's umask). The function
returns <CODE>0</CODE> upon success, or <CODE>-1</CODE> and sets <CODE>errno</CODE> upon failure.
<DT><B> Notes </B><DD><P>Not all systems support the <CODE>mkfifo</CODE> function and even on
systems that do implement the <CODE>mkfifo</CODE> system call, the
underlying file system may not support the concept of a named pipe,
e.g, an NFS filesystem.
<DT><B> See Also </B><DD><P><CODE>stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="setgid"></A> <A NAME="ss14.11">14.11 <B>setgid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set the group-id of the current process
<DT><B> Usage </B><DD><P><CODE>Int_Type setgid (Int_Type gid)</CODE>
<DT><B> Description </B><DD><P>The <CODE>setgid</CODE> function sets the effective group-id of the current
process. It returns zero upon success, or <CODE>-1</CODE> upon error and sets
<CODE>errno</CODE> appropriately.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>getgid, setuid</CODE>
</DL>
<P>
<P>
<H2><A NAME="setpgid"></A> <A NAME="ss14.12">14.12 <B>setpgid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set the process group-id
<DT><B> Usage </B><DD><P><CODE>Int_Type setpgid (Int_Type pid, Int_Type gid)</CODE>
<DT><B> Description </B><DD><P>The <CODE>setpgid</CODE> function sets the group-id <CODE>gid</CODE> of the
process whose process-id is <CODE>pid</CODE>. If <CODE>pid</CODE> is <CODE>0</CODE>, then the
current process-id will be used. If <CODE>pgid</CODE> is <CODE>0</CODE>, then the pid
of the affected process will be used.
<P>If successful zero will be returned, otherwise the function will
return <CODE>-1</CODE> and set <CODE>errno</CODE> accordingly.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>setgid, setuid</CODE>
</DL>
<P>
<P>
<H2><A NAME="setuid"></A> <A NAME="ss14.13">14.13 <B>setuid</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set the user-id of the current process
<DT><B> Usage </B><DD><P><CODE>Int_Type setuid (Int_Type id)</CODE>
<DT><B> Description </B><DD><P>The <CODE>setuid</CODE> function sets the effective user-id of the current
process. It returns zero upon success, or <CODE>-1</CODE> upon error and sets
<CODE>errno</CODE> appropriately.
<DT><B> Notes </B><DD><P>This function is not supported by all systems.
<DT><B> See Also </B><DD><P><CODE>setgid, setpgid, getuid, geteuid</CODE>
</DL>
<P>
<P>
<H2><A NAME="sleep"></A> <A NAME="ss14.14">14.14 <B>sleep</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Pause for a specified number of seconds
<DT><B> Usage </B><DD><P><CODE>sleep (Double_Type n)</CODE>
<DT><B> Description </B><DD><P>The <CODE>sleep</CODE> function delays the current process for the
specified number of seconds. If it is interrupted by a signal, it
will return prematurely.
<DT><B> Notes </B><DD><P>Not all system support sleeping for a fractional part of a second.
</DL>
<P>
<P>
<H2><A NAME="system"></A> <A NAME="ss14.15">14.15 <B>system</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Execute a shell command
<DT><B> Usage </B><DD><P><CODE>Integer_Type system (String_Type cmd)</CODE>
<DT><B> Description </B><DD><P>The <CODE>system</CODE> function may be used to execute the string
expression <CODE>cmd</CODE> in an inferior shell. This function is an
interface to the C <CODE>system</CODE> function which returns an
implementation-defined result. On Linux, it returns 127 if the
inferior shell could not be invoked, -1 if there was some other
error, otherwise it returns the return code for <CODE>cmd</CODE>.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
define dir ()
{
() = system ("DIR");
}
</PRE>
</CODE></BLOCKQUOTE>
displays a directory listing of the current directory under MSDOS or
VMS.
<DT><B> See Also </B><DD><P><CODE>popen, listdir</CODE>
</DL>
<P>
<P>
<H2><A NAME="umask"></A> <A NAME="ss14.16">14.16 <B>umask</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set the file creation mask
<DT><B> Usage </B><DD><P><CODE>Int_Type umask (Int_Type m)</CODE>
<DT><B> Description </B><DD><P>The <CODE>umask</CODE> function sets the file creation mask to <CODE>m</CODE> and
returns the previous mask.
<DT><B> See Also </B><DD><P><CODE>stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="uname"></A> <A NAME="ss14.17">14.17 <B>uname</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the system name
<DT><B> Usage </B><DD><P><CODE>Struct_Tye uname ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>uname</CODE> function returns a structure containing information
about the operating system. The structure contains the following
fields:
<BLOCKQUOTE><CODE>
<PRE>
sysname (Name of the operating system)
nodename (Name of the node within the network)
release (Release level of the OS)
version (Current version of the release)
machine (Name of the hardware)
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Not all systems support this function.
<DT><B> See Also </B><DD><P><CODE>getenv, pack, unpack</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-15.html">Next</A>
<A HREF="slangfun-13.html">Previous</A>
<A HREF="slangfun.html#toc14">Contents</A>
</BODY>
</HTML>
