Vely logo install | documentation | examples | articles | changelog
16.6.0 released on Mar 08, 2023 | articles updated on Mar 20, 2023

write-file


Purpose: Write to a file.

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

Without file-id

This is a simple method of writing a file. File named <file> is opened, data written, and file is closed.

write-file writes <content> to <file>, which is either a full path of the file or a path relative to the application home directory (see how_vely_works).

If "append" clause is used without optional boolean expression <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>. Note that <position> can be beyond the end of file, and 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 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 is written and <content> can hold a binary value or a string.

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 VV_ERR_POSITION (if <position> is negative or file does not support it), VV_ERR_WRITE (if there is an error writing file) or VV_ERR_OPEN if file is not open. Note that no partial data will be written; if all of data cannot be written to the file, then none will be written, and in that case an error of VV_ERR_WRITE will be reported in <status>.

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.

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 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 is written and <content> can hold a binary value or a string.

If "append" clause is used without optional boolean expression <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 VV_ERR_POSITION (if <position> is negative or file does not support it), VV_ERR_WRITE (if there is an error writing file) or VV_ERR_OPEN if file is not open. Note that no partial data will be written; if all of data cannot be written to the file, then none will be written, and in that case an error of VV_ERR_WRITE will be reported in <status>.

Examples

To overwrite file "/path/to/file" with "Hello World":
write-file "/path/to/file" from "Hello World"
To append "Hello World" to file:
char *path="/path/to/file";
char *cont="Hello World";
write-file path from cont append
To write only 5 bytes (i.e. "Hello") and get status (if successful, number variable "st" would be "5"):
char *cont="Hello World";
write-file "file" from cont length 5 status define st
To write a string "Hello" at byte position 3 in the existing "file":
char *cont="Hello";
write-file "file" from cont position 3 status define st
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) 2017-2023 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. Contact email vely@vely.dev.