Home Libraries Author Links

Legacy Interface
[Getopts: Parse Command Line and Generate Manual Text]

Collaboration diagram for Legacy Interface:

Detailed Description

The variables and functions of this module are deprecated and should not be used for new program code.


Enumerations

enum  StmGetoptsErrnos {
  StmGetoptsSystemError = -1,
  StmGetoptsOk = 0,
  StmGetoptsOptionError = 1,
  StmGetoptsOptionArgError = 2,
  StmGetoptsArgumentError = 3,
  StmGetoptsWrongUsage = 4
}
 Constants used for the variable stmGetoptsOpterr. More...
enum  StmGetoptsResults {
  StmGetoptsQuestion = (int) '?',
  StmGetoptsEnd = EOF
}
 Constants used as specal return values of stmGetopts(). More...

Functions

int stmGetopts (int argc, const char **argv, const char *optSpec)
 Parse command line options.
int stmFprintfStrArray (FILE *fp, int width, int dim, const char **strArray)
 Format and print an array of character strings.

Variables

const char * stmGetoptsProg
 Program name.
const char * stmGetoptsOptarg
 Option argument.
int stmGetoptsOptind
 Option index.
int stmGetoptsOpterr
 Option error number.
char * stmGetoptsErrbuf
 Option error message.
FILE * stmGetoptsOptfp
 Option error file stream.
StmBool stmGetoptsStrict
 Strict flag.


Enumeration Type Documentation

enum StmGetoptsErrnos

Constants used for the variable stmGetoptsOpterr.

Deprecated:
Do not use for new code.
Enumerator:
StmGetoptsSystemError  System error.

StmGetoptsOk  No error.

StmGetoptsOptionError  Option error.

StmGetoptsOptionArgError  Option argument error.

StmGetoptsArgumentError  Argument error.

StmGetoptsWrongUsage  Wrong usage error.

Definition at line 938 of file getopts.h.

enum StmGetoptsResults

Constants used as specal return values of stmGetopts().

Deprecated:
Do not use for new code.
Enumerator:
StmGetoptsQuestion  Illegal option character.

StmGetoptsEnd  End of options.

Definition at line 954 of file getopts.h.


Function Documentation

int stmGetopts ( int  argc,
const char **  argv,
const char *  optSpec 
)

Parse command line options.

Deprecated:
This function is supplied only for backward compatibility. For new program code use the abstract data type StmCmdLine instead.
Die Funktion stmGetopts implementiert in etwa dieselbe Funktionalitaet wie die Funktion getopt der UNIX Standardlibrary. Bei Systemfehlern kehrt die Funktion mit -1 zurueck, die Variable stmGetoptsOpterr hat den Wert StmGetoptsSystemError und die Variable errno enthaelt den Fehlergrund. Sie kehrt mit dem naechsten Optionsbuchstaben aus argv, der in der die moeglichen Optionsbuchstaben kennzeichneneden Zeichenkette optSpec enthalten ist, zurueck, falls es einen solchen gemaess der Common Command Syntax gibt. Die Zeichenkette optSpec enthaelt alle erlaubten Optionsbuchstaben. Erfordert ein Optionsbuchstabe ein Ar- gument, so folgt ihm in optSpec das Zeichen ':', welches selbst als Optionsbuchstabe nicht erlaubt ist, oder das Zeichen '-'. Ist stmGetoptsStrict StmTrue, so muss das Argument einer argumentbehafteten Option von ihrem Optionsbuchstaben durch Whitespace getrennt sein, sonst nicht. Das Zeichen '-' in optSpec nach einem Optionsbuchstaben, zeigt an, dass mit der zugehoerigen Option die Behandlung der Optionenfolge abge- schlossen wird. Es wird in diesem Fall StmGetoptsEnd zurueckgegeben, und stmGetoptsOptind zeigt auf den betreffenden Optionsbuchstaben und stmGetoptsOptarg auf sein Argument. Nicht argumentbehaftete Optionen koennen nach dem einleitenden '-' zusammengefasst sein, argumentbehaftete Optionen jedoch nicht. Auch ist das Argument einer argumentbehafteten Option nicht optional. Nach der Rueckkehr zeigt stmGetoptsOptarg bei einer argumentbehafteten Option auf den Beginn ihres Arguments. stmGetopts setzt stmGetoptsOptind auf den Index des naechsten zu behandelnden Elements des Vektors argv. D.h. zu Beginn des Kommandoparsings sollte stmGetoptsOptind auf 0 gesetzt werden. Wenn stmGetoptsOptind 0 oder optSpec der Nullzeiger ist, wird die Variable stmGetoptsProg mit dem Basisnamen des in argv [0] enthaltenen Kommandonamen belegt. Sie kann vom rufenden Programm spaeter z.B. fuer Fehlermeldungen verwendet werden. Ist optSpec der Nullzeiger, so wird sofort mit StmGetoptsOk zurueckgekehrt, ohne stmGetoptsOptind zu erhoehen. Wenn alle Optionen behandelt sind, d.h. beim ersten Nichtoptionsar- gument, kehrt stmGetopts mit StmGetoptsEnd (EOF) zurueck. Die spezielle Option '--' kann benutzt werden, um die Folge von Optionen explizit abzuschliessen. In diesem Fall wird mit StmGetoptsEnd zurueckgekehrt und '--' wird uebersprungen. Auch ein alleinstehendes '-' gilt als Nichtoptionsargument und schliesst die Optionen ab, wird jedoch nicht uebersprungen. Im Anwendungsfehlerfall, d.h. bei nicht spezifizierten oder falsch verwendeten Optionsbuchstaben wird mit StmGetoptsQuestion zurueckgekehrt, die Variable stmGetoptsOpterr enthaelt eine entsprechende Fehlernummer (siehe oben) und der dynamische string stmGetoptsErrbuf (siehe dvec.h) enthaelt einen Fehlermeldungstext. Ist dann die Variable stmGetoptsOptfp ungleich NULL und zeigt auf einen gueltigen FILE-Pointer, so wird dieser auf den zu stmGetoptsOptfp gehoerenden Stream ausgegeben. Im Erfolgsfall enthaelt die Variable stmGetoptsOpterr den Wert StmGetoptsOk (siehe oben).

int stmFprintfStrArray ( FILE *  fp,
int  width,
int  dim,
const char **  strArray 
)

Format and print an array of character strings.

Deprecated:
This function is supplied only for backward compatibility. For new program code use one of the functions for formatting and printing man pages (see Format and Print Manual Page Text) instead.
Die Funktion stmFprintfStrArray formatiert das dim-elementige Array von Zeichenketten strArray und gibt es auf dem Stream fp mit einer Zeilen- weite von width aus. Die ersten beiden Elemente von strArray sind die linke und rechte Kopfzeile, die links- bzw. rechtsbuendig als erste Zeile ausgegeben werden. Die Summe ihrer Laengen plus 1 darf width nicht ueberschreiten. Alle folgenden Elemente von strArray werden wie folgt verwendet: Ihr Inhalt wird durch Blank und Tabulator definierte Worte aufgespalten und als Ausgabezeilen im Blocksatz formatiert. Trennstriche am Zeilenende werden, falls sie in die Mitte der Ausgabe- zeile geraten, entfernt. Ist eine Eingabezeile leer, so wird auch eine leere Ausgabezeile erzeugt. Endet eine Eingabezeile mit '.', so wird auch in der Ausgabe eine neue Zeile begonnen. Blanks, die innerhalb von durch Paare einfacher oder doppelter Anfuehrungszeichen geklammer- ter Ausdruecke stehen werden nicht als Wortgrenzen interpretiert. Im Erfolgsfall wird mit 0, im Fehlerfall mit -1 zurueckgekehrt. Die Variable errno enthaelt dann eine entsprechende Fehlernummer.


Variable Documentation

const char* stmGetoptsProg

Program name.

Deprecated:
Do not use for new code.
Basename of the program handled by stmGetopts().

const char* stmGetoptsOptarg

Option argument.

Deprecated:
Do not use for new code.
Argument of the option currently handled by stmGetopts().

int stmGetoptsOptind

Option index.

Deprecated:
Do not use for new code.
Index of the option currently handled by stmGetopts().

int stmGetoptsOpterr

Option error number.

Deprecated:
Do not use for new code.
Error number of the option currently handled by stmGetopts().

char* stmGetoptsErrbuf

Option error message.

Deprecated:
Do not use for new code.
Buffer containing the error message of the option currently handled by stmGetopts().

FILE* stmGetoptsOptfp

Option error file stream.

Deprecated:
Do not use for new code.
If not NULL, the file stream on which error messages concerning the option currently handled by stmGetopts() are printed.

StmBool stmGetoptsStrict

Strict flag.

Deprecated:
Do not use for new code.
If the flag stmGetoptsStrict is StmTrue, the argument of an option shall be separated from its option character by whitespace, else this is not mandatory. By default the flag stmGetoptsStrict is StmTrue.


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).