wordexp(3C) wordexp(3C)
NAME
wordexp, wordfree - Wort-Expansionen durchführen
SYNTAX
#include <wordexp.h>
int wordexp(const char *words, wordexpt *pwordexp, int flags);
void wordfree(wordexpt *pwordexp);
BESCHREIBUNG
Die Funktion wordexp() führt Wort-Expansionen durch und legt die Liste
der expandierten Worte in der Struktur ab, auf die pwordexp zeigt.
Das Argument words ist ein Zeiger auf eine Zeichenkette, die ein oder
mehr Worte enthält, die expandiert werden sollen. Die Expansionen ent-
sprechen denen, die von der Shell durchgeführt würden, wenn words der
Bestandteil einer Kommandozeile wäre, der die Argumente für ein
Dienstprogramm angibt. Daher darf words kein Neue-Zeile-Zeichen ent-
halten, das nicht in Anführungszeichen geschrieben ist, bzw. keine der
folgenden Sonderzeichen der Shell enthalten, die nicht in Anführungs-
zeichen geschrieben sind:
| & ; < >
Eine Ausnahme hierfür stellt die Kommando-Substitution dar (die
Kommando-Substitution ermöglicht es, die Ausgabe eines Kommandos statt
des Kommandonamens anzugeben). Außerdem dürfen keine runden oder
geschweiften Klammern enthalten sein, die nicht in Anführungszeichen
geschrieben sind (außer bei der Kommando- oder Variablen-Substitu-
tion). Wenn das Argument words ein nicht in Anführungszeichen
geschriebenes Kommentarzeichen (Nummernzeichen) enthält, das den
Anfang eines Tokens darstellt, kann wordexp() das Kommentarzeichen als
normales Zeichen behandeln oder als Hinweis auf einen Kommentar inter-
pretieren und folglich den Rest von words ignorieren.
Die Struktur wordexpt ist in der Include-Datei wordexp.h definiert.
Sie enthält mindestens die folgenden Komponenten:
______________________________________________________________________
| Komponententyp | Komponentenname | Beschreibung |
|________________|_________________|__________________________________|
| sizet | wewordc | Anzahl der Worte, die words |
| | | entsprechen |
|________________|_________________|__________________________________|
| char ** | wewordv | Zeiger auf eine Liste mit |
| | | expandierten Worten |
|________________|_________________|__________________________________|
| sizet | weoffs | zu reservierende Slots am Anfang|
| | | von pwordexp->wewordv |
|________________|_________________|__________________________________|
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
wordexp(3C) wordexp(3C)
Die Funktion wordexp() legt die Anzahl der generierten Worte in
pword->wewordc ab. Außerdem legt sie einen Zeiger auf eine Liste mit
Zeigern auf Worte in pwordexp->wewordv ab. Jedes einzelne Feld, das
bei der Feldtrennung oder bei der Pfadnamen-Expansion erstellt wird,
ist in der Liste pwordexp->wewordv ein eigenes Wort. Der erste Zeiger
nach dem letzten Wort-Zeiger ist ein Nullzeiger. Die Expansion beson-
derer Parameter (wie zum Beispiel *, @, #, ?, - $, !, 0) ist nicht
definiert.
Feldtrennung
Nach der Parameter-Expansion, Kommando-Substitution und arithmetischen
Expansion durchsucht die Shell die Ergebnisse der Expansionen und Sub-
stitutionen, die nicht in Anführungszeichen vorkamen, da es zu Feld-
trennung und Mehrfachfeldern kommen kann. Die Shell behandelt jedes
Zeichen von IFS (input field separator; Umgebungsvariable) als Begren-
zer und verwendet die Begrenzer, um die Ergebnisse der Parameter-
Expansion und Kommando-Substitution in Felder aufzuteilen.
1. Wenn der Wert von IFS ein Leerzeichen, Tabulator und Neue-Zeile-
Zeichen ist oder wenn der Wert von IFS nicht gesetzt ist, wird eine
beliebige Folge von Leerzeichen, Tabulatoren oder Neue-Zeile-
Zeichen am Anfang oder Ende der Eingabe ignoriert. Eine Folge die-
ser Zeichen in der Eingabe begrenzt ein Feld.
2. Wenn der Wert von IFS gleich Null ist, wird die Feldtrennung nicht
durchgeführt.
3. Andernfalls werden die folgenden Regeln in dieser Reihenfolge ange-
wandt. Der Ausdruck IFS-Zwischenraumzeichen wird in der folgenden
Bedeutung verwendet: eine beliebige Folge (null oder mehr) Zwi-
schenraumzeichen im IFS-Wert.
- IFS-Zwischenraumzeichen werden am Anfang und am Ende der Eingabe
ignoriert.
- Jedes Vorkommen eines IFS-Zeichens in der Eingabe, das kein
IFS-Zwischenraumzeichen ist, begrenzt, zusammen mit benachbarten
IFS-Zwischenraumzeichen, ein Feld.
- IFS-Zwischenraumzeichen mit einer Länge ungleich Null begrenzen
ein Feld.
Pfadnamen-Expansion
Wenn set -f nach der Feldtrennung nicht wirksam ist, wird jedes Feld
in der Kommandozeile unter Verwendung der Mustervergleichssyntax
expandiert.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
wordexp(3C) wordexp(3C)
Wort-Expansionen
Dies ist die Reihenfolge für die Wort-Expansionen:
1. Tilden-Expansion, Parameter-Expansion, Kommando-Substitution und
arithmetische Expansion werden vom Anfang bis zum Ende durchge-
führt.
2. Die Feldtrennung wird für die Teile der Felder durchgeführt, die
von Schritt 1 generiert werden, wenn IFS nicht Null ist.
3. Die Pfadnamen-Expansion wird durchgeführt, wenn set -f nicht wirk-
sam ist.
4. Die Entfernung der Anführungszeichen wird immer zuletzt durchge-
führt.
Wenn die vollständige Expansion für ein Wort als Ergebnis ein leeres
Feld hat, wird das leere Feld in der Liste mit den Feldern gelöscht,
die das vollständig expandierte Kommando bilden, wenn das ursprüngli-
che Wort keine Hochkommata oder Anführungszeichen enthielt.
Das Zeichen $ wird für die Parameter-Expansion, Kommando-Substitution
oder arithmetische Auswertung verwendet. Wenn auf ein nicht mit Anfüh-
rungszeichen versehenes Dollar-Zeichen ($) ein Zeichen folgt, das ent-
weder nicht numerisch, der Names eines der besonderen Parameter, das
gültige erste Zeichen eines Variablennamens, eine öffnende geschweifte
Klammer { oder eine öffnende Klammer ist, ist das Ergebnis nicht defi-
niert.
IFS wird für die Durchführung der Feldtrennung bei den Ergebnissen der
Parameter- und Kommando-Substitution verwendet. Es wird nicht für die
Trennung aller Felder verwendet. IFS wurde von früheren Versionen der
Shell für die Trennung aller Felder bei der Feldtrennung verwendet.
Dies führt allerdings zu schwerwiegenden Problemen, da die Shell die
eigene Shell-Prozedur nicht mehr analysieren kann. Außerdem hat dieses
Verhalten wesentliche Auswirkungen auf die Sicherheit. Alle sinnvollen
Anwendungen von IFS verwenden dieses Mittel für die Analyse der Ein-
gabe des Dienstprogramms read und für die Trennung der Ergebnisse
einer Parameter- und Kommando-Substitution.
Die Funktion wordexp() soll von einer Anwendung verwendet werden, die
die Expansionen der Shell für vom Benutzer eingegebene Worte durchfüh-
ren will. Wenn die Anwendung zum Beispiel zur Eingabe eines (oder meh-
rerer) Dateinamen auffordert und die Eingabe dann mit wordexp() bear-
beitet, kann der Benutzer mit allen Eingaben reagieren, die auch als
Eingabe für die Shell gültig sind.
Es liegt in der Verantwortung des Aufrufers, den Speicher, auf den
pwordexp zeigt, zuzuweisen. Die Funktion wordexp() weist weiteren
Platz je nach Bedarf zu (dies gilt auch für den Speicher, auf den
pwordexp->wewordv zeigt). Die Funktion wordfree() gibt den
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
wordexp(3C) wordexp(3C)
Speicherplatz frei, der pwordexp in einem vorherigen Aufruf von wor-
dexp() zugewiesen wurde.
Mit dem Argument flags wird das Verhalten von wordexp() gesteuert. Der
Wert von flags ist eine bitweise, inklusive ODER-Verknüpfung keiner
oder mehrerer der folgenden Konstanten, die in wordexp.h definiert
sind:
WRDEAPPEND Generierte Worte an die Worte eines vorherigen Aufrufs
von wordexp() anhängen.
WRDEDOOFFS Verwendung von pwordexp->weoffs. Wenn dieses Flag
gesetzt ist, wird mit pwordexp->weoffs angegeben, wie
viele Nullzeiger am Anfang von pwordexp->wewordv ein-
gefügt werden sollen. pwordexp->wewordv zeigt also
auf pwordexp->weoffs Nullzeiger, gefolgt von
pwordexp->wewordc Wort-Zeigern, gefolgt von einem
Nullzeiger.
WRDENOCMD Fehlschlag, wenn Kommando-Substitution angefordert
wird.
WRDEREUSE Das Argument pwordexp wurde an einen vorherigen,
erfolgreichen Aufruf von wordexp() übergeben, wurde
aber nicht an wordfree() übergeben. Das Ergebnis ist
das gleiche, als ob die Anwendung wordfree() und dann
wordexp() ohne WRDEREUSE aufgerufen hätte.
WRDESHOWERR stderr nicht zu /dev/null umleiten.
WRDEUNDEF Nach einem Versuch, eine undefinierte Shell-Variable
zu expandieren, soll ein Fehler gemeldet werden.
Mit dem Flag WRDEAPPEND kann eine neue Menge mit Worten an die durch
einen vorherigen Aufruf von wordexp() generierten Worte angehängt wer-
den. Die folgenden Regeln gelten, wenn zwei oder mehr Aufrufe von
wordexp() mit dem gleichen Wert für pwordexp und ohne zwischenzeitli-
che Aufrufe von wordfree() durchgeführt werden:
1. Im ersten Aufruf darf WRDEAPPEND nicht gesetzt werden. Bei allen
weiteren Aufrufen muß das Flag gesetzt sein.
2. WRDEDOOFFS muß entweder in allen anderen Aufrufen gesetzt oder
darf in keinem Aufruf gesetzt sein.
3. Nach dem zweiten und allen folgenden Aufrufen zeigt
pwordexp->wewordv auf eine Liste mit dem folgenden Inhalt:
- Keine oder mehr Nullzeiger, je nach WRDEDOOFFS und
pwordexp->weoffs.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
wordexp(3C) wordexp(3C)
- Zeiger auf die Worte, die vor dem Aufruf in der Liste
pwordexp->wewordv waren (Reihenfolge wie zuvor).
- Zeiger auf die neuen Worte, die vom letzten Aufruf generiert
wurden (in der angegebenen Reihenfolge).
4. Die in pwordexp->wewordc zurückgegebene Anzahl ist die Gesamtzahl
der Worte für alle Aufrufe.
5. Die Anwendung kann beliebige Felder nach einem Aufruf von wordexp()
verändern. In diesem Fall müssen die Felder vor einem weiteren Auf-
ruf von wordfree() oder wordexp() mit dem Flag WRDEAPPEND bzw.
WRDEREUSE, für den der gleiche Wert für pwordexp verwendet wird,
auf die ursprünglichen Werte zurückgesetzt werden.
Wenn words die folgenden Zeichen in einem entsprechenden Kontext ohne
Anführungszeichen enthält:
<newline> | & , < > ( ) { }
schlägt wordexp() fehl. Die Anzahl der expandierten Worte beträgt
Null.
Wenn WRDESHOWERR nicht in flags gesetzt ist, leitet wordexp() stderr
für alle Dienstprogramme nach /dev/null um, die als Ergebnis der
Kommando-Substitution bei der Wort-Expansion ausgeführt werden. Wenn
WRDESHOWERR gesetzt ist, kann wordexp() Meldungen nach stderr schrei-
ben, wenn bei der Expansion von words Syntaxfehler entdeckt werden.
Wenn WRDEDOOFFS gesetzt ist, muß pwordexp->weoffs für jeden Aufruf
von wordexp() und wordfree() mit einem bestimmten Argument.
Das Flag WRDENOCMD wird für Anwendungen zur Verfügung gestellt, die
aus Sicherheitsgründen oder aus anderen Gründen verhindern wollen, daß
ein Benutzer Shell-Kommandos ausführt. Das Verbot von Sonderzeichen
für die Shell ohne Anführungszeichen verhindert außerdem unerwünschte
Seiteneffekte wie die Ausführung eines Kommandos oder das Schreiben
für eine Datei.
Die folgenden Konstanten sind als Rückgabewerte für Fehler definiert:
WRDEBADCHAR Eines der folgenden Zeichen: <newline>, >, &, ;, <, >,
(, ), {, } erscheint in words in einem ungeeigneten
Kontext ohne Anführungszeichen.
WRDEBADVAL Bezug auf eine nicht definierte Shell-Variable, wenn
WRDEUNDEF in flags gesetzt ist.
WRDECMDSUB Kommando-Substitution erforderlich, wenn WRDENOCMD in
flags gesetzt ist.
WRDENOSPACE Ein Versuch der Speicherzuweisung schlug fehl.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
wordexp(3C) wordexp(3C)
WRDESYNTAX Shell-Syntaxfehler (zum Beispiel fehlende Klammer oder
nicht abgeschlossene Zeichenkette).
ERGEBNIS
Bei erfolgreicher Beendigung gibt wordexp() Null zurück.
Andernfalls wird ein Wert ungleich Null, wie er in wordexp.h beschrie-
ben ist, zurückgegeben. Dieser Wert zeigt einen Fehler an. Wenn
wordexp() den Wert WRDENOSPACE zurückgibt, werden pwordexp->wewordc
und pwordexp->wewordv aktualisiert. Sie geben dann die Worte an, die
erfolgreich expandiert wurden. In anderen Fällen werden sie nicht
modifiziert.
Die Funktion wordfree() gibt keinen Wert zurück.
SIEHE AUCH
fnmatch(3C), glob(3C), wordexp(5).
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98