fcntl(2) fcntl(2)
NAME
fcntl - Geöffnete Datei steuern
SYNTAX
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl(int fildes, int cmd, ... /* arg */);
BESCHREIBUNG
fcntl() ermöglicht die Steuerung von offenen Dateien. fildes ist ein
Dateideskriptor einer geöffneten Datei.
An fcntl() kann ein drittes Argument übergeben werden, dessen Datentyp
und Wert vom übergebenen Kommando cmd abhängen. cmd spezifiziert die
Operation, die von fcntl() ausgeführt wird, und kann einer der folgen-
den Werte sein:
FDUPFD Ein neuer Dateideskriptor wird wie folgt zurückgegeben:
- Dateideskriptor mit der niedrigsten verfügbaren Nummer,
die größer als oder gleich dem ganzzahligen Wert ist,
der als drittes Argument übergeben wird,
- dieselbe offene Datei (oder Pipe) wie die ursprüngliche
Datei,
- derselbe Schreib-/Lesezeiger wie der der ursprünglichen
Datei (d. h. beide Dateideskriptoren teilen sich den-
selben Schreib-/Lesezeiger),
- derselbe Zugriffsmodus (Lesen, Schreiben oder
Lesen/Schreiben) wie die ursprüngliche Datei,
- dieselben Dateistatus-Bits wie die ursprüngliche Datei,
- das Bit "Schließen-bei-exec" (siehe FGETFD), das zum
neuen Dateideskriptor gehört, so setzen, daß die Datei
bei exec(2)-Aufrufen geöffnet bleibt.
FGETFD Ruft das Flag "Schließen-bei-exec" ab, das zu dem Dateide-
skriptor fildes gehört. Wenn das niederwertige Bit 0 ist,
bleibt die Datei bei exec offen, andernfalls wird die
Datei bei Aufruf von exec geschlossen.
FSETFD Setzt das zu fildes gehörende Flag "Schließen-bei-exec"
auf das niederwertige Bit des ganzzahligen Wertes, der als
drittes Argument übergeben wird (0 oder 1 wie oben).
FGETFL Ruft das Dateistatus-Flag für fildes ab.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
FSETFL Setzt das Dateistatus-Flag für fildes auf den ganzzahligen
Wert, der als drittes Argument übergeben wird. Nur
bestimmte Bits können gesetzt werden [siehe fcntl(5)].
FFREESP Gibt Speicherplatz, der mit einem Abschnitt der regulären
fildes-Datei verbunden ist, frei. Dieser Abschnitt wird
von einer Variablen des Datentyps struct flock, auf die
das dritte Argument arg zeigt, spezifiziert. Der Datentyp
struct flock ist in der Include-Datei fcntl.h definiert
[siehe fcntl(5)] und beinhaltet folgende Mitglieder:
lwhence ist 0, 1 oder 2, um anzuzeigen, daß der relative
Offset lstart vom Anfang der Datei, von der momentanen
Position, oder vom Ende der Datei gemessen wird. lstart
ist der Offset von der Position aus, die in lwhence spe-
zifiziert wird. llen ist die Länge dieses Abschnitts.
Eine Länge von 0 gibt bis zum Ende der Datei alles frei;
in diesem Fall wird das Ende der Datei auf den Anfang des
freigegebenen Teils gesetzt. Auf die Daten, die vorher in
diesen Teil geschrieben wurden, kann nicht mehr zugegrif-
fen werden.
Die folgenden Kommandos werden für Dateisperren und Datensatzsperren
benutzt. Sperren können auf eine ganze Datei oder auf Segmente einer
Datei gelegt werden.
FSETLK Eine Sperre in einem der Dateisegmente ist entsprechend
der Variablen des Typs struct flock, auf die arg zeigt, zu
setzen oder zu löschen [siehe fcntl(5)]. Die Aktion
FSETLK wird zum Einrichten der Lesesperre (FRDLCK) und
der Schreibsperre (FWRLCK) sowie für die Aufhebung beider
Sperrtypen (FUNLCK) verwendet. Läßt sich eine Lese- oder
Schreibsperre nicht setzen, gibt fcntl() sofort den Feh-
lerwert -1 zurück.
FSETLKW Dieses cmd ist dasselbe wie FSETLK, außer daß der Prozeß
schläft, bis das Segment frei zum Sperren ist, wenn die
Sperranforderung durch andere Sperren blockiert wird.
FGETLK Wenn die durch die flock-Struktur angegebene Sperranforde-
rung, auf die arg zeigt, erzeugt werden könnte, wird diese
Struktur unverändert zurückgegeben, außer daß der Sperrtyp
auf FUNLCK und das Feld lwhence auf SEEKSET gesetzt
wird. Wird eine Sperre gefunden, die eine Erzeugung dieser
Sperre verhindern würde, dann wird die Struktur mit der
Beschreibung der ersten Sperre überschrieben.
Dieses Kommando erzeugt niemals eine Sperre; es testet
nur, ob einzelne Sperren eingerichtet werden könnten.
FRSETLK Dieses Kommando wird vom Netzwerkdämon lockd benutzt, um
mit dem NFS-Server NFS-Dateien zu sperren.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
FRSETLKW Dieses Kommando wird vom Netzwerkdämon lockd benutzt, um
mit dem NFS-Server NFS-Dateien zu sperren.
FRGETLK Dieses Kommando wird vom Netzwerkdämon lockd benutzt, um
mit dem NFS-Server NFS-Dateien zu sperren.
Eine Lesesperre verhindert, daß ein Prozeß den geschützten Bereich mit
einer Schreibsperre belegen kann. Für ein bestimmtes Segment einer
Datei kann zu einem Zeitpunkt mehr als eine Lesesperre vorhanden sein.
Der Dateideskriptor, auf den die Lesesperre gesetzt wird, muß mit der
Leseerlaubnis geöffnet worden sein.
Eine Schreibsperre verhindert, daß ein Prozeß den geschützten Bereich
mit einer Schreib- oder eine Lesesperre belegt. Für ein bestimmtes
Segment einer Datei kann zu einem gegebenen Zeitpunkt jeweils nur eine
Schreib- oder Lesesperre vorliegen. Der Dateideskriptor, auf den eine
Schreibsperre gesetzt wird, muß mit Schreiberlaubnis geöffnet worden
sein.
Die Struktur flock beschreibt Typ (ltype), Startpunkt-Offset
(lwhence), relativen Offset (lstart), Größe (llen), Prozeßnummer
(lpid) und Systemnummer (lsysid) des betroffenen Segments in der
Datei.
Der Wert von lwhence ist entweder SEEKSET, SEEKCUR oder SEEKEND,
je nachdem, ob der relative Offset lstart Byte vom Anfang der Datei,
der aktuellen Position oder dem Ende der Datei gerechnet wird. Der
Wert von llen entspricht der Anzahl der aufeinanderfolgenden Bytes,
die gesperrt werden sollen. Der Wert von llen kann negativ sein (wenn
die Definition von offt negative Werte für llen zuläßt). Das Feld
lpid wird nur für FGETLK verwendet, um die Prozeßnummer des Prozes-
ses zurückzugeben, der ein blockierende Sperre enthält. Nach einer
erfolgreichen FGETLK-Anforderung, wenn also eine Sperre gefunden
wurde, ist der Wert von lwhence SEEKSET.
Wenn llen positiv ist, beginnt der entsprechende Bereich bei lstart
und endet bei lstart + llen-1. Wenn llen negativ ist, beginnt der
entsprechende Bereich bei lstart + llen und endet bei lstart-1.
Sperren können jenseits des aktuellen Dateiendes beginnen und auch
darüber hinausgehen, dürfen aber in Bezug auf den Dateianfang nicht
negativ sein. Eine Sperre erstreckt sich auf den größtmöglichen Wert
des Datei-Offsets für diese Datei, wenn llen auf 0 gesetzt ist. Wenn
für eine solche Sperre lstart auch auf 0 gesetzt ist und lwhence auf
SEEKSET gesetzt ist, ist die gesamte Datei gesperrt.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
Für jedes Byte der Datei wird maximal ein Sperren-Typ gesetzt. Wenn
der aufrufende Prozeß bereits Sperren für Bytes in dem Bereich hat,
der durch die Anforderung angegeben ist, wird vor einer erfolgreichen
Rückkehr von einer FSETLK- oder einer FSETLKW-Anforderung der vor-
herige Sperren-Typ für jedes Byte in dem angegebenen Bereich durch den
neuen Sperren-Typ ersetzt. Wie weiter oben unter der Beschreibung von
gemeinsamen Sperren und exklusiven Sperren angegeben ist, schlägt eine
FSETLK- bzw. eine FSETLKW-Anforderung fehl oder blockiert, wenn für
einen anderen Prozeß Sperren für Bytes in dem angegebenen Bereich vor-
handen sind und der Typ einer dieser Sperren nicht mit dem Typ in der
Anforderung zusammenpaßt.
Alle Sperren, die einer Datei für einen bestimmten Prozeß zugeordnet
sind, werden gelöscht, wenn der Dateideskriptor für diese Datei durch
diesen Prozeß geschlossen wird oder der Prozeß, der den Dateideskrip-
tor enthält, beendet wird. Sperren werden von einem Sohnprozeß, der
mit der Funktion fork() erzeugt wurde, nicht geerbt.
Es besteht die Gefahr eines Deadlocks, wenn ein Prozeß, der einen
gesperrten Bereich steuert, zeitweise stillgelegt wird, indem versucht
wird, den gesperrten Bereich eines anderen Prozesses zu sperren. Wenn
das System entdeckt, daß das Stillegen eines Prozesses bis zur Frei-
gabe eines gesperrten Bereichs dazu führen würde, daß sich das Pro-
gramm aufhängt, so schlägt die Funktion fcntl() fehl und gibt den Feh-
ler EDEADLK zurück.
Wenn obligatorisches Sperren von Dateien und Dateisätzen in einer
Datei aktiv ist [siehe chmod(2)], werden open(2)-, read(2)- und
write(2)-Systemaufrufe auf die Datei durch die eingeschalteten Datei-
satzsperren beeinflußt.
Eine Anforderung zum Aufheben einer Sperre (FUNLCK), in der llen
ungleich Null ist, und der Offset des letzten Byte des angeforderten
Segments dem Maximalwert für ein Objekt des Typs offt entspricht,
wird als Anforderung zum Aufheben einer Sperre vom Anfang des angefor-
derten Segments mit einer llen gleich 0 behandelt, wenn der Prozeß
eine vorhandene Sperre aufweist, in der llen gleich 0 ist, und die
das letzte Byte des angeforderten Segments enthält. Andernfalls ver-
sucht eine Anforderung FUNLCK nur die Sperre für das angeforderte
Segment aufzuheben.
Der folgende zusätzliche Wert kann beim Erstellen von oflag verwendet
werden:
OLARGEFILE
Falls dieser Wert gesetzt ist, ist das in der internen Beschrei-
bung der offenen Datei festgelegte Offset-Maximum der höchste
Wert, der in einem Objekt des Typs off64t korrekt dargestellt
werden kann.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
Das Flag OLARGEFILE kann mit FSETFL aktiviert oder deaktiviert wer-
den. Bei einem nicht korrekt geschriebenen Programm kann dieses Flag
versehentlich gelöscht werden. Einige Programme versetzen eine Datei
zum Beispiel wie folgt in den Anhängemodus (append mode):
fcntl(fd, FSETFL, OAPPEND);
Dies ist nicht die korrekte Vorgehensweise, da auch alle anderen offe-
nen Flags, einschließlich OLARGEFILE deaktiviert werden. Statt dessen
muß zum Einstellen des Anhängemodus zuerst FGETFL verwendet werden,
um die aktuellen Flags auszugeben:
int oflag = fcntl(fd, FGETFL, 0);
anschließend muß OAPPEND in die Flags aufgenommen werden:
oflag |= OAPPEND;
und dann müssen die neuen Flags gesetzt werden:
fcntl(fd, FSETFL, oflag);
Ein vollständiges Programmbeispiel würde auch die Überprüfung auf
fcntl()-Fehler hin einschließen.
Das Verhalten der folgenden zusätzlichen Werte entspricht dem des
jeweiligen Werts der Single UNIX Specification (SUS) (FGETLK, FSETLK,
FSETLKW), mit der Ausnahme, daß hier ein Argument struct flock64
anstelle eines Arguments struct flock erforderlich ist.
FGETLK64
FSETLK64
FSETLKW64
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
fcntl() ist erfolglos, wenn einer oder mehrere der nachstehenden
Punkte zutreffen:
EACCES cmd ist FSETLK, der Typ der Sperre (ltype) ist eine
Lesesperre (FRDLCK), und das Segment einer zu sperrenden
Datei ist bereits von einem anderen Prozeß schreibge-
sperrt.
EACCES Der Typ ist eine Schreibsperre (FWRLCK), und das Segment
einer zu sperrenden Datei wird bereits von einem anderen
Prozeß lese- oder schreibgesperrt.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
EAGAIN cmd ist FFREESP, die Datei existiert, obligatorisches
Datei-/Datensatzsperren ist gesetzt, und es gibt noch aus-
stehende Datensatzsperren in der Datei.
EAGAIN cmd ist FSETLK oder FSETLKW, und die Datei wird momentan
mit mmap [siehe mmap(2)] in den virtuellen Speicher abge-
bildet.
EBADF fildes ist kein gültiger offener Dateideskriptor.
EBADF cmd ist FSETLK oder SETLKW, die Sperre (ltype) ist eine
Lesesperre (FRDLCK), und fildes ist kein gültiger, zum
Lesen geöffneter Dateideskriptor.
EBADF cmd ist FSETLK oder SETLKW, die Sperre (ltype) ist eine
Schreibsperre (FWRLCK), und fildes ist kein gültiger, zum
Schreiben geöffneter Dateideskriptor.
EBADF cmd ist FFREESP, und fildes ist kein gültiger, zum
Schreiben geöffneter Dateideskriptor.
EDEADLK cmd ist FSETLKW, die Sperre ist durch eine Sperre von
einem anderen Prozeß blockiert, und ein Deadlock würde
verursacht, wenn der Prozeß schlafend gesetzt wird, um auf
die Aufhebung dieser Sperre zu warten.
EDEADLK cmd ist FFREESP, obligatorisches Datensatzsperren ist
möglich, ONDELAY und ONONBLOCK sind gelöscht, und es
wurde eine Situation entdeckt, in der es zu einem Deadlock
kommen könnte.
EFAULT cmd ist FFREESP, und der Wert, auf den arg zeigt, befin-
det sich in einer Adresse außerhalb des Adreßraums, der
vom Prozeß belegt wird.
EFAULT cmd ist FGETLK, FSETLK oder FSETLKW und der Wert, auf
den arg zeigt, befindet sich in einer Adresse außerhalb
des Adreßraums, der vom Prozeß belegt wird.
EINTR Ein Signal wurde während des Systemaufrufs fcntl() abge-
fangen.
EIO Während des Lesens oder Schreibens vom Dateisystem trat
ein Ein-/Ausgabefehler auf.
EMFILE cmd ist FDUPFD, und im aufrufenden Prozeß ist die Anzahl
der offenen Dateideskriptoren gleich dem in der Konfigura-
tion angegebenen Maximalwert der offenen Dateien für jeden
Benutzer.
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
EINVAL cmd ist FDUPFD. arg ist entweder negativ, größer oder
gleich dem Wert für die maximale Anzahl der jedem Benutzer
zur Verfügung stehenden offenen Dateideskriptoren.
EINVAL cmd besitzt keinen gültigen Wert.
EINVAL cmd ist FGETLK, FSETLK oder SETLKW, und arg oder die
Daten, auf die verwiesen wird, sind nicht gültig; oder
fildes gibt eine Datei an, die Sperren nicht unterstützt.
ENOLCK cmd ist FSETLK oder FSETLKW, der Typ der Sperre ist eine
Lese- oder Schreibsperre, und keine weiteren Dateisatz-
sperren stehen zur Verfügung (zuviele Dateisegmente
gesperrt), weil das Maximum des Systems überschritten
wurde.
ENOLINK fildes ist auf einem fernen Rechner, und die Verbindung zu
diesem Rechner ist nicht mehr aktiv.
ENOLINK cmd ist FFREESP, die Datei ist auf einem fernen Rechner,
und die Verbindung zu diesem Rechner ist nicht mehr aktiv.
EOVERFLOW Einer der zurückzugebenden Werte kann nicht korrekt darge-
stellt werden.
EOVERFLOW Das Argument cmd ist FGETLK, FSETLK oder FSETLKW und
der kleinste oder, wenn llen ungleich Null ist, der
größte Offset jedes Byte im angeforderten Segment kann in
einem Objekt des Typs offt nicht korrekt dargestellt wer-
den.
ERGEBNIS
Nach erfolgreicher Beendigung hängt der jeweils zurückgegebene Wert
wie folgt von cmd ab:
FDUPFD Ein neuer Dateideskriptor.
FGETFD Wert des Status-Flag für "Schließen-bei-exec" (nur das
niederwertige Bit wird definiert).
FSETFD Wert, der nicht -1 ist.
FFREESP Wert 0.
FGETFL Wert des Dateistatus-Bits, nie negativ.
FSETFL Wert, der nicht -1 ist.
FGETLK Wert, der nicht -1 ist.
FSETLK Wert, der nicht -1 ist.
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
fcntl(2) fcntl(2)
FSETLKW Wert, der nicht -1 ist.
Bei einem Fehler wird -1 zurückgegeben, und errno wird zur Anzeige des
Fehlers gesetzt.
HINWEISE
Da die Variable errno in Zukunft auf EAGAIN und nicht auf EACCES
gesetzt wird, wenn ein Teil einer Datei bereits von einem anderen Pro-
zeß gesperrt ist, sollten portable Anwenderprogramme beide Werte
erwarten und beide Werte prüfen.
SIEHE AUCH
close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2),
unistd(4), fcntl(5), lfs(5), types(5).
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98