CreateNewProc

Create a new Process (V36)

This creates a new Process according to the tags passed in. See <dos/dostags.h> for the tags.

You must specify one of NP_Seglist or NP_Entry. NP_Seglist takes a seglist (as returned by LoadSeg()). NP_Entry takes a function pointer for the routine to call.

There are many options, as you can see by examining <dos/dostags.h>. The defaults are for a non-CLI Process, with copies of your CurrentDir, HomeDir (used for PROGDIR:), priority, consoletask, windowptr, and variables. The input and output filehandles default to opens of NIL:, stack to 4000, and others as shown in <dos/dostags.h>. This is a fairly reasonable default setting for creating threads, though you may wish to modify it (for example, to give a descriptive name to the Process.)

CreateNewProc() is callable from a Task, though any actions that require doing dos.library I/O (DupLock() of currentdir, for example) will not occur.

NOTE:

if you call CreateNewProc() with both NP_Arguments, you must

not specify an NP_Input of NULL. When NP_Arguments is specified, it needs to modify the input FileHandle to make ReadArgs() work properly.

tags

a pointer to a TagItem array. The following tags are supported

as of V47, see also <dos/dostags.h>:

NP_Seglist (BPTR)

Seglist of the code to run, as returned by LoadSeg() or InternalLoadSeg().

NP_FreeSeglist (BOOL)

A flag that indicates whether the seglist provided by NP_Seglist is to be released on exit. Default is FALSE.

NP_Entry (APTR)

Entry point of the code to run, mutually exclusive to NP_Seglist. Do NOT specify NP_FreeSegList with this tag.

NP_Input (BPTR)

Filehandle to use as pr_CIS, default is Open("NIL:",MODE_OLDFILE).

NP_Output (BPTR)- Filehandle to use as pr_COS, default is Open("NIL:",MODE_NEWFILE).

NP_CloseInput (BOOL)

Close pr_CIS on exit. Default is TRUE. Make sure not to reset this tag if you do not specify NP_Input.

NP_CloseOutput (BOOL)

Close pr_COS on exit. Default is TRUE. Make sure not to reset this tag if you do not specify NP_Output.

NP_Error (BPTR)

Filehandle to use as pr_CES, default is NULL, i.e. error output will be redirected to pr_COS.

NP_CloseError (BOOL)

Close pr_CES on exit. Default is FALSE.

NP_CurrentDir (BPTR)

Lock to use as current directory. Default is DupLock() of the current directory of the caller, or NULL if the caller is a Task, not a Process.

NP_StackSize (ULONG)

Stack size for the Process. Defaults to 4000 bytes.

NP_Name (const TEXT *)

Name for the new Process. Default is "New Process".

NP_Priority (BYTE)

Priority of the new Process. Default is the same as the parent.

NP_ConsoleTask (struct MsgPort *)

Message port of the Process handling "*" and "CONSOLE:". Default is the same as the caller, or NULL if the caller is a Task.

NP_WindowPtr (struct Window *)

Pointer to the window in which context error requesters will be displayed. Default is the same as the caller, or NULL if the caller is a Task.

NP_HomeDir (BPTR)

Lock to the home directory of the Process, used to resolve PROGDIR:, default is DupLock() of home directory of the caller, or NULL of the caller is a Task.

NP_CopyVars (BOOL)

Copy local shell variables if they exist. Default is TRUE.

NP_Cli (BOOL)

Create a struct CommandLineInterface and attach it to the caller. Default is FALSE.

NP_Path (BPTR)

Singly BPTR-linked list of locks to be used for searching for commands (see <dos/dosextens.h>, struct PathLock). Only used if NP_Cli is set. Default is to copy the path of the caller if it exists.

NP_CommandName (const TEXT *)

Pointer to a string of at most 104 characters, to be used as command name of the shell to be created. Used only if NP_Cli is set. Default is the command name of the caller. Note that the input string is a NUL-terminated C style string, not a BSTR.

NP_Arguments (const TEXT *)

Pointer to command line arguments, passed into the Process created, both through the registers A0 (pointer) and D0 (length) as well as in the buffer of pr_CIS, which therefore shall exist, either by default (NP_Input unspecified) or by a non-zero value of NP_Input. The arguments are copied before they are passed in, and the copy is released on exit. Default is not to set up any arguments and to keep the buffer of pr_CIS untouched.

NP_ExitCode (APTR)

Code to be called when Process dies down, receives the return code in D0, and NP_ExitData in D1.

NP_ExitData (LONG)

Data to be forwarded to NP_ExitCode in register D1.

process

The created Process, or NULL. Note that if it returns NULL, you must free any items that were passed in via tags, such as if you passed in a new current directory with NP_CurrentDir.

In V36, NP_Arguments was broken in a number of ways and probably should be avoided (instead you should start a small piece of your own code, which calls RunCommand() to run the actual code you wish to run). In V37 NP_Arguments works, though see the note above.

NP_FreeSeglist was erroneously documented to have the default TRUE, but the default was always FALSE.

NP_Error was documented in V40, but was disfunctional until V47. It is supported in V47.

NP_CloseError was documented to have the default TRUE, but pr_CES was never closed, nor populated (see above). In fact, the tag was ignored completely. To avoid problems, the default for NP_CloseError is FALSE in V47.

NP_CurrentDir, NP_HomeDir and NP_Path copy by default the corresponding fields of the caller, by DupLock() or by a series of DupLocks(). While this was always true, the include file <dos/dostags.h> may have suggested that the Lock(s) were used for the new Process without creating copies.

NP_Synchronous and NP_NotifyOnDeath were never implemented, even though they are documented. Do not use and do not expect to work.

LoadSeg(), CreateProc(), ReadArgs(), RunCommand(), <dos/dostags.h>, <dos/dosextens.h>