OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.6 I/O | Up: 8 API Reference | 8.8 Pipe Input and Output > | 9 Release Notes >>

## 8.7 Operating System Helpers

#### 8.7.0.1 CMD_SWITCHES

    include std/os.e
    namespace os
    public constant CMD_SWITCHES

### 8.7.1 Operating System Constants

#### 8.7.1.1 WIN32

    include std/os.e
    namespace os
    public enum WIN32

#### 8.7.1.2 WINDOWS

    include std/os.e
    namespace os
    public enum WINDOWS

#### 8.7.1.3 LINUX

    include std/os.e
    namespace os
    public enum LINUX

#### 8.7.1.4 OSX

    include std/os.e
    namespace os
    public enum OSX

#### 8.7.1.5 OPENBSD

    include std/os.e
    namespace os
    public enum OPENBSD

#### 8.7.1.6 NETBSD

    include std/os.e
    namespace os
    public enum NETBSD

#### 8.7.1.7 FREEBSD

    include std/os.e
    namespace os
    public enum FREEBSD

These constants are returned by the platform function.

- `WIN32` -- Host operating system is Windows
- `LINUX` -- Host operating system is Linux
- `FREEBSD` -- Host operating system is FreeBSD
- `OSX` -- Host operating system is Mac OS X
- `OPENBSD` -- Host operating system is OpenBSD
- `NETBSD` -- Host operating system is NetBSD

##### Note:

In most situations you are better off to test the host platform by using the ifdef statement. It is faster.

### 8.7.2 Environment

#### 8.7.2.1 instance

    include std/os.e
    namespace os
    public function instance()

returns `hInstance` on Windows and Process ID (pid) on Unix.

##### Comments:

On Windows the `hInstance` can be passed around to various Windows routines.

#### 8.7.2.2 get_pid

    include std/os.e
    namespace os
    public function get_pid()

returns the ID of the current Process (pid).

##### Returns:

An atom: The current id for a process.

##### Example 1:

    mypid = get_pid()

#### 8.7.2.3 uname

    include std/os.e
    namespace os
    public function uname()

retrieves the name of the host OS.

##### Returns:

A sequence, starting with the OS name. If identification fails, returns an OS name of `UNKNOWN`. Extra information depends on the OS.

On Unix returns the same information as the `uname` syscall in the same order as the struct `utsname`. This information is:

    OS Name/Kernel Name
    Local Hostname
    Kernel Version/Kernel Release
    Kernel Specific Version information (This is usually the date that the
    kernel was compiled on and the name of the host that performed the compiling.)
    Architecture Name (Usually a string of i386 vs x86_64 vs ARM vs etc)

On Windows returns the following in order:

    Windows Platform (out of WinCE, Win9x, WinNT, Win32s, or Unknown Windows)
    Name of Windows OS (Windows 3.1, Win95, WinXP, etc)
    Platform Number
    Build Number
    Minor OS version number
    Major OS version number

On `UNKNOWN` returns an OS name of `"UNKNOWN"`. No other information is returned.

Returns an empty string of "" if an internal error has occured.

##### Comments:

On Unix `M_UNAME` is defined as a `machine_func` and this is passed to the C backend. If the `M_UNAME` call fails, the raw `machine_func` returns -1. On non-Unix platforms, calling the `machine_func` directly returns 0.

#### 8.7.2.4 is_win_nt

    include std/os.e
    namespace os
    public function is_win_nt()

reports whether the host system is a newer Windows version (NT/2K/XP/Vista).

##### Returns:

An integer, 1 if host system is a newer Windows (NT/2K/XP/Vista), else 0.

#### 8.7.2.5 getenv

    <built-in> function getenv(sequence var_name)

returns the value of an environment variable.

##### Parameters:

1. `var_name` : a string, the name of the variable being queried.

##### Returns:

An object, -1 if the variable does not exist, else a sequence holding its value.

##### Comments:

Both the argument and the return value, may, or may not be, case sensitive. You might need to test this on your own system.

##### Example 1:

    e = getenv("EUDIR")
    -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.

##### See Also:

setenv, command_line

#### 8.7.2.6 setenv

    include std/os.e
    namespace os
    public function setenv(sequence name, sequence val, integer overwrite = 1)

sets an environment variable.

##### Parameters:

1. `name` : a string, the environment variable name
2. `val` : a string, the value to set to
3. `overwrite` : an integer, nonzero to overwrite an existing variable, 0 to disallow this.

##### Example 1:

    ? setenv("NAME", "John Doe")
    ? setenv("NAME", "Jane Doe")
    ? setenv("NAME", "Jim Doe", 0)

##### See Also:

getenv, unsetenv

#### 8.7.2.7 unsetenv

    include std/os.e
    namespace os
    public function unsetenv(sequence env)

unsets an environment variable.

##### Parameters:

1. `name` : name of environment variable to unset

##### Example 1:

    ? unsetenv("NAME")

##### See Also:

setenv, getenv

#### 8.7.2.8 platform

    <built-in> function platform()

indicates the platform that the program is being executed on.

##### Returns:

An integer,

    public constant
        WIN32 = WINDOWS,
        LINUX,
        FREEBSD,
        OSX,
       OPENBSD,
        NETBSD,
        FREEBSD

##### Comments:

The ifdef statement is much more versatile and in most cases supersedes `platform`.

`platform` used to be the way to execute different code depending on which platform the program is running on. Additional platforms will be added as Euphoria is ported to new machines and operating environments.

##### Example 1:

    ifdef WINDOWS then
        -- call system Beep routine
        err = c_func(Beep, {0,0})
    elsedef
        -- do nothing (Linux/FreeBSD)
    end if

##### See Also:

Platform-Specific Issues, ifdef statement

### 8.7.3 Interacting with the OS

#### 8.7.3.1 system

    <built-in> procedure system(sequence command, integer mode=0)

passes a command string to the operating system command interpreter.

##### Parameters:

1. `command` : a string to be passed to the shell
2. `mode` : an integer, indicating the manner in which to return from the call.

##### Errors:

`command` should not exceed 1_024 characters.

##### Comments:

Allowable values for `mode` are:

- 0: the previous graphics mode is restored and the screen is cleared.
- 1: a beep sound will be made and the program will wait for the user to press a key before the previous graphics mode is restored.
- 2: the graphics mode is not restored and the screen is not cleared.

`mode` = 2 should only be used when it is known that the command executed by `system` will not change the graphics mode.

You can use Euphoria as a sophisticated "batch" (.bat) language by making calls to `system` and `system_exec`.

`system` will start a new command shell.

`system` allows you to use command-line redirection of standard input and output in `command`.

##### Example 1:

    system("copy temp.txt a:\\temp.bak", 2)
    -- note use of double backslash in literal string to get
    -- single backslash

##### Example 2:

    system("eui \\test\\myprog.ex < indata > outdata", 2)
    -- executes myprog by redirecting standard input and
    -- standard output

##### See Also:

system_exec, command_line, current_dir, getenv

#### 8.7.3.2 system_exec

    <built-in> function system_exec(sequence command, integer mode=0)

tries to run the a shell executable command.

##### Parameters:

1. `command` : a string to be passed to the shell, representing an executable command
2. `mode` : an integer, indicating the manner in which to return from the call.

##### Returns:

An integer, basically the exit or return code from the called process.

##### Errors:

`command` should not exceed 1_024 characters.

##### Comments:

Allowable values for `mode` are:

- 0 -- the previous graphics mode is restored and the screen is cleared.
- 1 -- a beep sound will be made and the program will wait for the user to press a key before the previous graphics mode is restored.
- 2 -- the graphics mode is not restored and the screen is not cleared.

If it is not possible to run the program, `system_exec` will return -1.

On Windows `system_exec` will only run `.exe` and `.com` programs. To run `.bat` files, or built-in shell commands, you need system. Some commands, such as `DEL`, are not programs, they are actually built-in to the command interpreter.

On Windows `system_exec` does not allow the use of command-line redirection in `command`. Nor does it allow you to quote strings that contain blanks, such as file names.

exit codes from Windows programs are normally in the range 0 to 255, with 0 indicating "success".

You can run a Euphoria program using `system_exec`. A Euphoria program can return an exit code using abort.

`system_exec` does not start a new command shell.

##### Example 1:

    integer exit_code
    exit_code = system_exec("xcopy temp1.dat temp2.dat", 2)

    if exit_code = -1 then
        puts(2, "\n couldn't run xcopy.exe\n")
    elsif exit_code = 0 then
        puts(2, "\n xcopy succeeded\n")
    else
        printf(2, "\n xcopy failed with code %d\n", exit_code)
    end if

##### Example 2:

    -- executes myprog with two file names as arguments
    if system_exec("eui \\test\\myprog.ex indata outdata", 2) then
        puts(2, "failure!\n")
    end if

##### See Also:

system, abort

### 8.7.4 Miscellaneous

#### 8.7.4.1 sleep

    include std/os.e
    namespace os
    public procedure sleep(atom t)

suspend thread execution for `t` seconds.

##### Parameters:

1. `t` : an atom, the number of seconds for which to sleep.

##### Comments:

The operating system will suspend your process and schedule other processes.

With multiple tasks, the whole program sleeps, not just the current task. To make just the current task sleep, you can call `task_schedule(task_self(), {i, i})` and then execute task_yield. Another option is to call task_delay.

##### Example 1:

    puts(1, "Waiting 15 seconds and a quarter...\n")
    sleep(15.25)
    puts(1, "Done.\n")

##### See Also:

task_schedule, task_yield, task_delay

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.6 I/O | Up: 8 API Reference | 8.8 Pipe Input and Output > | 9 Release Notes >>