S-Lang Run-Time Library Reference: Version 1.4.0: System Call Functions

Next Previous Contents

## 14. System Call Functions

## 14.1 errno

Synopsis

  Error code set by system functions.

Usage

  `Integer_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)
  >              error ("mkdir %s failied: %s", dir, errno_string);
  >         }

  > `

See Also

  `errno_string, error, mkdir`

## 14.2 errno_string

Synopsis

  Return a string describing an errno.

Usage

  `String_Type errno_string (Integer_Type err)`

Description

  The `errno_string` function returns a string describing the integer error code `err`. The variable `err` usually corresponds to the `errno` intrinsic function. 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);
  >            if (st == NULL)
  >              verror ("%s: %s", file, errno_string (errno);
  >            return st.st_size;
  >         }

  > `

See Also

  `errno, stat, verror`

## 14.3 getegid

Synopsis

  Get the effective group id

Usage

  `Int_Type getegid ()`

Description

  The `getegid` function returns the effective group ID of the current process.

Notes

  This function is not supported by all systems.

See Also

  `getgid, geteuid, setgid`

## 14.4 geteuid

Synopsis

  Get the effective user-id of the current process

Usage

  `Int_Type geteuid ()`

Description

  The `geteuid` function returns the effective user-id of the current process.

Notes

  This function is not supported by all systems.

See Also

  `getuid, setuid, setgid`

## 14.5 getgid

Synopsis

  Get the group id

Usage

  `Integer_Type getgid ()`

Description

  The `getgid` function returns the real group id of the current process.

Notes

  This function is not supported by all systems.

See Also

  `getpid, getppid`

## 14.6 getpid

Synopsis

  Get the current process id

Usage

  `Integer_Type getpid ()`

Description

  The `getpid` function returns the current process identification number.

See Also

  `getppid, getgid`

## 14.7 getppid

Synopsis

  Get the parent process id

Usage

  `Integer_Type getppid ()`

Description

  The `getpid` function returns the process identification number of the parent process.

Notes

  This function is not supported by all systems.

See Also

  `getpid, getgid`

## 14.8 getuid

Synopsis

  Get the user-id of the current process

Usage

  `Int_Type getuid ()`

Description

  The `getuid` function returns the user-id of the current process.

Notes

  This function is not supported by all systems.

See Also

  `getuid, getegid`

## 14.9 kill

Synopsis

  Send a signal to a process

Usage

  `Integer_Type kill (Integer_Type pid, Integer_Type sig)`

Description

  This function may be used to send a signal given by the integer `sig` to the process specified by `pid`. The function returns zero upon sucess and `-1` upon failure setting errno accordingly.

Example

  The `kill` function may be used to determine whether or not a specific process exists:

  > `

  >         define process_exists (pid)
  >         {
  >            if (-1 == kill (pid, 0))
  >              return 0;     % Process does not exist
  >            return 1;
  >         }

  > `

Notes

  This function is not supported by all systems.

See Also

  `getpid`

## 14.10 mkfifo

Synopsis

  Create a named pipe

Usage

  `Int_Type mkfifo (String_Type name, Int_Type mode)`

Description

  The `mkfifo` attempts to create a named pipe with the specified name and mode (modified by the process's umask). The function returns `0` upon success, or `-1` and sets `errno` upon failure.

Notes

  Not all systems support the `mkfifo` function and even on systems that do implement the `mkfifo` system call, the underlying file system may not support the concept of a named pipe, e.g, an NFS filesystem.

See Also

  `stat_file`

## 14.11 setgid

Synopsis

  Set the group-id of the current process

Usage

  `Int_Type setgid (Int_Type gid)`

Description

  The `setgid` function sets the effective group-id of the current process. It returns zero upon success, or `-1` upon error and sets `errno` appropriately.

Notes

  This function is not supported by all systems.

See Also

  `getgid, setuid`

## 14.12 setpgid

Synopsis

  Set the process group-id

Usage

  `Int_Type setpgid (Int_Type pid, Int_Type gid)`

Description

  The `setpgid` function sets the group-id `gid` of the process whose process-id is `pid`. If `pid` is `0`, then the current process-id will be used. If `pgid` is `0`, then the pid of the affected process will be used.

  If successful zero will be returned, otherwise the function will return `-1` and set `errno` accordingly.

Notes

  This function is not supported by all systems.

See Also

  `setgid, setuid`

## 14.13 setuid

Synopsis

  Set the user-id of the current process

Usage

  `Int_Type setuid (Int_Type id)`

Description

  The `setuid` function sets the effective user-id of the current process. It returns zero upon success, or `-1` upon error and sets `errno` appropriately.

Notes

  This function is not supported by all systems.

See Also

  `setgid, setpgid, getuid, geteuid`

## 14.14 sleep

Synopsis

  Pause for a specified number of seconds

Usage

  `sleep (Double_Type n)`

Description

  The `sleep` function delays the current process for the specified number of seconds. If it is interrupted by a signal, it will return prematurely.

Notes

  Not all system support sleeping for a fractional part of a second.

## 14.15 system

Synopsis

  Execute a shell command

Usage

  `Integer_Type system (String_Type cmd)`

Description

  The `system` function may be used to execute the string expression `cmd` in an inferior shell. This function is an interface to the C `system` 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 `cmd`.

Example

  > `

  >         define dir ()
  >         {
  >            () = system ("DIR");
  >         }

  > `

  displays a directory listing of the current directory under MSDOS or VMS.
See Also

  `popen, listdir`

## 14.16 umask

Synopsis

  Set the file creation mask

Usage

  `Int_Type umask (Int_Type m)`

Description

  The `umask` function sets the file creation mask to `m` and returns the previous mask.

See Also

  `stat_file`

## 14.17 uname

Synopsis

  Get the system name

Usage

  `Struct_Tye uname ()`

Description

  The `uname` function returns a structure containing information about the operating system. The structure contains the following fields:

  > `

  >            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)

  > `

Notes

  Not all systems support this function.

See Also

  `getenv, pack, unpack`

Next Previous Contents