☰

Operating system utilities

Author(s): Daniel Cabeza, Manuel Carro.

This module contains predicates for invoking services which are typically provided by the operating system. Note that the predicates which take names of files or directories as arguments in this module expect atoms, not path aliases. I.e., generally these predicates will not call absolute_file_name/2 on names of files or directories taken as arguments.

Documentation on exports

PREDICATEnow/1
now(Time)

Time is unified with the number of seconds elapsed since January, 1, 1970 (UTC).

Usage:

PREDICATEdatime/1
datime(Datime)

Datime is unified with a term of the form datime(Year,Month,Day,Hour,Minute,Second) which contains the current date and time.

Usage:

REGTYPEdatime_struct/1
A regular type, defined as follows:
datime_struct(datime(Year,Month,Day,Hour,Min,Sec)) :-
    int(Year),
    int(Month),
    int(Day),
    int(Hour),
    int(Min),
    int(Sec).

PREDICATEdatime/9
datime(Time,Year,Month,Day,Hour,Min,Sec,WeekDay,YearDay)

Time is as in now/1. WeekDay is the number of days since Sunday, in the range 0 to 6. YearDay is the number of days since January 1, in the range 0 to 365.

Usage 1:

If Time is given, the rest of the arguments are unified with the date and time to which the Time argument refers.

Usage 2:

Bound Time, WeekDay and YearDay as determined by the input arguments.

Usage 3:

Bound Time to current time and the rest of the arguments refer to current time.

REGTYPEcopy_option/1

Usage:copy_option(Opt)

Opt is a file copy option. 

copy_option(overwrite).
copy_option(timestamp).
copy_option(symlink).
copy_option(append).

    REGTYPEcopy_options/1

    Usage:copy_options(Opts)

    Opts is a list of file copy options.

      PREDICATEcopy_file/2
      copy_file(Source,Destination)

      Copies the file Source to Destination.

      Usage:

      PREDICATEcopy_file/3

      Usage:

      PREDICATEgetenvstr/2
      getenvstr(Name,Value)

      The environment variable Name has Value. Fails if variable Name is not defined.

      Usage:

      • Call and exit should be compatible with:
        (basic_props:string/1)Value is a string (a list of character codes).
      • The following properties should hold at call time:
        (basic_props:atm/1)Name is an atom.
      • The following properties should hold upon exit:
        (basic_props:string/1)Value is a string (a list of character codes).

      PREDICATEsetenvstr/2
      setenvstr(Name,Value)

      The environment variable Name is assigned Value.

      Usage:

      PREDICATEset_env/2
      set_env(Name,Value)

      The environment variable Name is assigned Value.

      Usage:

      PREDICATEdel_env/1
      del_env(Name)

      The environment variable Name is removed.

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)Name is an atom.

      PREDICATEcurrent_env/2
      current_env(Name,Value)

      If Name is an atom, then unifies the environment variable Name with its value. Note that this predicate can be used to enumerate all the environment variables using backtracking.

      Usage:

      PREDICATEextract_paths/2
      extract_paths(PathList,Paths)

      Split PathList atom into the list of paths Paths. Paths in String are separated by the path list separator character (colons in POSIX-like systems, semicolons in Windows). Empty paths are removed from Paths. Paths is empty if PathList is the empty atom.

      Usage:

      • Calls should, and exit will be compatible with:
        (basic_props:list/2)Paths is a list of atms.
      • The following properties should hold at call time:
        (basic_props:atm/1)PathList is an atom.
      • The following properties hold upon exit:
        (basic_props:list/2)Paths is a list of atms.

      PREDICATEcurrent_host/1
      current_host(Hostname)

      Hostname is unified with the fully qualified name of the host.

      Usage:

      PREDICATEcurrent_executable/1
      current_executable(Path)

      Unifies Path with the path to the current Ciao executable (which may be a standalone binary or bytecode executable)

      Usage:

      PREDICATEumask/2

      Usage 1:umask(OldMask,NewMask)

      The process file creation mask was OldMask, and it is changed to NewMask.

      • The following properties should hold at call time:
        (basic_props:int/1)NewMask is an integer.
      • The following properties hold upon exit:
        (basic_props:int/1)OldMask is an integer.

      Usage 2:umask(OldMask,NewMask)

      Gets the process file creation mask without changing it.

      PREDICATEworking_directory/2
      working_directory(OldDir,NewDir)

      Unifies current working directory with OldDir, and then changes the working directory to NewDir. Calling working_directory(Dir,Dir) simply unifies Dir with the current working directory without changing anything else.

      Usage 1:

      Changes current working directory.

      Usage 2:working_directory(OldDir,NewDir)

      Gets current working directory.

      PREDICATEcd/1
      cd(Path)

      Changes working directory to Path.

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)Path is an atom.

      PREDICATEdirectory_files/2
      directory_files(Directory,FileList)

      FileList is the unordered list of entries (files, directories, etc.) in Directory.

      Usage:

      • Calls should, and exit will be compatible with:
        (basic_props:list/2)FileList is a list of atms.
      • The following properties should hold at call time:
        (basic_props:atm/1)Directory is an atom.
      • The following properties hold upon exit:
        (basic_props:list/2)FileList is a list of atms.

      PREDICATEmktemp/2
      mktemp(Template,Filename)

      Returns a unique Filename based on Template: Template must be a valid file name with six trailing X, which are substituted to create a new file name. Filename is created in read/write mode but closed immediately after creation.

      Usage:

      • Calls should, and exit will be compatible with:
        (basic_props:atm/1)Filename is an atom.
      • The following properties should hold at call time:
        (basic_props:atm/1)Template is an atom.
      • The following properties hold upon exit:
        (basic_props:atm/1)Filename is an atom.

      PREDICATEmktemp_in_tmp/2
      No further documentation available for this predicate.

      PREDICATEfile_exists/1
      file_exists(File)

      Succeeds if File (a file or directory) exists (and is accessible).

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)File is an atom.

      PREDICATEfile_exists/2
      file_exists(File,Mode)

      File (a file or directory) exists and it is accessible with Mode, as in the Unix call access(2). Typically, Mode is 4 for read permission, 2 for write permission and 1 for execute permission.

      Usage:

      PREDICATEfile_property/2
      file_property(File,Property)

      File has the property Property. The possible properties are:

      type(Type)
      Type is one of regular, directory, fifo, socket or unknown.

      linkto(Linkto)
      If File is a symbolic link, Linkto is the file pointed to by the link (and the other properties come from that file, not from the link itself).

      mod_time(ModTime)
      ModTime is the time of last modification (seconds since January, 1, 1970).

      mode(Protection)
      Protection is the protection mode.

      size(Size)
      Size is the size.

      If Property is uninstantiated, the predicate will enumerate the properties on backtracking.

      Usage:

      PREDICATEfile_properties/6
      file_properties(Path,Type,Linkto,Time,Protection,Size)

      The file Path has the following properties:

      • File type Type (one of regular, directory, fifo, socket or unknown).

      • If Path is a symbolic link, Linkto is the file pointed to. All other properties come from the file pointed, not the link. Linkto is '' if Path is not a symbolic link.

      • Time of last modification Time (seconds since January, 1, 1970).

      • Protection mode Protection.

      • Size in bytes Size.

      Usage:

      PREDICATEmodif_time/2
      modif_time(File,Time)

      The file File was last modified at Time, which is in seconds since January, 1, 1970. Fails if File does not exist.

      Usage:

      PREDICATEmodif_time0/2
      modif_time0(File,Time)

      If File exists, Time is its latest modification time, as in modif_time/2. Otherwise, if File does not exist, Time is zero.

      Usage:

      PREDICATEtouch/1
      touch(File)

      Change the modification time of File to the current time of day. If the file does not exist, it is created with default permissions.

      Note: This operation cannot be fully implemented with modif_time/2. In POSIX systems, that can be done as long as the user has write permissions on the file, even if the owner is different. Change of modification time to arbitrary time values is not allowed in this case.

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)File is an atom.

      PREDICATEfmode/2
      fmode(File,Mode)

      The file File has protection mode Mode.

      Usage:

      PREDICATEchmod/2
      chmod(File,NewMode)

      Change the protection mode of file File to NewMode.

      Usage:

      PREDICATEchmod/3
      chmod(File,OldMode,NewMode)

      The file File has protection mode OldMode and it is changed to NewMode.

      Usage 1:

      Usage 2:chmod(File,OldMode,NewMode)

      If OldMode is identical to NewMode then it is equivalent to fmode(File,OldMode)

      PREDICATEset_exec_mode/2
      set_exec_mode(SourceName,ExecName)

      Copies the permissions of SourceName to ExecName adding permissions to execute.

      Usage:

      PREDICATEdelete_directory/1
      delete_directory(File)

      Delete the directory Directory.

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)File is an atom.

      PREDICATEdelete_file/1
      delete_file(File)

      Delete the file File.

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)File is an atom.

      PREDICATErename_file/2
      rename_file(File1,File2)

      Change the name of File1 to File2.

      Usage:

      PREDICATEmake_directory/2
      make_directory(DirName,Mode)

      Creates the directory DirName with a given Mode. This is, as usual, operated against the current umask value.

      Usage:

      PREDICATEmake_directory/1
      make_directory(DirName)

      Equivalent to make_directory(D,0o777).

      Usage:

      • The following properties should hold at call time:
        (basic_props:atm/1)DirName is an atom.

      PREDICATEsystem_error_report/1

      Usage:system_error_report(Report)

      Report is the error message from the last system call, like strerror in POSIX.

      • The following properties should hold at call time:
        (term_typing:var/1)Report is a free variable.
      • The following properties should hold upon exit:
        (basic_props:atm/1)Report is an atom.

      PREDICATEget_tmp_dir/1

      Usage:get_tmp_dir(TmpDir)

      TmpDir is the (normalized) temporary directory for scratch space. On POSIX systems it is computed from normalizing the path specified in the TMPDIR environment variable. On Windows it is determined by the TMP or TEMP environment variable. If none is defined, this predicate tries to guess it from some usual locations (/tmp, /var/tmp, /usr/tmp on POSIX, c:\temp, c:\tmp, \temp, \tmp on Windows) or use . as last resort.

      • The following properties should hold at call time:
        (term_typing:var/1)TmpDir is a free variable.
      • The following properties should hold upon exit:
        (basic_props:atm/1)TmpDir is an atom.

      PREDICATEdev_null/1

      Usage:dev_null(Path)

      File path for the null device (/dev/null file in POSIX, nul in Windows)

      PREDICATEpause/1
      pause(Seconds)

      Make this thread sleep for some Seconds.

      Usage:

      • The following properties should hold at call time:
        (basic_props:int/1)Seconds is an integer.

      PREDICATEwait/2

      Usage:wait(Pid,RetCode)

      wait/2 waits for the process numbered Pid. Fails if the process does not terminate normally or in case of error (see C waitpid() for details). RetCode is a positive number indicating the process return code if the process terminated normally, or a negative number if the process terminated due to a signal.

      PREDICATEkill/2

      Usage:kill(Pid,Signal)

      kill/2 sends the signal Signal to the process or process group specified by Pid. See Unix man page for a detailed description of signals.

      PREDICATEget_pid/1
      get_pid(Pid)

      Unifies Pid with the process identificator of the current process or thread.

      Usage:

      PREDICATEget_uid/1
      get_uid(Uid)

      Unifies Uid with the user id of the current process.

      Usage:

      PREDICATEget_gid/1
      get_gid(Uid)

      Unifies Gid with the group id of the current process.

      Usage:

      PREDICATEget_pwnam/1
      get_pwnam(User)

      Unifies User with the user of the current process, as specified in the /etc/passwd file.

      Usage:

      PREDICATEget_grnam/1
      get_grnam(Group)

      Unifies Group with the group of the current process, as specified in the /etc/group file.

      Usage:

      PREDICATEget_numcores/1
      get_numcores(N)

      Unifies N with the number of CPU cores.

      Usage:

      PREDICATEshell/0

      Usage:

      Executes the OS-specific system shell. When the shell process terminates, control is returned to Prolog. See shell/2 for details.

        PREDICATEshell/1
        shell(Command)

        Command is executed in the OS-specific system shell. It succeeds if the exit code is zero and fails otherwise. See shell/2 for details.

        Usage:

        • The following properties should hold at call time:
          (basic_props:atm/1)Command is an atom.

        PREDICATEshell/2
        shell(Command,RetCode)

        Executes Command using the OS-specific system shell and stores the exit code in RetCode. If Command is the empty atom '', executes the OS-specific system shell.

        On POSIX-like systems the system shell is specified by the SHELL environment variable ($SHELL -c "command" for passing user commands). On Windows (native builds, MinGW) it is specified by the COMSPEC environment variable (%COMSPEC% /s /c "command" for passing user commands).

        Note that the use of shell/2 predicates is discouraged for portability and security reasons. Please consider process for a more robust way to launch external processes.

        Usage:

        • Calls should, and exit will be compatible with:
          (basic_props:int/1)RetCode is an integer.
        • The following properties should hold at call time:
          (basic_props:atm/1)Command is an atom.
        • The following properties hold upon exit:
          (basic_props:int/1)RetCode is an integer.

        PREDICATEsystem/1
        system(Command)

        Like shell/1 but ignores exit code.

        Usage:

        • The following properties should hold at call time:
          (basic_props:atm/1)Command is an atom.

        PREDICATEsystem/2
        system(Command,RetCode)

        Synonym for shell/2.

        Usage:

        • Calls should, and exit will be compatible with:
          (basic_props:int/1)RetCode is an integer.
        • The following properties should hold at call time:
          (basic_props:atm/1)Command is an atom.
        • The following properties hold upon exit:
          (basic_props:int/1)RetCode is an integer.

        PREDICATEfd_dup/2
        fd_dup(FD,NewFD)

        Duplicate the file descriptor FD into NewFD

        Usage 1:

        Duplicate a file description into a new free file descriptor (C dup())

        Usage 2:

        Duplicate a file description into a specified file descriptor (C dup2())

        PREDICATEfd_close/1

        Usage:

        Close the file descriptor (using C close())

        • The following properties should hold at call time:
          (basic_props:int/1)Arg1 is an integer.

        PREDICATEwinpath/3
        winpath(Option,Posix,WinPath)

        Option specifies if you want to get a relative or a full path. Posix represent a path as usual in unix, and WinPath is the Windows-Style representation of Posix.

        Usage 1:

        Usage 2:

        PREDICATEwinpath/2

        Usage 1:winpath(A,B)

        Usage 2:winpath(A,B)

        Usage 3:winpath(A,B)

        PREDICATEwinpath_c/3
        Same as winpath/3, but for strings.

        PREDICATEcyg2win/3

        Usage:cyg2win(CygWinPath,WindowsPath,SwapSlash)

        Converts a posix path to a Windows-style path. If SwapSlash is swap, slashes are converted in to backslash. If it is noswap, they are preserved.

        PREDICATEno_swapslash/3
        No further documentation available for this predicate.

        PREDICATEcyg2win_a/3
        Same as cyg2win/3, but for atoms.

        PREDICATEusing_windows/0

        Usage:

        Using the Windows native API (not POSIX)

          PREDICATEget_home/1

          Usage:get_home(H)

          H is the home directory (HOME environment variable in POSIX systems and APPDATA in Windows)

          • The following properties should hold at call time:
            (term_typing:var/1)H is a free variable.

          PREDICATEfind_executable/2

          Usage:find_executable(Name,Path)

          Path is the absolute path of the command Name, reachable from the PATH (environment variable) directories if Name is not an absolute path. The suffix for executable files is optionally added to Path depending on the current operating system.

          Documentation on imports

          This module has the following direct dependencies:
          Generated with LPdoc using Ciao