NAME¶

read-file - (files)

PURPOSE¶

Read file into a string variable.

SYNTAX¶

read-file <file> | ( file-id <file id> ) \


    to <content> \


    [ position <position> ] \


    [ length <length> ] \


    [ status <status> ] \


    [ end-of-file <eof> ]

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 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 GG_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), GG_ERR_READ (if <length> is negative or there is an error reading file) or GG_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. Golf 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 GG_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), GG_ERR_READ (if <length> is negative or there is an error reading file) or GG_ERR_OPEN if file is not open. 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/>


    p-web file_content


    @<hr/>
else-if


    @Could not read (<<print-format "%ld", st>>)
end-if

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

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

SEE ALSO¶

Files

change-mode 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