Switch ref.xattr to the new structure

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@176306 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2005-01-02 16:49:45 +00:00
parent 43ae92eaed
commit 88400e3671
6 changed files with 472 additions and 298 deletions

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<section id="xattr.constants">
&reftitle.constants;
&extension.constants;
@ -11,7 +11,7 @@
</term>
<listitem>
<simpara>
Set attribute in root (trusted) namespace. Requires root privileges.
</simpara>
</listitem>
</varlistentry>
@ -22,7 +22,7 @@
</term>
<listitem>
<simpara>
Do not follow the symbolic link but operate on symbolic link itself.
</simpara>
</listitem>
</varlistentry>
@ -33,7 +33,7 @@
</term>
<listitem>
<simpara>
Function will fail if extended attribute already exists.
</simpara>
</listitem>
</varlistentry>
@ -44,7 +44,7 @@
</term>
<listitem>
<simpara>
Function will fail if extended attribute doesn't exist.
</simpara>
</listitem>
</varlistentry>

View file

@ -1,57 +1,84 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry id="function.xattr-get">
<refnamediv>
<refname>xattr_get</refname>
<refpurpose>
Get an extended attribute
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>xattr_get</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function gets a value of an extended attribute named <parameter>name</parameter>
of a file <parameter>path</parameter>.
</para>
<para>
Extended attributes have two different namespaces: user and root namespace.
User namespace is available for all users while root namespace is available
only for user with root privileges. xattr operates on user namespace by default,
but you can change that using <parameter>flags</parameter> argument.
</para>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry>XATTR_DONTFOLLOW</entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry>XATTR_ROOT</entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Returns <type>string</type> with value or &false; if attribute doesn't exist.
</para>
<example>
<title><function>xattr_get</function> example</title>
<para>
The following code checks if system administrator has signed the file.
</para>
<programlisting role="php">
<refentry id="function.xattr-get">
<refnamediv>
<refname>xattr_get</refname>
<refpurpose>
Get an extended attribute
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>xattr_get</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function gets the value of an extended attribute of a file.
</para>
&xattr.namespace;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The file from which we get the attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The name of the attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>XATTR_DONTFOLLOW</constant></entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry><constant>XATTR_ROOT</constant></entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string containing the value or &false; if the attribute doesn't
exist.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Checks if system administrator has signed the file</title>
<programlisting role="php">
<![CDATA[
<?php
$file = '/usr/local/sbin/some_binary';
@ -61,14 +88,21 @@ $signature = xattr_get($file, 'Root signature', XATTR_ROOT);
?>
]]>
</programlisting>
</example>
<para>
See also <function>xattr_set</function>, <function>xattr_remove</function>,
<function>xattr_list</function>, <function>xattr_supported</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>xattr_list</function></member>
<member><function>xattr_set</function></member>
<member><function>xattr_remove</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
@ -89,4 +123,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

View file

@ -1,56 +1,74 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry id="function.xattr-list">
<refnamediv>
<refname>xattr_list</refname>
<refpurpose>
Get a list of extended attributes
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>xattr_list</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This functions gets a list of names of extended attributes of a file
<parameter>path</parameter>.
</para>
<para>
Extended attributes have two different namespaces: user and root namespace.
User namespace is available for all users while root namespace is available
only for user with root privileges. xattr operates on user namespace by default,
but you can change that using <parameter>flags</parameter> argument.
</para>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry>XATTR_DONTFOLLOW</entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry>XATTR_ROOT</entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
This function returns <type>array</type> with names of extended attributes.
</para>
<example>
<title><function>xattr_list</function> example</title>
<para>
The following code prints names of all extended attributes of file.
</para>
<programlisting role="php">
<refentry id="function.xattr-list">
<refnamediv>
<refname>xattr_list</refname>
<refpurpose>
Get a list of extended attributes
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>xattr_list</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This functions gets a list of names of extended attributes of a file.
</para>
&xattr.namespace;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The path of the file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>XATTR_DONTFOLLOW</constant></entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry><constant>XATTR_ROOT</constant></entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array with names of extended attributes.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Prints names of all extended attributes of file</title>
<programlisting role="php">
<![CDATA[
<?php
$file = 'some_file';
@ -69,14 +87,19 @@ foreach ($attributes as $attr_name) {
?>
]]>
</programlisting>
</example>
<para>
See also <function>xattr_get</function>, <function>xattr_set</function>,
<function>xattr_remove</function>, <function>xattr_supported</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>xattr_get</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
@ -97,4 +120,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

View file

@ -1,57 +1,83 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry id="function.xattr-remove">
<refnamediv>
<refname>xattr_remove</refname>
<refpurpose>
Remove an extended attribute
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>xattr_remove</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function removes an extended attribute named <parameter>name</parameter>
of a file <parameter>path</parameter>.
</para>
<para>
Extended attributes have two different namespaces: user and root namespace.
User namespace is available for all users while root namespace is available
only for user with root privileges. xattr operates on user namespace by default,
but you can change that using <parameter>flags</parameter> argument.
</para>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry>XATTR_DONTFOLLOW</entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry>XATTR_ROOT</entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
&return.success;
</para>
<example>
<title><function>xattr_remove</function> example</title>
<para>
The following code removes all extended attributes of file.
</para>
<programlisting role="php">
<refentry id="function.xattr-remove">
<refnamediv>
<refname>xattr_remove</refname>
<refpurpose>
Remove an extended attribute
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>xattr_remove</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function removes an extended attribute of a file.
</para>
&xattr.namespace;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The file from which we remove the attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The name of the attribute to remove.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>XATTR_DONTFOLLOW</constant></entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry><constant>XATTR_ROOT</constant></entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Removes all extended attributes of a file</title>
<programlisting role="php">
<![CDATA[
<?php
$file = 'some_file';
@ -62,14 +88,21 @@ foreach ($attributes as $attr_name) {
}
?>
]]>
</programlisting>
</example>
<para>
See also <function>xattr_get</function>, <function>xattr_set</function>,
<function>xattr_list</function>, <function>xattr_supported</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>xattr_list</function></member>
<member><function>xattr_set</function></member>
<member><function>xattr_get</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
@ -90,4 +123,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

View file

@ -1,69 +1,102 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry id="function.xattr-set">
<refnamediv>
<refname>xattr_set</refname>
<refpurpose>
Set an extended attribute
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>xattr_set</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam><type>string</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function sets value of an extended attribute named <parameter>name</parameter>
to <parameter>value</parameter> of a file <parameter>path</parameter>.
Extended attribute will be created if it doesn't exist or replaced
otherwise. You can change this behaviour by using <parameter>flags</parameter>
parameter.
</para>
<para>
Extended attributes have two different namespaces: user and root namespace.
User namespace is available for all users while root namespace is available
only for user with root privileges. xattr operates on user namespace by default,
but you can change that using <parameter>flags</parameter> argument.
</para>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry>XATTR_CREATE</entry>
<entry>Function will fail if extended attribute already exists.</entry>
</row>
<row>
<entry>XATTR_REPLACE</entry>
<entry>Function will fail if extended attribute doesn't exist.</entry>
</row>
<row>
<entry>XATTR_DONTFOLLOW</entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry>XATTR_ROOT</entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
&return.success;
</para>
<example>
<title><function>xattr_set</function> example</title>
<para>
The following code sets extended attributes on .wav file.
</para>
<programlisting role="php">
<refentry id="function.xattr-set">
<refnamediv>
<refname>xattr_set</refname>
<refpurpose>
Set an extended attribute
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>xattr_set</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam><type>string</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function sets the value of an extended attribute of a file.
</para>
&xattr.namespace;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The file in which we set the attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The name of the exteded attribute. This attribute will be created if
it doesn't exist or replaced otherwise. You can change this behaviour
by using the <parameter>flags</parameter> parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value of the attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>XATTR_CREATE</constant></entry>
<entry>Function will fail if extended attribute already exists.</entry>
</row>
<row>
<entry><constant>XATTR_REPLACE</constant></entry>
<entry>Function will fail if extended attribute doesn't exist.</entry>
</row>
<row>
<entry><constant>XATTR_DONTFOLLOW</constant></entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
<row>
<entry><constant>XATTR_ROOT</constant></entry>
<entry>Set attribute in root (trusted) namespace. Requires root privileges.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Sets extended attributes on .wav file</title>
<programlisting role="php">
<![CDATA[
<?php
$file = 'my_favourite_song.wav';
@ -76,14 +109,20 @@ xattr_set($file, 'Listen count', '34');
printf("You've played this song %d times", xattr_get($file, 'Listen count'));
?>
]]>
</programlisting>
</example>
<para>
See also <function>xattr_get</function>, <function>xattr_remove</function>,
<function>xattr_list</function>, <function>xattr_supported</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>xattr_get</function></member>
<member><function>xattr_remove</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
@ -104,4 +143,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

View file

@ -1,36 +1,75 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry id="function.xattr-supported">
<refnamediv>
<refname>xattr_supported</refname>
<refpurpose>
Check if filesystem supports extended attributes
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>xattr_supported</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<refentry id="function.xattr-supported">
<refnamediv>
<refname>xattr_supported</refname>
<refpurpose>
Check if filesystem supports extended attributes
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>xattr_supported</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This functions checks if the filesystem holding the given file supports
extended attributes. Read access to the file is required.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The path of the tested file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<table>
<title>Supported xattr flags</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>XATTR_DONTFOLLOW</constant></entry>
<entry>Do not follow the symbolic link but operate on symbolic link itself.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns &true; if filesystem supports extended attributes,
&false; if it doesn't and &null; if it can't be determined (for example
wrong path or lack of permissions to file).
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>xattr_supported</function> example</title>
<para>
This functions checks if filesystem holding file <parameter>path</parameter>
supports extended attributes. Read access to file <parameter>path</parameter>
is required.
The following code checks if we can use extended attributes.
</para>
<para>
This function returns &true; if filesystem supports extended attributes,
&false; if it doesn't and &null; if it can't be determined (for example
wrong path or lack of permissions to file).
</para>
<example>
<title><function>xattr_supported</function> example</title>
<para>
The following code checks if we can use extended attributes.
</para>
<programlisting role="php">
<programlisting role="php">
<![CDATA[
<?php
$file = 'some_file';
@ -41,14 +80,20 @@ if (xattr_supported($file)) {
?>
]]>
</programlisting>
</example>
<para>
See also <function>xattr_get</function>, <function>xattr_set</function>,
<function>xattr_remove</function>, <function>xattr_list</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>xattr_get</function></member>
<member><function>xattr_list</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
@ -69,4 +114,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->