<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!-- $Id$ -->

<refentry id="gfs-chmod.3">

<refentryinfo><date>22 Feb 2005</date></refentryinfo>

<refmeta>
<refentrytitle>gfs_chmod</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfs_chmod</refname>
<refpurpose>change permissions of a file</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<funcsynopsis>
<funcsynopsisinfo format="linespecific">
#include &lt;gfarm/gfarm.h&gt;
</funcsynopsisinfo>

<funcprototype>
  <funcdef><function moreinfo="none"><returnvalue>char *</returnvalue>gfs_chmod</function></funcdef>
    <paramdef>char * <parameter moreinfo="none">gfarm_url</parameter></paramdef>
    <paramdef>mode_t <parameter moreinfo="none">mode</parameter></paramdef>
</funcprototype>


</funcsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para><function moreinfo="none">gfs_chmod()</function> changes the mode of the file
given by <parameter moreinfo="none">gfarm_url</parameter>.  Permission bit masks of
<parameter moreinfo="none">mode</parameter> are similar to ones of mode parameter to
<function moreinfo="none">chmod(2)</function>, though only the least 9 bit are
effective.</para>

<para>An executable file cannot be changed to a non-executable file
and vice versa, unless the number of fragment of the file is only one.
In detail, a file has multiple fragments with any execution bit should not
be changed to that with no execution bit.  It is necessary to have
at least one execution bit.  Similarly, a file has multiple fragments
with no execution bit should not be changed to that with any execution bit.
</para>

</refsect1>

<refsect1 id="return-values"><title>RETURN VALUES</title>
<variablelist>

<varlistentry>
<term><constant>NULL</constant></term>
<listitem>
<para>The function terminated successfully.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_NO_MEMORY</constant></term>
<listitem>
<para>Insufficient memory was available.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_AUTHENTICATION</constant></term>
<listitem>
<para>User authentication failed when connecting to gfmd(8) or gfsd(8).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_PERMISSION_DENIED</constant></term>
<listitem>
<para>The parent directory of <parameter moreinfo="none">gfarm_url</parameter>
did not allow write permission.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_OPERATION_NOT_PERMITTED</constant></term>
<listitem>
<para>The effective UID does not match the owner of the file, and is not
zero.  Or an attempt was made to change an executable file with more than
one fragment to a non-executable file, or vice versa.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_NO_SUCH_OBJECT</constant></term>
<listitem>
<para>The file does not exist.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_NOT_A_DIRECTORY</constant></term>
<listitem>
<para>A component of the path prefix is not a directory.</para>
</listitem>
</varlistentry>

<!--
<varlistentry>
<term><constant>GFARM_ERR_READ_ONLY_FILE_SYSTEM</constant></term>
<listitem>
<para>The named file resides on a read-only filesystem.</para>
</listitem>
</varlistentry>
-->

<varlistentry>
<term>Others</term>
<listitem>
<para>An error except the above occurred.  The reason is shown by its
pointed strings.</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>
</refentry>

