SystemTagList

Have a shell execute a command line (V36)

Similar to Execute(), creates a new shell in various ways. Spawns a Shell Process to execute the command. Depending on its arguments, may or may not wait for the command(s) to be completed. If it does wait, returns the return code of the command, or returns 0 for success in all cases, or -1 if the command(s) could not be run for any reason.

If System() waits for completion, the input and output filehandles will not be closed by System, you must close them (if needed) after System returns if you specified them via SYS_Input or SYS_Output. The command stream SYS_Command/SYS_CmdName will always be closed on success, regardless of other arguments.

By default, the new Process will use your current Input() and Output() filehandles. Normal Shell command-line parsing will be done including redirection on 'command'. The current directory and path will be inherited from your Process. Your path will be used to find the command if no path is specified.

Note that you may NOT pass the same FileHandle for both SYS_Input and SYS_Output. If you want input and output to both be to the same CON: window, pass a SYS_Input of a FileHandle on the CON: window, and pass a SYS_Output of NULL. The shell will automatically set the default Output() stream to the window you passed via SYS_Input, by opening "*" on that handler, or "NIL:" if "*" could not be opened.

If used with the SYS_Asynch flag, it WILL close both its input and output filehandles after running the command (even if these were your Input() and Output()!).

If command is NULL, System() will read from SYS_CmdStream, or SYS_Input if the former is not given. It will return immediately and execute such commands in the background, even without SYS_Asynch set. (V40) This mode is used to implement RUN, see NOTES below.

SYS_Asynch can also be set along with a command or a SYS_CmdStream. In such a case, the shell will execute the commands from SYS_CmdStream or command asynchronously, and after its depletion, will continue to read commands interactively from the input FileHandle. (V47) This mode is used to implement the NEWSHELL command, see NOTES.

Normally uses the boot (ROM) shell, but other shells can be specified via SYS_UserShell and SYS_CustomShell. Normally, you should send things written by the user to the UserShell. The UserShell defaults to the same shell as the boot shell.

The tags are passed through to CreateNewProc(), tags that conflict with SystemTagList() will be filtered out. This allows setting things like priority, etc. for the new Process. The tags that are currently filtered out are:

• NP_Seglist
  
  
• NP_FreeSeglist
  
  
• NP_Entry
  
  
• NP_Input
  
  
• NP_Output
  
  
• NP_Error
  
  
• NP_CloseInput
  
  
• NP_CloseOutput
  
  
• NP_CloseError
  
  
• NP_HomeDir
  
  
• NP_Cli
  
  

command

Program and arguments or NULL. In case command is NULL, a new shell will be started that reads commands from SYS_CmdStream or SYS_CmdIn (if supplied) followed by SYS_Input or SYS_InName, until both sources are exhausted. See below for interaction with SYS_Asynch.

tags

see <dos/dostags.h>. Note that both SystemTagList()- specific tags and tags from CreateNewProc() may be passed.

SYS_Input (BPTR)

The input stream the shell will receive. This stream will go into cli_StandardInput of the shell and will by that also become the input stream of the command if one is supplied. If command is NULL and SYS_CmdStream/CmdName is not supplied, commands are read from SYS_Input/InName instead. Default is the input stream of the caller.

SYS_InName (const TEXT *, V47)

A file name that will be opened to supply an input stream. This is mutually exclusive to SYS_Input and overrides it if present. The input file will be closed when the command or shell returns.

SYS_Output (BPTR)

The output stream of the shell to be created. This stream will go into cli_StandardOutput of the shell and will by that also become the output stream of the command if one is supplied. Default is the output stream of the caller. If this is NULL, System() will instead use Open("*",MODE_NEWFILE) as output from the handler responsible for SYS_Input if this stream is interactive. Otherwise, or if "*" could not be opened, output will go to "NIL:".

SYS_OutName (const TEXT *, V47)

A file name that will be opened to supply an output stream. This is mutually exclusive to SYS_Output.

The file will be closed on exit.

SYS_CmdStream (BPTR, V47)

Mutually exclusive to the command argument. If command is NULL, then the shell will instead read commands from this stream until it depletes. If SYS_Asynch is also set, then the shell will continue reading from SYS_Input.

The default is NULL in which case the command to be executed comes either from command or SYS_Input or SYS_InCmd. The CmdStream is always closed on exit, even if it is your stream.

SYS_CmdName (BPTR, V47)

A file name that will be openend to supply the command stream. This is mutually exclusive to SYS_CmdStream.

The stream will be closed on exit.

SYS_Asynch (BOOL)

Start the new shell in the background and return immediately. This is implicit if command is NULL and SYS_CmdStream is not supplied. This also implies that all streams will be closed by the shell/command once it returns, and NP_CurrentDir will be unlocked.

SYS_UserShell (BOOL)

Starts the user shell, i.e. "Shell" on the resident list instead of the system Boot CLI.

SYS_CustomShell (BOOL)

Starts a custom shell from the resident list. The argument is a name of a resident module.

error

0 for success, result from command, or -1.

Note that on error, the caller is responsible for any filehandles or other things passed in via tags.

-1 will only be returned if dos.library could not create the new shell. If the command is not found, the shell will return an error value, normally RETURN_ERROR.

If System() runs a shell or command asynchronously, the result code is either 0 for success, or -1 in case the shell or command(s) could not be launched.

This function requires (as of V47) about 800 bytes stack space, and needs the caller to be a Process. There is no automatic stack extension.

The RUN command is equivalent to

System(NULL,SYS_Input,instream,SYS_Output,Output(),

where instream is a stream that delivers the command to be run. For historical reasons, SYS_Async is implicitly set by System(), even if not given, and the command is passed in through a faked stream, not as first argument, see also BUGS below.

The NEWSHELL command is equivalent to

While V47 goes through System(), previous releases of NewShell used an undocumented legacy shell startup mechanism that has been deprecated.

The Execute() function is roughly equivalent to

V45 and before could release SYS_Input in some error cases. This is fixed in V47 where System() either returns the command return code, or -1, and does not release caller resources in the latter case.

In case the function returned -1 to indicate failure, any Lock passed in as NP_CurrentDir was released by V45 and before, even though the docs stated and still state that the caller is responsible for releasing it on error. This also got fixed in V47. Note that in case of success, NP_CurrentDir is passed over to the shell/command created and is released there - this is as documented and not a bug.

NP_Name was not honoured. Instead, the new shell always received the name "Background CLI", even with NP_Name set. V47 fixes this.

If command is NULL, System() always detaches the shell it creates and does not wait for its completion, even if SYS_Async is FALSE. V47 retains this behaviour for compatibility reasons. The shell created this way is non-interactive, signal-handling is not forwarded to the shell, and the console port remains unset, i.e. the configuration is as required for the Run command which uses such parameters, see NOTES above. To create an interactive shell, set SYS_Asynch to TRUE explicitly.

In case command is NULL and a command and input stream coincide, System() prints the CLI number of the created shell in brackets over the output stream as these arguments also reflect the Run command. This should be again better implemented in the Run and not in the System() function but also remains as such for compatibility.

V45 and below did not clearly document that System() can (obviously) not return a command result code in asynchronous operations.

Execute(), CreateNewProc(), <dos/dostags.h>, Input(), Output()