Next Previous Contents

19. System Call Functions

19.1 getegid

Synopsis

Get the effective group id of the current process

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

19.2 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

19.3 getgid

Synopsis

Get the group id of the current process

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

19.4 getpgid

Synopsis

Get the process group id

Usage

Int_Type getpgid (Int_Type pid)

Description

The getpgid function returns the process group id of the process whose process is pid. If pid is 0, then the current process will be used.

Notes

This function is not supported by all systems.

See Also

getpgrp, getpid, getppid

19.5 getpgrp

Synopsis

Get the process group id of the calling process

Usage

Int_Type getpgrp ()

Description

The getpgrp function returns the process group id of the current process.

Notes

This function is not supported by all systems.

See Also

getpgid, getpid, getppid

19.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

19.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

19.8 getpriority

Synopsis

Get a process's scheduling priority

Usage

result = getpriority (which, who)

Description

The setpriority function may be used to obtain the kernel's scheduling priority for a process, process group, or a user depending upon the values of the which and who parameters. Specifically, if the value of which is PRIO_PROCESS, then the value of who specifies the process id of the affected process. If which is PRIO_PGRP, then who specifies a process group id. If which is PRIO_USER, then the value of who is interpreted as a user id. For the latter two cases, where which refers to a set of processes, the value returned corresponds to the highest priority of a process in the set. A value of 0 may be used for who to denote the process id, process group id, or real user ID of the current process.

Upon success, the function returns the specified priority value. If an error occurs, the function will return NULL with errno set accordingly.

See Also

setpriority, getpid, getppid

19.9 getrusage

Synopsis

Get process resource usage

Usage

Struct_Type getrusage ([Int_Type who]

Description

This function returns a structure whose fields contain information about the resource usage of calling process, summed over all threads of the process. The optional integer argument who may be used to obtain resource usage of child processes, or of the calling thread itself. Specifically, the optional integer argument who may take on one of the following values:

    RUSAGE_SELF (default)
    RUSAGE_CHILDREN
If RUSAGE_CHILDREN is specified, then the process information will be the sum of all descendents of the calling process that have terminated and have been waited for (via, e.g., waitpid). It will not contain any information about child processes that have not terminated.

The structure that is returned will contain the following fields:

   ru_utimesecs       user CPU time used (Double_Type secs)
   ru_stimesecs       system CPU time used (Double_Type secs)
   ru_maxrss          maximum resident_set_size
   ru_minflt          page reclaims (soft page faults)
   ru_majflt          page faults (hard page faults)
   ru_inblock         block input operations
   ru_oublock         block output operations
   ru_nvcsw           voluntary context switches
   ru_nivcsw          involuntary context switches
   ru_ixrss           integral shared memory size
   ru_idrss           integral unshared data size
   ru_isrss           integral unshared stack size
   ru_nswap           swaps
   ru_msgsnd          IPC messages sent
   ru_msgrcv          IPC messages received
   ru_nsignals        signals received
Some of the fields may not be supported for a particular OS or kernel version. For example, on Linux the 2.6.32 kernel supports only the following fields:
    ru_utimesecs
    ru_stimesecs
    ru_maxrss (since Linux 2.6.32)
    ru_minflt
    ru_majflt
    ru_inblock (since Linux 2.6.22)
    ru_oublock (since Linux 2.6.22)
    ru_nvcsw (since Linux 2.6)
    ru_nivcsw (since Linux 2.6)

Notes

The underlying system call returns the CPU user and system times as C struct timeval objects. For convenience, the interpreter interface represents these objects as double precision floating point values.

See Also

times

19.10 getsid

Synopsis

get the session id of a process

Usage

Int_Type getsid ([Int_Type pid])

Description

The getsid function returns the session id of the current process. If the optional integer pid argument is given, then the function returns the session id of the specified process id.

See Also

setsid, getpid, getpid

19.11 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

19.12 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 success or -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

killpg, getpid

19.13 killpg

Synopsis

Send a signal to a process group

Usage

Integer_Type killpg (Integer_Type pgrppid, Integer_Type sig)

Description

This function may be used to send a signal given by the integer sig to the process group specified by pgrppid. The function returns zero upon success or -1 upon failure setting errno accordingly.

Notes

This function is not supported by all systems.

See Also

kill, getpid

19.14 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

19.15 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

19.16 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 0 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

19.17 setpriority

Synopsis

Set the scheduling priority for a process

Usage

Int_Type setpriority (which, who, prio)

Description

The setpriority function may be used to set the kernel's scheduling priority for a process, process group, or a user depending upon the values of the which and who parameters. Specifically, if the value of which is PRIO_PROCESS, then the value of who specifies the process id of the affected process. If which is PRIO_PGRP, then who specifies a process group id. If which is PRIO_USER, then the value of who is interpreted as a user id. A value of 0 may be used for who to denote the process id, process group id, or real user ID of the current process.

Upon sucess, the setpriority function returns 0. If an error occurs, -1 is returned and errno will be set accordingly.

Example

The getpriority and setpriority functions may be used to implement a nice function for incrementing the priority of the current process as follows:

   define nice (dp)
   {
      variable p = getpriority (PRIO_PROCESS, 0);
      if (p == NULL)
        return -1;
      variable s = setpriority (PRIO_PROCESS, 0, p + dp);
      if (s == -1)
        return -1;
      return getpriority (PRIO_PROCESS, 0);
   }

Notes

Priority values are sometimes called "nice" values. The actual range of priority values is system dependent but commonly range from -20 to 20, with -20 being the highest scheduling priority, and +20 the lowest.

See Also

getpriority, getpid

19.18 setsid

Synopsis

Create a new session for the current process

Usage

Int_Type setsid ()

Description

If the current process is not a session leader, the setsid function will create a new session and make the process the session leader for the new session. It returns the the process group id of the new session.

Upon failure, -1 will be returned and errno set accordingly.

See Also

getsid, setpgid

19.19 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

19.20 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.

19.21 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

system_intr, system_intr<@@ref>new_processnew_process, popen

19.22 system_intr

Synopsis

Execute a shell command

Usage

Integer_Type system_intr (String_Type cmd)

Description

The system_intr function performs the same task as the system function, except that the SIGINT signal will not be ignored by the calling process. This means that if a S-Lang script calls system_intr function, and Ctrl-C is pressed, both the command invoked by the system_intr function and the script will be interrupted. In contrast, if the command were invoked using the system function, only the command called by it would be interrupted, but the script would continue executing.

See Also

system, system<@@ref>new_processnew_process, popen

19.23 umask

Synopsis

Set the file creation mask

Usage

Int_Type umask (Int_Type m)

Description

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

See Also

stat_file

19.24 uname

Synopsis

Get the system name

Usage

Struct_Type 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


Next Previous Contents