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.
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


You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a dofollow link back to this page - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind. Icons from table-icons.io copyright Paweł Kuna, licensed under MIT license.