boinc/doc/files.php

<?php
require_once("docutil.php");
page_head("Storage");
echo "
<h3>Files and data servers</h3> 
<p>
The BOINC storage model is based on <b>files</b>.
The inputs and outputs of applications,
and the application executables, are files.
<p>
The BOINC core client transfers files to and from <b>data servers</b>
operated by the project, using HTTP.
<p>
A file is described by an XML element of the form 
<pre>
&lt;file_info>
    &lt;name>foobar&lt;/name>
    &lt;url>http://a.b.c/foobar&lt;/url>
    &lt;url>http://x.y.z/foobar&lt;/url>
    ...
    &lt;md5_cksum>123123123123&lt;/md5_cksum>
    &lt;nbytes>134423&lt;/nbytes>
    &lt;max_nbytes>200000&lt;/max_nbytes>
    &lt;status>1&lt;/status>
    [ &lt;generated_locally/> ]
    [ &lt;executable/> ]
    [ &lt;upload_when_present/> ]
    [ &lt;sticky/> ]
    [ &lt;signature_required/> ]
&lt;/file_info>
</pre>
The elements are as follows:
";
list_start();
list_item(
    "name", "The file's name, which must be unique within the project."
);
list_item("url", "a URL where the file is
(or will be) located on a data server.");
list_item("md5_cksum", "The MD5 checksum of the file.");
list_item("nbytes", "the size of the file in
bytes (may be greater than 2^32).");
list_item("max_nbytes", "The maximum allowable
size of the file in bytes (may be greater than 2^32).
This is used to prevent flooding data servers with bogus data.");
list_item("status", "0 if the file is not present,
1 if the file is present, or a negative error code if there was a
problem in downloading or generating the file.");
list_item("generated_locally", "If present,
indicates that the file will be generated by an application on
the client, as opposed to being downloaded.");
list_item("executable", "If present, indicates
that the file protections should be set to allow execution.");
list_item("upload_when_present", "If present,
indicates that the file should be uploaded after it is created.");
list_item("sticky", "If present, indicates that
the file should be retained on the client after its initial use.");
list_item("signature_required", "If present,
indicates that the file should be verified with an RSA signature.
This generally only applies to executable files.");
list_end();
echo "
These attributes allow the specification of various types of files: for
example, input or output files that are retained for use as input to
later computations.
<p>
Once a file is created (on a data server or a participant host) it
is immutable.
<h3>File references</h3> 
<p>
Files may be associated with <a href=work.php>workunits</a>,
<a href=result.php>results</a> and
<a href=app.php>application versions</a>.
Each such association is represented by an XML element of the form 
<pre>
&lt;file_ref>
    &lt;file_name>foobar&lt;/file_name>
    [ &lt;open_name>input&lt;/open_name> ]
    [ &lt;main_program/> ]
&lt;/file_ref>
</pre>
The elements are as follows: 
";
list_start();
list_item("file_name", "Specifies a file.");
list_item("open_name", "The name by
which the application will refer to the file.");
list_item("main_program", "Used for files
associated with application versions.
It indicates that this file is the application's main program.");
list_end();
page_tail();
?>