Non-option argument -
</PRE>
<P>
<H3><A NAME="SEC390" HREF="library_toc.html#SEC390" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC390">Parsing Long Options</A></H3>
<P>
To accept GNU-style long options as well as single-character options,
use <CODE>getopt_long</CODE> instead of <CODE>getopt</CODE>.  You should make every
program accept long options if it uses any options, for this takes
little extra work and helps beginners remember how to use the program.
<P>
<A NAME="IDX1641"></A>
<U>Data Type:</U> <B>struct option</B><P>
This structure describes a single long option name for the sake of
<CODE>getopt_long</CODE>.  The argument <VAR>longopts</VAR> must be an array of
these structures, one for each long option.  Terminate the array with an
element containing all zeros.
<P>
The <CODE>struct option</CODE> structure has these fields:
<P>
<DL COMPACT>
<DT><CODE>const char *name</CODE>
<DD>This field is the name of the option.  It is a string.
<P>
<DT><CODE>int has_arg</CODE>
<DD>This field says whether the option takes an argument.  It is an integer,
and there are three legitimate values: <CODE>no_argument</CODE>,
<CODE>required_argument</CODE> and <CODE>optional_argument</CODE>.
<P>
<DT><CODE>int *flag</CODE>
<DD><DT><CODE>int val</CODE>
<DD>These fields control how to report or act on the option when it occurs.
<P>
If <CODE>flag</CODE> is a null pointer, then the <CODE>val</CODE> is a value which
identifies this option.  Often these values are chosen to uniquely
identify particular long options.
<P>
If <CODE>flag</CODE> is not a null pointer, it should be the address of an
<CODE>int</CODE> variable which is the flag for this option.  The value in
<CODE>val</CODE> is the value to store in the flag to indicate that the option
was seen.
</DL>
<P>
<A NAME="IDX1642"></A>
<U>Function:</U> int <B>getopt_long</B> <I>(int <VAR>argc</VAR>, char **<VAR>argv</VAR>, const char *<VAR>shortopts</VAR>, struct option *<VAR>longopts</VAR>, int *<VAR>indexptr</VAR>)</I><P>
Decode options from the vector <VAR>argv</VAR> (whose length is <VAR>argc</VAR>).
The argument <VAR>shortopts</VAR> describes the short options to accept, just as
it does in <CODE>getopt</CODE>.  The argument <VAR>longopts</VAR> describes the long
options to accept (see above).
<P>
When <CODE>getopt_long</CODE> encounters a short option, it does the same
thing that <CODE>getopt</CODE> would do: it returns the character code for the
option, and stores the options argument (if it has one) in <CODE>optarg</CODE>.
<P>
When <CODE>getopt_long</CODE> encounters a long option, it takes actions based
on the <CODE>flag</CODE> and <CODE>val</CODE> fields of the definition of that
option.
<P>
If <CODE>flag</CODE> is a null pointer, then <CODE>getopt_long</CODE> returns the
contents of <CODE>val</CODE> to indicate which option it found.  You should
arrange distinct values in the <CODE>val</CODE> field for options with
different meanings, so you can decode these values after
<CODE>getopt_long</CODE> returns.  If the long option is equivalent to a short
option, you can use the short option's character code in <CODE>val</CODE>.
<P>
If <CODE>flag</CODE> is not a null pointer, that means this option should just
set a flag in the program.  The flag is a variable of type <CODE>int</CODE>
that you define.  Put the address of the flag in the <CODE>flag</CODE> field.
Put in the <CODE>val</CODE> field the value you would like this option to
store in the flag.  In this case, <CODE>getopt_long</CODE> returns <CODE>0</CODE>.
<P>
For any long option, <CODE>getopt_long</CODE> tells you the index in the array
<VAR>longopts</VAR> of the options definition, by storing it into
<CODE>*<VAR>indexptr</VAR></CODE>.  You can get the name of the option with
<CODE><VAR>longopts</VAR>[*<VAR>indexptr</VAR>].name</CODE>.  So you can distinguish among
long options either by the values in their <CODE>val</CODE> fields or by their
indices.  You can also distinguish in this way among long options that
set flags.
<P>
When a long option has an argument, <CODE>getopt_long</CODE> puts the argument
value in the variable <CODE>optarg</CODE> before returning.  When the option
has no argument, the value in <CODE>optarg</CODE> is a null pointer.  This is
how you can tell whether an optional argument was supplied.
<P>
When <CODE>getopt_long</CODE> has no more options to handle, it returns
<CODE>-1</CODE>, and leaves in the variable <CODE>optind</CODE> the index in
<VAR>argv</VAR> of the next remaining argument.
<P>
<H3><A NAME="SEC391" HREF="library_toc.html#SEC391" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC391">Example of Parsing Long Options</A></H3>
<P>
<PRE>
#include &#60;stdio.h&#62;

/* Flag set by <SAMP>`--verbose'</SAMP>.   */
static int verbose_flag;

int
main (argc, argv)
     int argc;
     char **argv;
{
  int c;

  while (1)
    {
      static struct option long_options[] =
	{
	  /* These options set a flag.   */
	  {"verbose", 0, &#38;verbose_flag, 1},
	  {"brief", 0, &#38;verbose_flag, 0},
	  /* These options don't set a flag.
	     We distinguish them by their indices.  */
	  {"add", 1, 0, 0},
	  {"append", 0, 0, 0},
	  {"delete", 1, 0, 0},
	  {"create", 0, 0, 0},
	  {"file", 1, 0, 0},
	  {0, 0, 0, 0}
	};
      /* <CODE>getopt_long</CODE> stores the option index here.   */
      int option_index = 0;

      c = getopt_long (argc, argv, "abc:d:",
		       long_options, &#38;option_index);

      /* Detect the end of the options.   */
      if (c == -1)
	break;

      switch (c)
	{
	case 0:
	  /* If this option set a flag, do nothing else now.   */
	  if (long_options[option_index].flag != 0)
	    break;
	  printf ("option %s", long_options[option_index].name);
	  if (optarg)
	    printf (" with arg %s", optarg);
	  printf ("\n");
	  break;

	case 'a':
	  puts ("option -a\n");
	  break;

	case 'b':
	  puts ("option -b\n");
	  break;

	case 'c':
	  printf ("option -c with value `%s'\n", optarg);
	  break;

	case 'd':
	  printf ("option -d with value `%s'\n", optarg);
	  break;

	case '?':
	  /* <CODE>getopt_long</CODE> already printed an error message.   */
	  break;

	default:
	  abort ();
	}
    }

  /* Instead of reporting <SAMP>`--verbose'</SAMP>
     and <SAMP>`--brief'</SAMP> as they are encountered,
     we report the final status resulting from them.  */
  if (verbose_flag)
    puts ("verbose flag is set");

  /* Print any remaining command line arguments (not options).   */
  if (optind &#60; argc)
    {
      printf ("non-option ARGV-elements: ");
      while (optind &#60; argc)
	printf ("%s ", argv[optind++]);
      putchar ('\n');
    }

  exit (0);
}
</PRE>
<P>
<H2><A NAME="SEC392" HREF="library_toc.html#SEC392" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC392">Environment Variables</A></H2>
<A NAME="IDX1643"></A>
<P>
When a program is executed, it receives information about the context in
which it was invoked in two ways.  The first mechanism uses the
<VAR>argv</VAR> and <VAR>argc</VAR> arguments to its <CODE>main</CODE> function, and is
discussed in section <A HREF="library_22.html#SEC386" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC386">Program Arguments</A>.  The second mechanism uses
<DFN>environment variables</DFN> and is discussed in this section.
<P>
The <VAR>argv</VAR> mechanism is typically used to pass command-line
arguments specific to the particular program being invoked.  The
environment, on the other hand, keeps track of information that is
shared by many programs, changes infrequently, and that is less
frequently accessed.
<P>
The environment variables discussed in this section are the same
environment variables that you set using assignments and the
<CODE>export</CODE> command in the shell.  Programs executed from the shell
inherit all of the environment variables from the shell.
<A NAME="IDX1644"></A>
<P>
Standard environment variables are used for information about the user's
home directory, terminal type, current locale, and so on; you can define
additional variables for other purposes.  The set of all environment
variables that have values is collectively known as the
<DFN>environment</DFN>.
<P>
Names of environment variables are case-sensitive and must not contain
the character <SAMP>`='</SAMP>.  System-defined environment variables are
invariably uppercase.
<P>
The values of environment variables can be anything that can be
represented as a string.  A value must not contain an embedded null
character, since this is assumed to terminate the string.
<P>
<A NAME="IDX1645"></A>
<A NAME="IDX1646"></A>
<H3><A NAME="SEC393" HREF="library_toc.html#SEC393" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC393">Environment Access</A></H3>
<P>
The value of an environment variable can be accessed with the
<CODE>getenv</CODE> function.  This is declared in the header file
<TT>`stdlib.h'</TT>.
<A NAME="IDX1647"></A>
<P>
<A NAME="IDX1648"></A>
<U>Function:</U> char * <B>getenv</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a string that is the value of the environment
variable <VAR>name</VAR>.  You must not modify this string.  In some systems
not using the GNU library, it might be overwritten by subsequent calls
to <CODE>getenv</CODE> (but not by any other library function).
If the environment variable <VAR>name</VAR> is not defined, the value is a
null pointer.
<P>
<A NAME="IDX1649"></A>
<U>Function:</U> int <B>putenv</B> <I>(const char *<VAR>string</VAR>)</I><P>
The <CODE>putenv</CODE> function adds or removes definitions from the environment.
If the <VAR>string</VAR> is of the form <SAMP>`<VAR>name</VAR>=<VAR>value</VAR>'</SAMP>, the
definition is added to the environment.  Otherwise, the <VAR>string</VAR> is
interpreted as the name of an environment variable, and any definition
for this variable in the environment is removed.
<P>
The GNU library provides this function for compatibility with SVID; it
may not be available in other systems.
<P>
You can deal directly with the underlying representation of environment
objects to add more variables to the environment (for example, to
communicate with another program you are about to execute; see
section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>).  
<P>
<A NAME="IDX1650"></A>
<U>Variable:</U> char ** <B>environ</B><P>
The environment is represented as an array of strings.  Each string is
of the format <SAMP>`<VAR>name</VAR>=<VAR>value</VAR>'</SAMP>.  The order in which
strings appear in the environment is not significant, but the same
<VAR>name</VAR> must not appear more than once.  The last element of the
array is a null pointer.
<P>
This variable is declared in the header file <TT>`unistd.h'</TT>.
<P>
If you just want to get the value of an environment variable, use
<CODE>getenv</CODE>.
<P>
<A NAME="IDX1651"></A>
<H3><A NAME="SEC394" HREF="library_toc.html#SEC394" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC394">Standard Environment Variables</A></H3>
<P>
These environment variables have standard meanings.  This doesn't mean
that they are always present in the environment; but if these variables
<EM>are</EM> present, they have these meanings, and that you shouldn't try
to use these environment variable names for some other purpose.
<P>
<DL COMPACT>
<A NAME="IDX1652"></A>
<A NAME="IDX1653"></A>
<DT><CODE>HOME</CODE>
<DD><P>
This is a string representing the user's <DFN>home directory</DFN>, or
initial default working directory.
<P>
The user can set <CODE>HOME</CODE> to any value.
If you need to make sure to obtain the proper home directory
for a particular user, you should not use <CODE>HOME</CODE>; instead,
look up the user's name in the user database (see section <A HREF="library_25.html#SEC441" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC441">User Database</A>).
<P>
For most purposes, it is better to use <CODE>HOME</CODE>, precisely because
this lets the user specify the value.
<P>
<A NAME="IDX1654"></A>
<DT><CODE>LOGNAME</CODE>
<DD><P>
This is the name that the user used to log in.  Since the value in the
environment can be tweaked arbitrarily, this is not a reliable way to
identify the user who is running a process; a function like
<CODE>getlogin</CODE> (see section <A HREF="library_25.html#SEC440" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC440">Identifying Who Logged In</A>) is better for that purpose.
<P>
For most purposes, it is better to use <CODE>LOGNAME</CODE>, precisely because
this lets the user specify the value.
<P>
<A NAME="IDX1655"></A>
<DT><CODE>PATH</CODE>
<DD><P>
A <DFN>path</DFN> is a sequence of directory names which is used for
searching for a file.  The variable <CODE>PATH</CODE> holds a path used
for searching for programs to be run.
<P>
The <CODE>execlp</CODE> and <CODE>execvp</CODE> functions (see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>)