txlyre
/
avram


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
							<html lang="en">
<head>
<title>File Names - avram - a virtual machine code interpreter</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="avram - a virtual machine code interpreter">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="File-Manipulation.html#File-Manipulation" title="File Manipulation">
<link rel="prev" href="File-Manipulation.html#File-Manipulation" title="File Manipulation">
<link rel="next" href="Raw-Files.html#Raw-Files" title="Raw Files">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="File-Names"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Raw-Files.html#Raw-Files">Raw Files</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="File-Manipulation.html#File-Manipulation">File Manipulation</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="File-Manipulation.html#File-Manipulation">File Manipulation</a>
<hr>
</div>

<h4 class="subsection">3.3.1 File Names</h4>

<p>A standard representation is used by virtual code applications for the
<a name="index-file-names-528"></a>path names of files, following the description in <a href="Input-Data-Structure.html#Input-Data-Structure">Input Data Structure</a>. The functions and constants declared in <code>fnames.h</code>
provide an API for operating on file names in this form.

<div class="defun">
&mdash; Function: list <b>avm_path_representation</b> (<var>char *path</var>)<var><a name="index-avm_005fpath_005frepresentation-529"></a></var><br>
<blockquote><p>If a C program is to invoke a virtual code application and pass a path
name to it as a parameter, this function can be used to generate the
appropriate representation from a given character string.

     <pre class="example">          conf_path = avm_path_representation("/etc/resolve.conf");
</pre>
        <p>In this example, <code>conf_path</code> is a <code>list</code>.  For potentially
better portability, a C program can use the character constant
<code>avm_path_separator_character</code> in place of the slashes in hard
coded path names.

        <p>Other useful constants are <code>avm_current_directory_prefix</code> as a
<a name="index-g_t_0040code_007bavm_005fpath_005fseparator_005fcharacter_007d-530"></a><a name="index-g_t_0040code_007bavm_005fpath_005fseparator_007d-531"></a><a name="index-g_t_0040code_007bavm_005fcurrent_005fdirectory_005fprefix_007d-532"></a><a name="index-g_t_0040code_007bavm_005fparent_005fdirectory_005fprefix_007d-533"></a><a name="index-g_t_0040code_007bavm_005froot_005fdirectory_005fprefix_007d-534"></a>portable replacement for <code>"./"</code>, as well as
<code>avm_parent_directory_prefix</code> instead of <code>"../"</code>. There is
also <code>avm_root_directory_prefix</code> for <code>"/"</code>. These three
constants are null terminated strings, unlike
<code>avm_path_separator_character</code>, which is a character.

        <p>If a <code>NULL</code> pointer is passed as the <var>path</var>, a
<code>NULL</code> list is returned, which is the path representation for
standard input or standard output. If the address of an empty string is
passed to this function as the <var>path</var>, the list of the empty
string will be returned, which is the path representation for the root
directory. Trailing path separators are ignored, so <code>"/"</code> is the
same as the empty string.

        <p>Some memory needs to be allocated for the result of this function. If
the memory is not available, an error message is written to standard
error and the process is terminated. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: list <b>avm_date_representation</b> (<var>char *path</var>)<var><a name="index-avm_005fdate_005frepresentation-535"></a></var><br>
<blockquote><p>This function is essentially a wrapper around the standard
<code>ctime_r</code> function that not only gets the time stamp for a file at
a given path, but transforms it to a list representation according to
<a href="Character-Table.html#Character-Table">Character Table</a>. It needs to allocate memory for the result and
will cause the program to exit with an error message if there is not
enough memory available.

        <p>The time stamp will usually be in a format like <code>Sun Mar 4 10:56:40
GMT 2001</code>. If for some reason the time stamp can not be obtained, the
<a name="index-g_t_0040code_007bunknown-date_007d-536"></a>result will be a representation of the string <code>unknown date</code>. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: char* <b>avm_path_name</b> (<var>list path</var>)<var><a name="index-avm_005fpath_005fname-537"></a></var><br>
<blockquote><p>This function is the inverse of <code>avm_path_representation</code>, in that
it takes a list representing a path to the path name expressed as a character
string. This function can be used in C programs that invoke virtual code
applications returning paths as part of their results, so that the C
program can get the path into a character string in order to open the file.

        <p>If the <var>path</var> parameter is <code>NULL</code>, a <code>NULL</code> pointer
is returned as the result. The calling program should check for a
<a name="index-standard-input-538"></a><a name="index-standard-output-539"></a><code>NULL</code> result and interpret it as the path to standard input or
standard output.

        <p>The memory needed for the character string whose address is returned is
allocated by this function if possible. The given <var>path</var> is
not required to be consistent with the host file system, but it is
required to consist of representations of non-null printable characters
or spaces as lists per <a href="Character-Table.html#Character-Table">Character Table</a>.  In the event of any error
or overflow, control does not return to the caller, but an error message
is printed and the program is aborted. The possible error messages from
this function are the following. 
<a name="index-g_t_0040code_007bcounter-overflow_007d-540"></a><a name="index-g_t_0040code_007bmemory-overflow_007d-541"></a><a name="index-g_t_0040code_007bnull-character-in-file-name_007d-542"></a><a name="index-g_t_0040code_007bbad-character-in-file-name_007d-543"></a><a name="index-g_t_0040code_007binvalid-file-name_007d-544"></a>
          <ul>
<li><var>program-name</var><code>: counter overflow (code </code><var>nn</var><code>)</code>
<li><var>program-name</var><code>: memory overflow (code </code><var>nn</var><code>)</code>
<li><var>program-name</var><code>: null character in file name</code>
<li><var>program-name</var><code>: bad character in file name</code>
<li><var>program-name</var><code>: invalid file name (code </code><var>nn</var><code>)</code>
</ul>

        </blockquote></div>

<div class="defun">
&mdash; Function: void <b>avm_initialize_fnames</b> ()<var><a name="index-avm_005finitialize_005ffnames-545"></a></var><br>
<blockquote><p>A few housekeeping operations relevant to internal data structures are
performed by this function, making it necessary to be called by the
client program prior to using any of the other ones. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: void <b>avm_count_fnames</b> ()<var><a name="index-avm_005fcount_005ffnames-546"></a></var><br>
<blockquote><p>This function can be used after the the last call to any of the other
functions in this section during a run, and it will detect memory leaks
that may be attributable to code in these functions or misuse
thereof. If any unreclaimed storage remains when this function is
called, a warning message will be written to standard error. If the
function <code>avm_count_lists</code> is also being used by the client, it
should be called after this one. 
</p></blockquote></div>

   </body></html>