Read file

Purpose: Read file into a string variable.

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

Copied!

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 current working directory (which by default is the application home directory, see directories).

Data read is stored into string <content>. Note that file can be binary or text and <content> may have null-bytes.

If "position" and "length" clauses are not specified, read-file reads the entire <file> into <content>.

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 RIM_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), RIM_ERR_READ (if <length> is negative or there is an error reading file) or RIM_ERR_OPEN if file cannot be opened. If the number of bytes read isn't what's requested, you can use "end-of-file" clause to get boolean <eof>, which is true if the end of file happened, or false if there is an error (in which case you can use "errno" clause in get-req to obtain the actual reason for error).

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. RimStone will automatically close any such open files).

Data read is stored into string <content>. Note that file can be binary or text and <content> may have null-bytes.

If "position" clause is used, then data is read starting from byte <position> (with position of 0 being the first byte), 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 RIM_ERR_POSITION (if <position> is negative, outside the file, or file does not support it) or RIM_ERR_READ (if <length> is negative or there is an error reading file). If file is not open, then your program will error out. If the number of bytes read isn't what's requested, you can use "end-of-file" clause to get boolean <eof>, which is true if the end of file happened, or false if there is an error (in which case you can use "errno" clause in get-req to obtain the actual reason for error).

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 file_content status st
if-true st greater-than 0
    @Read:
    @<hr/>
    print-out file_content web-encode
    @<hr/>
else-if
    @Could not read (<<print-format "%ld", st>>)
end-if

Copied!

To read 10 bytes starting at position 20 (with position 0 being the first byte):

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

Copied!

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