Ubuntu Manpage: read-file

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.

NAME

PURPOSE

SYNTAX

DESCRIPTION

EXAMPLES

SEE ALSO