Click above to get retro games delivered to your door ever month!

system
======

Syntax
------

     #include <stdlib.h>
     
     int system(const char *cmd);

Description
-----------

This function runs the command or program specified by CMD.  When
calling programs compiled by DJGPP this function will not use
`command.com' and so will not be subject to its 126 character limit on
command lines.

Command lines and pipes( i.e., the use of "<", ">", ">>", and "|") will
be simulated internally in this function; this means that you can have
both long command lines and redirection/pipes when running DJGPP
programs with this function.

By default, `command.com' will only be invoked to run commands internal
to it, or to run batch files (but this can be changed, see below).  In
these cases, the returned error code will always be zero, since
`command.com' always exits with code 0.

Certain commands internal to `command.com' that don't make sense or
cause no effect in the context of `system' are ignored by this
function.  These are `REM', `EXIT', `GOTO', `SHIFT'; `SET', `PATH' and
`PROMPT' are ignored only if called with an argument.  You can disable
this feature if you need, see below.

Some commands are emulated internally by `system', because the
emulation is better than the original.  Currently, the only emulated
command is `CD' or `CHDIR': the emulation knows about forward slashes
and also switches the current drive.  This emulation can also be
switched off, as explained below.

When `system' is presented with an internal shell command, it checks
the environment variables `SHELL' and `COMSPEC' (in that order) and
invokes the program that they point to.  If the shell thus found is one
of the DOS shells (`command.com', `4DOS' or `NDOS'), they are called
with the `/c' switch prepended to the command line.  Otherwise,
`system' assumes that the shell is a Unix-style shell and invokes it
with a `-c' switch, passing the entire command line via a response file
(this should work with any shell compiled with DJGPP, and with the
`ms_sh' shell).

Shell scripts and batch files are invoked by calling either the program
whose name appears on the first line (like in `#! /bin/sh'), or the
default shell if none is specified by the script.  If the name of the
shell specified by the script is a Unix-style pathname, without a drive
letter and with no extension, `system' will additionally search for it
on the `PATH'.  This allows to invoke Unix shell scripts unmodified, if
you have a ported shell installed on your system.

You can customize the behavior of `system' using a bit-mapped variable
__SYSTEM_FLAGS, defined on `<stdlib.h>'.  The following bits are
currently defined:

`__system_redirect'
     When set (the default), specifies that `system' can use its
     internal redirection and pipe code.  If reset, any command line
     that includes an unquoted redirection symbol will be passed to the
     shell.

`__system_call_cmdproc'
     When set, `system' will always call the shell to execute the
     command line.  If reset (the default), the shell will only be
     called when needed, as described above.

     You should *always* set this bit if you use a real, Unix-style
     shell (also, set `__system_use_shell', described below, and the
     `SHELL' environment variable).

`__system_use_shell'
     When set (the default), the `SHELL' environment variable will take
     precedence upon `COMSPEC'; this allows you to specify a special
     shell for `system' that doesn't affect the rest of DOS.  If reset,
     only `COMSPEC' is used to find the name of the command processor.

`__system_allow_multiple_cmds'
     When set, you can put multiple commands together separated by the
     `;' character.  If reset (the default), the command line passed to
     `system' is executed as a single command and `;' has no special
     meaning.

`__system_allow_long_cmds'
     When set (the default), `system' will handle command lines longer
     than the DOS 126-character limit; this might crash your program in
     some cases, as the low-level functions that invoke the child
     program will only pass them the first 126 characters.  When reset,
     `system' will detect early that the command line is longer than
     126 characters and refuse to run it, but you will not be able to
     call DJGPP programs with long command lines.

`__system_emulate_command'
     If reset (the default), `system' will pass the entire command line
     to the shell if its name is one of the following: `sh.exe',
     `sh16.exe', `sh32.exe', `bash.exe', `tcsh.exe'.  When set,
     `system' will attempt to emulate redirection and pipes internally,
     even if `COMSPEC' or `SHELL' point to a Unix-style shell.

`__system_handle_null_commands'
     When set (the default), commands internal to `COMMAND.COM' and
     compatible shells which have no effect in the context of `system',
     are ignored (the list of these commands was given above).  If
     reset, these commands are processed as all others, which means
     `COMMAND.COM' will be called to execute them.

     Note that this bit shouldn't be used with a Unix-style shell,
     because it does the wrong thing then.  With Unix-style shells, you
     are supposed to set the `__system_call_cmdproc' bit which will
     always call the shell.

`__system_ignore_chdir'
     If set, the `CD' and `CHDIR' commands are ignored.  When reset
     (the default), the processing of these commands depends on the
     `__system_emulate_chdir' bit, see below.

     This bit is for compatibility with Unix, where a single `cd dir'
     command has no effect, because the current working directory there
     is not a global notion (as on MSDOS).  Don't set this bit if you
     use multiple commands (see `__system_allow_multiple_cmds' above).

`__system_emulate_chdir'
     When set, the `CD' and `CHDIR' commands are emulated internally:
     they change the drive when the argument specifies a drive letter,
     and they support both forward slashes and backslashes in
     pathnames.  When `CD' is called without an argument, it prints the
     current working directory with forward slashes and down-cases DOS
     8+3 names.  If this bit is reset (the default), `CD' and `CHDIR'
     are passed to the shell.

The behavior of `system' can be customized at run time by defining the
variable `DJSYSFLAGS' in the environment.  The value of that variable
should be the numerical value of `__system_flags' that you'd like to
set; it will override the value of `__system_flags' specified when the
program was compiled.

Return Value
------------

The exit status of the child process in the lower 8 bits of the return
value; bits 8-17 of the return value will hold `SIGINT' or `SIGABRT' if
the child process was aborted by `Ctrl-C' or Critical Device Error,
respectively; otherwise it will be zero.  If the child couldn't be run,
`system' will return -1 and set `errno' to an appropriate value.  Note
that if `COMMAND.COM' was used to run the child, it will always return
a 0 status, even if the command didn't run successfully.  However,
`system' only calls `COMMAND.COM' when it needs to run commands
internal to it.

Example
-------

     system("cc1plus.exe @cc123456.gp");