Ubuntu Manpage: write-file

NAME

       write-file -  (files)

PURPOSE

       Write to a file.

SYNTAX

           write-file <file> | ( file-id <file id> ) \
               from <content> \
               [ length <length> ] \
               [ ( position <position> ) | ( append [ <append> ] ) ] \
               [ status <status> ]

DESCRIPTION

       WITHOUT FILE-ID

       This is a simple method of writing a file. File named <file> is opened, data written, and file is closed.
       <file> can be a full path name, or a path relative to the application home directory (see directories).

       write-file  writes  <content> to <file>. If "append" clause is used without boolean variable <append>, or
       if <append> evaluates to true, the <content> is appended to the file; otherwise the file  is  overwritten
       with  <content>,  unless "position" clause is used in which case file is not overwritten and <content> is
       written at byte <position> (with 0 being the first byte). Note that <position> can be beyond the  end  of
       file, in which case null-bytes are written between the current end of file and <position>.

       File  is  created  if  it  does not exist (even if "append" is used), unless "position" clause is used in
       which case file must exist.

       If "length" is not used, then a whole string <content> is written to a file,  and  the  number  of  bytes
       written is the length of that string. If "length" is specified, then exactly <length> bytes are written.

       If  "status"  clause  is  used,  then  the  number  of  bytes written 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 or file does not support it), GG_ERR_WRITE (if there is an error writing file) or GG_ERR_OPEN
       if file cannot be open.

       WITH FILE-ID

       This method uses a <file id> that was created with open-file. You can then write (and  read)  file  using
       this <file id> and the file stays open until close-file is called or the request ends.

       If  "position"  clause  is  used,  then  data is written starting from byte <position>, otherwise writing
       starts from the current file position determined by the previous reads/writes or as set  by  using  "set"
       clause  in  file-position. After each read or write, the file position is advanced by the number of bytes
       read or written. Position can be set passed the last byte of the file, in which case  writing  will  fill
       the space between the current end of file and the current position with null-bytes.

       If "length" is not used, then a whole string is written to a file, and the number of bytes written is the
       length of that string. If "length" is specified, then exactly <length> bytes are written.

       If "append" clause is used without boolean variable <append>, or if <append> evaluates to true, then file
       pointer is set at the end of file and data written.

       If  "status"  clause  is  used,  then  the  number  of  bytes written 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 or file does not support it), GG_ERR_WRITE (if there is an error writing file) or GG_ERR_OPEN
       if file is not open.

EXAMPLES

       To overwrite file "/path/to/file" with "Hello World":

           write-file "/path/to/file" from "Hello World"

       To append "Hello World" to file:

           set-string path="/path/to/file"
           set-string cont="Hello World"
           write-file path from cont append

       To write only 5 bytes (i.e. "Hello") and get status (if successful, number "st" would be "5"):

           set-string cont="Hello World"
           write-file "file" from cont length 5 status st

       To write a string "Hello" at byte position 3 in the existing "file":

           set-string cont="Hello"
           write-file "file" from cont position 3 status st

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

NAME

PURPOSE

SYNTAX

DESCRIPTION

EXAMPLES

SEE ALSO