1@node libopts procedures 2@subsection libopts External Procedures 3 4These are the routines that libopts users may call directly from their 5code. There are several other routines that can be called by code 6generated by the libopts option templates, but they are not to be 7called from any other user code. The @file{options.h} header is 8fairly clear about this, too. 9 10@menu 11* libopts-ao_string_tokenize:: ao_string_tokenize 12* libopts-configFileLoad:: configFileLoad 13* libopts-optionFileLoad:: optionFileLoad 14* libopts-optionFindNextValue:: optionFindNextValue 15* libopts-optionFindValue:: optionFindValue 16* libopts-optionFree:: optionFree 17* libopts-optionGetValue:: optionGetValue 18* libopts-optionLoadLine:: optionLoadLine 19* libopts-optionMemberList:: optionMemberList 20* libopts-optionNextValue:: optionNextValue 21* libopts-optionOnlyUsage:: optionOnlyUsage 22* libopts-optionPrintVersion:: optionPrintVersion 23* libopts-optionPrintVersionAndReturn:: optionPrintVersionAndReturn 24* libopts-optionProcess:: optionProcess 25* libopts-optionRestore:: optionRestore 26* libopts-optionSaveFile:: optionSaveFile 27* libopts-optionSaveState:: optionSaveState 28* libopts-optionUnloadNested:: optionUnloadNested 29* libopts-optionVersion:: optionVersion 30* libopts-strequate:: strequate 31* libopts-streqvcmp:: streqvcmp 32* libopts-streqvmap:: streqvmap 33* libopts-strneqvcmp:: strneqvcmp 34* libopts-strtransform:: strtransform 35@end menu 36 37This subsection was automatically generated by AutoGen 38using extracted information and the aginfo3.tpl template. 39 40@node libopts-ao_string_tokenize 41@subsubsection ao_string_tokenize 42@findex ao_string_tokenize 43 44tokenize an input string 45 46@noindent 47Usage: 48@example 49token_list_t * res = ao_string_tokenize( string ); 50@end example 51@noindent 52Where the arguments are: 53@multitable @columnfractions .05 .15 .20 .55 54@item @tab Name @tab Type @tab Description 55@item @tab ----- @tab ----- @tab ------------- 56@item @tab string @tab @code{char const *} 57@tab string to be tokenized 58@item @tab returns @tab token_list_t * 59@tab pointer to a structure that lists each token 60@end multitable 61 62This function will convert one input string into a list of strings. 63The list of strings is derived by separating the input based on 64white space separation. However, if the input contains either single 65or double quote characters, then the text after that character up to 66a matching quote will become the string in the list. 67 68The returned pointer should be deallocated with @code{free(3C)} when 69are done using the data. The data are placed in a single block of 70allocated memory. Do not deallocate individual token/strings. 71 72The structure pointed to will contain at least these two fields: 73@table @samp 74@item tkn_ct 75The number of tokens found in the input string. 76@item tok_list 77An array of @code{tkn_ct + 1} pointers to substring tokens, with 78the last pointer set to NULL. 79@end table 80 81There are two types of quoted strings: single quoted (@code{'}) and 82double quoted (@code{"}). Singly quoted strings are fairly raw in that 83escape characters (@code{\\}) are simply another character, except when 84preceding the following characters: 85@example 86@code{\\} double backslashes reduce to one 87@code{'} incorporates the single quote into the string 88@code{\n} suppresses both the backslash and newline character 89@end example 90 91Double quote strings are formed according to the rules of string 92constants in ANSI-C programs. 93 94NULL is returned and @code{errno} will be set to indicate the problem: 95@itemize @bullet 96@item 97@code{EINVAL} - There was an unterminated quoted string. 98@item 99@code{ENOENT} - The input string was empty. 100@item 101@code{ENOMEM} - There is not enough memory. 102@end itemize 103 104 105@node libopts-configFileLoad 106@subsubsection configFileLoad 107@findex configFileLoad 108 109parse a configuration file 110 111@noindent 112Usage: 113@example 114const tOptionValue * res = configFileLoad( fname ); 115@end example 116@noindent 117Where the arguments are: 118@multitable @columnfractions .05 .15 .20 .55 119@item @tab Name @tab Type @tab Description 120@item @tab ----- @tab ----- @tab ------------- 121@item @tab fname @tab @code{char const *} 122@tab the file to load 123@item @tab returns @tab const tOptionValue * 124@tab An allocated, compound value structure 125@end multitable 126 127This routine will load a named configuration file and parse the 128text as a hierarchically valued option. The option descriptor 129created from an option definition file is not used via this interface. 130The returned value is "named" with the input file name and is of 131type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to 132@code{optionGetValue()}, @code{optionNextValue()} and 133@code{optionUnloadNested()}. 134 135If the file cannot be loaded or processed, @code{NULL} is returned and 136@var{errno} is set. It may be set by a call to either @code{open(2)} 137@code{mmap(2)} or other file system calls, or it may be: 138@itemize @bullet 139@item 140@code{ENOENT} - the file was not found. 141@item 142@code{ENOMSG} - the file was empty. 143@item 144@code{EINVAL} - the file contents are invalid -- not properly formed. 145@item 146@code{ENOMEM} - not enough memory to allocate the needed structures. 147@end itemize 148 149 150@node libopts-optionFileLoad 151@subsubsection optionFileLoad 152@findex optionFileLoad 153 154Load the locatable config files, in order 155 156@noindent 157Usage: 158@example 159int res = optionFileLoad( opts, prog ); 160@end example 161@noindent 162Where the arguments are: 163@multitable @columnfractions .05 .15 .20 .55 164@item @tab Name @tab Type @tab Description 165@item @tab ----- @tab ----- @tab ------------- 166@item @tab opts @tab @code{tOptions *} 167@tab program options descriptor 168 169@item @tab prog @tab @code{char const *} 170@tab program name 171@item @tab returns @tab int 172@tab 0 -> SUCCESS, -1 -> FAILURE 173@end multitable 174 175This function looks in all the specified directories for a configuration 176file ("rc" file or "ini" file) and processes any found twice. The first 177time through, they are processed in reverse order (last file first). At 178that time, only "immediate action" configurables are processed. For 179example, if the last named file specifies not processing any more 180configuration files, then no more configuration files will be processed. 181Such an option in the @strong{first} named directory will have no effect. 182 183Once the immediate action configurables have been handled, then the 184directories are handled in normal, forward order. In that way, later 185config files can override the settings of earlier config files. 186 187See the AutoOpts documentation for a thorough discussion of the 188config file format. 189 190Configuration files not found or not decipherable are simply ignored. 191 192Returns the value, "-1" if the program options descriptor 193is out of date or indecipherable. Otherwise, the value "0" will 194always be returned. 195 196 197@node libopts-optionFindNextValue 198@subsubsection optionFindNextValue 199@findex optionFindNextValue 200 201find a hierarcicaly valued option instance 202 203@noindent 204Usage: 205@example 206const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value ); 207@end example 208@noindent 209Where the arguments are: 210@multitable @columnfractions .05 .15 .20 .55 211@item @tab Name @tab Type @tab Description 212@item @tab ----- @tab ----- @tab ------------- 213@item @tab odesc @tab @code{const tOptDesc *} 214@tab an option with a nested arg type 215 216@item @tab pPrevVal @tab @code{const tOptionValue *} 217@tab the last entry 218 219@item @tab name @tab @code{char const *} 220@tab name of value to find 221 222@item @tab value @tab @code{char const *} 223@tab the matching value 224@item @tab returns @tab const tOptionValue * 225@tab a compound value structure 226@end multitable 227 228This routine will find the next entry in a nested value option or 229configurable. It will search through the list and return the next entry 230that matches the criteria. 231 232The returned result is NULL and errno is set: 233@itemize @bullet 234@item 235@code{EINVAL} - the @code{pOptValue} does not point to a valid 236hierarchical option value. 237@item 238@code{ENOENT} - no entry matched the given name. 239@end itemize 240 241 242@node libopts-optionFindValue 243@subsubsection optionFindValue 244@findex optionFindValue 245 246find a hierarcicaly valued option instance 247 248@noindent 249Usage: 250@example 251const tOptionValue * res = optionFindValue( odesc, name, val ); 252@end example 253@noindent 254Where the arguments are: 255@multitable @columnfractions .05 .15 .20 .55 256@item @tab Name @tab Type @tab Description 257@item @tab ----- @tab ----- @tab ------------- 258@item @tab odesc @tab @code{const tOptDesc *} 259@tab an option with a nested arg type 260 261@item @tab name @tab @code{char const *} 262@tab name of value to find 263 264@item @tab val @tab @code{char const *} 265@tab the matching value 266@item @tab returns @tab const tOptionValue * 267@tab a compound value structure 268@end multitable 269 270This routine will find an entry in a nested value option or configurable. 271It will search through the list and return a matching entry. 272 273The returned result is NULL and errno is set: 274@itemize @bullet 275@item 276@code{EINVAL} - the @code{pOptValue} does not point to a valid 277hierarchical option value. 278@item 279@code{ENOENT} - no entry matched the given name. 280@end itemize 281 282 283@node libopts-optionFree 284@subsubsection optionFree 285@findex optionFree 286 287free allocated option processing memory 288 289@noindent 290Usage: 291@example 292optionFree( pOpts ); 293@end example 294@noindent 295Where the arguments are: 296@multitable @columnfractions .05 .15 .20 .55 297@item @tab Name @tab Type @tab Description 298@item @tab ----- @tab ----- @tab ------------- 299@item @tab pOpts @tab @code{tOptions *} 300@tab program options descriptor 301@end multitable 302 303AutoOpts sometimes allocates memory and puts pointers to it in the 304option state structures. This routine deallocates all such memory. 305 306As long as memory has not been corrupted, 307this routine is always successful. 308 309 310@node libopts-optionGetValue 311@subsubsection optionGetValue 312@findex optionGetValue 313 314get a specific value from a hierarcical list 315 316@noindent 317Usage: 318@example 319const tOptionValue * res = optionGetValue( pOptValue, valueName ); 320@end example 321@noindent 322Where the arguments are: 323@multitable @columnfractions .05 .15 .20 .55 324@item @tab Name @tab Type @tab Description 325@item @tab ----- @tab ----- @tab ------------- 326@item @tab pOptValue @tab @code{const tOptionValue *} 327@tab a hierarchcal value 328 329@item @tab valueName @tab @code{char const *} 330@tab name of value to get 331@item @tab returns @tab const tOptionValue * 332@tab a compound value structure 333@end multitable 334 335This routine will find an entry in a nested value option or configurable. 336If "valueName" is NULL, then the first entry is returned. Otherwise, 337the first entry with a name that exactly matches the argument will be 338returned. If there is no matching value, NULL is returned and errno is 339set to ENOENT. If the provided option value is not a hierarchical value, 340NULL is also returned and errno is set to EINVAL. 341 342The returned result is NULL and errno is set: 343@itemize @bullet 344@item 345@code{EINVAL} - the @code{pOptValue} does not point to a valid 346hierarchical option value. 347@item 348@code{ENOENT} - no entry matched the given name. 349@end itemize 350 351 352@node libopts-optionLoadLine 353@subsubsection optionLoadLine 354@findex optionLoadLine 355 356process a string for an option name and value 357 358@noindent 359Usage: 360@example 361optionLoadLine( opts, line ); 362@end example 363@noindent 364Where the arguments are: 365@multitable @columnfractions .05 .15 .20 .55 366@item @tab Name @tab Type @tab Description 367@item @tab ----- @tab ----- @tab ------------- 368@item @tab opts @tab @code{tOptions *} 369@tab program options descriptor 370 371@item @tab line @tab @code{char const *} 372@tab NUL-terminated text 373@end multitable 374 375This is a client program callable routine for setting options from, for 376example, the contents of a file that they read in. Only one option may 377appear in the text. It will be treated as a normal (non-preset) option. 378 379When passed a pointer to the option struct and a string, it will find 380the option named by the first token on the string and set the option 381argument to the remainder of the string. The caller must NUL terminate 382the string. The caller need not skip over any introductory hyphens. 383Any embedded new lines will be included in the option 384argument. If the input looks like one or more quoted strings, then the 385input will be "cooked". The "cooking" is identical to the string 386formation used in AutoGen definition files (@pxref{basic expression}), 387except that you may not use backquotes. 388 389Invalid options are silently ignored. Invalid option arguments 390will cause a warning to print, but the function should return. 391 392 393@node libopts-optionMemberList 394@subsubsection optionMemberList 395@findex optionMemberList 396 397Get the list of members of a bit mask set 398 399@noindent 400Usage: 401@example 402char * res = optionMemberList( od ); 403@end example 404@noindent 405Where the arguments are: 406@multitable @columnfractions .05 .15 .20 .55 407@item @tab Name @tab Type @tab Description 408@item @tab ----- @tab ----- @tab ------------- 409@item @tab od @tab @code{tOptDesc *} 410@tab the set membership option description 411@item @tab returns @tab char * 412@tab the names of the set bits 413@end multitable 414 415This converts the OPT_VALUE_name mask value to a allocated string. 416It is the caller's responsibility to free the string. 417 418 419@node libopts-optionNextValue 420@subsubsection optionNextValue 421@findex optionNextValue 422 423get the next value from a hierarchical list 424 425@noindent 426Usage: 427@example 428const tOptionValue * res = optionNextValue( pOptValue, pOldValue ); 429@end example 430@noindent 431Where the arguments are: 432@multitable @columnfractions .05 .15 .20 .55 433@item @tab Name @tab Type @tab Description 434@item @tab ----- @tab ----- @tab ------------- 435@item @tab pOptValue @tab @code{const tOptionValue *} 436@tab a hierarchcal list value 437 438@item @tab pOldValue @tab @code{const tOptionValue *} 439@tab a value from this list 440@item @tab returns @tab const tOptionValue * 441@tab a compound value structure 442@end multitable 443 444This routine will return the next entry after the entry passed in. At the 445end of the list, NULL will be returned. If the entry is not found on the 446list, NULL will be returned and "@var{errno}" will be set to EINVAL. 447The "@var{pOldValue}" must have been gotten from a prior call to this 448routine or to "@code{opitonGetValue()}". 449 450The returned result is NULL and errno is set: 451@itemize @bullet 452@item 453@code{EINVAL} - the @code{pOptValue} does not point to a valid 454hierarchical option value or @code{pOldValue} does not point to a 455member of that option value. 456@item 457@code{ENOENT} - the supplied @code{pOldValue} pointed to the last entry. 458@end itemize 459 460 461@node libopts-optionOnlyUsage 462@subsubsection optionOnlyUsage 463@findex optionOnlyUsage 464 465Print usage text for just the options 466 467@noindent 468Usage: 469@example 470optionOnlyUsage( pOpts, ex_code ); 471@end example 472@noindent 473Where the arguments are: 474@multitable @columnfractions .05 .15 .20 .55 475@item @tab Name @tab Type @tab Description 476@item @tab ----- @tab ----- @tab ------------- 477@item @tab pOpts @tab @code{tOptions *} 478@tab program options descriptor 479 480@item @tab ex_code @tab @code{int} 481@tab exit code for calling exit(3) 482@end multitable 483 484This routine will print only the usage for each option. 485This function may be used when the emitted usage must incorporate 486information not available to AutoOpts. 487 488 489@node libopts-optionPrintVersion 490@subsubsection optionPrintVersion 491@findex optionPrintVersion 492 493Print the program version 494 495@noindent 496Usage: 497@example 498optionPrintVersion( opts, od ); 499@end example 500@noindent 501Where the arguments are: 502@multitable @columnfractions .05 .15 .20 .55 503@item @tab Name @tab Type @tab Description 504@item @tab ----- @tab ----- @tab ------------- 505@item @tab opts @tab @code{tOptions *} 506@tab program options descriptor 507 508@item @tab od @tab @code{tOptDesc *} 509@tab the descriptor for this arg 510@end multitable 511 512This routine will print the version to stdout. 513 514 515@node libopts-optionPrintVersionAndReturn 516@subsubsection optionPrintVersionAndReturn 517@findex optionPrintVersionAndReturn 518 519Print the program version 520 521@noindent 522Usage: 523@example 524optionPrintVersionAndReturn( opts, od ); 525@end example 526@noindent 527Where the arguments are: 528@multitable @columnfractions .05 .15 .20 .55 529@item @tab Name @tab Type @tab Description 530@item @tab ----- @tab ----- @tab ------------- 531@item @tab opts @tab @code{tOptions *} 532@tab program options descriptor 533 534@item @tab od @tab @code{tOptDesc *} 535@tab the descriptor for this arg 536@end multitable 537 538This routine will print the version to stdout and return 539instead of exiting. Please see the source for the 540@code{print_ver} funtion for details on selecting how 541verbose to be after this function returns. 542 543 544@node libopts-optionProcess 545@subsubsection optionProcess 546@findex optionProcess 547 548this is the main option processing routine 549 550@noindent 551Usage: 552@example 553int res = optionProcess( opts, a_ct, a_v ); 554@end example 555@noindent 556Where the arguments are: 557@multitable @columnfractions .05 .15 .20 .55 558@item @tab Name @tab Type @tab Description 559@item @tab ----- @tab ----- @tab ------------- 560@item @tab opts @tab @code{tOptions *} 561@tab program options descriptor 562 563@item @tab a_ct @tab @code{int} 564@tab program arg count 565 566@item @tab a_v @tab @code{char **} 567@tab program arg vector 568@item @tab returns @tab int 569@tab the count of the arguments processed 570@end multitable 571 572This is the main entry point for processing options. It is intended 573that this procedure be called once at the beginning of the execution of 574a program. Depending on options selected earlier, it is sometimes 575necessary to stop and restart option processing, or to select completely 576different sets of options. This can be done easily, but you generally 577do not want to do this. 578 579The number of arguments processed always includes the program name. 580If one of the arguments is "--", then it is counted and the processing 581stops. If an error was encountered and errors are to be tolerated, then 582the returned value is the index of the argument causing the error. 583A hyphen by itself ("-") will also cause processing to stop and will 584@emph{not} be counted among the processed arguments. A hyphen by itself 585is treated as an operand. Encountering an operand stops option 586processing. 587 588Errors will cause diagnostics to be printed. @code{exit(3)} may 589or may not be called. It depends upon whether or not the options 590were generated with the "allow-errors" attribute, or if the 591ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked. 592 593 594@node libopts-optionRestore 595@subsubsection optionRestore 596@findex optionRestore 597 598restore option state from memory copy 599 600@noindent 601Usage: 602@example 603optionRestore( pOpts ); 604@end example 605@noindent 606Where the arguments are: 607@multitable @columnfractions .05 .15 .20 .55 608@item @tab Name @tab Type @tab Description 609@item @tab ----- @tab ----- @tab ------------- 610@item @tab pOpts @tab @code{tOptions *} 611@tab program options descriptor 612@end multitable 613 614Copy back the option state from saved memory. 615The allocated memory is left intact, so this routine can be 616called repeatedly without having to call optionSaveState again. 617If you are restoring a state that was saved before the first call 618to optionProcess(3AO), then you may change the contents of the 619argc/argv parameters to optionProcess. 620 621If you have not called @code{optionSaveState} before, a diagnostic is 622printed to @code{stderr} and exit is called. 623 624 625@node libopts-optionSaveFile 626@subsubsection optionSaveFile 627@findex optionSaveFile 628 629saves the option state to a file 630 631@noindent 632Usage: 633@example 634optionSaveFile( opts ); 635@end example 636@noindent 637Where the arguments are: 638@multitable @columnfractions .05 .15 .20 .55 639@item @tab Name @tab Type @tab Description 640@item @tab ----- @tab ----- @tab ------------- 641@item @tab opts @tab @code{tOptions *} 642@tab program options descriptor 643@end multitable 644 645This routine will save the state of option processing to a file. The name 646of that file can be specified with the argument to the @code{--save-opts} 647option, or by appending the @code{rcfile} attribute to the last 648@code{homerc} attribute. If no @code{rcfile} attribute was specified, it 649will default to @code{.@i{programname}rc}. If you wish to specify another 650file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. 651 652The recommend usage is as follows: 653@example 654optionProcess(&progOptions, argc, argv); 655if (i_want_a_non_standard_place_for_this) 656SET_OPT_SAVE_OPTS("myfilename"); 657optionSaveFile(&progOptions); 658@end example 659 660If no @code{homerc} file was specified, this routine will silently return 661and do nothing. If the output file cannot be created or updated, a message 662will be printed to @code{stderr} and the routine will return. 663 664 665@node libopts-optionSaveState 666@subsubsection optionSaveState 667@findex optionSaveState 668 669saves the option state to memory 670 671@noindent 672Usage: 673@example 674optionSaveState( pOpts ); 675@end example 676@noindent 677Where the arguments are: 678@multitable @columnfractions .05 .15 .20 .55 679@item @tab Name @tab Type @tab Description 680@item @tab ----- @tab ----- @tab ------------- 681@item @tab pOpts @tab @code{tOptions *} 682@tab program options descriptor 683@end multitable 684 685This routine will allocate enough memory to save the current option 686processing state. If this routine has been called before, that memory 687will be reused. You may only save one copy of the option state. This 688routine may be called before optionProcess(3AO). If you do call it 689before the first call to optionProcess, then you may also change the 690contents of argc/argv after you call optionRestore(3AO) 691 692In fact, more strongly put: it is safest to only use this function 693before having processed any options. In particular, the saving and 694restoring of stacked string arguments and hierarchical values is 695disabled. The values are not saved. 696 697If it fails to allocate the memory, 698it will print a message to stderr and exit. 699Otherwise, it will always succeed. 700 701 702@node libopts-optionUnloadNested 703@subsubsection optionUnloadNested 704@findex optionUnloadNested 705 706Deallocate the memory for a nested value 707 708@noindent 709Usage: 710@example 711optionUnloadNested( pOptVal ); 712@end example 713@noindent 714Where the arguments are: 715@multitable @columnfractions .05 .15 .20 .55 716@item @tab Name @tab Type @tab Description 717@item @tab ----- @tab ----- @tab ------------- 718@item @tab pOptVal @tab @code{tOptionValue const *} 719@tab the hierarchical value 720@end multitable 721 722A nested value needs to be deallocated. The pointer passed in should 723have been gotten from a call to @code{configFileLoad()} (See 724@pxref{libopts-configFileLoad}). 725 726 727@node libopts-optionVersion 728@subsubsection optionVersion 729@findex optionVersion 730 731return the compiled AutoOpts version number 732 733@noindent 734Usage: 735@example 736char const * res = optionVersion(); 737@end example 738@noindent 739Where the arguments are: 740@multitable @columnfractions .05 .15 .20 .55 741@item @tab Name @tab Type @tab Description 742@item @tab ----- @tab ----- @tab ------------- 743@item @tab returns @tab char const * 744@tab the version string in constant memory 745@end multitable 746 747Returns the full version string compiled into the library. 748The returned string cannot be modified. 749 750 751@node libopts-strequate 752@subsubsection strequate 753@findex strequate 754 755map a list of characters to the same value 756 757@noindent 758Usage: 759@example 760strequate( ch_list ); 761@end example 762@noindent 763Where the arguments are: 764@multitable @columnfractions .05 .15 .20 .55 765@item @tab Name @tab Type @tab Description 766@item @tab ----- @tab ----- @tab ------------- 767@item @tab ch_list @tab @code{char const *} 768@tab characters to equivalence 769@end multitable 770 771Each character in the input string get mapped to the first character 772in the string. 773This function name is mapped to option_strequate so as to not conflict 774with the POSIX name space. 775 776none. 777 778 779@node libopts-streqvcmp 780@subsubsection streqvcmp 781@findex streqvcmp 782 783compare two strings with an equivalence mapping 784 785@noindent 786Usage: 787@example 788int res = streqvcmp( str1, str2 ); 789@end example 790@noindent 791Where the arguments are: 792@multitable @columnfractions .05 .15 .20 .55 793@item @tab Name @tab Type @tab Description 794@item @tab ----- @tab ----- @tab ------------- 795@item @tab str1 @tab @code{char const *} 796@tab first string 797 798@item @tab str2 @tab @code{char const *} 799@tab second string 800@item @tab returns @tab int 801@tab the difference between two differing characters 802@end multitable 803 804Using a character mapping, two strings are compared for "equivalence". 805Each input character is mapped to a comparison character and the 806mapped-to characters are compared for the two NUL terminated input strings. 807This function name is mapped to option_streqvcmp so as to not conflict 808with the POSIX name space. 809 810none checked. Caller responsible for seg faults. 811 812 813@node libopts-streqvmap 814@subsubsection streqvmap 815@findex streqvmap 816 817Set the character mappings for the streqv functions 818 819@noindent 820Usage: 821@example 822streqvmap( from, to, ct ); 823@end example 824@noindent 825Where the arguments are: 826@multitable @columnfractions .05 .15 .20 .55 827@item @tab Name @tab Type @tab Description 828@item @tab ----- @tab ----- @tab ------------- 829@item @tab from @tab @code{char} 830@tab Input character 831 832@item @tab to @tab @code{char} 833@tab Mapped-to character 834 835@item @tab ct @tab @code{int} 836@tab compare length 837@end multitable 838 839Set the character mapping. If the count (@code{ct}) is set to zero, then 840the map is cleared by setting all entries in the map to their index 841value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" 842character. If @code{ct} is greater than 1, then @code{From} and @code{To} 843are incremented and the process repeated until @code{ct} entries have been 844set. For example, 845@example 846streqvmap('a', 'A', 26); 847@end example 848@noindent 849will alter the mapping so that all English lower case letters 850will map to upper case. 851 852This function name is mapped to option_streqvmap so as to not conflict 853with the POSIX name space. 854 855none. 856 857 858@node libopts-strneqvcmp 859@subsubsection strneqvcmp 860@findex strneqvcmp 861 862compare two strings with an equivalence mapping 863 864@noindent 865Usage: 866@example 867int res = strneqvcmp( str1, str2, ct ); 868@end example 869@noindent 870Where the arguments are: 871@multitable @columnfractions .05 .15 .20 .55 872@item @tab Name @tab Type @tab Description 873@item @tab ----- @tab ----- @tab ------------- 874@item @tab str1 @tab @code{char const *} 875@tab first string 876 877@item @tab str2 @tab @code{char const *} 878@tab second string 879 880@item @tab ct @tab @code{int} 881@tab compare length 882@item @tab returns @tab int 883@tab the difference between two differing characters 884@end multitable 885 886Using a character mapping, two strings are compared for "equivalence". 887Each input character is mapped to a comparison character and the 888mapped-to characters are compared for the two NUL terminated input strings. 889The comparison is limited to @code{ct} bytes. 890This function name is mapped to option_strneqvcmp so as to not conflict 891with the POSIX name space. 892 893none checked. Caller responsible for seg faults. 894 895 896@node libopts-strtransform 897@subsubsection strtransform 898@findex strtransform 899 900convert a string into its mapped-to value 901 902@noindent 903Usage: 904@example 905strtransform( dest, src ); 906@end example 907@noindent 908Where the arguments are: 909@multitable @columnfractions .05 .15 .20 .55 910@item @tab Name @tab Type @tab Description 911@item @tab ----- @tab ----- @tab ------------- 912@item @tab dest @tab @code{char *} 913@tab output string 914 915@item @tab src @tab @code{char const *} 916@tab input string 917@end multitable 918 919Each character in the input string is mapped and the mapped-to 920character is put into the output. 921This function name is mapped to option_strtransform so as to not conflict 922with the POSIX name space. 923 924The source and destination may be the same. 925 926none. 927 928