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
+context of Unix systems. 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.
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}.
+see the event from the execor's point of view, see @ref{Executing a File}.
@menu
-* Program Arguments:: Parsing your program's command-line arguments.
+* Program Arguments:: Parsing your program's command-line arguments
* Environment Variables:: Less direct parameters affecting your program
+* Auxiliary Vector:: Least 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
+@node Program Arguments, Environment Variables, , Program Basics
@section Program Arguments
@cindex program arguments
@cindex command line arguments
@item
Options typically precede other non-option arguments.
-The implementations of @code{getopt} and @code{argp_parse} in the GNU C
-library normally make it appear as if all the option arguments were
+The implementations of @code{getopt} and @code{argp_parse} in @theglibc{}
+normally make it appear as if all the option arguments were
specified before all the non-option arguments for the purposes of
parsing, even if the user of your program intermixed option and
non-option arguments. They do this by reordering the elements of the
@samp{--@var{name}=@var{value}}. This syntax enables a long option to
accept an argument that is itself optional.
-Eventually, the GNU system will provide completion for long option names
+Eventually, @gnusystems{} will provide completion for long option names
in the shell.
@node Parsing Program Arguments, , Argument Syntax, Program Arguments
programming of code like this the function @code{getsubopt} is
available.
-@comment stdlib.h
-@deftypefun int getsubopt (char **@var{optionp}, const char* const *@var{tokens}, char **@var{valuep})
+@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep})
+@standards{???, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c getsubopt ok
+@c strchrnul dup ok
+@c memchr dup ok
+@c strncmp dup ok
The @var{optionp} parameter must be a pointer to a variable containing
-the address of the string to process. When the function returns the
+the address of the string to process. When the function returns, the
reference is updated to point to the next suboption or to the
-terminating @samp{\0} character if there is no more suboption available.
+terminating @samp{\0} character if there are no more suboptions available.
The @var{tokens} parameter references an array of strings containing the
known suboptions. All strings must be @samp{\0} terminated and to mark
@end smallexample
-@node Environment Variables
+@node Environment Variables, Auxiliary Vector, Program Arguments, Program Basics
@section Environment Variables
@cindex environment variable
The value of an environment variable can be accessed with the
@code{getenv} function. This is declared in the header file
-@file{stdlib.h}. All of the following functions can be safely used in
-multi-threaded programs. It is made sure that concurrent modifications
-to the environment do not lead to errors.
+@file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
+Libraries should use @code{secure_getenv} instead of @code{getenv}, so
+that they do not accidentally use untrusted environment variables.
+Modifications of environment variables are not allowed in
+multi-threaded programs. The @code{getenv} and @code{secure_getenv}
+functions can be safely used in multi-threaded programs.
+
@deftypefun {char *} getenv (const char *@var{name})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Unguarded access to __environ.
This function returns a string that is the value of the environment
variable @var{name}. You must not modify this string. In some non-Unix
-systems not using the GNU library, it might be overwritten by subsequent
+systems not using @theglibc{}, it might be overwritten by subsequent
calls to @code{getenv} (but not by any other library function). If the
environment variable @var{name} is not defined, the value is a null
pointer.
@end deftypefun
+@deftypefun {char *} secure_getenv (const char *@var{name})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Calls getenv unless secure mode is enabled.
+This function is similar to @code{getenv}, but it returns a null
+pointer if the environment is untrusted. This happens when the
+program file has SUID or SGID bits set. General-purpose libraries
+should always prefer this function over @code{getenv} to avoid
+vulnerabilities if the library is referenced from a SUID/SGID program.
+
+This function is a GNU extension.
+@end deftypefun
+
-@comment stdlib.h
-@comment SVID
@deftypefun int putenv (char *@var{string})
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c putenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c strchr dup ok
+@c strndup dup @ascuheap @acsmem
+@c add_to_environ dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c free dup @ascuheap @acsmem
+@c unsetenv dup @mtasuconst:@mtsenv @asulock @aculock
The @code{putenv} function adds or removes definitions from the environment.
If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
definition is added to the environment. Otherwise, the @var{string} is
interpreted as the name of an environment variable, and any definition
for this variable in the environment is removed.
+If the function is successful it returns @code{0}. Otherwise the return
+value is nonzero and @code{errno} is set to indicate the error.
+
The difference to the @code{setenv} function is that the exact string
given as the parameter @var{string} is put into the environment. If the
user should change the string after the @code{putenv} call this will
-reflect in automatically in the environment. This also requires that
-@var{string} is no automatic variable which scope is left before the
+reflect automatically in the environment. This also requires that
+@var{string} not be an automatic variable whose scope is left before the
variable is removed from the environment. The same applies of course to
dynamically allocated variables which are freed later.
-This function is part of the extended Unix interface. Since it was also
-available in old SVID libraries you should define either
-@var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header.
+This function is part of the extended Unix interface. You should define
+@var{_XOPEN_SOURCE} before including any header.
@end deftypefun
-@comment stdlib.h
-@comment BSD
@deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c setenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c add_to_environ @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c strlen dup ok
+@c libc_lock_lock @asulock @aculock
+@c strncmp dup ok
+@c realloc dup @ascuheap @acsmem
+@c libc_lock_unlock @aculock
+@c malloc dup @ascuheap @acsmem
+@c free dup @ascuheap @acsmem
+@c mempcpy dup ok
+@c memcpy dup ok
+@c KNOWN_VALUE ok
+@c tfind(strcmp) [no @mtsrace guarded access]
+@c strcmp dup ok
+@c STORE_VALUE @ascuheap @acucorrupt @acsmem
+@c tsearch(strcmp) @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt guarded access makes for mtsafe and @asulock]
+@c strcmp dup ok
The @code{setenv} function can be used to add a new definition to the
environment. The entry with the name @var{name} is replaced by the
value @samp{@var{name}=@var{value}}. Please note that this is also true
Please note that you cannot remove an entry completely using this function.
-This function is part of the BSD library. The GNU C Library provides
-this function for compatibility but it may not be available on other
-systems.
+If the function is successful it returns @code{0}. Otherwise the
+environment is unchanged and the return value is @code{-1} and
+@code{errno} is set.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard.
@end deftypefun
-@comment stdlib.h
-@comment BSD
-@deftypefun void unsetenv (const char *@var{name})
+@deftypefun int unsetenv (const char *@var{name})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c unsetenv @mtasuconst:@mtsenv @asulock @aculock
+@c strchr dup ok
+@c strlen dup ok
+@c libc_lock_lock @asulock @aculock
+@c strncmp dup ok
+@c libc_lock_unlock @aculock
Using this function one can remove an entry completely from the
environment. If the environment contains an entry with the key
@var{name} this whole entry is removed. A call to this function is
equivalent to a call to @code{putenv} when the @var{value} part of the
string is empty.
-This function is part of the BSD library. The GNU C Library provides
-this function for compatibility but it may not be available on other
-systems.
+The function returns @code{-1} if @var{name} is a null pointer, points to
+an empty string, or points to a string containing a @code{=} character.
+It returns @code{0} if the call succeeded.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard. The BSD version had no return value, though.
@end deftypefun
There is one more function to modify the whole environment. This
never happened. But we still provide this function as a GNU extension
to enable writing standard compliant Fortran environments.
-@comment stdlib.h
-@comment GNU
@deftypefun int clearenv (void)
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c clearenv @mtasuconst:@mtsenv @ascuheap @asulock @aculock @acsmem
+@c libc_lock_lock @asulock @aculock
+@c free dup @ascuheap @acsmem
+@c libc_lock_unlock @aculock
The @code{clearenv} function removes all entries from the environment.
Using @code{putenv} and @code{setenv} new entries can be added again
later.
communicate with another program you are about to execute;
@pxref{Executing a File}).
-@comment unistd.h
-@comment POSIX.1
@deftypevar {char **} environ
+@standards{POSIX.1, unistd.h}
The environment is represented as an array of strings. Each string is
of the format @samp{@var{name}=@var{value}}. The order in which
strings appear in the environment is not significant, but the same
@code{getenv}.
@end deftypevar
-Unix systems, and the GNU system, pass the initial value of
+Unix systems, and @gnusystems{}, pass the initial value of
@code{environ} as the third argument to @code{main}.
@xref{Program Arguments}.
@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
@end table
+@node Auxiliary Vector
+@section Auxiliary Vector
+@cindex auxiliary vector
+
+When a program is executed, it receives information from the operating
+system about the environment in which it is operating. The form of this
+information is a table of key-value pairs, where the keys are from the
+set of @samp{AT_} values in @file{elf.h}. Some of the data is provided
+by the kernel for libc consumption, and may be obtained by ordinary
+interfaces, such as @code{sysconf}. However, on a platform-by-platform
+basis there may be information that is not available any other way.
+
+@subsection Definition of @code{getauxval}
+@deftypefun {unsigned long int} getauxval (unsigned long int @var{type})
+@standards{???, sys/auxv.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Reads from hwcap or iterates over constant auxv.
+This function is used to inquire about the entries in the auxiliary
+vector. The @var{type} argument should be one of the @samp{AT_} symbols
+defined in @file{elf.h}. If a matching entry is found, the value is
+returned; if the entry is not found, zero is returned and @code{errno} is
+set to @code{ENOENT}.
+@end deftypefun
+
+For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire
+about any instruction set extensions available at runtime. In this case,
+there will (of necessity) be a platform-specific set of @samp{HWCAP_}
+values masked together that describe the capabilities of the cpu on which
+the program is being executed.
+
@node System Calls
@section System Calls
kernel. The service is generally something that only the kernel has
the privilege to do, such as doing I/O. Programmers don't normally
need to be concerned with system calls because there are functions in
-the GNU C library to do virtually everything that system calls do.
+@theglibc{} to do virtually everything that system calls do.
These functions work by making system calls themselves. For example,
there is a system call that changes the permissions of a file, but
-you don't need to know about it because you can just use the GNU C
-library's @code{chmod} function.
+you don't need to know about it because you can just use @theglibc{}'s
+@code{chmod} function.
@cindex kernel call
System calls are sometimes called kernel calls.
However, there are times when you want to make a system call explicitly,
-and for that, the GNU C library provides the @code{syscall} function.
+and for that, @theglibc{} provides the @code{syscall} function.
@code{syscall} is harder to use and less portable than functions like
@code{chmod}, but easier and more portable than coding the system call
in assembler instructions.
@code{syscall} is most useful when you are working with a system call
-which is special to your system or is newer than the GNU C library you
+which is special to your system or is newer than @theglibc{} you
are using. @code{syscall} is implemented in an entirely generic way;
the function does not know anything about what a particular system
call does or even if it is valid.
The description of @code{syscall} in this section assumes a certain
-protocol for system calls on the various platforms on which the GNU C
-library runs. That protocol is not defined by any strong authority, but
+protocol for system calls on the various platforms on which @theglibc{}
+runs. That protocol is not defined by any strong authority, but
we won't describe it here either because anyone who is coding
@code{syscall} probably won't accept anything less than kernel and C
library source code as a specification of the interface between them
@code{syscall} is declared in @file{unistd.h}.
-@comment unistd.h
-@comment ???
-@deftypefun long int syscall (long int @var{sysno}, ...)
+@deftypefun {long int} syscall (long int @var{sysno}, @dots{})
+@standards{???, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{syscall} performs a generic system call.
#include <sys/syscall.h>
#include <errno.h>
-...
+@dots{}
int rc;
#include <sys/stat.h>
#include <errno.h>
-...
+@dots{}
int rc;
calling @code{exit}, and the value that @code{main} returns is used as
the argument to @code{exit}.
-@comment stdlib.h
-@comment ISO
@deftypefun void exit (int @var{status})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:exit}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c Access to the atexit/on_exit list, the libc_atexit hook and tls dtors
+@c is not guarded. Streams must be flushed, and that triggers the usual
+@c AS and AC issues with streams.
The @code{exit} function tells the system that the program is done, which
causes it to terminate the process.
are declared in the file @file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
@deftypevr Macro int EXIT_SUCCESS
+@standards{ISO, stdlib.h}
This macro can be used with the @code{exit} function to indicate
successful program completion.
expression.
@end deftypevr
-@comment stdlib.h
-@comment ISO
@deftypevr Macro int EXIT_FAILURE
+@standards{ISO, stdlib.h}
This macro can be used with the @code{exit} function to indicate
unsuccessful program completion in a general sense.
@end deftypevr
Don't confuse a program's exit status with a process' termination status.
-There are lots of ways a process can terminate besides having it's program
+There are lots of ways a process can terminate besides having its program
finish. In the event that the process termination @emph{is} caused by program
-termination (i.e. @code{exit}), though, the program's exit status becomes
+termination (i.e., @code{exit}), though, the program's exit status becomes
part of the process' termination status.
@node Cleanups on Exit
application, by setting up a cleanup function in the library itself
using @code{atexit} or @code{on_exit}.
-@comment stdlib.h
-@comment ISO
@deftypefun int atexit (void (*@var{function}) (void))
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c atexit @ascuheap @asulock @aculock @acsmem
+@c cxa_atexit @ascuheap @asulock @aculock @acsmem
+@c __internal_atexit @ascuheap @asulock @aculock @acsmem
+@c __new_exitfn @ascuheap @asulock @aculock @acsmem
+@c __libc_lock_lock @asulock @aculock
+@c calloc dup @ascuheap @acsmem
+@c __libc_lock_unlock @aculock
+@c atomic_write_barrier dup ok
The @code{atexit} function registers the function @var{function} to be
called at normal program termination. The @var{function} is called with
no arguments.
the function cannot be registered.
@end deftypefun
-@comment stdlib.h
-@comment SunOS
@deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
+@standards{SunOS, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c on_exit @ascuheap @asulock @aculock @acsmem
+@c new_exitfn dup @ascuheap @asulock @aculock @acsmem
+@c atomic_write_barrier dup ok
This function is a somewhat more powerful variant of @code{atexit}. It
accepts two arguments, a function @var{function} and an arbitrary
pointer @var{arg}. At normal program termination, the @var{function} is
called with two arguments: the @var{status} value passed to @code{exit},
and the @var{arg}.
-This function is included in the GNU C library only for compatibility
+This function is included in @theglibc{} only for compatibility
for SunOS, and may not be supported by other implementations.
@end deftypefun
for this function is in @file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
@deftypefun void abort (void)
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c The implementation takes a recursive lock and attempts to support
+@c calls from signal handlers, but if we're in the middle of flushing or
+@c using streams, we may encounter them in inconsistent states.
The @code{abort} function causes abnormal program termination. This
does not execute cleanup functions registered with @code{atexit} or
@code{on_exit}.
by @code{exit}. It is declared in the header file @file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun void _exit (int @var{status})
+@standards{POSIX.1, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall (exit_group or exit); calls __task_terminate on hurd,
+@c and abort in the generic posix implementation.
The @code{_exit} function is the primitive for causing a process to
terminate with status @var{status}. Calling this function does not
execute cleanup functions registered with @code{atexit} or
@code{on_exit}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun void _Exit (int @var{status})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias for _exit.
The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}.
The @w{ISO C} committee members were not sure whether the definitions of
@code{_exit} and @code{_Exit} were compatible so they have not used the
projects / thirdparty / glibc.git / blobdiff