Vely logo install
examples
documentation

Vely 15.2.0 released on Jan 18, 2023
Articles updated Jan 17, 2023

read-file


Issues with this documentation page? Report here.

Purpose:


Read file into a string variable.

Syntax:



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


Description:



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)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Vely elephant logo (c) 2022 DaSoftver LLC. This web page is licensed under CC-BY-SA-4.0.