<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Set an extended attribute</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.xattr-remove.html">xattr_remove</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.xattr-supported.html">xattr_supported</a></div>
<div class="up"><a href="ref.xattr.html">xattr Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.xattr-set" class="refentry">
<div class="refnamediv">
<h1 class="refname">xattr_set</h1>
<p class="verinfo">(PECL xattr >= 0.9.0)</p><p class="refpurpose"><span class="refname">xattr_set</span> — <span class="dc-title">
Set an extended attribute
</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.xattr-set-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>xattr_set</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$filename</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$name</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$value</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$flags</code><span class="initializer"> = 0</span></span>
] )</div>
<p class="para rdfs-comment">
This function sets the value of an extended attribute of a file.
</p>
<p class="para">Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace by default, but this can be changed with the
<em><code class="parameter">flags</code></em> parameter.</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.xattr-set-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">filename</code></em></span>
<dd>
<p class="para">
The file in which we set the attribute.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">name</code></em></span>
<dd>
<p class="para">
The name of the extended attribute. This attribute will be created if
it doesn't exist or replaced otherwise. You can change this behaviour
by using the <em><code class="parameter">flags</code></em> parameter.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">value</code></em></span>
<dd>
<p class="para">
The value of the attribute.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">flags</code></em></span>
<dd>
<p class="para">
<table class="doctable table">
<caption><strong>Supported xattr flags</strong></caption>
<tbody class="tbody">
<tr>
<td><strong><code>XATTR_CREATE</code></strong></td>
<td>Function will fail if extended attribute already exists.</td>
</tr>
<tr>
<td><strong><code>XATTR_REPLACE</code></strong></td>
<td>Function will fail if extended attribute doesn't exist.</td>
</tr>
<tr>
<td><strong><code>XATTR_DONTFOLLOW</code></strong></td>
<td>Do not follow the symbolic link but operate on symbolic link itself.</td>
</tr>
<tr>
<td><strong><code>XATTR_ROOT</code></strong></td>
<td>Set attribute in root (trusted) namespace. Requires root privileges.</td>
</tr>
</tbody>
</table>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.xattr-set-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.xattr-set-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-2447">
<p><strong>Example #1 Sets extended attributes on <var class="filename">.wav</var> file</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$file </span><span style="color: #007700">= </span><span style="color: #DD0000">'my_favourite_song.wav'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">xattr_set</span><span style="color: #007700">(</span><span style="color: #0000BB">$file</span><span style="color: #007700">, </span><span style="color: #DD0000">'Artist'</span><span style="color: #007700">, </span><span style="color: #DD0000">'Someone'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">xattr_set</span><span style="color: #007700">(</span><span style="color: #0000BB">$file</span><span style="color: #007700">, </span><span style="color: #DD0000">'My ranking'</span><span style="color: #007700">, </span><span style="color: #DD0000">'Good'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">xattr_set</span><span style="color: #007700">(</span><span style="color: #0000BB">$file</span><span style="color: #007700">, </span><span style="color: #DD0000">'Listen count'</span><span style="color: #007700">, </span><span style="color: #DD0000">'34'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* ... other code ... */<br /><br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"You've played this song %d times"</span><span style="color: #007700">, </span><span style="color: #0000BB">xattr_get</span><span style="color: #007700">(</span><span style="color: #0000BB">$file</span><span style="color: #007700">, </span><span style="color: #DD0000">'Listen count'</span><span style="color: #007700">)); <br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.xattr-set-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.xattr-get.html" class="function" rel="rdfs-seeAlso">xattr_get()</a> - Get an extended attribute</span></li>
<li class="member"> <span class="function"><a href="function.xattr-remove.html" class="function" rel="rdfs-seeAlso">xattr_remove()</a> - Remove an extended attribute</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.xattr-remove.html">xattr_remove</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.xattr-supported.html">xattr_supported</a></div>
<div class="up"><a href="ref.xattr.html">xattr Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
