Read file

19.0.0 released Nov 08, 2023

Read file

Purpose: Read file into a string variable.

read-file <file> | ( file-id <file id> ) \
    to [ define ] <content> \
    [ position <position> ] \
    [ length <length> ] \
    [ status [ define ] <status> ]

Without file-id

This is a simple method of reading a file. File named <file> is opened, data read, and file is closed.

<file> can be a full path name, or a path relative to the application home directory (see how-vely-works).

Data read is stored into <content>, which can be created with optional "define". <content> is allocated memory. Note that file can be binary or text and <content> may have null-bytes. Regardless, a null-byte is always placed after the data read.

If "position" and "length" clauses are not specified, read-file reads the entire <file> into <content>, which can be created with optional "define".

If "position" clause is used, then reading starts at byte <position>, otherwise it starts at the beginning of the file. Position of zero (0) represents the beginning of the file.

If "length" clause is used, then <length> number of bytes is read, otherwise the rest of the file is read. If <length> is 0, <content> is empty string and <status> is 0.

If "status" clause is used, then the number of bytes read is stored to <status>, unless error occurred, in which case <status> is negative and has the error code. The error code can be VV_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), VV_ERR_READ (if <length> is negative or there is an error reading file) or VV_ERR_OPEN if file is not open.

With file-id

This method uses a <file id> that was created with open-file. You can then read (and write) file using this <file id> and the file stays open until close-file is called, or the request ends (i.e. Vely will automatically close any such open files).

Data read is stored into <content>, which can be created with optional "define". <content> is allocated memory. Note that file can be binary or text and <content> may have null-bytes. Regardless, a null-byte is always placed after the data read.

If "position" clause is used, then data is read starting from byte <position>, otherwise reading starts from the current file position determined by the previous reads/writes or as set by using "set" clause in file-position. Note that after each read or write, the file position is advanced by the number of bytes read or written.

If "length" clause is used, then <length> number of bytes is read, otherwise the rest of the file is read. If <length> is 0, <content> is empty string and <status> is 0.

Note that when you reach the end of file and no more bytes can be read, <status> is 0.

If "status" clause is used, then the number of bytes read is stored to <status>, unless error occurred, in which case <status> has the error code. The error code can be VV_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), VV_ERR_READ (if <length> is negative or there is an error reading file) or VV_ERR_OPEN if file is not open.

Examples

To read the entire file and create both the variable that holds its content and the status variable:

read-file "/home/user/some_file" to define file_content status define st
if (st>=0) {
    @Read:
    @<hr/>
    p-web file_content
    @<hr/>
} else {
    @Could not read (<<pf-out "%lld" st>>)
}

"define" in both the content variable and the status are optional, so it could be:

num st;
char *file_content;

read-file "/home/user/some_file" to file_content status st

To read 10 bytes starting at position 20:

read-file "/home/user/some_file" to file_content position 20 length 10

See open-file for an example with "file-id" clause.