Home / Autodocs / dos.library
NAME
- Write
-
Write bytes of data to a file
SYNOPSIS
returnedLength = Write( file, buffer, length )
D0 D1 D2 D3
LONG Write (BPTR, void *, LONG)
D0 D1 D2 D3
LONG Write (BPTR, void *, LONG)
FUNCTION
Write() writes bytes of data to the opened file 'file'. 'length' indicates the length of data to be transferred; 'buffer' is a pointer to the buffer. The value returned is the length of information actually written. So, when 'length' is greater than zero, the value of 'length' is the number of characters written. Errors are indicated by a value of -1.
- Note:
-
this is an unbuffered operation, i.e. the request is passed
INPUTS
- file
-
BCPL pointer to a FileHandle
- buffer
-
pointer to the buffer
- length
-
integer; this must be a number > 0 for data to be written to the file, as pointed to by the buffer address. A length value of 0 is a valid choice.
RESULT
- returnedLength
-
integer value. A value of -1 indicates that an error has occurred; check with IoErr() why Write() has failed. Any value >= 0 indicates success, or at least partial success, which is the number of bytes successfully transmitted or written to the file.
WARNING
A file system or handler may not be able to store or transmit exactly as much data as you requested. Instead of returning -1 to indicate an error, it may return the number of data bytes it managed to write or transmit successfully. A networked file system may show exactly this behaviour, but it is not necessarily limited to this kind of file system.
If your program relies upon Write() to perform exactly what was requested, you should check the length returned by Write() and compare it against the number of bytes to be written. The file system or handler may return a "partial success" with fewer data bytes written than were requested. It is up to you to handle this case gracefully. Comparing the length returned against -1 in order to detect an error and otherwise assuming the file system or handler to have transmitted or written all the data is bound to lead to loss of data and/or corruption.
If your program relies upon Write() to perform exactly what was requested, you should check the length returned by Write() and compare it against the number of bytes to be written. The file system or handler may return a "partial success" with fewer data bytes written than were requested. It is up to you to handle this case gracefully. Comparing the length returned against -1 in order to detect an error and otherwise assuming the file system or handler to have transmitted or written all the data is bound to lead to loss of data and/or corruption.
NOTES
Amiga file system operations limit the size of files to 2 GBytes (2,147,483,647 bytes). It is safe to assume that random access to files which do not exceed this limitation is reliable, unless the file system itself imposes additional size limitations. File systems may even make larger files accessible, but you may find that random access becomes unreliable. Writing data sequentially beyond the 2 GByte limit may become unreliable, too.
Some handlers may accept a write length value of -1 as an indication that the buffer contains a NUL-terminated 'C' string, which prompts them to determine the number of bytes to be written all by themselves. This is at best a side effect and not a feature which could be relied upon. If you know that the buffer contains a NUL-terminated 'C' string, use strlen() to determine the length of the string to be written instead of using -1.
Some handlers may accept a write length value of -1 as an indication that the buffer contains a NUL-terminated 'C' string, which prompts them to determine the number of bytes to be written all by themselves. This is at best a side effect and not a feature which could be relied upon. If you know that the buffer contains a NUL-terminated 'C' string, use strlen() to determine the length of the string to be written instead of using -1.