<?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="gfarm-url-hosts-schedule.3">

<refentryinfo><date>1 May 2002</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfarm_url_hosts_schedule</refname>
<refpurpose>schedule filesystem nodes using file-affinity scheduling</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<funcsynopsis>
<funcsynopsisinfo format="linespecific">
#include &lt;gfarm/gfarm.h&gt;
</funcsynopsisinfo>

<funcprototype>
  <funcdef><function moreinfo="none"><returnvalue>char *</returnvalue>gfarm_url_hosts_schedule</function></funcdef>
    <paramdef>char * <parameter moreinfo="none">gfarm_url</parameter></paramdef>
    <paramdef>char * <parameter moreinfo="none">option</parameter></paramdef>
    <paramdef>int * <parameter moreinfo="none">nhostsp</parameter></paramdef>
    <paramdef>char *** <parameter moreinfo="none">hostsp</parameter></paramdef>
</funcprototype>


</funcsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>The <function moreinfo="none">gfarm_url_hosts_schedule()</function> function schedules filesystem
nodes using file-affinity scheduling with a Gfarm file
<parameter moreinfo="none">gfarm_url</parameter>, and returns an array of filesystem hostnames
<parameter moreinfo="none">hostsp</parameter> and the number of scheduled hosts <parameter moreinfo="none">nhostsp</parameter>.  The
returned array of hostnames <parameter moreinfo="none">hostsp</parameter> should be free'ed with
gfarm_strings_free_deeply(3).</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>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="notes"><title>NOTES</title>
<para>The argument
<parameter moreinfo="none">option</parameter>
is reserved to specify options for scheduling, although it is not used
in the current implementation.</para>
</refsect1>
</refentry>

