<?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-utimes.3">

<refentryinfo><date>4 Dec 2003</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfs_utimes</refname>
<refpurpose>set file access and modification times</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_utimes</function></funcdef>
    <paramdef>const char * <parameter moreinfo="none">gfarm_url</parameter></paramdef>
    <paramdef>const struct gfarm_timespec * <parameter moreinfo="none">tsp</parameter></paramdef>
</funcprototype>


</funcsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>

<para><function moreinfo="none">gfs_utimes()</function> sets the access and
modification times of the file pointed to by the
<parameter moreinfo="none">gfarm_url</parameter> argument to the value of the
<parameter moreinfo="none">tsp</parameter> argument.  The <parameter moreinfo="none">tsp</parameter>
argument is an array of gfarm_timespec structures.  The first array
member represents the access time, and the second member represents
the modification time.  The gfarm_timespec structure is:
<screen format="linespecific">
	struct gfarm_timespec {
		unsigned int tv_sec;	/* seconds */
		unsigned int tv_nsec;	/* nanoseconds */
	};
</screen>
</para>

<para> If the <parameter moreinfo="none">tsp</parameter> argument is a null pointer,
the access and modification times of the file are set to the current
time.</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_GFARM_URL_PREFIX_IS_MISSING</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> does not start with the gfarm: prefix.</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).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_PERMISSION_DENIED</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter>
points outside your accessible address space.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_NO_SUCH_OBJECT</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> does not exist.</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>

<refsect1 id="see-also"><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gfs_stat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

