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

<refentryinfo><date>3 Sep 2015</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfs_pio_create</refname>
<refpurpose>create a file in the Gfarm file system</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<funcsynopsis>
<funcsynopsisinfo format="linespecific">
#include &lt;gfarm/gfarm.h&gt;
</funcsynopsisinfo>

<funcprototype>
  <funcdef><function moreinfo="none"><returnvalue>gfarm_error_t</returnvalue> gfs_pio_create</function></funcdef>
    <paramdef>const char * <parameter moreinfo="none">gfarm_url</parameter></paramdef>
    <paramdef>int <parameter moreinfo="none">flags</parameter></paramdef>
    <paramdef>gfarm_mode_t <parameter moreinfo="none">mode</parameter></paramdef>
    <paramdef>GFS_File * <parameter moreinfo="none">gfp</parameter></paramdef>
</funcprototype>

</funcsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para><function moreinfo="none">gfs_pio_create()</function> creates a new file in the
Gfarm file system whose name is the
string pointed to by <parameter moreinfo="none">gfarm_url</parameter> with the access mode <parameter moreinfo="none">mode</parameter>,
and returns a <parameter moreinfo="none">GFS_File</parameter> structure to the address pointed to by
<parameter moreinfo="none">gfp</parameter>.  <parameter moreinfo="none">Mode</parameter> specifies the file permissions to be created,
and is modified by the process's <varname>umask</varname>.</para>

<para>
The
<parameter moreinfo="none">flags</parameter>
argument has the same meaning as the second argument of
<function moreinfo="none">gfs_pio_open()</function>, including the point
such that exactly one of
<parameter moreinfo="none">GFARM_FILE_RDONLY</parameter>,
<parameter moreinfo="none">GFARM_FILE_WRONLY</parameter>, and
<parameter moreinfo="none">GFARM_FILE_RDWR</parameter>
should be specified.
In addition, it is possible to specify
<parameter moreinfo="none">GFARM_FILE_EXCLUSIVE</parameter>.
With this flag, 
<function moreinfo="none">gfs_pio_create()</function>
will fail when the file already exists.
</para>
<para>
Note that
<parameter moreinfo="none">GFARM_FILE_TRUNC</parameter>
must be explicitly specified by the
<parameter moreinfo="none">flags</parameter>
argument if needed.
</para>
</refsect1>

<refsect1 id="return-values"><title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term><constant>GFARM_ERR_NO_ERROR</constant></term>
<listitem>
<para>The function terminated successfully.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_IS_A_DIRECTORY</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> refers to a directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_IS_A_SYMBOLIC_LINK</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> refers to a symbolic link.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_OPERATION_NOT_PERMITTED</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> refers to not a regular file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_NOT_A_DIRECTORY</constant></term>
<listitem>
<para>A component used as a directory in <parameter moreinfo="none">gfarm_url</parameter> is not, in fact, a
directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_PERMISSION_DENIED</constant></term>
<listitem>
<para>The requested access to the file is not allowed, or one of the
directories in <parameter moreinfo="none">gfarm_url</parameter> did not allow search (execute)
permission, or the file did not exist yet and write access to the
parent directory is not allowed.
Or, the authentication to the metadata server fails.</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_INVALID_ARGUMENT</constant></term>
<listitem>
<para><parameter moreinfo="none">flags</parameter>
is not valid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_GFARM_URL_HOST_IS_MISSING</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter>
does not include a metadata server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_GFARM_URL_PORT_IS_MISSING</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter>
does not include a port number of the metadata server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_UNKNOWN_HOST</constant></term>
<listitem>
<para>The metadata server cannot be resolved.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_TOO_MANY_OPEN_FILES</constant></term>
<listitem>
<para>The process opens too many files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_TOO_MANY_OPEN_FILES_IN_SYSTEM</constant></term>
<listitem>
<para>The system limit on the total number of open files has been reached.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_NETWORK_IS_UNREACHABLE</constant></term>
<listitem>
<para>Network is unrechable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_OPERATION_TIMED_OUT</constant></term>
<listitem>
<para>Connetion timeout occurs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_PROTOCOL</constant></term>
<listitem>
<para>Protocol error occurs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_BROKEN_PIPE</constant></term>
<listitem>
<para>Connection to the metadata server is broken.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_PROTOCOL_NOT_SUPPORTED</constant></term>
<listitem>
<para>Specified authentication protocol is not supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_AUTHENTICATION</constant></term>
<listitem>
<para>User authentication failed when connecting to the metadata server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_ERR_ALREADY_EXISTS</constant></term>
<listitem>
<para><parameter moreinfo="none">gfarm_url</parameter> already exists and GFARM_FILE_EXCLUSIVE was used.</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>
<para>
<parameter moreinfo="none">gfarm_url</parameter> refers to a file on a read-only filesystem and
write access was requested.
</para>
</listitem>
</varlistentry>
-->

<varlistentry>
<term>Others</term>
<listitem>
<para>An error except the above occurred.  The reason is shown by
<citerefentry><refentrytitle>gfarm_error_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 id="see-also"><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gfs_pio_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_create</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_eof</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_getc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_getline</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_putc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_putline</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_puts</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_seek</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_ungetc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_write</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
