system

Syntax

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

Description

This function runs the command or program specified by cmd. If cmd is a null pointer, system returns non-zero only if a shell is available. If cmd is an empty string, the command processor pointed to by `SHELL' or `COMSPEC' variables in the environment will be invoked interactively; type exit RET to return to the program which called 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 `COMMAND.COM' and so will not be subject to its 126 character limit on command lines.

When the calling program runs on Windows 9X or Windows 2000 and calls the system shell to run the child program, or if the child program is a native Windows program (in PE-COFF format), or when the system shell is `4DOS' or `NDOS', command lines longer than 126 characters are passed via the environment variable CMDLINE.

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 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 `#! /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

If cmd is a null pointer, system returns non-zero if a shell is available. The actual test for the existence of an executable file pointed to by `SHELL' or `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 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 SIGINT or SIGABRT if the child process was aborted by Ctrl-C or Critical Device Error, respectively; otherwise they will be zero(4). 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.

Portability

ANSI/ISO C	C89; C99
POSIX	1003.2-1992; 1003.1-2001

Example

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