1: @node Program Basics, Processes, Signal Handling, Top
    2: @c %MENU% Writing the beginning and end of your program
    3: @chapter The Basic Program/System Interface
    4: 
    5: @cindex process
    6: @cindex program
    7: @cindex address space
    8: @cindex thread of control
    9: @dfn{Processes} are the primitive units for allocation of system
   10: resources.  Each process has its own address space and (usually) one
   11: thread of control.  A process executes a program; you can have multiple
   12: processes executing the same program, but each process has its own copy
   13: of the program within its own address space and executes it
   14: independently of the other copies.  Though it may have multiple threads
   15: of control within the same program and a program may be composed of
   16: multiple logically separate modules, a process always executes exactly
   17: one program.
   18: 
   19: Note that we are using a specific definition of ``program'' for the
   20: purposes of this manual, which corresponds to a common definition in the
   21: context of Unix system.  In popular usage, ``program'' enjoys a much
   22: broader definition; it can refer for example to a system's kernel, an
   23: editor macro, a complex package of software, or a discrete section of
   24: code executing within a process.
   25: 
   26: Writing the program is what this manual is all about.  This chapter
   27: explains the most basic interface between your program and the system
   28: that runs, or calls, it.  This includes passing of parameters (arguments
   29: and environment) from the system, requesting basic services from the
   30: system, and telling the system the program is done.
   31: 
   32: A program starts another program with the @code{exec} family of system calls.
   33: This chapter looks at program startup from the execee's point of view.  To
   34: see the event from the execor's point of view, @xref{Executing a File}.
   35: 
   36: @menu
   37: * Program Arguments::           Parsing your program's command-line arguments.
   38: * Environment Variables::       Less direct parameters affecting your program
   39: * System Calls::                Requesting service from the system
   40: * Program Termination::         Telling the system you're done; return status
   41: @end menu
   42: 
   43: @node Program Arguments
   44: @section Program Arguments
   45: @cindex program arguments
   46: @cindex command line arguments
   47: @cindex arguments, to program
   48: 
   49: @cindex program startup
   50: @cindex startup of program
   51: @cindex invocation of program
   52: @cindex @code{main} function
   53: @findex main
   54: The system starts a C program by calling the function @code{main}.  It
   55: is up to you to write a function named @code{main}---otherwise, you
   56: won't even be able to link your program without errors.
   57: 
   58: In @w{ISO C} you can define @code{main} either to take no arguments, or to
   59: take two arguments that represent the command line arguments to the
   60: program, like this:
   61: 
   62: @smallexample
   63: int main (int @var{argc}, char *@var{argv}[])
   64: @end smallexample
   65: 
   66: @cindex argc (program argument count)
   67: @cindex argv (program argument vector)
   68: The command line arguments are the whitespace-separated tokens given in
   69: the shell command used to invoke the program; thus, in @samp{cat foo
   70: bar}, the arguments are @samp{foo} and @samp{bar}.  The only way a
   71: program can look at its command line arguments is via the arguments of
   72: @code{main}.  If @code{main} doesn't take arguments, then you cannot get
   73: at the command line.
   74: 
   75: The value of the @var{argc} argument is the number of command line
   76: arguments.  The @var{argv} argument is a vector of C strings; its
   77: elements are the individual command line argument strings.  The file
   78: name of the program being run is also included in the vector as the
   79: first element; the value of @var{argc} counts this element.  A null
   80: pointer always follows the last element: @code{@var{argv}[@var{argc}]}
   81: is this null pointer.
   82: 
   83: For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
   84: three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
   85: 
   86: In Unix systems you can define @code{main} a third way, using three arguments:
   87: 
   88: @smallexample
   89: int main (int @var{argc}, char *@var{argv}[], char *@var{envp}[])
   90: @end smallexample
   91: 
   92: The first two arguments are just the same.  The third argument
   93: @var{envp} gives the program's environment; it is the same as the value
   94: of @code{environ}.  @xref{Environment Variables}.  POSIX.1 does not
   95: allow this three-argument form, so to be portable it is best to write
   96: @code{main} to take two arguments, and use the value of @code{environ}.
   97: 
   98: @menu
   99: * Argument Syntax::             By convention, options start with a hyphen.
  100: * Parsing Program Arguments::   Ways to parse program options and arguments.
  101: @end menu
  102: 
  103: @node Argument Syntax, Parsing Program Arguments, , Program Arguments
  104: @subsection Program Argument Syntax Conventions
  105: @cindex program argument syntax
  106: @cindex syntax, for program arguments
  107: @cindex command argument syntax
  108: 
  109: POSIX recommends these conventions for command line arguments.
  110: @code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
  111: it easy to implement them.
  112: 
  113: @itemize @bullet
  114: @item
  115: Arguments are options if they begin with a hyphen delimiter (@samp{-}).
  116: 
  117: @item
  118: Multiple options may follow a hyphen delimiter in a single token if
  119: the options do not take arguments.  Thus, @samp{-abc} is equivalent to
  120: @samp{-a -b -c}.
  121: 
  122: @item
  123: Option names are single alphanumeric characters (as for @code{isalnum};
  124: @pxref{Classification of Characters}).
  125: 
  126: @item
  127: Certain options require an argument.  For example, the @samp{-o} command
  128: of the @code{ld} command requires an argument---an output file name.
  129: 
  130: @item
  131: An option and its argument may or may not appear as separate tokens.  (In
  132: other words, the whitespace separating them is optional.)  Thus,
  133: @w{@samp{-o foo}} and @samp{-ofoo} are equivalent.
  134: 
  135: @item
  136: Options typically precede other non-option arguments.
  137: 
  138: The implementations of @code{getopt} and @code{argp_parse} in the GNU C
  139: library normally make it appear as if all the option arguments were
  140: specified before all the non-option arguments for the purposes of
  141: parsing, even if the user of your program intermixed option and
  142: non-option arguments.  They do this by reordering the elements of the
  143: @var{argv} array.  This behavior is nonstandard; if you want to suppress
  144: it, define the @code{_POSIX_OPTION_ORDER} environment variable.
  145: @xref{Standard Environment}.
  146: 
  147: @item
  148: The argument @samp{--} terminates all options; any following arguments
  149: are treated as non-option arguments, even if they begin with a hyphen.
  150: 
  151: @item
  152: A token consisting of a single hyphen character is interpreted as an
  153: ordinary non-option argument.  By convention, it is used to specify
  154: input from or output to the standard input and output streams.
  155: 
  156: @item
  157: Options may be supplied in any order, or appear multiple times.  The
  158: interpretation is left up to the particular application program.
  159: @end itemize
  160: 
  161: @cindex long-named options
  162: GNU adds @dfn{long options} to these conventions.  Long options consist
  163: of @samp{--} followed by a name made of alphanumeric characters and
  164: dashes.  Option names are typically one to three words long, with
  165: hyphens to separate words.  Users can abbreviate the option names as
  166: long as the abbreviations are unique.
  167: 
  168: To specify an argument for a long option, write
  169: @samp{--@var{name}=@var{value}}.  This syntax enables a long option to
  170: accept an argument that is itself optional.
  171: 
  172: Eventually, the GNU system will provide completion for long option names
  173: in the shell.
  174: 
  175: @node Parsing Program Arguments, , Argument Syntax, Program Arguments
  176: @subsection Parsing Program Arguments
  177: 
  178: @cindex program arguments, parsing
  179: @cindex command arguments, parsing
  180: @cindex parsing program arguments
  181: If the syntax for the command line arguments to your program is simple
  182: enough, you can simply pick the arguments off from @var{argv} by hand.
  183: But unless your program takes a fixed number of arguments, or all of the
  184: arguments are interpreted in the same way (as file names, for example),
  185: you are usually better off using @code{getopt} (@pxref{Getopt}) or
  186: @code{argp_parse} (@pxref{Argp}) to do the parsing.
  187: 
  188: @code{getopt} is more standard (the short-option only version of it is a
  189: part of the POSIX standard), but using @code{argp_parse} is often
  190: easier, both for very simple and very complex option structures, because
  191: it does more of the dirty work for you.
  192: 
  193: @menu
  194: * Getopt::                      Parsing program options using @code{getopt}.
  195: * Argp::                        Parsing program options using @code{argp_parse}.
  196: * Suboptions::                  Some programs need more detailed options.
  197: * Suboptions Example::          This shows how it could be done for @code{mount}.
  198: @end menu
  199: 
  200: @c Getopt and argp start at the @section level so that there's
  201: @c enough room for their internal hierarchy (mostly a problem with
  202: @c argp).         -Miles
  203: 
  204: @include getopt.texi
  205: @include argp.texi
  206: 
  207: @node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
  208: @c This is a @section so that it's at the same level as getopt and argp
  209: @subsubsection Parsing of Suboptions
  210: 
  211: Having a single level of options is sometimes not enough.  There might
  212: be too many options which have to be available or a set of options is
  213: closely related.
  214: 
  215: For this case some programs use suboptions.  One of the most prominent
  216: programs is certainly @code{mount}(8).  The @code{-o} option take one
  217: argument which itself is a comma separated list of options.  To ease the
  218: programming of code like this the function @code{getsubopt} is
  219: available.
  220: 
  221: @comment stdlib.h
  222: @deftypefun int getsubopt (char **@var{optionp}, const char* const *@var{tokens}, char **@var{valuep})
  223: 
  224: The @var{optionp} parameter must be a pointer to a variable containing
  225: the address of the string to process.  When the function returns the
  226: reference is updated to point to the next suboption or to the
  227: terminating @samp{\0} character if there is no more suboption available.
  228: 
  229: The @var{tokens} parameter references an array of strings containing the
  230: known suboptions.  All strings must be @samp{\0} terminated and to mark
  231: the end a null pointer must be stored.  When @code{getsubopt} finds a
  232: possible legal suboption it compares it with all strings available in
  233: the @var{tokens} array and returns the index in the string as the
  234: indicator.
  235: 
  236: In case the suboption has an associated value introduced by a @samp{=}
  237: character, a pointer to the value is returned in @var{valuep}.  The
  238: string is @samp{\0} terminated.  If no argument is available
  239: @var{valuep} is set to the null pointer.  By doing this the caller can
  240: check whether a necessary value is given or whether no unexpected value
  241: is present.
  242: 
  243: In case the next suboption in the string is not mentioned in the
  244: @var{tokens} array the starting address of the suboption including a
  245: possible value is returned in @var{valuep} and the return value of the
  246: function is @samp{-1}.
  247: @end deftypefun
  248: 
  249: @node Suboptions Example, , Suboptions, Parsing Program Arguments
  250: @subsection Parsing of Suboptions Example
  251: 
  252: The code which might appear in the @code{mount}(8) program is a perfect
  253: example of the use of @code{getsubopt}:
  254: 
  255: @smallexample
  256: @include subopt.c.texi
  257: @end smallexample
  258: 
  259: 
  260: @node Environment Variables
  261: @section Environment Variables
  262: 
  263: @cindex environment variable
  264: When a program is executed, it receives information about the context in
  265: which it was invoked in two ways.  The first mechanism uses the
  266: @var{argv} and @var{argc} arguments to its @code{main} function, and is
  267: discussed in @ref{Program Arguments}.  The second mechanism uses
  268: @dfn{environment variables} and is discussed in this section.
  269: 
  270: The @var{argv} mechanism is typically used to pass command-line
  271: arguments specific to the particular program being invoked.  The
  272: environment, on the other hand, keeps track of information that is
  273: shared by many programs, changes infrequently, and that is less
  274: frequently used.
  275: 
  276: The environment variables discussed in this section are the same
  277: environment variables that you set using assignments and the
  278: @code{export} command in the shell.  Programs executed from the shell
  279: inherit all of the environment variables from the shell.
  280: @c !!! xref to right part of bash manual when it exists
  281: 
  282: @cindex environment
  283: Standard environment variables are used for information about the user's
  284: home directory, terminal type, current locale, and so on; you can define
  285: additional variables for other purposes.  The set of all environment
  286: variables that have values is collectively known as the
  287: @dfn{environment}.
  288: 
  289: Names of environment variables are case-sensitive and must not contain
  290: the character @samp{=}.  System-defined environment variables are
  291: invariably uppercase.
  292: 
  293: The values of environment variables can be anything that can be
  294: represented as a string.  A value must not contain an embedded null
  295: character, since this is assumed to terminate the string.
  296: 
  297: 
  298: @menu
  299: * Environment Access::          How to get and set the values of
  300:                                  environment variables.
  301: * Standard Environment::        These environment variables have
  302:                                  standard interpretations.
  303: @end menu
  304: 
  305: @node Environment Access
  306: @subsection Environment Access
  307: @cindex environment access
  308: @cindex environment representation
  309: 
  310: The value of an environment variable can be accessed with the
  311: @code{getenv} function.  This is declared in the header file
  312: @file{stdlib.h}.  All of the following functions can be safely used in
  313: multi-threaded programs.  It is made sure that concurrent modifications
  314: to the environment do not lead to errors.
  315: @pindex stdlib.h
  316: 
  317: @comment stdlib.h
  318: @comment ISO
  319: @deftypefun {char *} getenv (const char *@var{name})
  320: This function returns a string that is the value of the environment
  321: variable @var{name}.  You must not modify this string.  In some non-Unix
  322: systems not using the GNU library, it might be overwritten by subsequent
  323: calls to @code{getenv} (but not by any other library function).  If the
  324: environment variable @var{name} is not defined, the value is a null
  325: pointer.
  326: @end deftypefun
  327: 
  328: 
  329: @comment stdlib.h
  330: @comment SVID
  331: @deftypefun int putenv (char *@var{string})
  332: The @code{putenv} function adds or removes definitions from the environment.
  333: If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
  334: definition is added to the environment.  Otherwise, the @var{string} is
  335: interpreted as the name of an environment variable, and any definition
  336: for this variable in the environment is removed.
  337: 
  338: The difference to the @code{setenv} function is that the exact string
  339: given as the parameter @var{string} is put into the environment.  If the
  340: user should change the string after the @code{putenv} call this will
  341: reflect in automatically in the environment.  This also requires that
  342: @var{string} is no automatic variable which scope is left before the
  343: variable is removed from the environment.  The same applies of course to
  344: dynamically allocated variables which are freed later.
  345: 
  346: This function is part of the extended Unix interface.  Since it was also
  347: available in old SVID libraries you should define either
  348: @var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header.
  349: @end deftypefun
  350: 
  351: 
  352: @comment stdlib.h
  353: @comment BSD
  354: @deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
  355: The @code{setenv} function can be used to add a new definition to the
  356: environment.  The entry with the name @var{name} is replaced by the
  357: value @samp{@var{name}=@var{value}}.  Please note that this is also true
  358: if @var{value} is the empty string.  To do this a new string is created
  359: and the strings @var{name} and @var{value} are copied.  A null pointer
  360: for the @var{value} parameter is illegal.  If the environment already
  361: contains an entry with key @var{name} the @var{replace} parameter
  362: controls the action.  If replace is zero, nothing happens.  Otherwise
  363: the old entry is replaced by the new one.
  364: 
  365: Please note that you cannot remove an entry completely using this function.
  366: 
  367: This function was originally part of the BSD library but is now part of
  368: the Unix standard.
  369: @end deftypefun
  370: 
  371: @comment stdlib.h
  372: @comment BSD
  373: @deftypefun int unsetenv (const char *@var{name})
  374: Using this function one can remove an entry completely from the
  375: environment.  If the environment contains an entry with the key
  376: @var{name} this whole entry is removed.  A call to this function is
  377: equivalent to a call to @code{putenv} when the @var{value} part of the
  378: string is empty.
  379: 
  380: The function return @code{-1} if @var{name} is a null pointer, points to
  381: an empty string, or points to a string containing a @code{=} character.
  382: It returns @code{0} if the call succeeded.
  383: 
  384: This function was originally part of the BSD library but is now part of
  385: the Unix standard.  The BSD version had no return value, though.
  386: @end deftypefun
  387: 
  388: There is one more function to modify the whole environment.  This
  389: function is said to be used in the POSIX.9 (POSIX bindings for Fortran
  390: 77) and so one should expect it did made it into POSIX.1.  But this
  391: never happened.  But we still provide this function as a GNU extension
  392: to enable writing standard compliant Fortran environments.
  393: 
  394: @comment stdlib.h
  395: @comment GNU
  396: @deftypefun int clearenv (void)
  397: The @code{clearenv} function removes all entries from the environment.
  398: Using @code{putenv} and @code{setenv} new entries can be added again
  399: later.
  400: 
  401: If the function is successful it returns @code{0}.  Otherwise the return
  402: value is nonzero.
  403: @end deftypefun
  404: 
  405: 
  406: You can deal directly with the underlying representation of environment
  407: objects to add more variables to the environment (for example, to
  408: communicate with another program you are about to execute;
  409: @pxref{Executing a File}).
  410: 
  411: @comment unistd.h
  412: @comment POSIX.1
  413: @deftypevar {char **} environ
  414: The environment is represented as an array of strings.  Each string is
  415: of the format @samp{@var{name}=@var{value}}.  The order in which
  416: strings appear in the environment is not significant, but the same
  417: @var{name} must not appear more than once.  The last element of the
  418: array is a null pointer.
  419: 
  420: This variable is declared in the header file @file{unistd.h}.
  421: 
  422: If you just want to get the value of an environment variable, use
  423: @code{getenv}.
  424: @end deftypevar
  425: 
  426: Unix systems, and the GNU system, pass the initial value of
  427: @code{environ} as the third argument to @code{main}.
  428: @xref{Program Arguments}.
  429: 
  430: @node Standard Environment
  431: @subsection Standard Environment Variables
  432: @cindex standard environment variables
  433: 
  434: These environment variables have standard meanings.  This doesn't mean
  435: that they are always present in the environment; but if these variables
  436: @emph{are} present, they have these meanings.  You shouldn't try to use
  437: these environment variable names for some other purpose.
  438: 
  439: @comment Extra blank lines make it look better.
  440: @table @code
  441: @item HOME
  442: @cindex @code{HOME} environment variable
  443: @cindex home directory
  444: 
  445: This is a string representing the user's @dfn{home directory}, or
  446: initial default working directory.
  447: 
  448: The user can set @code{HOME} to any value.
  449: If you need to make sure to obtain the proper home directory
  450: for a particular user, you should not use @code{HOME}; instead,
  451: look up the user's name in the user database (@pxref{User Database}).
  452: 
  453: For most purposes, it is better to use @code{HOME}, precisely because
  454: this lets the user specify the value.
  455: 
  456: @c !!! also USER
  457: @item LOGNAME
  458: @cindex @code{LOGNAME} environment variable
  459: 
  460: This is the name that the user used to log in.  Since the value in the
  461: environment can be tweaked arbitrarily, this is not a reliable way to
  462: identify the user who is running a program; a function like
  463: @code{getlogin} (@pxref{Who Logged In}) is better for that purpose.
  464: 
  465: For most purposes, it is better to use @code{LOGNAME}, precisely because
  466: this lets the user specify the value.
  467: 
  468: @item PATH
  469: @cindex @code{PATH} environment variable
  470: 
  471: A @dfn{path} is a sequence of directory names which is used for
  472: searching for a file.  The variable @code{PATH} holds a path used
  473: for searching for programs to be run.
  474: 
  475: The @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
  476: use this environment variable, as do many shells and other utilities
  477: which are implemented in terms of those functions.
  478: 
  479: The syntax of a path is a sequence of directory names separated by
  480: colons.  An empty string instead of a directory name stands for the
  481: current directory (@pxref{Working Directory}).
  482: 
  483: A typical value for this environment variable might be a string like:
  484: 
  485: @smallexample
  486: :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
  487: @end smallexample
  488: 
  489: This means that if the user tries to execute a program named @code{foo},
  490: the system will look for files named @file{foo}, @file{/bin/foo},
  491: @file{/etc/foo}, and so on.  The first of these files that exists is
  492: the one that is executed.
  493: 
  494: @c !!! also TERMCAP
  495: @item TERM
  496: @cindex @code{TERM} environment variable
  497: 
  498: This specifies the kind of terminal that is receiving program output.
  499: Some programs can make use of this information to take advantage of
  500: special escape sequences or terminal modes supported by particular kinds
  501: of terminals.  Many programs which use the termcap library
  502: (@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
  503: Manual}) use the @code{TERM} environment variable, for example.
  504: 
  505: @item TZ
  506: @cindex @code{TZ} environment variable
  507: 
  508: This specifies the time zone.  @xref{TZ Variable}, for information about
  509: the format of this string and how it is used.
  510: 
  511: @item LANG
  512: @cindex @code{LANG} environment variable
  513: 
  514: This specifies the default locale to use for attribute categories where
  515: neither @code{LC_ALL} nor the specific environment variable for that
  516: category is set.  @xref{Locales}, for more information about
  517: locales.
  518: 
  519: @ignore
  520: @c I doubt this really exists
  521: @item LC_ALL
  522: @cindex @code{LC_ALL} environment variable
  523: 
  524: This is similar to the @code{LANG} environment variable.  However, its
  525: value takes precedence over any values provided for the individual
  526: attribute category environment variables, or for the @code{LANG}
  527: environment variable.
  528: @end ignore
  529: 
  530: @item LC_ALL
  531: @cindex @code{LC_ALL} environment variable
  532: 
  533: If this environment variable is set it overrides the selection for all
  534: the locales done using the other @code{LC_*} environment variables.  The
  535: value of the other @code{LC_*} environment variables is simply ignored
  536: in this case.
  537: 
  538: @item LC_COLLATE
  539: @cindex @code{LC_COLLATE} environment variable
  540: 
  541: This specifies what locale to use for string sorting.
  542: 
  543: @item LC_CTYPE
  544: @cindex @code{LC_CTYPE} environment variable
  545: 
  546: This specifies what locale to use for character sets and character
  547: classification.
  548: 
  549: @item LC_MESSAGES
  550: @cindex @code{LC_MESSAGES} environment variable
  551: 
  552: This specifies what locale to use for printing messages and to parse
  553: responses.
  554: 
  555: @item LC_MONETARY
  556: @cindex @code{LC_MONETARY} environment variable
  557: 
  558: This specifies what locale to use for formatting monetary values.
  559: 
  560: @item LC_NUMERIC
  561: @cindex @code{LC_NUMERIC} environment variable
  562: 
  563: This specifies what locale to use for formatting numbers.
  564: 
  565: @item LC_TIME
  566: @cindex @code{LC_TIME} environment variable
  567: 
  568: This specifies what locale to use for formatting date/time values.
  569: 
  570: @item NLSPATH
  571: @cindex @code{NLSPATH} environment variable
  572: 
  573: This specifies the directories in which the @code{catopen} function
  574: looks for message translation catalogs.
  575: 
  576: @item _POSIX_OPTION_ORDER
  577: @cindex @code{_POSIX_OPTION_ORDER} environment variable.
  578: 
  579: If this environment variable is defined, it suppresses the usual
  580: reordering of command line arguments by @code{getopt} and
  581: @code{argp_parse}.  @xref{Argument Syntax}.
  582: 
  583: @c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
  584: @end table
  585: 
  586: @node System Calls
  587: @section System Calls
  588: 
  589: @cindex system call
  590: A system call is a request for service that a program makes of the
  591: kernel.  The service is generally something that only the kernel has
  592: the privilege to do, such as doing I/O.  Programmers don't normally
  593: need to be concerned with system calls because there are functions in
  594: the GNU C library to do virtually everything that system calls do.
  595: These functions work by making system calls themselves.  For example,
  596: there is a system call that changes the permissions of a file, but
  597: you don't need to know about it because you can just use the GNU C
  598: library's @code{chmod} function.
  599: 
  600: @cindex kernel call
  601: System calls are sometimes called kernel calls.
  602: 
  603: However, there are times when you want to make a system call explicitly,
  604: and for that, the GNU C library provides the @code{syscall} function.
  605: @code{syscall} is harder to use and less portable than functions like
  606: @code{chmod}, but easier and more portable than coding the system call
  607: in assembler instructions.
  608: 
  609: @code{syscall} is most useful when you are working with a system call
  610: which is special to your system or is newer than the GNU C library you
  611: are using.  @code{syscall} is implemented in an entirely generic way;
  612: the function does not know anything about what a particular system
  613: call does or even if it is valid.
  614: 
  615: The description of @code{syscall} in this section assumes a certain
  616: protocol for system calls on the various platforms on which the GNU C
  617: library runs.  That protocol is not defined by any strong authority, but
  618: we won't describe it here either because anyone who is coding
  619: @code{syscall} probably won't accept anything less than kernel and C
  620: library source code as a specification of the interface between them
  621: anyway.
  622: 
  623: 
  624: @code{syscall} is declared in @file{unistd.h}.
  625: 
  626: @comment unistd.h
  627: @comment ???
  628: @deftypefun {long int} syscall (long int @var{sysno}, ...)
  629: 
  630: @code{syscall} performs a generic system call.
  631: 
  632: @cindex system call number
  633: @var{sysno} is the system call number.  Each kind of system call is
  634: identified by a number.  Macros for all the possible system call numbers
  635: are defined in @file{sys/syscall.h}
  636: 
  637: The remaining arguments are the arguments for the system call, in
  638: order, and their meanings depend on the kind of system call.  Each kind
  639: of system call has a definite number of arguments, from zero to five.
  640: If you code more arguments than the system call takes, the extra ones to
  641: the right are ignored.
  642: 
  643: The return value is the return value from the system call, unless the
  644: system call failed.  In that case, @code{syscall} returns @code{-1} and
  645: sets @code{errno} to an error code that the system call returned.  Note
  646: that system calls do not return @code{-1} when they succeed.
  647: @cindex errno
  648: 
  649: If you specify an invalid @var{sysno}, @code{syscall} returns @code{-1}
  650: with @code{errno} = @code{ENOSYS}.
  651: 
  652: Example:
  653: 
  654: @smallexample
  655: 
  656: #include <unistd.h>
  657: #include <sys/syscall.h>
  658: #include <errno.h>
  659: 
  660: @dots{}
  661: 
  662: int rc;
  663: 
  664: rc = syscall(SYS_chmod, "/etc/passwd", 0444);
  665: 
  666: if (rc == -1)
  667:    fprintf(stderr, "chmod failed, errno = %d\n", errno);
  668: 
  669: @end smallexample
  670: 
  671: This, if all the compatibility stars are aligned, is equivalent to the
  672: following preferable code:
  673: 
  674: @smallexample
  675: 
  676: #include <sys/types.h>
  677: #include <sys/stat.h>
  678: #include <errno.h>
  679: 
  680: @dots{}
  681: 
  682: int rc;
  683: 
  684: rc = chmod("/etc/passwd", 0444);
  685: if (rc == -1)
  686:    fprintf(stderr, "chmod failed, errno = %d\n", errno);
  687: 
  688: @end smallexample
  689: 
  690: @end deftypefun
  691: 
  692: 
  693: @node Program Termination
  694: @section Program Termination
  695: @cindex program termination
  696: @cindex process termination
  697: 
  698: @cindex exit status value
  699: The usual way for a program to terminate is simply for its @code{main}
  700: function to return.  The @dfn{exit status value} returned from the
  701: @code{main} function is used to report information back to the process's
  702: parent process or shell.
  703: 
  704: A program can also terminate normally by calling the @code{exit}
  705: function.
  706: 
  707: In addition, programs can be terminated by signals; this is discussed in
  708: more detail in @ref{Signal Handling}.  The @code{abort} function causes
  709: a signal that kills the program.
  710: 
  711: @menu
  712: * Normal Termination::          If a program calls @code{exit}, a
  713:                                  process terminates normally.
  714: * Exit Status::                 The @code{exit status} provides information
  715:                                  about why the process terminated.
  716: * Cleanups on Exit::            A process can run its own cleanup
  717:                                  functions upon normal termination.
  718: * Aborting a Program::          The @code{abort} function causes
  719:                                  abnormal program termination.
  720: * Termination Internals::       What happens when a process terminates.
  721: @end menu
  722: 
  723: @node Normal Termination
  724: @subsection Normal Termination
  725: 
  726: A process terminates normally when its program signals it is done by
  727: calling @code{exit}.  Returning from @code{main} is equivalent to
  728: calling @code{exit}, and the value that @code{main} returns is used as
  729: the argument to @code{exit}.
  730: 
  731: @comment stdlib.h
  732: @comment ISO
  733: @deftypefun void exit (int @var{status})
  734: The @code{exit} function tells the system that the program is done, which
  735: causes it to terminate the process.
  736: 
  737: @var{status} is the program's exit status, which becomes part of the
  738: process' termination status.  This function does not return.
  739: @end deftypefun
  740: 
  741: Normal termination causes the following actions:
  742: 
  743: @enumerate
  744: @item
  745: Functions that were registered with the @code{atexit} or @code{on_exit}
  746: functions are called in the reverse order of their registration.  This
  747: mechanism allows your application to specify its own ``cleanup'' actions
  748: to be performed at program termination.  Typically, this is used to do
  749: things like saving program state information in a file, or unlocking
  750: locks in shared data bases.
  751: 
  752: @item