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

<refentryinfo><date>8 Aug 2020</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfs_pio_open</refname>
<refpurpose>open 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_open</function></funcdef>
    <paramdef>const char * <parameter moreinfo="none">gfarm_url</parameter></paramdef>
    <paramdef>int <parameter moreinfo="none">flags</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_open()</function> opens a file in the Gfarm
file system specified by <parameter moreinfo="none">gfarm_url</parameter>,
and returns a <parameter moreinfo="none">GFS_File</parameter> structure
to the address pointed by <parameter moreinfo="none">gfp</parameter>.
<parameter moreinfo="none">gfarm_url</parameter> is a path name in the Gfarm file
system, or a Gfarm URL in the form of gfarm://metaserver:port/path/name.
</para>

<para>
Values of <parameter moreinfo="none">flags</parameter> are constructed by a
bitwise-inclusive-OR of the following list.  Exactly one of the first
three values should be specified:
</para>
<variablelist>
<varlistentry>
<term><constant>GFARM_FILE_RDONLY</constant></term>
<listitem>
<para>Open for reading only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_WRONLY</constant></term>
<listitem>
<para>Open for writing only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_RDWR</constant></term>
<listitem>
<para>Open for reading and writing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_TRUNC</constant></term>
<listitem>
<para>If the file already exist and is a regular file, it will be
truncated to length 0 if the open mode allows writing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_APPEND</constant></term>
<listitem>
<para>The file is opened in append mode.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_UNBUFFERED</constant></term>
<listitem>
<para>The file is accessed without buffering.</para>
</listitem>
</varlistentry>
</variablelist>

<!--
<para>
The following may be specified as a hint for efficient execution:
</para>
<variablelist>
<varlistentry>
<term><constant>GFARM_FILE_SEQUENTIAL</constant></term>
<listitem>
<para>File will be accessed sequentially.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_REPLICATION</constant></term>
<listitem>
<para>File may be replicated to a local filesystem when accessing
remotely.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_NOT_REPLICATION</constant></term>
<listitem>
<para>File may not be replicated to a local filesystem when accessing
remotely.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GFARM_FILE_NOT_RETRY</constant></term>
<listitem>
<para>When the selected file replica does not exist or cannot be
accessed by some reason, open will fail without trying to access
another file replica.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<constant>GFARM_FILE_REPLICATION</constant> and
<constant>GFARM_FILE_NOT_REPLICATION</constant> cannot be specified at
the same time.
</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_NO_SUCH_OBJECT</constant></term>
<listitem>
<para>A component used as a directory in <parameter moreinfo="none">gfarm_url</parameter> does not exist.</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 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_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>

