sysinfo - get system-specific information

SYNOPSIS

<sysinfo $what [$arg ...]>

DESCRIPTION
The sysinfo function obtains various system- or OS-level parameters. This information can be used to monitor the performance of large or long-running processes. The $what argument determines what is returned:

• time Returns the current wall-clock (real) time, in seconds since midnight Jan. 1 1970 GMT, as a double. Fractions of a second up to the system clock resolution are returned as well. This is the same value as a normal date, but with sub-second resolution. It can be printed and inserted as a date. Note: User and system time - obtainable with the proctime option - more accurately reflect the CPU utilization of a process. Also, the time needed to fetch a Web page is obtainable with options to urlinfo (here).

• proctime Returns user, system and real process times, in seconds since process start, as 3 double values. These are the number of seconds the process has spent actually running (user), doing system calls (system), and wall-clock time since process start (real). If the optional $arg argument is given, those values are first subtracted. This allows a certain section of the process to be measured, instead of the entire cumulative process time (see example below). On error, values of -1 are returned.

• procmem

  Returns virtual size and resident set size of the process, in bytes, as 2 long or int64 values. On error, or if the current OS is unsupported, values of -1 are returned. Although the exact definition varies by platform, the virtual size is typically the total memory used by the process (code, data and stack), and the resident set size is the amount of that memory currently in physical RAM (as opposed to disk swap).

• physmem

  Returns the amount of physical memory the system contains, in bytes, as a long or int64 value. If this cannot be determined, -1 is returned. Added in version 3.01.981000000 20010131.

• getpid or pid Returns the process ID, as an integer. Same as the getpid function (here).

• getppid or ppid Returns the parent process' ID, as an integer. Not supported for Windows.

• procexists For each process ID given in the $arg list, returns 1 if that process exists, 0 if not. Same as the procexists function (here).

• loadavg Returns the 3 system load averages as doubles, or -1 if unavailable or the OS is unsupported. Same as the loadavg function (here).

• cwd or pwd or getcwd Returns the current working directory of the process.

• platform Returns a string describing the hardware, vendor, OS and file bit size that this executable was created for, and is probably running on. Returned as 4 values separated by dashes. Added in version 3.01.980200000 20010122. Note that this may vary from the actual platform that is running, e.g. the revision of the OS.

• regquery $key $subkey $name [$default] Under Windows, queries the registry under the given $key and $subkey for the value associated with $name. $key must be one of the predefined HKEY_... values such as "HKEY_LOCAL_MACHINE". $subkey is generally a string "path". If there is no value defined, the $default value is returned if given. Under non-Windows platforms this function is unimplemented; the $default value is always returned. Added in version 3.01.976300000 20001208. regqueryvalue is an alias for regquery.

• umask Returns the process's umask, as a chmod-style symbolic string. Added in version 4.00.997400000 20010809.

• getenv $var Returns the value of environment variable named by $var. Note: Vortex variables are automatically initialized from environment variables; e.g. $PATH in Vortex contains the path from the environment. This call is less efficient, and should only be needed if environment variables have been changed since script start with syscp setenv. Added in version 4.00.997400000 20010809.

• freespace $path

  Returns the amount of free disk space in bytes for each filesystem in $path, as an int64 value. If the free space cannot be determined, -1 is returned. On some platforms an inaccurate value may be returned. Added in version 4.04.1080180000 20040324.

• hostname Returns the machine's hostname as configured. Added in version 4.04.1080000000 20040322.

• fullhostname Returns the machine's hostname, fully-qualified via DNS. Added in version 4.04.1080000000 20040322.

• user Returns the current user name running the script. Added in version 4.04.1072150000 20031222.

• maxdescriptors Returns the maximum number of open file descriptors possible, or -1 if unknown. Added in version 4.02.1037476167 20021116.

• opendescriptors Returns the current number of open file descriptors, or -1 if unknown. Added in version 4.02.1037476167 20021116.

DIAGNOSTICS
sysinfo returns various OS-level parameters depending on its first argument.

EXAMPLE
To obtain the CPU utilization of an entire script, call <sysinfo proctime> at the end. In this example, we time a single function call, <CPUhog>, while ignoring any previous or later functions:

... ignore time of earlier calls here ...
<sysinfo proctime>
<$start = $ret>
<CPUhog>
<sysinfo proctime $start>
CPUhog times: <LOOP $ret> $ret </LOOP>
...

CAVEATS
The sysinfo function was added in version 3.01.967500000 20000828.

Some options may be unavailable on some platforms, or may require additional user privileges (such as reading kernel memory). Vortex should not be run as root to obtain these privileges; use a lower privilege user that still has the required perms (e.g. kmem). No databases should be accessed when running as such a non-Texis user, to avoid making files inaccessible to other (Texis user) invocations of Vortex.

SEE ALSO
syscp, sysutil