path: root/manual/startup.texi

@node Program Basics, Processes, Signal Handling, Top
@c %MENU% Writing the beginning and end of your program
@chapter The Basic Program/System Interface

@cindex process
@cindex program
@cindex address space
@cindex thread of control
@dfn{Processes} are the primitive units for allocation of system
resources.  Each process has its own address space and (usually) one
thread of control.  A process executes a program; you can have multiple
processes executing the same program, but each process has its own copy
of the program within its own address space and executes it
independently of the other copies.  Though it may have multiple threads
of control within the same program and a program may be composed of
multiple logically separate modules, a process always executes exactly
one program.

Note that we are using a specific definition of ``program'' for the
purposes of this manual, which corresponds to a common definition in the
context of Unix system.  In popular usage, ``program'' enjoys a much
broader definition; it can refer for example to a system's kernel, an
editor macro, a complex package of software, or a discrete section of
code executing within a process.

Writing the program is what this manual is all about.  This chapter
explains the most basic interface between your program and the system
that runs, or calls, it.  This includes passing of parameters (arguments
and environment) from the system, requesting basic services from the
system, and telling the system the program is done.

A program starts another program with the @code{exec} family of system calls.
This chapter looks at program startup from the execee's point of view.  To
see the event from the execor's point of view, @xref{Executing a File}.

@menu
* Program Arguments::           Parsing your program's command-line arguments.
* Environment Variables::       Less direct parameters affecting your program
* System Calls::                Requesting service from the system
* Program Termination::         Telling the system you're done; return status
@end menu

@node Program Arguments
@section Program Arguments
@cindex program arguments
@cindex command line arguments
@cindex arguments, to program

@cindex program startup
@cindex startup of program
@cindex invocation of program
@cindex @code{main} function
@findex main
The system starts a C program by calling the function @code{main}.  It
is up to you to write a function named @code{main}---otherwise, you
won't even be able to link your program without errors.

In @w{ISO C} you can define @code{main} either to take no arguments, or to
take two arguments that represent the command line arguments to the
program, like this:

@smallexample
int main (int @var{argc}, char *@var{argv}[])
@end smallexample

@cindex argc (program argument count)
@cindex argv (program argument vector)
The command line arguments are the whitespace-separated tokens given in
the shell command used to invoke the program; thus, in @samp{cat foo
bar}, the arguments are @samp{foo} and @samp{bar}.  The only way a
program can look at its command line arguments is via the arguments of
@code{main}.  If @code{main} doesn't take arguments, then you cannot get
at the command line.

The value of the @var{argc} argument is the number of command line
arguments.  The @var{argv} argument is a vector of C strings; its
elements are the individual command line argument strings.  The file
name of the program being run is also included in the vector as the
first element; the value of @var{argc} counts this element.  A null
pointer always follows the last element: @code{@var{argv}[@var{argc}]}
is this null pointer.

For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.

In Unix systems you can define @code{main} a third way, using three arguments:

@smallexample
int main (int @var{argc}, char *@var{argv}[], char *@var{envp}[])
@end smallexample

The first two arguments are just the same.  The third argument
@var{envp} gives the program's environment; it is the same as the value
of @code{environ}.  @xref{Environment Variables}.  POSIX.1 does not
allow this three-argument form, so to be portable it is b