(****************************************************************)
(*                                                              *)
(*         Gardens Point Modula-2 Library Definition            *)
(*                                                              *)
(*                                                              *)
(*     (c) Copyright 1996 Faculty of Information Technology     *)
(*              Queensland University of Technology             *)
(*                                                              *)
(*     Permission is granted to use, copy and change this       *)
(*     program as long as the copyright message is left intact  *)
(*                                                              *)
(****************************************************************)

FOREIGN DEFINITION MODULE UxProcesses;
  IMPORT IMPLEMENTATION FROM "uxprocesses.o";

  FROM BuildArgs IMPORT ArgPtr;
  FROM Types IMPORT Int32, Card32;

  PROCEDURE Fork() : Int32;
  (* Spawns a duplicate process. Same as UNIX fork(2).       *)
  (* Returns 0 to child process, and the child's process ID  *)
  (* to the parent process. Returns -1 if fork unsuccessful  *)

  PROCEDURE Exec (path : ARRAY OF CHAR; (* absolute file name *)
		  argv : ArgPtr);       (* the argument array *)
  PROCEDURE Execp(path : ARRAY OF CHAR; (* base of file name  *)
		  argv : ArgPtr);       (* the argument array *)
  (* postcondition : the process designated by path is exec- *)
  (*		     uted in place of the current process.   *)
  (*		     Execp searches for the file on $PATH.   *)
  (*		     Only returns if file cannot be execed.  *)
  (*    Exec  ==>  Equivalent to UNIX execv(2) system call.  *)
  (*    Execp ==>  Equivalent to UNIX execvp(2) system call. *)

  PROCEDURE Wait(VAR result : Int32) : Int32;
  (* postcondition : Waits for the termination of a child,   *)
  (*		     or the receipt of a signal. Returns -1  *)
  (*		     for a signal, child ID for termination. *)
  (*		     (result DIV 256) holds 0 for signal, or *)
  (*			exit code for termination.	     *)
  (*		     (result MOD 256) holds signal number,   *)
  (*			or zero for termination of child.    *)

  PROCEDURE Sleep(time : Card32) : Card32;
  (* postcondition : (time - function-return-value) seconds  *)
  (*		      have elapsed. Returns early (after     *)
  (*		      signal handling) if a signal is caught *)

  (* Various procedures for fetching process and parent ids  *)
  PROCEDURE ProcessID() : Int32;
  PROCEDURE ProcessGroupID() : Int32;
  PROCEDURE ParentProcessID() : Int32;

  (* Various procedures for fetching user and group idents   *)
  PROCEDURE UserID() : Card32;
  PROCEDURE GroupID () : Card32;
  PROCEDURE EffectiveUID() : Card32;
  PROCEDURE EffectiveGID() : Card32;

  (* Typical Usage :
   *  FROM UxProcesses IMPORT Fork, Exec, Wait;
   *  FROM BuildArgs IMPORT ArgPtr, Arg3;
   *  FROM Types IMPORT Int32;
   *
   *  VAR result : Int32; childId : Int32;
   *  ...
   *  IF Fork() = 0 THEN (* do child stuff here *)
   *  ELSE (* in the parent here *)
   *    childId := Wait(result);
   *    Exec("/usr/bin/vi",Arg3("vi","+39","uxproces.def"));
   *    Error("Couldn't exec vi");
   *  END;
   *)
END UxProcesses.