From f0db61fc3ac106f2037964138a48f13f708150e6 Mon Sep 17 00:00:00 2001 From: jbj Date: Mon, 25 Oct 1999 20:10:00 +0000 Subject: Add poptDupArgv() and const's to popt.3 man page. --- popt.3 | 58 +++++++++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 25 deletions(-) (limited to 'popt.3') diff --git a/popt.3 b/popt.3 index 582a270..96848d3 100644 --- a/popt.3 +++ b/popt.3 @@ -5,9 +5,9 @@ popt \- Parse command line options .nf .B #include .sp -.BI "poptContext poptGetContext(char * " name ", int " argc , -.BI " char ** "argv , -.BI " struct poptOption * " options , +.BI "poptContext poptGetContext(const char * " name ", int " argc , +.BI " har ** "argv , +.BI " const struct poptOption * " options , .BI " int " flags ); .sp .BI "void poptFreeContext(poptContext " con ); @@ -20,13 +20,13 @@ popt \- Parse command line options .sp .BI "char * poptGetArg(poptContext " con ); .sp -.BI "char * poptPeekArg(poptContext " con ); +.BI "const char * poptPeekArg(poptContext " con ); .sp -.BI "char ** poptGetArgs(poptContext " con ); +.BI "const char ** poptGetArgs(poptContext " con ); .sp -.BI "const char * poptStrerror(const int " error ); +.BI "const char *const poptStrerror(const int " error ); .sp -.BI "char * poptBadOption(poptContext " con ", int " flags ); +.BI "const char * poptBadOption(poptContext " con ", int " flags ); .sp .BI "int poptReadDefaultConfig(poptContext " con ", int " flags ); .sp @@ -36,9 +36,12 @@ popt \- Parse command line options .BI " int " flags ); .sp .BI "int poptParseArgvString(char * " s ", int * " argcPtr , -.BI " char *** " argvPtr ); +.BI " const char *** " argvPtr ); .sp -.BI "int poptStuffArgs(poptContext " con ", char ** " argv ); +.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ", +.BI " const char *** " argvPtr ");" +.sp +.BI "int poptStuffArgs(poptContext " con ", const char ** " argv ); .sp .fi .SH DESCRIPTION @@ -242,9 +245,9 @@ modified outside the popt library. .RB "New popt contexts are created by " poptGetContext() ":" .sp .nf -.BI "poptContext poptGetContext(char * " name ", int "argc ", +.BI "poptContext poptGetContext(const char * " name ", int "argc ", .BI " char ** "argv ", -.BI " struct poptOption * "options ", +.BI " const struct poptOption * "options ", .BI " int "flags ");" .fi .sp @@ -351,7 +354,7 @@ processed. .PP .nf .HP -.BI "char * poptPeekArg(poptContext " con ");" +.BI "const char * poptPeekArg(poptContext " con ");" .fi The next leftover argument is returned but not marked as processed. This allows an application to look ahead into the argument list, @@ -359,7 +362,7 @@ without modifying the list. .PP .nf .HP -.BI "char ** poptGetArgs(poptContext " con ");" +.BI "const char ** poptGetArgs(poptContext " con ");" .fi All the leftover arguments are returned in a manner identical to .IR argv ". The final element in the returned array points to " @@ -457,14 +460,14 @@ Two functions are available to make it easy for applications to provide good error messages. .HP .nf -.BI "const char * poptStrerror(const int " error ");" +.BI "const char *const poptStrerror(const int " error ");" .fi This function takes a popt error code and returns a string describing .RB "the error, just as with the standard " strerror() " function." .PP .HP .nf -.BI "char * poptBadOption(poptContext " con ", int " flags ");" +.BI "const char * poptBadOption(poptContext " con ", int " flags ");" .fi .RB "If an error occurred during " poptGetNextOpt() ", this function " .RI "returns the option that caused the error. If the " flags " argument" @@ -551,10 +554,10 @@ currently reserved for future expansion. The new alias is specified .sp .nf struct poptAlias { - char * longName; /* may be NULL */ + const char * longName; /* may be NULL */ char shortName; /* may be '\\0' */ int argc; - char ** argv; /* must be free()able */ + const char ** argv; /* must be free()able */ }; .fi .sp @@ -571,20 +574,25 @@ using rules similiar to normal shell parsing. .sp .nf .B "#include " -.BI "int poptParseArgvString(char * " s ", int * "argcPtr ", +.BI "int poptParseArgvString(char * " s ", int * " argcPtr ", .BI " char *** " argvPtr ");" +.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ", +.BI " const char *** " argvPtr ");" .fi .sp .RI "The string s is parsed into an " argv "-style array. The integer " -.RI "pointed to by the second parameter, " argcPtr ", contains the number " -of elements parsed, and the pointer pointed to by the final parameter is -set to point to the newly created array. The array is dynamically -.RB "allocated and should be " free() "ed when the application is finished " -with it. +.RI "pointed to by the " argcPtr " parameter contains the number of elements " +.RI "parsed, and the final " argvPtr " parameter contains the address of the" +newly created array. +.RB "The routine " poptDupArgv() " can be used to make a copy of an existing " +argument array. .sp .RI "The " argvPtr -.RB "created by " poptParseArgvString() " is suitable to pass directly " +.RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly " .RB "to " poptGetContext() . +Both routines return a single dynamically allocated contiguous +.RB "block of storage and should be " free() "ed when the application is" +finished with the storage. .SH "HANDLING EXTRA ARGUMENTS" Some applications implement the equivalent of option aliasing but need .RB "to do so through special logic. The " poptStuffArgs() " function " @@ -593,7 +601,7 @@ allows an application to insert new arguments into the current .sp .nf .B "#include " -.BI "int poptStuffArgs(poptContext "con ", char ** " argv ");" +.BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");" .fi .sp .RI "The passed " argv -- cgit v1.2.1