@node _write, file system
@subheading Syntax

@example
#include <io.h>

ssize_t _write(int fildes, void *buf, size_t nbyte);
@end example

@subheading Description

This is a direct connection to the MS-DOS write function call, int
0x21, %ah = 0x40.  No conversion is done on the data; it is written as
raw binary data.  This function can be hooked by the File-system
extensions, see @ref{File System Extensions}.  If you don't want this,
you should use @code{_dos_write} instead, see @ref{_dos_write}.

@subheading Return Value

The number of bytes written, or -1 (and @code{errno} set) in case of
failure.

Note that DOS doesn't return an error indication when the target disk is
full; therefore if the disk fills up while the data is written,
@code{_write} does @strong{not} return -1, it returns the number of
bytes it succeeded to write.  If you need to detect the disk full
condition reliably, call @code{_write} again to try to write the rest of
the data.  This will cause DOS to return zero as the number of written
bytes, and @emph{then} @code{_write} will return -1 and set @code{errno}
to @code{ENOSPC}.  The example below shows one way of doing this.

@subheading Portability

@portability !ansi, !posix

@subheading Example

This example shows how to call @code{_write} in a way which ensures that
@code{errno} will be set to @code{ENOSPC} if the target filesystem is or
becomes full:

@example
  char *buf_ptr;    /* the buffer to write */
  size_t buf_len;   /* the number of bytes to write */
  int desc;         /* the file descriptor to write to */

  while (buf_len > 0)
  @{
    int written = _write (desc, buf_ptr, buf_len);
    if (written <= 0)
      break;

    buf_ptr += written;
    buf_len -= written;
  @}
@end example