Operating system interface

6.27 | Operating system interface

6.27.1 | `argument_counter/1`

Templates

  `argument_counter(?integer)`

Description
`argument_counter(Counter)` succeeds if `Counter` is the number of arguments of the command-line. Since the first argument is always the name of the running program, `Counter` is always ³ 1.
Errors

`Counter` is neither a variable nor an integer |  | `type_error(integer, Counter)`

Portability
GNU Prolog predicate.

6.27.2 | `argument_value/2`

Templates

  `argument_value(+integer, ?atom)`

Description
`argument_value(N, Arg)` succeeds if the `N`th argument on the command-line unifies with `Arg`. The first argument is always the name of the running program and its number is 0. The number of arguments on the command-line can be obtained using `argument_counter/1` (section 6.27.1).
Errors

`N` is a variable |  | `instantiation_error`
`N` is neither a variable nor an integer |  | `type_error(integer, N)`
`N` is an integer < 0 |  | `domain_error(not_less_than_zero, N)`
`Arg` is neither a variable nor an atom |  | `type_error(atom, Arg)`

Portability
GNU Prolog predicate.

6.27.3 | `argument_list/1`

Templates

  `argument_list(?list)`

Description
`argument_list(Args)` succeeds if `Args` unifies with the list of atoms associated to each argument on the command-line other than the first argument (the name of the running program).
Errors

`Args` is neither a partial list nor a list |  | `type_error(list, Args)`

Portability
GNU Prolog predicate.

6.27.4 | `environ/2`

Templates

  `environ(?atom, ?atom)`

Description
`environ(Name, Value)` succeeds if `Name` is the name of an environment variable whose value is `Value`. This predicate is re-executable on backtracking.
Errors

`Name` is neither a variable nor an atom |  | `type_error(atom, Name)`
`Value` is neither a variable nor an atom |  | `type_error(atom, Value)`

Portability
GNU Prolog predicate.

6.27.5 | `make_directory/1`, `delete_directory/1`, `change_directory/1`

Templates

  `make_directory(+atom)
  delete_directory(+atom)
  change_directory(+atom)`

Description
`make_directory(PathName)` creates the directory whose pathname is `PathName`.
`delete_directory(PathName)` removes the directory whose pathname is `PathName`.
`change_directory(PathName)` sets the current directory to the directory whose pathname is `PathName`.
See `absolute_file_name/2` for information about the syntax of `PathName` (section 6.26.1).
Errors

`PathName` is a variable |  | `instantiation_error`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
`PathName` is an atom but not a valid pathname |  | `domain_error(os_path, PathName)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

6.27.6 | `working_directory/1`

Templates

  `working_directory(?atom)`

Description
`working_directory(PathName)` succeeds if `PathName` is the pathname of the current directory.
Errors

`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`

Portability
GNU Prolog predicate.

6.27.7 | `directory_files/2`

Templates

  `directory_files(+atom, ?list)`

Description
`directory_files(PathName, Files)` succeeds if `Files` is the list of all entries (files, sub-directories,...) in the directory whose pathname is `PathName`. See `absolute_file_name/2` for information about the syntax of `PathName` (section 6.26.1).
Errors

`PathName` is a variable |  | `instantiation_error`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
`PathName` is an atom but not a valid pathname |  | `domain_error(os_path, PathName)`
`Files` is neither a partial list nor a list |  | `type_error(list, Files)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.8 | `rename_file/2`

Templates

  `rename_file(+atom, +atom)`

Description
`rename_file(PathName1, PathName2)` renames the file or directory whose pathname is `PathName1` to `PathName2`. See `absolute_file_name/2` for information about the syntax of `PathName1` and `PathName2` (section 6.26.1).
Errors

`PathName1` is a variable |  | `instantiation_error`
`PathName1` is neither a variable nor an atom |  | `type_error(atom, PathName1)`
`PathName1` is an atom but not a valid pathname |  | `domain_error(os_path, PathName1)`
`PathName2` is a variable |  | `instantiation_error`
`PathName2` is neither a variable nor an atom |  | `type_error(atom, PathName2)`
`PathName2` is an atom but not a valid pathname |  | `domain_error(os_path, PathName2)`
an operating system error occurs and value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.9 | `delete_file/1`, `unlink/1`

Templates

  `delete_file(PathName)
  unlink(PathName)`

Description
`delete_file(PathName)` removes the existing file whose pathname is `PathName`.
`unlink/1` is similar to `delete_file/1` except that it never causes a `system_error` (e.g. if `PathName` does not refer to an existing file).
See `absolute_file_name/2` for information about the syntax of `PathName` (section 6.26.1).
Errors

`PathName` is a variable |  | `instantiation_error`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
`PathName` is an atom but not a valid pathname |  | `domain_error(os_path, PathName)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

6.27.10 | `file_permission/2`, `file_exists/1`

Templates

  `file_permission(+atom, +atom)
  file_permission(+atom, +atom_list)
  file_exists(+atom)`

Description
`file_permission(PathName, Permission)` succeeds if `PathName` is the pathname of an existing file (or directory) whose permissions include `Permission`.
File permissions: `Permission` can be a single permission or a list of permissions. A permission is an atom among:

- `read`: the file or directory can be read.
- `write`: the file or directory can be written.
- `execute`: the file can be executed.
- `search`: the directory can be searched.

If `PathName` does not exists or if it its permissions do not include `Permission` this predicate fails.
`file_exists(PathName)` is equivalent to `file_permission(PathName, [])`, i.e. it succeeds if `PathName` is the pathname of an existing file (or directory).
See `absolute_file_name/2` for information about the syntax of `PathName` (section 6.26.1).
Errors

`PathName` is a variable |  | `instantiation_error`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
`PathName` is an atom but not a valid pathname |  | `domain_error(os_path, PathName)`
`Permission` is a partial list or a list with an element which is a variable |  | `instantiation_error`
`Permission` is neither an atom nor partial list or a list |  | `type_error(list, Permission)`
an element `E` of the `Permission` list is neither a variable nor an atom |  | `type_error(atom, E)`
an element `E` of the `Permission` is an atom but not a valid permission |  | `domain_error(os_file_permission, Permission)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

6.27.11 | `file_property/2`

Templates

  `file_property(+atom, ?os_file_property)`

Description
`file_property(PathName, Property)` succeeds if `PathName` is the pathname of an existing file (or directory) and if `Property` unifies with one of the properties of the file. This predicate is re-executable on backtracking.
File properties:

- `absolute_file_name(File)`: `File` is the absolute file name of `PathName` (section 6.26.1).
- `real_file_name(File)`: `File` is the real file name of `PathName` (follows symbolic links).
- `type(Type)`: `Type` is the type of `PathName`. Possible values are: `regular`, `directory`, `fifo`, `socket`, `character_device`, `block_device` or `unknown`.
- `size(Size)`: `Size` is the size (in bytes) of `PathName`.
- `permission(Permission)`: `Permission` is a permission of `PathName` (section 6.27.10).
- `last_modification(DT)`: `DT` is the last modification date and time (section 6.27.14).

See `absolute_file_name/2` for information about the syntax of `PathName` (section 6.26.1).
Errors

`PathName` is a variable |  | `instantiation_error`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
`PathName` is an atom but not a valid pathname |  | `domain_error(os_path, PathName)`
`Property` is neither a variable nor a file property term |  | `domain_error(os_file_property, Property)`
`Property` = `absolute_file_name(E)`, `real_file_name(E)`, `type(E)` or `permission(E)` and `E` is neither a variable nor an atom |  | `type_error(atom, E)`
`Property` = `last_modification(DateTime)` and `DateTime` is neither a variable nor a compound term |  | `type_error(compound, DateTime)`
`Property` = `last_modification(DateTime)` and `DateTime` is a compound term but not a structure `dt/6` |  | `domain_error(date_time, DateTime)`
`Property` = `size(E)` or `last_modification(DateTime)` and `DateTime` is a structure `dt/6` but an element `E` is neither a variable nor an integer |  | `type_error(integer, E)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.12 | `temporary_name/2`

Templates

  `temporary_name(+atom, ?atom)`

Description
`temporary_name(Template, PathName)` creates a unique file name `PathName` whose pathname begins by `Template`. `Template` should contain a pathname with six trailing `X`s. `PathName` is `Template` with the six `X`s replaced with a letter and the process identifier. This predicate is an interface to the C Unix function `mktemp(3)`.
See `absolute_file_name/2` for information about the syntax of `Template` (section 6.26.1).
Errors

`Template` is a variable |  | `instantiation_error`
`Template` is neither a variable nor an atom |  | `type_error(atom, Template)`
`Template` is an atom but not a valid pathname |  | `domain_error(os_path, Template)`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.13 | `temporary_file/3`

Templates

  `temporary_file(+atom, +atom, ?atom)`

Description
`temporary_file(Directory, Prefix, PathName)` creates a unique file name `PathName` whose pathname begins by `Directory/Prefix`. If `Directory` is the empty atom `''` a standard temporary directory will be used (e.g. `/tmp`). `Prefix` can be the empty atom `''`. This predicate is an interface to the C Unix function `tempnam(3)`.
See `absolute_file_name/2` for information about the syntax of `Directory` (section 6.26.1).
Errors

`Directory` is a variable |  | `instantiation_error`
`Directory` is neither a variable nor an atom |  | `type_error(atom, Directory)`
`Directory` is an atom but not a valid pathname |  | `domain_error(os_path, Directory)`
`Prefix` is a variable |  | `instantiation_error`
`Prefix` is neither a variable nor an atom |  | `type_error(atom, Prefix)`
`PathName` is neither a variable nor an atom |  | `type_error(atom, PathName)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.14 | `date_time/1`

Templates

  `date_time(?compound)`

Description
`date_time(DateTime)` unifies `DateTime` with a compound term containing the current date and time. `DateTime` is a structure `dt(Year, Month, Day, Hour, Minute, Second)`. Each sub-argument of the term `dt/6` is an integer.
Errors

`DateTime` is neither a variable nor a compound term |  | `type_error(compound, DateTime)`
`DateTime` is a compound term but not a structure `dt/6` |  | `domain_error(date_time, DateTime)`
`DateTime` is a structure `dt/6` and an element `E` is neither a variable nor an integer |  | `type_error(integer, E)`

Portability
GNU Prolog predicate.

6.27.15 | `host_name/1`

Templates

  `host_name(?atom)`

Description
`host_name(HostName)` unifies `HostName` with the name of the host machine executing the current GNU Prolog process. If the sockets are available (section 6.28.1), the name returned will be fully qualified. In that case, `host_name/1` will also succeed if `HostName` is instantiated to the unqualified name (or an alias) of the machine.
Errors

`Hostname` is neither a variable nor an atom |  | `type_error(atom, HostName)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.16 | `os_version/1`

Templates

  `os_version(?atom)`

Description
`os_version(OSVersion)` unifies `OSVersion` with the operating system version of the machine executing the current GNU Prolog process.
Errors

`OSVersion` is neither a variable nor an atom |  | `type_error(atom, OSVersion)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.17 | `architecture/1`

Templates

  `architecture(?atom)`

Description
`architecture(Architecture)` unifies `Architecture` with the name of the machine executing the current GNU Prolog process.
Errors

`Architecture` is neither a variable nor an atom |  | `type_error(atom, Architecture)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.18 | `shell/2`, `shell/1`, `shell/0`

Templates

  `shell(+atom, ?integer)
  shell(+atom)
  shell`

Description
`shell(Command, Status)` invokes a new shell (named by the `SHELL` environment variable) passing `Command` for execution and unifies `Status` with the result of the execution. If `Command` is the empty atom `''` a new interactive shell is executed. The control is returned to Prolog upon termination of the called process.
`shell(Command)` is equivalent to `shell(Command, 0)`.
`shell` is equivalent to `shell('', 0)`.
Errors

`Command` is a variable |  | `instantiation_error`
`Command` is neither a variable nor an atom |  | `type_error(atom, Command)`
`Status` is neither a variable nor an integer |  | `type_error(integer, Status)`

Portability
GNU Prolog predicates.

6.27.19 | `system/2`, `system/1`

Templates

  `system(+atom, ?integer)
  system(+atom)`

Description
`system(Command, Status)` invokes a new default shell passing `Command` for execution and unifies `Status` with the result of the execution. The control is returned to Prolog upon termination of the shell process. This predicate is an interface to the C Unix function `system(3)`.
`system(Command)` is equivalent to `system(Command, 0)`.
Errors

`Command` is a variable |  | `instantiation_error`
`Command` is neither a variable nor an atom |  | `type_error(atom, Command)`
`Status` is neither a variable nor an integer |  | `type_error(integer, Status)`

Portability
GNU Prolog predicates.

6.27.20 | `spawn/3`, `spawn/2`

Templates

  `spawn(+atom, +atom_list, ?integer)
  spawn(+atom, +atom_list)`

Description
`spawn(Command, Arguments, Status)` executes `Command` passing as arguments of the command-line each element of the list `Arguments` and unifies `Status` with the result of the execution. The control is returned to Prolog upon termination of the command.
`spawn(Command, Arguments)` is equivalent to `spawn(Command, Arguments, 0)`.
Errors

`Command` is a variable |  | `instantiation_error`
`Command` is neither a variable nor an atom |  | `type_error(atom, Command)`
`Arguments` is a partial list or a list with an element which is a variable |  | `instantiation_error`
`Arguments` is neither a partial list nor a list |  | `type_error(list, Arguments)`
an element `E` of the `Arguments` list is neither a variable nor an atom |  | `type_error(atom, E)`
`Status` is neither a variable nor an integer |  | `type_error(integer, Status)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

6.27.21 | `popen/3`

Templates

  `popen(+atom, +io_mode, -stream)`

Description
`popen(Command, Mode, Stream)` invokes a new default shell (by creating a pipe) passing `Command` for execution and associates a stream either to the standard input or the standard output of the created process. if `Mode` is `read` (resp. `write`) an input (resp. output) stream is created and `Stream` is unified with the stream-term associated. Writing to the stream writes to the standard input of the command while reading from the stream reads the command's standard output. The stream must be closed using `close/2` (section 6.10.7). This predicate is an interface to the C Unix function `popen(3)`.
Errors

`Command` is a variable |  | `instantiation_error`
`Command` is neither a variable nor an atom |  | `type_error(atom, Command)`
`Mode` is a variable |  | `instantiation_error`
`Mode` is neither a variable nor an atom |  | `type_error(atom, Mode)`
`Mode` is an atom but neither `read` nor `write`. |  | `domain_error(io_mode, Mode)`
`Stream` is not a variable |  | `type_error(variable, Stream)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.22 | `exec/5`, `exec/4`

Templates

  `exec(+atom, -stream, -stream, -stream, -integer)
  exec(+atom, -stream, -stream, -stream)`

Description
`exec(Command, StreamIn, StreamOut, StreamErr, Pid)` invokes a new default shell passing `Command` for execution and associates streams to standard streams of the created process. `StreamIn` is unified with the stream-term associated to the standard input stream of `Command` (it is an output stream). `StreamOut` is unified with the stream-term associated to the standard output stream of `Command` (it is an input stream). `StreamErr` is unified with the stream-term associated to the standard error stream of `Command` (it is an input stream). `Pid` is unified with the process identifier of the new process. This information is only useful if it is necessary to obtain the status of the execution using `wait/2` (section 6.27.23). Until a call to `wait/2` is done the process remains in the system processes table (as a zombie process if terminated). For this reason, if the status is not needed it is preferable to use `exec/4`.
`exec/4` is similar to `exec/5` but the process is removed from system processes as soon as it is terminated.
Errors

`Command` is a variable |  | `instantiation_error`
`Command` is neither a variable nor an atom |  | `type_error(atom, Command)`
`StreamIn` is not a variable |  | `type_error(variable, StreamIn)`
`StreamOut` is not a variable |  | `type_error(variable, StreamOut)`
`StreamErr` is not a variable |  | `type_error(variable, StreamErr)`
`Pid` is not a variable |  | `type_error(variable, Pid)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

6.27.23 | `wait/2`

Templates

  `wait(+integer, ?integer)`

Description
`wait(Pid, Status)` waits for the child process whose identifier is `Pid` to terminate. `Status` is then unified with the exit status. This predicate is an interface to the C Unix function `waitpid(2)`.
Errors

`Pid` is a variable |  | `instantiation_error`
`Pid` is neither a variable nor an integer |  | `type_error(integer, Pid)`
`Status` is neither a variable nor an integer |  | `type_error(integer, Status)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.24 | `prolog_pid/1`

Templates

  `prolog_pid(?integer)`

Description
`prolog_pid(Pid)` unifies `Pid` with the process identifier of the current GNU Prolog process.
Errors

`Pid` is neither a variable nor an integer |  | `type_error(integer, Pid)`

Portability
GNU Prolog predicate.

6.27.25 | `send_signal/2`

Templates

  `send_signal(+integer, +integer)
  send_signal(+integer, +atom)`

Description
`send_signal(Pid, Signal)` sends `Signal` to the process whose identifier is `Pid.` `Signal` can be specified directly as an integer or symbolically as an atom. Allowed atoms depend on the machine (e.g. `'SIGINT'`, `'SIGQUIT'`, `'SIGKILL'`, `'SIGUSR1'`, `'SIGUSR2'`, `'SIGALRM'`,...). This predicate is an interface to the C Unix function `kill(2)`.
Errors

`Pid` is a variable |  | `instantiation_error`
`Pid` is neither a variable nor an integer |  | `type_error(integer, Pid)`
`Signal` is a variable |  | `instantiation_error`
`Signal` is neither a variable nor an integer or an atom |  | `type_error(integer, Signal)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.27.26 | `sleep/1`

Templates

  `sleep(+number)`

Description
`sleep(Seconds)` puts the GNU Prolog process to sleep for `Second`s seconds. `Seconds` can be an integer or a floating point number (in which case it can be < 1). This predicate is an interface to the C Unix function `usleep(3)`.
Errors

`Seconds` is a variable |  | `instantiation_error`
`Seconds` is neither a variable nor a number |  | `type_error(number, Seconds)`
`Seconds` is a number < 0 |  | `domain_error(not_less_than_zero, Seconds)`

Portability
GNU Prolog predicate.

6.27.27 | `select/5`

Templates

  `select(+list, ?list, +list, ?list, +number)`

Description
`select(Reads, ReadyReads, Writes, ReadyWrites, TimeOut)` waits for a number of streams (or file descriptors) to change status. `ReadyReads` is unified with the list of elements listed in `Reads` that have characters available for reading. Similarly `ReadyWrites` is unified with the list of elements of `Writes` that are ok for immediate writing. The elements of `Reads` and `Writes` are either stream-terms or aliases or integers considered as file descriptors, e.g. for sockets (section 6.28). Streams that must be tested with `select/5` should not be buffered. This can be done at the opening using `open/4` (section 6.10.6) or later using `set_stream_buffering/2` (section 6.10.24). `TimeOut` is an upper bound on the amount of time (in milliseconds) elapsed before `select/5` returns. If `TimeOut` £ 0 (no timeout) `select/5` waits until something is available (either or reading or for writing) and thus can block indefinitely. This predicate is an interface to the C Unix function `select(2)`.
Errors

`Reads` (or `Writes`) is a partial list or a list with an element `E` which is a variable |  | `instantiation_error`
`Reads` is neither a partial list nor a list |  | `type_error(list, Reads)`
`Writes` is neither a partial list nor a list |  | `type_error(list, Writes)`
`ReadyReads` is neither a partial list nor a list |  | `type_error(list, ReadyReads)`
`ReadyWrites` is neither a partial list nor a list |  | `type_error(list, ReadyWrites)`
an element `E` of the `Reads` (or `Writes`) list is neither a stream-term or alias nor an integer |  | `domain_error(stream_or_alias, E)`
an element `E` of the `Reads` (or `Writes`) list is not a selectable item |  | `domain_error(selectable_item, E)`
an element `E` of the `Reads` (or `Writes`) list is an integer < 0 |  | `domain_error(not_less_than_zero, E)`
an element `E` of the `Reads` (or `Writes`) list is a stream-tern or alias not associated with an open stream |  | `existence_error(stream, E)`
an element `E` of the `Reads` list is associated to an output stream |  | `permission_error(input, stream, E)`
an element `E` of the `Writes` list is associated to an input stream |  | `permission_error(output, stream, E)`
`TimeOut` is a variable |  | `instantiation_error`
`TimeOut` is neither a variable nor a number |  | `type_error(number, TimeOut)`
an operating system error occurs and the value of the `os_error` Prolog flag is `error` (section 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

Copyright (C) 1999,2000 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright