3.3.2 Raw Files

Some low level operations involving lists and data files are provided by these functions, which are declared in the header file ‘rawio.h’.

Function: list avm_received_list (FILE *object, char *filename)

This function is a convenient way of transferring data directly from a raw format file into a list in memory. It might typically be used to load the virtual code for an application that has been written to a file by a compiler.

object

is the address of a file which should already be open for reading before this function is called, and will be read from its current position.

filename

should be set by the caller to the address of a null terminated string containing the name of the file, but is not used unless it needs to be printed as part of an error message. If it is a null pointer, standard input is assumed.

The result returned is a list containing data read from the file.

The file format is described in File Format. The preamble section of the file, if any, is ignored. If the file ends prematurely or otherwise conflicts with the format, the program is aborted with a message of

program-name: invalid raw file format in filename

written to standard error. The program will also be aborted by this function in the event of a memory overflow.

The file is left open when this function returns, and could therefore be used to store other data after the end of the list. The end of a list is detected automatically by this function, and it reads no further, leaving the file position on the next character, if any.

Function: void avm_send_list (FILE *repository, list operand, char *filename)

This function can be used to transfer data from a list in memory to a file, essentially by implementing the printing algorithm described in Bit String Encoding.

repository

is the address of a file already open for writing, to which the data are written starting from the current position.

operand

is the list containing the data to be written

filename

is the address of a null terminated string containing the name of the file that will be reported in an error message if necessary.

No preamble section is written by this function, but one could be written to the file by the caller prior to calling it. Error messages are possible either because of i/o errors or because of insufficient memory. I/o errors are not fatal and will result only in a warning message being printed to standard error, but a memory overflow will cause the process to abort. An i/o error message reported by this function would be of the form

program-name: can't write to filename

followed by the diagnostic obtained from the standard strerror function if it exists on the host platform. The file is left open when this function returns.

Function: void avm_initialize_rawio ()

This function initializes some necessary data structures for the functions in this section, and should be called prior to them at the beginning of a run.

Function: void avm_count_rawio ()

This function does nothing in the present version of the library, but should be called after the last call to all of the other functions in this section in order to maintain compatibility with future versions of the library. Future versions may decide to use this function to do some cleaning up of local data structures.

This document was generated on November 8, 2012 using texi2html 1.82.