HELP OS Robert Duncan, May 1991 Interface to the host operating system. CONTENTS - (Use g to access required sections) -- The OS Module -- Exceptions -- Operating System Version -- The Current Process State -- Process Control -- Unix-only Functions -- VMS-only Functions -- The OS Module ------------------------------------------------------ signature OS structure OS : OS The autoloadable library module -OS- defines a set of functions which provide access to features of the host operating system. It is described by the following signature: signature OS = sig (* Exceptions *) exception Error of string * string * string exception NotImplemented of string (* O/S Version *) val version : unit -> string val isunix : unit -> bool val isvms : unit -> bool (* The Current Process State *) val pid : unit -> int val username : unit -> string val pwd : unit -> string val cd : string -> unit val arglist0 : unit -> string list val arglist : unit -> string list val translate : string -> string Option.option val date : unit -> string (* Process Control *) val obey : string -> int val wait : unit -> (int * int) Option.option val kill : int -> bool (* UNIX only *) val envlist : unit -> string list val fork : unit -> int Option.option val execve : string -> string list -> string list -> 'a (* VMS only *) val spawn : string -> string -> string -> bool -> int Option.option val attach : int -> bool end (* signature OS *) POPLOG ML runs under both the Unix and VMS operating systems. As far as possible, these functions have been made compatible between both systems. However, certain functions are restricted to one or other system: attempting to run one of these functions on a system other than that for which it was intended will generate the exception NotImplemented() where is the name of the function concerned. -- Exceptions --------------------------------------------------------- exception NotImplemented (name : string) As described above, this exception is raised whenever an unimplemented function is called. exception Error (name : string, msg : string, argument : string) Raised whenever an operating system error occurs during the execution of any of these functions. -name- is the name of the function which failed; -msg- is a message describing the reason for the error and -argument- is the argument supplied to the function call (where appropriate). For example, trying to change to the directory "nonexistent" using the -cd- function might generate the exception: Error("cd", "no such file or directory", "nonexistent") -- Operating System Version ------------------------------------------- val version () : string Returns a string giving an approximate description of the host operating system. val isunix () : bool Returns -true- if the host is a Unix system. val isvms () : bool Returns -true- if the host is a VMS system. -- The Current Process State ------------------------------------------ val pid () : int Returns the Process ID of the current process. val username () : string Returns the name of the current user. val pwd () : string Returns the full pathname of the process' current (default) directory. val cd (dir : string) : unit Changes the process' current (default) directory to -dir-. Raises the exception Error("cd", , dir) if the directory can't be changed for any reason. val arglist0 () : string list Returns the command by which the current process was invoked. val arglist () : string list Returns the usable command-line arguments of the current process: this will always be some tail of the list returned by -arglist0- but with the first element (the command name) removed, together with any leading arguments already processed by Poplog. val translate (name : string) : string Option.option Translates the environment variable (logical name) -name- returning Option.SOME() if -name- is bound to -value- in the current environment, or Option.NONE if -name- is unbound. val date () : string Returns the current date and time in operating system format. -- Process Control ---------------------------------------------------- val obey (cmd : string) : int Runs -cmd- as a shell or DCL command and returns the exit status. val wait () : (int * int) Option.option Waits for the next child process to terminate. Returns Option.SOME(, ) if the child process identified by -pid- terminated with given exit -status-, or Option.NONE if the wait was interrupted. Raises the exception Error("wait", , "") if there were no children. val kill (pid : int) : bool Attempts to send a kill (terminate) signal to the process identified by -pid-. Returns -true- or -false- according to whether the signal could or could not be sent. -- Unix-only Functions ------------------------------------------------ val envlist () : string list Returns a list of all the variables in the process' environment where each entry in the list has the form = val fork () : int Option.option Interface to the fork(2) system call. Returns Option.SOME() to the parent process, where -pid- is the Process ID of the newly created child process, and Option.NONE to the child. Raises the exception Error("fork", , "") if the fork fails for any reason. val execve (cmd : string) (args : string list) (env : string list) : 'a Interface to the execve(2) system call. -cmd- is the pathname of the file to be executed; -args- is a list of arguments (where the first argument is conventionally the command name) and -env- is the environment for the sub-process in the format as returned by -envlist-. This function should never return, hence the arbitrary result type; the exception Error("execve", , cmd) is raised if the execve fails for any reason. -- VMS-only Functions ------------------------------------------------- val spawn (cmd:string) (input : string) (output : string) (wait : bool) : int Option.option Interface to the library routine "lib$spawn": spawns a sub-process with a command interpreter. If -cmd- is the null string, command input is read from the source named by -input-: if this is also null, commands are read from the input of the parent process. If -cmd- is not the null string, it is first obeyed as a DCL command. The process then terminates if -input- is null, or else continues reading commands from -input-. In either case, output is written to the file named by -output- or to the parent's output if -output- is null. The flag -wait- determines whether or not the parent should wait for the sub-process to terminate: if -true-, the call to -spawn- will not return until the sub-process has terminated and the result will be Option.NONE If -wait- is -false-, then the call to -spawn- returns immediately with the result Option.SOME() where is the Process ID of the sub-process. val attach (pid : int) : bool Suspends the current process and revives the process identified by -pid-. Returns -false- if there is no such process or if the process cannot be revived, or -true- whenever the current process is itself revived. --- C.all/pml/help/os --- Copyright University of Sussex 1991. All rights reserved. ----------