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> 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.
See also
Files (
close-file copy-file delete-file file-position file_storage file_uploading lock-file open-file read-file read-line rename-file stat-file temporary_file uniq-file unlock-file write-file )
SEE ALL (
documentation)