3.3.1 File Names

A standard representation is used by virtual code applications for the path names of files, following the description in Input Data Structure. The functions and constants declared in fnames.h provide an API for operating on file names in this form.

Function: list avm_path_representation (char *path)

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.

conf_path = avm_path_representation("/etc/resolve.conf");

In this example, conf_path is a list. For potentially better portability, a C program can use the character constant avm_path_separator_character in place of the slashes in hard coded path names.

Other useful constants are avm_current_directory_prefix as a portable replacement for "./", as well as avm_parent_directory_prefix instead of "../". There is also avm_root_directory_prefix for "/". These three constants are null terminated strings, unlike avm_path_separator_character, which is a character.

If a NULL pointer is passed as the path, a NULL 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 path, the list of the empty string will be returned, which is the path representation for the root directory. Trailing path separators are ignored, so "/" is the same as the empty string.

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.

Function: list avm_date_representation (char *path)

This function is essentially a wrapper around the standard ctime_r function that not only gets the time stamp for a file at a given path, but transforms it to a list representation according to Character Table. 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.

The time stamp will usually be in a format like Sun Mar 4 10:56:40 GMT 2001. If for some reason the time stamp can not be obtained, the result will be a representation of the string unknown date.

Function: char* avm_path_name (list path)

This function is the inverse of avm_path_representation, 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.

If the path parameter is NULL, a NULL pointer is returned as the result. The calling program should check for a NULL result and interpret it as the path to standard input or standard output.

The memory needed for the character string whose address is returned is allocated by this function if possible. The given path 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 Character Table. 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.

• program-name: counter overflow (code nn)
• program-name: memory overflow (code nn)
• program-name: null character in file name
• program-name: bad character in file name
• program-name: invalid file name (code nn)

Function: void avm_initialize_fnames ()

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.

Function: void avm_count_fnames ()

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 avm_count_lists is also being used by the client, it should be called after this one.

This document was generated on December 10, 2012 using texi2html 1.82.