SetFileSize

Sets the size of a file (V36)

Changes the file size, truncating or extending it as needed. Not all handlers may support this; be careful and check the return code. If SetFileSize() returns -1, changing the file size may not be supported.

The current read/write position of the FileHandle will be adjusted if the file becomes so short that the position would be beyond the new size of the file. In this case, the current read/write position will be set to the new end of the file.

If there is more than one FileHandle currently open on the file, then truncating the file size will be restricted to a size that allows for the respective current read/write position of each FileHandle to remain valid. Check the return code: it should be the file size you expected. The file may remain larger than you expected it to become.

The file read/write position should, otherwise, remain unchanged. However, see BUGS.

fh

File to be truncated/extended.

offset

Offset from position determined by mode.

mode

One of OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END.

newsize

position of new end-of-file or -1 for error.

The new file size should be >= 0 and should not exceed 2147483647 bytes.

Extending the size of a file will not initialize the portion that was added to the file. Its contents are undefined. If you need it to be initialized with specific contents, you will have to use Write() to fill it in.

Truncating a file may result in unexpected behaviour, namely in that SetFileSize() will return a file size > 0 instead of an error condition (then the value -1 will be returned), but the file will be larger than you asked it to be. If it is important that the size of the file is exactly what you asked for, you should verify that it is the case and treat a different file size as an error.

Not all file systems support changing the size of a file. If you depend upon this feature, you should check if SetFileSize() returned -1 and if IoErr() then returned ERROR_ACTION_NOT_KNOWN.

Some file systems may change the current FileHandle read/write position as a side effect of changing the file size, even if this is not warranted. This behaviour counts as a bug. If you expect a specific read/write position, call Seek() and remember the position, then call SetFileSize() and, if successful, restore the position you remembered.

The RAM: file system releases before V47 as well as the normal Amiga file system act differently where the file position is left after SetFileSize() that extended the size of a file. Older RAM: left you incorrectly at the new end of the file. This has been fixed in the V47 RAM-Handler. The correct behaviour is to leave the current read/write position alone, unless the file became so short that this position would have become invalid. In this case, the new read/write position will be set to the end of the file.

The best workaround is to not make any assumptions about the current read/write position after SetFileSize().

Seek()