\hypertarget{cmd__line_8h}{\section{opal/util/cmd\+\_\+line.h File Reference}
\label{cmd__line_8h}\index{opal/util/cmd\+\_\+line.\+h@{opal/util/cmd\+\_\+line.\+h}}
}


General command line parsing facility for use throughout Open M\+P\+I.  


{\ttfamily \#include \char`\"{}opal\+\_\+config.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/class/opal\+\_\+object.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/class/opal\+\_\+list.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/threads/mutex.\+h\char`\"{}}\\*
\subsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t}
\item 
struct \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t}
\begin{DoxyCompactList}\small\item\em \hyperlink{classDatatype}{Datatype} used to construct a command line handle; see \hyperlink{cmd__line_8h_a14f90d373e158d0cd437ca2ed5c6de28}{opal\+\_\+cmd\+\_\+line\+\_\+create()}. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
\hypertarget{cmd__line_8h_a60221761f26161a94f5d13e3a8f1bd8c}{typedef struct \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} {\bfseries opal\+\_\+cmd\+\_\+line\+\_\+t}}\label{cmd__line_8h_a60221761f26161a94f5d13e3a8f1bd8c}

\item 
\hypertarget{cmd__line_8h_af829c283c8b394162ed110d331f8d9b1}{typedef enum \hyperlink{cmd__line_8h_a0918040a61acb40dc8eb442c3c2eb086}{opal\+\_\+cmd\+\_\+line\+\_\+type\+\_\+t} {\bfseries opal\+\_\+cmd\+\_\+line\+\_\+type\+\_\+t}}\label{cmd__line_8h_af829c283c8b394162ed110d331f8d9b1}

\item 
\hypertarget{cmd__line_8h_af97e2712c518aeb24bbd0047988b23fb}{typedef struct \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} {\bfseries opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t}}\label{cmd__line_8h_af97e2712c518aeb24bbd0047988b23fb}

\end{DoxyCompactItemize}
\subsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
\hypertarget{cmd__line_8h_a0918040a61acb40dc8eb442c3c2eb086}{enum \hyperlink{cmd__line_8h_a0918040a61acb40dc8eb442c3c2eb086}{opal\+\_\+cmd\+\_\+line\+\_\+type\+\_\+t} \{ \\*
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+N\+U\+L\+L}, 
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+S\+T\+R\+I\+N\+G}, 
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+I\+N\+T}, 
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+S\+I\+Z\+E\+\_\+\+T}, 
\\*
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+B\+O\+O\+L}, 
{\bfseries O\+P\+A\+L\+\_\+\+C\+M\+D\+\_\+\+L\+I\+N\+E\+\_\+\+T\+Y\+P\+E\+\_\+\+M\+A\+X}
 \}}\label{cmd__line_8h_a0918040a61acb40dc8eb442c3c2eb086}

\begin{DoxyCompactList}\small\item\em Data types supported by the parser. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C \hyperlink{cmd__line_8h_a61df081510e910c3b9b57ed73b465fdd}{O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t})
\begin{DoxyCompactList}\small\item\em Top-\/level command line handle. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a14f90d373e158d0cd437ca2ed5c6de28}{opal\+\_\+cmd\+\_\+line\+\_\+create} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} $\ast$table)
\begin{DoxyCompactList}\small\item\em Make a command line handle from a table of initializers. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a6ee08ce5c480da26a5b970db54f5a455}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} entry)
\begin{DoxyCompactList}\small\item\em Create a command line option. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a7265b7055501418c6c848c10a8152b5d}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, char short\+\_\+name, const char $\ast$long\+\_\+name, int num\+\_\+params, const char $\ast$desc) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+deprecated\+\_\+\+\_\+
\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, char short\+\_\+name, const char $\ast$sd\+\_\+name, const char $\ast$long\+\_\+name, int num\+\_\+params, const char $\ast$desc)
\begin{DoxyCompactList}\small\item\em Create a command line option. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, bool ignore\+\_\+unknown, int argc, char $\ast$$\ast$argv)
\begin{DoxyCompactList}\small\item\em Parse a command line according to a pre-\/built O\+P\+A\+L command line handle. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char $\ast$ \hyperlink{cmd__line_8h_a49ed12bd1a9e077a80d2df8cc97697a7}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+malloc\+\_\+\+\_\+ \+\_\+\+\_\+opal\+\_\+attribute\+\_\+warn\+\_\+unused\+\_\+result\+\_\+\+\_\+
\begin{DoxyCompactList}\small\item\em Return a consolidated \char`\"{}usage\char`\"{} message for a O\+P\+A\+L command line handle. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C bool \hyperlink{cmd__line_8h_a332e3b206a3d8b4e13ca70f7aadb4537}{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, const char $\ast$opt) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(1) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(2)
\begin{DoxyCompactList}\small\item\em Test if a given option was taken on the parsed command line. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a631cc22053f21dff2399819e92d8011d}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+unused\+\_\+\+\_\+
\begin{DoxyCompactList}\small\item\em Return the number of arguments parsed on a O\+P\+A\+L command line handle. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char $\ast$ \hyperlink{cmd__line_8h_ae6595e1d3c7836ffdd3df34992190aa2}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, int index)
\begin{DoxyCompactList}\small\item\em Return a string argument parsed on a O\+P\+A\+L command line handle. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a36016de5a46c4e588687239d2e60cd44}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, const char $\ast$opt) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(1) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(2)
\begin{DoxyCompactList}\small\item\em Return the number of instances of an option found during parsing. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char $\ast$ \hyperlink{cmd__line_8h_ab989b6c1e4b0e340522be2a096aeb2f9}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, const char $\ast$opt, int instance\+\_\+num, int param\+\_\+num)
\begin{DoxyCompactList}\small\item\em Return a specific parameter for a specific instance of a option from the parsed command line. \end{DoxyCompactList}\item 
O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int \hyperlink{cmd__line_8h_a2115e4ca53847018f9ac7fae4c608864}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail} (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$cmd, int $\ast$tailc, char $\ast$$\ast$$\ast$tailv) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(1) \+\_\+\+\_\+opal\+\_\+attribute\+\_\+nonnull\+\_\+\+\_\+(2)
\begin{DoxyCompactList}\small\item\em Return the entire \char`\"{}tail\char`\"{} of unprocessed argv from a O\+P\+A\+L command line handle. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
General command line parsing facility for use throughout Open M\+P\+I. 

This scheme is inspired by the G\+N\+U getopt package. Command line options are registered. Each option can have up to three different matching tokens\+: a \char`\"{}short\char`\"{} name, a \char`\"{}single dash\char`\"{} name, and a \char`\"{}long\char`\"{} name. Each option can also take 0 or more arguments. Finally, each option can be repeated on the command line an arbitrary number of times.

The \char`\"{}short\char`\"{} name can only be a single letter, and will be found after a single dash (e.\+g., \char`\"{}-\/a\char`\"{}). Multiple \char`\"{}short\char`\"{} names can be combined into a single command line argument (e.\+g., \char`\"{}-\/abc\char`\"{} can be equivalent to \char`\"{}-\/a -\/b -\/c\char`\"{}).

The \char`\"{}single dash\char`\"{} name is a multi-\/character name that only requires a single dash. This only exists to provide backwards compatibility for some well-\/known command line options in prior M\+P\+I implementations (e.\+g., \char`\"{}mpirun -\/np 3\char`\"{}). It should be used sparingly.

The \char`\"{}long\char`\"{} name is a multi-\/character name that is found after a pair of dashes. For example, \char`\"{}-\/-\/some-\/option-\/name\char`\"{}.

A command line option is a combination of 1 or more of a short name, single dash name, and a long name. Any of the names may be used on the command line; they are treated as synonyms. For example, say the following was used in for an executable named \char`\"{}foo\char`\"{}\+:


\begin{DoxyCode}
\hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\_cmd\_line\_make\_opt3}(cmd, \textcolor{charliteral}{'a'}, NULL, \textcolor{stringliteral}{'add'}, 1, \textcolor{stringliteral}{"Add a user"});
\end{DoxyCode}


In this case, the following command lines are exactly equivalent\+:

\begin{DoxyVerb}* shell$ foo -a jsmith
* shell$ foo --add jsmith
* \end{DoxyVerb}


Note that this interface can also track multiple invocations of the same option. For example, the following is both legal and able to be retrieved through this interface\+:

\begin{DoxyVerb}* shell$ foo -a jsmith -add bjones
* \end{DoxyVerb}


The caller to this interface creates a command line handle (\hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t}) with O\+B\+J\+\_\+\+N\+E\+W() and then uses it to register the desired parameters via \hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3()} (or the deprecated \hyperlink{cmd__line_8h_a7265b7055501418c6c848c10a8152b5d}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt()}). Once all the parameters have been registered, the user invokes \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} with the command line handle and the argv/argc pair to be parsed (typically the arguments from main()). The parser will examine the argv and find registered options and parameters. It will stop parsing when it runs into an recognized string token or the special \char`\"{}-\/-\/\char`\"{} token.

After the parse has occurred, various accessor functions can be used to determine which options were selected, what parameters were passed to them, etc.\+:


\begin{DoxyItemize}
\item \hyperlink{cmd__line_8h_a49ed12bd1a9e077a80d2df8cc97697a7}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg()} returns a string suitable for \char`\"{}help\char`\"{} kinds of messages.
\item \hyperlink{cmd__line_8h_a332e3b206a3d8b4e13ca70f7aadb4537}{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken()} returns a true or false indicating whether a given command line option was found on the command line.
\item \hyperlink{cmd__line_8h_a631cc22053f21dff2399819e92d8011d}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc()} returns the number of tokens parsed on the handle.
\item \hyperlink{cmd__line_8h_ae6595e1d3c7836ffdd3df34992190aa2}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv()} returns any particular string from the original argv.
\item \hyperlink{cmd__line_8h_a36016de5a46c4e588687239d2e60cd44}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts()} returns the number of times a particular option was found on a command line.
\item \hyperlink{cmd__line_8h_ab989b6c1e4b0e340522be2a096aeb2f9}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param()} returns the Nth parameter in the Mth instance of a given parameter.
\item \hyperlink{cmd__line_8h_a2115e4ca53847018f9ac7fae4c608864}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail()} returns an array of tokens not parsed (i.\+e., if the parser ran into \char`\"{}-\/-\/\char`\"{} or an unrecognized token).
\end{DoxyItemize}

Note that a shortcut to creating a large number of options exists -- one can make a table of \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} instances and the table to \hyperlink{cmd__line_8h_a14f90d373e158d0cd437ca2ed5c6de28}{opal\+\_\+cmd\+\_\+line\+\_\+create()}. This creates an \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} handle that is pre-\/seeded with all the options from the table without the need to repeatedly invoke \hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3()} (or equivalent). This \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} instance is just like any other; it is still possible to add more options via \hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3()}, etc. 

\subsection{Function Documentation}
\hypertarget{cmd__line_8h_a61df081510e910c3b9b57ed73b465fdd}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N@{O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N}}
\index{O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N@{O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C O\+B\+J\+\_\+\+C\+L\+A\+S\+S\+\_\+\+D\+E\+C\+L\+A\+R\+A\+T\+I\+O\+N (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t}}]{}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a61df081510e910c3b9b57ed73b465fdd}


Top-\/level command line handle. 

This handle is used for accessing all command line functionality (i.\+e., all opal\+\_\+cmd\+\_\+line$\ast$() functions). Multiple handles can be created and simultaneously processed; each handle is independant from others.

The \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} handles are \mbox{[}simplisticly\mbox{]} thread safe; processing is guaranteed to be mutually exclusive if multiple threads invoke functions on the same handle at the same time -- access will be serialized in an unspecified order.

Once finished, handles should be released with \hyperlink{opal__object_8h_abc1e3a4a6f319e31f74659a2f073891a}{O\+B\+J\+\_\+\+R\+E\+L\+E\+A\+S\+E()}. The destructor for \hyperlink{structopal__cmd__line__t}{opal\+\_\+cmd\+\_\+line\+\_\+t} handles will free all memory associated with the handle. \hypertarget{cmd__line_8h_a14f90d373e158d0cd437ca2ed5c6de28}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+create@{opal\+\_\+cmd\+\_\+line\+\_\+create}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+create@{opal\+\_\+cmd\+\_\+line\+\_\+create}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+create}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+create (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} $\ast$}]{table}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a14f90d373e158d0cd437ca2ed5c6de28}


Make a command line handle from a table of initializers. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em table} & Table of \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} instances for all the options to be included in the resulting command line handler.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+S\+U\+C\+C\+E\+S\+S} & Upon success.\\
\hline
\end{DoxyRetVals}
This function takes a table of \hyperlink{structopal__cmd__line__init__t}{opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t} instances to pre-\/seed an O\+P\+A\+L command line handle. The last instance in the table must have '\textbackslash{}0' for the short name and N\+U\+L\+L for the single-\/dash and long names. The handle is expected to have been O\+B\+J\+\_\+\+N\+E\+W'ed or O\+B\+J\+\_\+\+C\+O\+N\+S\+T\+R\+U\+C\+T'ed already.

Upon return, the command line handle is just like any other. A sample using this syntax\+:


\begin{DoxyCode}
1 opal\_cmd\_line\_init\_t cmd\_line\_init[] = \{
2    \{ NULL, NULL, NULL, 'h', NULL, "help", 0, 
3      &orterun\_globals.help, OPAL\_CMD\_LINE\_TYPE\_BOOL,
4      "This help message" \},
5 
6    \{ NULL, NULL, NULL, '\(\backslash\)0', NULL, "wd", 1,
7      &orterun\_globals.wd, OPAL\_CMD\_LINE\_TYPE\_STRING,
8      "Set the working directory of the started processes" \},
9 
10    \{ NULL, NULL, NULL, '\(\backslash\)0', NULL, NULL, 0,
11      NULL, OPAL\_CMD\_LINE\_TYPE\_NULL, NULL \}
12 \};
\end{DoxyCode}
 

References O\+B\+J\+\_\+\+C\+O\+N\+S\+T\+R\+U\+C\+T.



Referenced by parse\+\_\+args().

\hypertarget{cmd__line_8h_a631cc22053f21dff2399819e92d8011d}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argc (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a631cc22053f21dff2399819e92d8011d}


Return the number of arguments parsed on a O\+P\+A\+L command line handle. 


\begin{DoxyParams}{Parameters}
{\em cmd} & A pointer to the O\+P\+A\+L command line handle.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+E\+R\+R\+O\+R} & If cmd is N\+U\+L\+L. \\
\hline
{\em argc} & Number of arguments previously added to the handle.\\
\hline
\end{DoxyRetVals}
Arguments are added to the handle via the \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} function. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+argc.

\hypertarget{cmd__line_8h_ae6595e1d3c7836ffdd3df34992190aa2}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char$\ast$ opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+argv (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{int}]{index}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_ae6595e1d3c7836ffdd3df34992190aa2}


Return a string argument parsed on a O\+P\+A\+L command line handle. 


\begin{DoxyParams}{Parameters}
{\em cmd} & A pointer to the O\+P\+A\+L command line handle. \\
\hline
{\em index} & The nth argument from the command line (0 is argv\mbox{[}0\mbox{]}, etc.).\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em N\+U\+L\+L} & If cmd is N\+U\+L\+L or index is invalid \\
\hline
{\em argument} & String of original argv\mbox{[}index\mbox{]}\\
\hline
\end{DoxyRetVals}
This function returns a single token from the arguments parsed on this handle. Arguments are added bia the \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} function.

What is returned is a pointer to the actual string that is on the handle; it should not be modified or freed. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+argc, and opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+argv.

\hypertarget{cmd__line_8h_a36016de5a46c4e588687239d2e60cd44}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{const char $\ast$}]{opt}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a36016de5a46c4e588687239d2e60cd44}


Return the number of instances of an option found during parsing. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em opt} & Short or long name of the option to check for.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em num} & Number of instances (to include 0) of a given potion found during \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}.\\
\hline
{\em O\+P\+A\+L\+\_\+\+E\+R\+R} & If the command line option was not found during \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}, or \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} was not invoked on this handle.\\
\hline
\end{DoxyRetVals}
This function should only be called after \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}.

The function will return the number of instances of a given option (either by its short or long name) -- to include 0 -- or O\+P\+A\+L\+\_\+\+E\+R\+R if either the option was not specified as part of the O\+P\+A\+L command line handle, or \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} was not invoked on this handle. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+mutex, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+params, opal\+\_\+list\+\_\+get\+\_\+end(), opal\+\_\+list\+\_\+get\+\_\+first(), opal\+\_\+list\+\_\+get\+\_\+next, opal\+\_\+mutex\+\_\+lock(), and opal\+\_\+mutex\+\_\+unlock().



Referenced by opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken().

\hypertarget{cmd__line_8h_ab989b6c1e4b0e340522be2a096aeb2f9}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char$\ast$ opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{const char $\ast$}]{opt, }
\item[{int}]{instance\+\_\+num, }
\item[{int}]{param\+\_\+num}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_ab989b6c1e4b0e340522be2a096aeb2f9}


Return a specific parameter for a specific instance of a option from the parsed command line. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em opt} & Short or long name of the option to check for. \\
\hline
{\em instance\+\_\+num} & Instance number of the option to query. \\
\hline
{\em param\+\_\+num} & Which parameter to return.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em param} & String of the parameter. \\
\hline
{\em N\+U\+L\+L} & If any of the input values are invalid.\\
\hline
\end{DoxyRetVals}
This function should only be called after \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}.

This function returns the Nth parameter for the Ith instance of a given option on the parsed command line (both N and I are zero-\/indexed). For example, on the command line\+:

executable --foo bar1 bar2 --foo bar3 bar4

The call to opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param(cmd, \char`\"{}foo\char`\"{}, 1, 1) would return \char`\"{}bar4\char`\"{}. opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param(cmd, \char`\"{}bar\char`\"{}, 0, 0) would return N\+U\+L\+L, as would opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+param(cmd, \char`\"{}foo\char`\"{}, 2, 2);

The returned string should {\itshape not} be modified or freed by the caller. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+mutex, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+params, opal\+\_\+list\+\_\+get\+\_\+end(), opal\+\_\+list\+\_\+get\+\_\+first(), opal\+\_\+list\+\_\+get\+\_\+next, opal\+\_\+mutex\+\_\+lock(), and opal\+\_\+mutex\+\_\+unlock().

\hypertarget{cmd__line_8h_a2115e4ca53847018f9ac7fae4c608864}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{int $\ast$}]{tailc, }
\item[{char $\ast$$\ast$$\ast$}]{tailv}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a2115e4ca53847018f9ac7fae4c608864}


Return the entire \char`\"{}tail\char`\"{} of unprocessed argv from a O\+P\+A\+L command line handle. 


\begin{DoxyParams}{Parameters}
{\em cmd} & A pointer to the O\+P\+A\+L command line handle. \\
\hline
{\em tailc} & Pointer to the output length of the null-\/terminated tail argv array. \\
\hline
{\em tailv} & Pointer to the output null-\/terminated argv of all unprocessed arguments from the command line.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+E\+R\+R\+O\+R} & If cmd is N\+U\+L\+L or otherwise invalid. \\
\hline
{\em O\+P\+A\+L\+\_\+\+S\+U\+C\+C\+E\+S\+S} & Upon success.\\
\hline
\end{DoxyRetVals}
The \char`\"{}tail\char`\"{} is all the arguments on the command line that were not processed for some reason. Reasons for not processing arguments include\+:

\begin{DoxySeeAlso}{See also}
The argument was not recognized 

The argument \char`\"{}-\/-\/\char`\"{} was seen, and therefore all arguments following it were not processed
\end{DoxySeeAlso}
The output tailc parameter will be filled in with the integer length of the null-\/terminated tailv array (length including the final N\+U\+L\+L entry). The output tailv parameter will be a copy of the tail parameters, and must be freed (likely with a call to \hyperlink{argv_8h_a812edb42a56e62651124d6fac215aeeb}{opal\+\_\+argv\+\_\+free()}) by the caller. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+mutex, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+tail\+\_\+argc, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+tail\+\_\+argv, opal\+\_\+argv\+\_\+copy(), opal\+\_\+mutex\+\_\+lock(), and opal\+\_\+mutex\+\_\+unlock().



Referenced by parse\+\_\+args().

\hypertarget{cmd__line_8h_a49ed12bd1a9e077a80d2df8cc97697a7}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg@{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C char$\ast$ opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a49ed12bd1a9e077a80d2df8cc97697a7}


Return a consolidated \char`\"{}usage\char`\"{} message for a O\+P\+A\+L command line handle. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em str} & Usage message.\\
\hline
\end{DoxyRetVals}
Returns a formatted string suitable for printing that lists the expected usage message and a short description of each option on the O\+P\+A\+L command line handle. Options that passed a N\+U\+L\+L description to \hyperlink{cmd__line_8h_a7265b7055501418c6c848c10a8152b5d}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt()} will not be included in the display (to allow for undocumented options).

This function is typically only invoked internally by the opal\+\_\+show\+\_\+help() function.

This function should probably be fixed up to produce prettier output.

The returned string must be freed by the caller. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+mutex, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+options, opal\+\_\+argv\+\_\+append(), opal\+\_\+argv\+\_\+free(), opal\+\_\+argv\+\_\+join(), opal\+\_\+list\+\_\+get\+\_\+end(), opal\+\_\+list\+\_\+get\+\_\+first(), opal\+\_\+list\+\_\+get\+\_\+next, opal\+\_\+list\+\_\+get\+\_\+size(), opal\+\_\+mutex\+\_\+lock(), and opal\+\_\+mutex\+\_\+unlock().



Referenced by parse\+\_\+args().

\hypertarget{cmd__line_8h_a332e3b206a3d8b4e13ca70f7aadb4537}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken@{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken@{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C bool opal\+\_\+cmd\+\_\+line\+\_\+is\+\_\+taken (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{const char $\ast$}]{opt}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a332e3b206a3d8b4e13ca70f7aadb4537}


Test if a given option was taken on the parsed command line. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em opt} & Short or long name of the option to check for.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em true} & If the command line option was found during \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}.\\
\hline
{\em false} & If the command line option was not found during \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}, or \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()} was not invoked on this handle.\\
\hline
\end{DoxyRetVals}
This function should only be called after \hyperlink{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{opal\+\_\+cmd\+\_\+line\+\_\+parse()}.

The function will return true if the option matching opt was found (either by its short or long name) during token parsing. Otherwise, it will return false. 

References opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+ninsts().

\hypertarget{cmd__line_8h_a7265b7055501418c6c848c10a8152b5d}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{char}]{short\+\_\+name, }
\item[{const char $\ast$}]{long\+\_\+name, }
\item[{int}]{num\+\_\+params, }
\item[{const char $\ast$}]{desc}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a7265b7055501418c6c848c10a8152b5d}
\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000043}{Deprecated}]\end{DoxyRefDesc}


Create a command line option.

This function is an older \mbox{[}deprecated\mbox{]} form of \hyperlink{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3()}. It is exactly equivalent to opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3(cmd, short\+\_\+name, N\+U\+L\+L, long\+\_\+name, num\+\_\+params, desc). 

References opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+long\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+short\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+single\+\_\+dash\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+description, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+component\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+param\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+type\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+num\+\_\+params, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+variable\+\_\+dest, and opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+variable\+\_\+type.

\hypertarget{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt3 (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{char}]{short\+\_\+name, }
\item[{const char $\ast$}]{sd\+\_\+name, }
\item[{const char $\ast$}]{long\+\_\+name, }
\item[{int}]{num\+\_\+params, }
\item[{const char $\ast$}]{desc}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a51e2092897ef6fab9d1c6b09730d75f5}


Create a command line option. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em short\+\_\+name} & \char`\"{}\+Short\char`\"{} name of the command line option. \\
\hline
{\em sd\+\_\+name} & \char`\"{}\+Single dash\char`\"{} name of the command line option. \\
\hline
{\em long\+\_\+name} & \char`\"{}\+Long\char`\"{} name of the command line option. \\
\hline
{\em num\+\_\+params} & How many parameters this option takes. \\
\hline
{\em dest} & Short string description of this option.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+E\+R\+R\+\_\+\+O\+U\+T\+\_\+\+O\+F\+\_\+\+R\+E\+S\+O\+U\+R\+C\+E} & If out of memory. \\
\hline
{\em O\+P\+A\+L\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+P\+A\+R\+A\+M} & If bad parameters passed. \\
\hline
{\em O\+P\+A\+L\+\_\+\+S\+U\+C\+C\+E\+S\+S} & Upon success.\\
\hline
\end{DoxyRetVals}
Adds a command line option to the list of options that a a O\+P\+A\+L command line handle will accept. The short\+\_\+name may take the special value '\textbackslash{}0' to not have a short name. Likewise, the sd\+\_\+name and long\+\_\+name may take the special value N\+U\+L\+L to not have a single dash or long name, respectively. However, one of the three must have a name.

num\+\_\+params indicates how many parameters this option takes. It must be greater than or equal to 0.

Finally, desc is a short string description of this option. It is used to generate the output from \hyperlink{cmd__line_8h_a49ed12bd1a9e077a80d2df8cc97697a7}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+usage\+\_\+msg()}. 

References opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+long\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+short\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+single\+\_\+dash\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+description, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+component\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+param\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+mca\+\_\+type\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+num\+\_\+params, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+variable\+\_\+dest, and opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+variable\+\_\+type.

\hypertarget{cmd__line_8h_a6ee08ce5c480da26a5b970db54f5a455}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca@{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+make\+\_\+opt\+\_\+mca (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t}}]{entry}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a6ee08ce5c480da26a5b970db54f5a455}


Create a command line option. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em entry} & Command line entry to add to the command line.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+S\+U\+C\+C\+E\+S\+S} & Upon success. \\
\hline
\end{DoxyRetVals}


References opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+long\+\_\+name, opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+short\+\_\+name, and opal\+\_\+cmd\+\_\+line\+\_\+init\+\_\+t\+::ocl\+\_\+cmd\+\_\+single\+\_\+dash\+\_\+name.

\hypertarget{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}{\index{cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}!opal\+\_\+cmd\+\_\+line\+\_\+parse@{opal\+\_\+cmd\+\_\+line\+\_\+parse}}
\index{opal\+\_\+cmd\+\_\+line\+\_\+parse@{opal\+\_\+cmd\+\_\+line\+\_\+parse}!cmd\+\_\+line.\+h@{cmd\+\_\+line.\+h}}
\subsubsection[{opal\+\_\+cmd\+\_\+line\+\_\+parse}]{\setlength{\rightskip}{0pt plus 5cm}O\+P\+A\+L\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C int opal\+\_\+cmd\+\_\+line\+\_\+parse (
\begin{DoxyParamCaption}
\item[{{\bf opal\+\_\+cmd\+\_\+line\+\_\+t} $\ast$}]{cmd, }
\item[{bool}]{ignore\+\_\+unknown, }
\item[{int}]{argc, }
\item[{char $\ast$$\ast$}]{argv}
\end{DoxyParamCaption}
)}}\label{cmd__line_8h_a4e4acdf997efeaa460dbf5330c9cfd81}


Parse a command line according to a pre-\/built O\+P\+A\+L command line handle. 


\begin{DoxyParams}{Parameters}
{\em cmd} & O\+P\+A\+L command line handle. \\
\hline
{\em ignore\+\_\+unknown} & Whether to print an error message upon finding an unknown token or not \\
\hline
{\em argc} & Length of the argv array. \\
\hline
{\em argv} & Array of strings from the command line.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em O\+P\+A\+L\+\_\+\+S\+U\+C\+C\+E\+S\+S} & Upon success. \\
\hline
{\em O\+P\+A\+L\+\_\+\+E\+R\+R\+\_\+\+S\+I\+L\+E\+N\+T} & If an error message was printed. This value will only be returned if the command line was not successfully parsed.\\
\hline
\end{DoxyRetVals}
Parse a series of command line tokens according to the option descriptions from a O\+P\+A\+L command line handle. The O\+P\+A\+L command line handle can then be queried to see what options were used, what their parameters were, etc.

If an unknown token is found in the command line (i.\+e., a token that is not a parameter or a registered option), the parsing will stop (see below). If ignore\+\_\+unknown is false, an error message is displayed. If ignore\+\_\+unknown is true, the error message is not displayed.

Error messages are always displayed (to stderr, and O\+P\+A\+L\+\_\+\+E\+R\+R\+\_\+\+S\+I\+L\+E\+N\+T is returned) if a token was encountered that required N parameters, but $<$N parameters were found (e.\+g., \char`\"{}cmd
-\/-\/param foo\char`\"{}, but --param was registered to require 2 option tokens).

The contents of argc and argv are not changed during parsing. argv\mbox{[}0\mbox{]} is assumed to be the executable name, and is ignored during parsing, except when printing error messages.

Parsing will stop in the following conditions\+:


\begin{DoxyItemize}
\item all argv tokens are processed
\item the token \char`\"{}-\/-\/\char`\"{} is found
\item an unrecognized token is found
\item a parameter registered with an integer type option finds a non-\/integer option token
\item a parameted registered N option tokens, but finds less then $<$N tokens available
\end{DoxyItemize}

Upon any of these conditions, any remaining tokens will be placed in the \char`\"{}tail\char`\"{} (and therefore not examined by the parser), regardless of the value of ignore\+\_\+unknown. The set of tail tokens is available from the \hyperlink{cmd__line_8h_a2115e4ca53847018f9ac7fae4c608864}{opal\+\_\+cmd\+\_\+line\+\_\+get\+\_\+tail()} function.

Note that \char`\"{}-\/-\/\char`\"{} is ignored if it is found in the middle an expected number of arguments. For example, if \char`\"{}-\/-\/foo\char`\"{} is expected to have 3 arguments, and the command line is\+:

executable --foo a b -- other arguments

This will result in an error, because \char`\"{}-\/-\/\char`\"{} will be parsed as the third parameter to the first instance of \char`\"{}foo\char`\"{}, and \char`\"{}other\char`\"{} will be an unrecognized option.

Invoking this function multiple times on different sets of argv tokens is safe, but will erase any previous parsing results. 

References opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+argc, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+argv, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+mutex, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+params, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+tail\+\_\+argc, opal\+\_\+cmd\+\_\+line\+\_\+t\+::lcl\+\_\+tail\+\_\+argv, O\+B\+J\+\_\+\+R\+E\+L\+E\+A\+S\+E, opal\+\_\+argv\+\_\+append(), opal\+\_\+argv\+\_\+copy(), opal\+\_\+argv\+\_\+count(), opal\+\_\+argv\+\_\+delete(), opal\+\_\+argv\+\_\+free(), opal\+\_\+argv\+\_\+insert(), opal\+\_\+list\+\_\+append, opal\+\_\+mutex\+\_\+lock(), and opal\+\_\+mutex\+\_\+unlock().



Referenced by parse\+\_\+args().

