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.
* 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
programming of code like this the function @code{getsubopt} is
available.
-@comment stdlib.h
@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 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
multi-threaded programs. The @code{getenv} and @code{secure_getenv}
functions can be safely used in multi-threaded programs.
-@comment stdlib.h
-@comment ISO
@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
pointer.
@end deftypefun
-@comment stdlib.h
-@comment GNU
@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
@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
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
the Unix standard.
@end deftypefun
-@comment stdlib.h
-@comment BSD
@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
equivalent to a call to @code{putenv} when the @var{value} part of the
string is empty.
-The function return @code{-1} if @var{name} is a null pointer, points to
+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.
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
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
basis there may be information that is not available any other way.
@subsection Definition of @code{getauxval}
-@comment sys/auxv.h
@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
@code{syscall} is declared in @file{unistd.h}.
-@comment unistd.h
-@comment ???
@deftypefun {long int} syscall (long int @var{sysno}, @dots{})
+@standards{???, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{syscall} performs a generic system call.
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
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.
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
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
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
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.
@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}.
projects / thirdparty / glibc.git / blobdiff