@node system, process
@subheading Syntax

@example
#include <stdlib.h>

int system(const char *cmd);
@end example

@subheading Description

This function runs the command or program specified by @var{cmd}.  If
@var{cmd} is a null pointer, @code{system} returns non-zero only if a
shell is available.  If @var{cmd} is an empty string, the command
processor pointed to by @samp{SHELL} or @samp{COMSPEC} variables in the
environment will be invoked interactively; type @kbd{exit @key{RET}} to
return to the program which called @code{system}.  (Note that some other
DOS compilers treat a null pointer like an empty command line, contrary
to ANSI C requirements.)

When calling programs compiled by DJGPP this function will not use
@file{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 @samp{<}, @samp{>}, @samp{>>},
and @samp{|}) 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, @file{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 @file{COMMAND.COM} always exits with code 0.

Certain commands internal to @file{COMMAND.COM} that don't make sense or
cause no effect in the context of @code{system} are ignored by this
function.  These are @code{REM}, @code{EXIT}, @code{GOTO}, @code{SHIFT};
@code{SET}, @code{PATH} and @code{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 @code{system}, because the
emulation is better than the original.  Currently, the only emulated
command is @samp{CD} or @samp{CHDIR}: the emulation knows about forward
slashes and also switches the current drive.  This emulation can also be
switched off, as explained below.

When @code{system} is presented with an internal shell command, it
checks the environment variables @samp{SHELL} and @samp{COMSPEC} (in
that order) and invokes the program that they point to.  If the shell
thus found is one of the DOS shells (@file{COMMAND.COM}, @file{4DOS} or
@file{NDOS}), they are called with the @samp{/c} switch prepended to the
command line.  Otherwise, @code{system} assumes that the shell is a
Unix-style shell and passes it the entire command line via a temporary
file, invoking the shell with a single argument which is the name of
that file.

Shell scripts and batch files are invoked by calling either the program
whose name appears on the first line (like in @w{@samp{#! /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, @code{system} will additionally
search for it on the @samp{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 @code{system} using a bit-mapped
variable @code{__system_flags}, defined on @file{<stdlib.h>}.  The
following bits are currently defined:

@table @code
@item __system_redirect
When set (the default), specifies that @code{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.

@item __system_call_cmdproc
When set, @code{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 @emph{always} set this bit if you use a real, Unix-style
shell (also, set @code{__system_use_shell}, described below, and the
@samp{SHELL} environment variable).

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

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

@item __system_allow_long_cmds
When set (the default), @code{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, @code{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.

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

@item __system_handle_null_commands
When set (the default), commands internal to @file{COMMAND.COM} and
compatible shells which have no effect in the context of @code{system},
are ignored (the list of these commands was given above).  If reset,
these commands are processed as all others, which means
@file{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 @code{__system_call_cmdproc} bit which will always call the
shell.

@item __system_ignore_chdir
If set, the @samp{CD} and @samp{CHDIR} commands are ignored.  When reset
(the default), the processing of these commands depends on the
@code{__system_emulate_chdir} bit, see below.

This bit is for compatibility with Unix, where a single @samp{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 @code{__system_allow_multiple_cmds} above).

@item __system_emulate_chdir
When set, the @samp{CD} and @samp{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 @samp{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), @samp{CD} and @samp{CHDIR}
are passed to the shell.
@end table

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

@subheading Return Value

If @var{cmd} is a null pointer, @code{system} returns non-zero if a
shell is available.  The actual test for the existence of an executable
file pointed to by @samp{SHELL} or @samp{COMSPEC} is only performed if
the shell is to be invoked to process the entire command line; if most
of the work is to be done by @code{system} itself, passing a null
pointer always yields a non-zero return value, since the internal
emulation is always ``available''.

Otherwise, the return value is the exit status of the child process in
its lower 8 bits; bits 8-17 of the return value will hold @code{SIGINT}
or @code{SIGABRT} if the child process was aborted by @kbd{Ctrl-C} or
Critical Device Error, respectively; otherwise they will be zero@footnote{
Many DOS programs catch @kbd{Ctrl-C} keystrokes and Critical Errors, and
handle them in customized ways.  If this handling prevents DOS from
realizing that the program was aborted due to these reasons, bits 8-17
of the value returned by @code{system} will most probably be zero.
Don't count on these bits to hold the signal number!}.  If the
child couldn't be run, @code{system} will return -1 and set @code{errno}
to an appropriate value.  Note that if @file{COMMAND.COM} was used to
run the child, it will always return a 0 status, even if the command
didn't run successfully.  However, @code{system} only calls
@file{COMMAND.COM} when it needs to run commands internal to it.

@subheading Portability

@portability ansi, posix

@subheading Example

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