<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 0bfb0eb957e0468912af86bba09fae588010c1df Maintainer: khp Status: ready -->

<!-- Reviewed: yes -->

<!-- Rev-Revision: 1.0 Reviewer: samesch -->

<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>flock</refname>

<refpurpose>Portables Datei-Sperrverfahren (advisory locking)</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>bool</type><methodname>flock</methodname>

<methodparam><type>resource</type><parameter>stream</parameter></methodparam>

<methodparam><type>int</type><parameter>operation</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter role="reference">would_block</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<para>

<function>flock</function> erlaubt, ein einfaches Leser-/Schreiber-Modell

umzusetzen, was auf nahezu jeder Plattform (inklusive der meisten

Unix-Abkömmlinge und sogar Windows) genutzt werden kann.

</para>

<para>

Die Sperre wird auch von <function>fclose</function> gelöst oder wenn

<parameter>stream</parameter> vom Garbage-Collector eingesammelt wird.

</para>

<para>

PHP unterstützt ein portables Verfahren, um komplette Dateien "beratend" zu

sperren (was bedeutet, dass alle zugreifenden Programme das gleiche

Sperrverfahren nutzen müssen, oder die Sperre wird nicht wirken).

Standardmäßig wird diese Funktion blockieren, bis die angefragte Sperre

erlangt wurde; dies kann mit der unten dokumentierten Option

<constant>LOCK_NB</constant> gesteuert werden.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>stream</parameter></term>

<listitem>

&fs.file.pointer;

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>operation</parameter></term>

<listitem>

<para>

<parameter>operation</parameter> ist einer der folgenden Werte:

<itemizedlist>

<listitem>

<simpara>

<constant>LOCK_SH</constant>, um eine geteilte Sperre (Leser) zu

erhalten.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>LOCK_EX</constant>, um eine exklusive Sperre (Schreiber) zu

erhalten.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>LOCK_UN</constant>, um eine Sperre zu lösen (geteilt oder

exklusiv).

</simpara>

</listitem>

</itemizedlist>

</para>

<para>

Man kann auch <constant>LOCK_NB</constant> als Bitmaske zu einer der

obigen Operationen hinzufügen, wenn <function>flock</function> während

des Sperrversuchs nicht blockieren soll.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>would_block</parameter></term>

<listitem>

<para>

Das optionale dritte Argument wird auf 1 gesetzt, falls die Sperre

blockieren würde (EWOULDBLOCK-Fehlernummer).

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.success;

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>flock</function>-Beispiel</title>

<programlisting role="php">

<![CDATA[

<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) { // exklusive Sperre

ftruncate($fp, 0); // kürze Datei

fwrite($fp, "Schreibe hier irgendwas\n");

fflush($fp); // leere Ausgabepuffer, bevor die Sperre aufgehoben wird

flock($fp, LOCK_UN); // hebe Sperre auf

} else {

echo "Konnte Sperre nicht erhalten!";

}

fclose($fp);

?>

]]>

</programlisting>

</example>

</para>

<para>

<example>

<title><function>flock</function> mit der Option <constant>LOCK_NB</constant></title>

<programlisting role="php">

<![CDATA[

<?php

$fp = fopen('/tmp/lock.txt', 'r+');

/* Aktiviere die LOCK_NB-Option bei einer LOCK_EX-Operation */

if(!flock($fp, LOCK_EX | LOCK_NB)) {

echo 'Kann Sperre nicht erhalten';

exit(-1);

}

/* ... */

fclose($fp);

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

<function>flock</function> nutzt unter Windows "verbindliche" (mandatory)

anstatt "beratende" (advisory) Sperren. "Verbindliches" Sperren wird

auch unter Linux und System-V-basierten Betriebssystemen durch den

üblichen Mechanismus, der von dem fcntl()-Systemaufruf geliefert wird,

unterstützt: das heißt, falls bei der fraglichen Datei das

setgid-Zugriffs-Bit gesetzt ist und das Ausführungs-Bit für Gruppen

null ist. Unter Linux muss das Dateisystem zusätzlich mit der Mount-Option

mand eingebunden sein, damit dies Auswirkungen hat.

</para>

</note>

<note>

<para>

Da <function>flock</function> einen Dateizeiger benötigt, muss unter

Umständen eine spezielle Sperrdatei benutzt werden, um den Zugriff auf

eine Datei zu schützen, welche Sie mittels Öffnen im Schreibmodus (mit

dem Argument "w" or "w+" von <function>fopen</function>) kürzen wollen.

</para>

</note>

<note>

<para>

Kann nur mit Dateizeigern verwendet werden, die von

<function>fopen</function> für lokale Dateien zurückgegeben wurden, oder

mit Dateizeigern, die auf Userspace-Streams zeigen, die die

<function>streamWrapper::stream_lock</function>-Methode implementieren.

</para>

</note>

<warning>

<para>

Weist man dem <parameter>stream</parameter>-Argument einen anderen Wert

zu, wird nachfolgender Code die Sperre lösen.

</para>

</warning>

<warning>

<para>

Bei einigen Betriebssystemen ist <function>flock</function> auf dem

Prozesslevel implementiert. Wenn Sie eine Multithreaded-Server-API

benutzen, können Sie sich nicht auf <function>flock</function>

verlassen, um Dateien vor anderen PHP-Skripten zu schützen, welche in

parallelen Threads der gleichen Server-Instanz laufen!

</para>

<para>

<function>flock</function> wird von antiquierten Dateisystemen wie

<literal>FAT</literal> und dessen Derivaten nicht unterstützt, und gibt

deshalb in solchen Umgebungen immer &false; zurück.

</para>

</warning>

<note>

<para>

Wenn der sperrende Prozess unter Windows die Datei ein zweites Mal öffnet,

kann er auf die Datei über dieses zweite Handle zugreifen, bis er die

Datei entsperrt.

</para>

</note>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->