Creating Processes

  This subsection describes the procedures used to start new processes. In the general case, many pieces of state must be specified for a new process, so in addition to the procedures that actually start a process there are a number of auxiliary procedures for specifying its state.

 

TYPE
  ProcessTemplate = REF;

  A process template is used as a way of shortening the parameter list to StartProcess and StartProcessSearch. It contains initial values for most components of a process (a few are passed explicitly to StartProcess and StartProcessSearch). One creates a process template with NewProcessTemplate; modifies it using SetDescriptor, SetUMask, SetWD, SetControlTerminal, UnsetControlTerminal, SetPGRP, SetUser, and SetSignalState, as well as OSFriends.SetSTrace and OSFriends.SetPriority described in Appendix A.4, page ; and finally passes it to StartProcess or StartProcessSearch. One eliminates a surplus process template (one that is not going to be used) by calling CloseTemplate.

 

PROCEDURE NewProcessTemplate(): ProcessTemplate RAISES {};

NewProcessTemplate creates a new process template with the following content:

•   An empty array of file handles (see SetDescriptor in this section and GetDescriptor on page ).
•                 The same process group, real and effective user name and password, umask, working directory, control terminal, and initial thread priority as those of process calling NewProcessTemplate.
•   The signal state SignalDefault for all signals, except the state SignalIgnore for those signals whose state in the process calling NewProcessTemplate is SignalIgnore.

  Once a process template has been used in a call to StartProcess or StartProcessSearch (unsuccessful or otherwise), it becomes invalid and InvalidArgumentEC is raised if it is used again. The value NIL is also considered to be an invalid process template.

  

PROCEDURE SetDescriptor(
    template: ProcessTemplate;
    d: CARDINAL;
    f: File)
  RAISES {Error}; (* BadFileEC, InvalidArgumentEC *)

  SetDescriptor sets the d'th entry in the array of file handles passed to the new process to the specified value. Once SetDescriptor returns, calling Close on the same file handle has no effect on the file handle stored in the template. (It is as if SetDescriptor calls Dup.) See the discussion of GetDescriptor on page . SetDescriptor raises InvalidArgumentEC if template is invalid.

  

PROCEDURE SetUMask(
    template: ProcessTemplate;
    umask: AccessMode)
  RAISES {Error}; (* InvalidArgumentEC *)

  SetUMask sets the umask (file access mode creation mask) in the template to the specified value. It raises InvalidArgumentEC if template is invalid.

  

PROCEDURE SetWD(
    template: ProcessTemplate;
    dir: Dir;
    path: PathName := NIL;
    euser: User := NIL)
  RAISES {Error};
  (* NotSuperUserEC, InvalidArgumentEC, NotADirectoryEC,
     FailureES? *)

  SetWD sets the working directory in the template to be the directory with the path name specified by the path and dir parameters. It raises InvalidArgumentEC if template is invalid, or NotADirectoryEC if this is not the path name of a directory.

SetWD interprets the euser parameter the same way Open does.

  

PROCEDURE SetControlTerminal(
    template: ProcessTemplate;
    f: File;
    setGroup: BOOLEAN := TRUE)
  RAISES {Error};
  (* InvalidArgumentEC, BadFileEC, NotATerminalEC *)

    SetControlTerminal sets the control terminal in the template to be the specified file. It raises InvalidArgumentEC if template is invalid, or NotATerminalEC if the file is not a tty device. If setGroup is TRUE, then when the new process is started using this template, the distinguished process group of the file is set to be that of the new process.

 

PROCEDURE UnsetControlTerminal(template: ProcessTemplate)
  RAISES {Error}; (* InvalidArgumentEC *)

  UnsetControlTerminal modifies the process template so that the new process created from it will not have a control terminal. As mentioned in Section 2.10, page , a process with no control terminal automatically acquires as a control terminal the first tty device that it opens. UnsetControlTerminal raises InvalidArgumentEC if template is invalid.

 

PROCEDURE SetPGRP(template: ProcessTemplate)
  RAISES {Error}; (* InvalidArgumentEC *)

    SetPGRP sets a flag in the template so the process started using that template will be its own process group leader: its process group identifier will be the same as its process identifier. (The process identifier of the new process is always returned by StartProcess and StartProcessSearch.) SetPGRP raises InvalidArgumentEC if template is invalid.

  

PROCEDURE SetUser(
    template: ProcessTemplate;
    effective: User;
    real: User := NIL;
    pswd: Text.T := NIL)
  RAISES {Error};
  (* InvalidArgumentEC, InvalidCredentialsEC, NotSuperUserEC *)

      SetUser sets the effective and real user names and password in the template to the specified values. It raises InvalidArgumentEC if template is invalid or effective is NIL. It raises NotSuperUserEC unless the calling process is the super-user, or the effective parameter is equal to the real parameter, or is equal to the current effective or real user name of the calling process.

  Specifying NIL for real means not to change the real user name or password in the template. If real is not NIL, then normally pswd must be the corresponding password (in clear text); after the password has been checked, the real user name and password are stored in the template. There are a few special cases:

• If real=real user name of calling process and pswd=NIL, the real user name and password already in the template are left unchanged.
• If real=`root' and pswd=NIL, then NotSuperUserEC is raised if the calling process is not the super-user, otherwise the specified real user name and password are stored in the template without further validation.
• In all other cases, the specified real user name and password are checked. InvalidCredentialsEC is raised if they are not valid, otherwise they are assigned to the template.

Ultrix note: SetUser currently raises NotSuperUser if the calling process is not the super-user.

 

PROCEDURE SetSignalState(
    template: ProcessTemplate;
    signal: Signal;
    state: SignalState)
  RAISES {Error}; (* InvalidArgumentEC, BadStateForSignalEC *)

  SetSignalState allows changing the initial signal states that will be in effect when a new process is started. The template created by NewProcessTemplate specifies SignalDefault for all signals, except those whose state in the calling process was SignalIgnore are also set to SignalIgnore in the template.

      SetSignalState raises InvalidArgumentEC if template is invalid. It raises BadStateForSignalEC if signal equals SigKill or SigStop, or if signal equals SigCont and state equals SignalIgnore.

    If an Ultrix application is started with this process template, the SignalState value is mapped to Ultrix signal handler and signal mask settings (see sigvec(2)) as follows:

 

TYPE
  Relationship = (Child, Orphan);

 

PROCEDURE StartProcess(
    dir: Dir;
    path: PathName;
    argv: Text.RefArray := NIL;
    template: ProcessTemplate := NIL;
    relationship: Relationship := Child;
    env: Text.RefArray := NIL;
    euser: User := NIL)
    : PID
  RAISES {Error};
  (* NotSuperUserEC, PathES, InvalidArgumentEC,
     BadExecutableEC, ShortExecutableEC, NotEnoughVMEC,
     FailureES? *)

  

PROCEDURE StartProcessSearch(
    VAR IN searchPath: SearchPath;
    path: PathName;
    argv: Text.RefArray := NIL;
    template: ProcessTemplate := NIL;
    relationship: Relationship := Child;
    env: Text.RefArray := NIL;
    spStart: CARDINAL := 0;
    spCount: CARDINAL := LAST(CARDINAL);
    euser: User := NIL)
    : PID
  RAISES {Error};
  (* NotSuperUserEC, PathES, InvalidArgumentEC,
     BadExecutableEC, ShortExecutableEC, NotEnoughVMEC,
     FailureES? *)

    StartProcess starts a new process running the program with the path name specified by dir and path. StartProcessSearch starts a new process running a program with a path name specified by searchPath[spStart FOR spCount] and path. (Like the OpenSearch procedure, described on page , it tries successive elements within searchPath to find a file executable by the calling process with the specified path name.) Both StartProcess and StartProcessSearch return the process identifier of the new process.

  The file specified by the path name is taken to be an a.out file if its first longword contains one of three `magic numbers'; for details see a.out(5). StartProcess and StartProcessSearch raise ShortExecutableEC if the a.out file is not as long as indicated by the size fields in its header.

Alternatively, if the specified file starts with an appropriate header, it is deemed to be a script to be executed by an interpreter specified in that header. The format of such a script header is given by the grammar:

<scriptheader> ::= # ! <optblanks> <interpreter> <optarg> <newline>
<optblanks>    ::= <empty> | <blanks>
<blanks>       ::= <blank> | <blanks> <blank>
<blank>        ::= <the \040 character>
<interpreter>  ::= <pathname>
<optarg>       ::= <empty> | <arg>
<arg>          ::= <blanks> <zero or more characters, excluding \012>
<newline>      ::= <the \012 character>

The <interpreter> specifies the path name of another file, which must be in a.out format (or else BadExecutableEC is raised). That program is started, with the original argument list prefixed by the name of the interpreter script and <arg> from the script header.

StartProcess and StartProcessSearch raise BadExecutableEC if the file is neither an a.out file nor an interpreter script.

  If the SetUIDonExec flag is set in the file mode of the file passed to StartProcess or StartProcessSearch, then the new process is created with its effective user name equal to the user name of the owner of the file.

If template is NIL, a new template as created by NewProcessTemplate is used. InvalidArgumentEC is raised if template is not NIL but is otherwise invalid.

        If relationship is Child, the new process becomes a child of the caller, who assumes the burden of eventually calling WaitForChild with the process identifier of the child. If relationship is Orphan, the new child becomes a child of the Init process (whose process identifier equals one). (WaitForChild raises an exception when called with the process identifier of an orphan.)

          If argv is not NIL, it contains character-string arguments to be passed to the child in the standard Ultrix fashion. If the child is a Topaz program, it can retrieve these arguments via Params.GetParameter. By convention, argv should be non-NIL and its first element should be the name of the program, i.e., the last component of the path parameter. (If argv is NIL or is a zero-length array, the child is given one argument equal to the path parameter used to start it.)

            If env is not NIL, it contains the environment variables to be passed to the child in the standard Ultrix fashion. (Each element of env is a string of the form name=value; see environ(7) for more details.) If the child is a Topaz program, it can retrieve these environment strings via Params.GetEnvironmentName and Params.GetEnvironment. If env is NIL, the environment of the calling process is passed. (To pass an empty environment, create a zero-length Text.RefArray.)

After StartProcess or StartProcessSearch returns or raises an exception, the supplied template becomes invalid. Each procedure raises TooManyProcessesEC if there are no more address spaces (on Taos) or process table entries (on Ultrix), or NotEnoughVMEC if the new process would require more virtual memory than is allowed by the imposed maximum (see getrlimit(2)).

StartProcess and StartProcessSearch interpret the euser parameter the same way Open does. Note that euser is only used to do the access check on the path parameter; it is not inherited as the user name of the new process unless SetUser is used.

Taos note: The SetUIDonExec flag is ignored if the file passed to StartProcess or StartProcessSearch resides on a remote machine. (In the future, Taos will allow `trusted servers to supply SetUIDonExec programs.)

Ultrix note: If relationship is Orphan, an extra transient process is created. If SetUser has been set for the new process, the new user must have execute permission on the given file.

 

PROCEDURE CloseTemplate(template: ProcessTemplate)
  RAISES {Error};

    CloseTemplate closes a template that is not going to be used to start a new process. This releases all resources held by the template and marks the template as invalid. CloseTemplate has no effect if the template has already been used to start a process or has been closed. CloseTemplate is an optimization for use by careful programmers; its effect occurs automatically when a template is garbage-collected or the creating process terminates.