Operating system interface
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 8.27 Operating system interface

- argument_counter/1
- argument_value/2
- argument_list/1
- environ/2
- make_directory/1, delete_directory/1, change_directory/1
- working_directory/1
- directory_files/2
- rename_file/2
- delete_file/1, unlink/1
- file_permission/2, file_exists/1
- file_property/2
- temporary_name/2
- temporary_file/3
- date_time/1
- host_name/1
- os_version/1
- architecture/1
- shell/2, shell/1, shell/0
- system/2, system/1
- spawn/3, spawn/2
- popen/3
- exec/5, exec/4
- fork_prolog/1
- create_pipe/2
- wait/2
- prolog_pid/1
- send_signal/2
- sleep/1
- select/5

#### 8.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. See (section 4.2) for more information about command-line arguments retrieved under the top_level.

Errors

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

Portability

GNU Prolog predicate.

#### 8.27.2 argument_value/2

Templates

  argument_value(+integer, ?atom)

Description

argument_value(N, Arg) succeeds if the Nth 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 8.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.

#### 8.27.3 argument_list/1

Templates

  argument_list(?list)

Description

argument_list(Args) succeeds if Args unifies with the list of atoms associated with 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.

#### 8.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.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.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.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.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 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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.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 8.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 8.27.10).
- last_modification(DT): DT is the last modification date and time (section 8.27.14).

See absolute_file_name/2 for information about the syntax of PathName (section 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 Xs. PathName is Template with the six Xs 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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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.

#### 8.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 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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.

#### 8.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.

#### 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.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 8.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 |  | uninstantiation_error(Stream)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.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 with the standard input stream of Command (it is an output stream). StreamOut is unified with the stream-term associated with the standard output stream of Command (it is an input stream). StreamErr is unified with the stream-term associated with 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 8.27.25). 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 |  | uninstantiation_error(StreamIn)
StreamOut is not a variable |  | uninstantiation_error(StreamOut)
StreamErr is not a variable |  | uninstantiation_error(StreamErr)
Pid is not a variable |  | uninstantiation_error(Pid)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.27.23 fork_prolog/1

Templates

  fork_prolog(-integer)

Description

fork_prolog(Pid) creates a child process that differs from the parent process only in its PID. In the parent process Pid is unified with the PID of the child while in the child process Pid is unified with 0. In the parent process, the status of the child process can be obtained using wait/2 (section 8.27.25). Until a call to wait/2 is done the child process remains in the system processes table (as a zombie process if terminated). This predicate is an interface to the C Unix function fork(2).

Errors

Pid is not a variable |  | uninstantiation_error(Pid)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.27.24 create_pipe/2

Templates

  create_pipe(-stream, -stream)

Description

create_pipe(StreamIn, StreamOut) creates a pair of streams pointing to a pipe inode. StreamIn is unified with the stream-term associated with the input side of the pipe and StreamOut is unified with the stream-term associated with output side. This predicate is an interface to the C Unix function pipe(2).

Errors

StreamIn is not a variable |  | uninstantiation_error(StreamIn)
StreamOut is not a variable |  | uninstantiation_error(StreamOut)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.27.25 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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.27.26 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.

#### 8.27.27 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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.27.28 sleep/1

Templates

  sleep(+number)

Description

sleep(Seconds) puts the GNU Prolog process to sleep for Seconds 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.

#### 8.27.29 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 8.28). Streams that must be tested with select/5 should not be buffered. This can be done at the opening using open/4 (section 8.10.6) or later using set_stream_buffering/2 (section 8.10.27). 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 with an output stream |  | permission_error(input, stream, E)
an element E of the Writes list is associated with 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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

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