1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>OS_GetOpt</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">OS_GetOpt* <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1> 12<H2>Syntax</H2> 13<DL> 14 <DD> 15 <PRE><CODE>#include <nitro/os.h></CODE> 16 17<CODE>int OS_GetOpt( const char* optstring );</CODE> 18<CODE>int OS_GetOptInd( void );</CODE> 19<CODE>const char *OS_GetOptArg( void );</CODE> 20<CODE>int OS_GetOptOpt( void );</CODE></PRE> 21</DL> 22<H2>Arguments</H2> 23<TABLE border="1"> 24 <TBODY> 25 <TR> 26<TD><CODE>optstring</CODE></TD> 27<TD>String that represents the option characters being accepted.</TD> 28 </TR> 29 </TBODY> 30</TABLE> 31<H2>Return Values</H2> 32<P>This function returns any discovered command-line option data. (See next section.)</P> 33<H2>Description</H2> 34<P>Analyzes the command-line argument data obtained by the <A href="OS_GetArgc.html"><CODE>OS_GetArgc</CODE></A> and/or <A href="OS_GetArgv.html">OS_GetArgv</A> functions and extracts any data related to options.</P> 35<P>The <CODE>OS_GetOpt</CODE> function assumes the characters in the <CODE>optstring</CODE> string are option identifiers. Each time this function is called, it reads and evaluates command-line arguments one at a time in order, and if the corresponding option is present, it returns that option's identifier character.</P> 36<P>Use the <CODE>OS_GetOptInd</CODE> function to retrieve the index value of the command-line argument currently being read by the <CODE>OS_GetOpt</CODE> function.</P> 37<P> In addition, if one or two colons (<CODE>:</CODE> or <CODE>::</CODE>) are appended to the end of the string within <CODE>optstring</CODE>, it indicates that the option takes an argument. Option argument data can be obtained using the <CODE>OS_GetOptArg</CODE> function.":"indicates that the option argument is mandatory. A double colon (<CODE>::</CODE>) indicates that the option argument can be omitted. If the option's argument is omitted, <CODE>OS_GetOptArg()</CODE> returns <CODE>NULL</CODE>.</P> 38<P> If there is an option in command line arguments not included in <CODE>optstring</CODE>, and if an option argument required due to the use of a single colon (<CODE>:</CODE>) is not present, the <CODE>OS_GetOpt</CODE> function returns the question mark (<CODE>?</CODE>) character code. In this situation, use the <CODE>OS_GetOptOpt</CODE> function to get the original command-line option identifier in question.</P> 39<P>The <CODE>OS_GetOpt</CODE> function can be set to act in either of two ways when it discovers a regular command-line argument that is not an option. This behavior changes depending on whether the lead character of <CODE>optstring</CODE> is a hyphen (<CODE>-</CODE>) or some other character.</P> 40<P> By default, the lead character of <CODE>optstring</CODE> is not a hyphen. In this case, the <CODE>OS_GetOpt</CODE> function returns -1 when it finds a regular command-line argument or no more command-line arguments. Argument evaluation ends at this position, and no further arguments are read. The <CODE>OS_GetOptInd</CODE> function returns the index value of this first-encountered regular argument. The <CODE>OS_GetOptArg</CODE> function returns <CODE>NULL</CODE>. By specifying the values in the range between the value returned from <CODE>OS_GetOptInd</CODE> and <CODE>OS_GetArgc()-1</CODE> as indices to the <CODE>OS_GetArgv</CODE> function, the application can access the set of command-line arguments with options removed.</P> 41<P>The following code shows how to do this.</P> 42<BLOCKQUOTE style="background-color:#ffffc0"><pre><CODE> 43BOOL opt_b = FALSE; 44const char* opt_s = NULL; 45const char* opt_t = NULL; 46int argc = OS_GetArgc(); 47int c, i; 48 49while ((c = OS_GetOpt("bs:t::")) > 0) 50{ 51 switch (c) 52 { 53 case 'b': // Switch-type option 54 opt_b = TRUE; 55 break; 56 57 case 's': // The option requires an argument 58 opt_s = OS_GetOptArg(); 59 break; 60 61 case 't': // The option does not require an argument 62 opt_t = OS_GetOptArg(); 63 break; 64 65 case '?': // Error processing 66 default: 67 OS_Printf("Error --- option '%c'\n", OS_GetOptOpt()); 68 break; 69 } 70} 71 72// Normal command-line argument 73for (i = OS_GetOptInd(); i < argc; i ++) 74{ 75 OS_Printf("ARG[%d]=%s\n", i, OS_GetArgv(i)); 76} 77</CODE> 78</pre></BLOCKQUOTE> 79<P> If the lead character of <CODE>optstring</CODE> is a hyphen (<CODE>-</CODE>), the <CODE>OS_GetOpt</CODE> function returns +1 when a regular command-line argument is found. Because applications can retrieve this argument value using the <CODE>OS_GetOptArg</CODE> function, applications can handle regular arguments as if the <CODE>OS_GetOpt</CODE> function had returned the character code <CODE>1</CODE> option character. Unlike this function's default behavior, the function will continue evaluating arguments after this point, and each time the <CODE>OS_GetOpt</CODE> function is called, the <CODE>OS_GetOptInd</CODE> function's return value will change to to the index of the next argument. Evaluation will continue until there are no more arguments, at which point the <CODE>OS_GetOpt</CODE> function will return -1.</P> 80<P>The following code shows how to do this.</P> 81<blockquote style="background-color:#ffffc0"> 82<PRE> 83<code> 84BOOL opt_b = FALSE; 85const char* opt_s = NULL; 86const char* opt_t = NULL; 87int c; 88 89while ((c = OS_GetOpt("-bs:t::")) > 0) 90{ 91 switch (c) 92 { 93 case 1: // Normal command-line argument 94 OS_Printf("ARG=%s\n", OS_GetOptArg()); 95 break; 96 97 case 'b': // Switch-type option 98 opt_b = TRUE; 99 break; 100 101 case 's':// The option requires an argument 102 opt_s = OS_GetOptArg(); 103 break; 104 105 case 't':// The option allows the argument to be omitted 106 opt_t = OS_GetOptArg(); 107 break; 108 109 case '?': // Error processing 110 default: 111 OS_Printf("Error --- option '%c'\n", OS_GetOptOpt()); 112 break; 113 } 114} 115</code> 116</PRE> 117</blockquote> 118<H2>See Also</H2> 119<P><A href="OS_GetArgc.html"><CODE>OS_GetArgc</CODE></A><BR> <A href="OS_GetArgv.html"><CODE>OS_GetArgv</CODE></A><BR> <A href="../../tools/buryarg.html"><CODE>buryarg</CODE> Tool</A></P> 120<H2>Revision History</H2> 121<P>2005/09/06 Added a description of how to switch behavior of the function when evaluating arguments.<BR>2005/08/30 Initial version.</P> 122<hr><p>CONFIDENTIAL</p></body> 123</HTML>
