OpenEuphoria

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

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

Return the ID of the current Process (pid)

Returns:

An atom: The current process' id.

Example:

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

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

Return 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:

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)

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

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

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

Try 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/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:

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

See Also:

task_schedule, task_yield, task_delay