Can write(2) return 0 bytes written*, and what to do if it does?

Question

I'd like to implement a proper write(2) loop that takes a buffer and keeps calling write until the entire buffer is written.

I guess the basic approach is something like:

/** write len bytes of buf to fd, returns 0 on success */
int write_fully(int fd, char *buf, size_t len) {
  while (len > 0) {
    ssize_t written = write(fd, buf, len);
    if (written < 0) {
      // some kind of error, probably should try again if its EINTR?
      return written;
    }
    buf += written;
    len -= written;
  }
  return 0;
} 

... but this raises the question of whether write() can validly return 0 bytes written and what to do in this case. If the situation persists, the above code will just hot spin on the write call which seems like a bad idea. As long as something other than zero is returned you are making forward progress.

The man page for write is a bit ambiguous. It says, for example:

On success, the number of bytes written is returned (zero indicates nothing was written).

Which seems to indicate that it is possible in some scenarios. Only one such scenario is explicitly called out:

If count is zero and fd refers to a regular file, then write() may return a failure status if one of the errors below is detected. If no errors are detected, or error detection is not performed, 0 will be returned without causing any other effect. If count is zero and fd refers to a file other than a regular file, the results are not specified.

That case is avoided above because I never call write with len == 0. There are lot of other cases where nothing could be written, but in general they all have specific error codes associated with them.

The file itself will be a opened from a path/name given on the command line. So it will usually be a regular file, but users may of course pass things like pipes, do input redirection, pass special devices like /dev/stdout and so on. I am at least in control of the open call and the O_NONBLOCK flag is not passed to open. I can't reasonably check the behavior for all the file systems, all the special devices (and even if I could, more will be added), so I want to know how to handle this in a reasonable and general way.

---

* ... for a non-zero buffer size.

Answer 1

TL;DR summary

Unless you go out of your way to invoke unspecified behaviour, you will not get a zero result back from write() unless, perhaps, you attempt to write zero bytes (which the code in the question avoids doing).

POSIX says:

The POSIX specification for write() covers the issue, I believe.

The write() function shall attempt to write nbyte bytes from the buffer pointed to by buf to the file associated with the open file descriptor, fildes.

Before any action described below is taken, and if nbyte is zero and the file is a regular file, the write() function may detect and return errors as described below. In the absence of errors, or if error detection is not performed, the write() function shall return zero and have no other results. If nbyte is zero and the file is not a regular file, the results are unspecified.

This states that if you request a write of zero bytes, you may get a return value of zero, but there are a bundle of caveats — it must be a regular file, and you might get an error if errors like EBADF are detected, and it is unspecified what happens if the file descriptor does not refer to a regular file.

If a write() requests that more bytes be written than there is room for (for example, [XSI]⌦ the file size limit of the process or ⌫ the physical end of a medium), only as many bytes as there is room for shall be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20. The next write of a non-zero number of bytes would give a failure return (except as noted below).

[XSI]⌦ If the request would cause the file size to exceed the soft file size limit for the process and there is no room for any bytes to be written, the request shall fail and the implementation shall generate the SIGXFSZ signal for the thread. ⌫

If write() is interrupted by a signal before it writes any data, it shall return -1 with errno set to [EINTR].

If write() is interrupted by a signal after it successfully writes some data, it shall return the number of bytes written.

If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-defined.

These rules do not really give permission to return 0 (though a pedant might say that a value of nbyte that's too large might be defined to return 0).

When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes and cannot accept the data immediately:

• If the O_NONBLOCK flag is clear, write() shall block the calling thread until the data can be accepted.

• If the O_NONBLOCK flag is set, write() shall not block the thread. If some data can be written without blocking the thread, write() shall write what it can and return the number of bytes written. Otherwise, it shall return -1 and set errno to [EAGAIN].

…details for obscure file types — a number of them with unspecified behaviour…

Return value

Upon successful completion, these functions shall return the number of bytes actually written to the file associated with fildes. This number shall never be greater than byte. Otherwise, -1 shall be returned and errno set to indicate the error.

So, since your code avoids attempting to write zero bytes, as long as len is not larger than {SSIZE_MAX}, and as long as you aren't writing to obscure file types (like a shared memory object or a typed memory object) you should not see zero returned by write().

---

POSIX Rationale says:

Later in the POSIX page for write(), in the Rationale section, there is the information:

Where this volume of POSIX.1-2008 requires -1 to be returned and errno set to [EAGAIN], most historical implementations return zero (with the O_NDELAY flag set, which is the historical predecessor of O_NONBLOCK, but is not itself in this volume of POSIX.1-2008). The error indications in this volume of POSIX.1-2008 were chosen so that an application can distinguish these cases from end-of-file. While write() cannot receive an indication of end-of-file, read() can, and the two functions have similar return values. Also, some existing systems (for example, Eighth Edition) permit a write of zero bytes to mean that the reader should get an end-of-file indication; for those systems, a return value of zero from write() indicates a successful write of an end-of-file indication.

Thus, although POSIX (largely if not wholly) precludes the possibility of a zero return from write(), there was prior art on related systems that did have write() return zero.

Answer 2

It depends on what the file descriptor refers to. When you call write on a file descriptor, the kernel ultimately ends up calling the write routine in the associated file operations vector, which corresponds to the underlying file system or device that the file descriptor refers to.

Most normal file systems will never return 0, but devices might do just about anything. You need to look at the documentation for the device in question to see what it might do. It is legal for a device driver to return 0 bytes written (the kernel won't flag it as an error or anything), and if it does, the write system call will return 0.

Answer 3

Posix defines it for pipes, FIFOs, and FDs that support non-blocking operations, in the case that nbyte (the third parameter) is positive and the call wasn't interrupted:

if O_NONBLOCK is clear ... it shall return nbyte.

In other words not only can it not return 0 unless nbyte was zero, it can't return a short length either, in the cases mentioned.

Answer 4

I think that the only feasible approach (apart from ignoring the problem altogether, which seems the thing to do according to the documentation) is to allow "spinning in place".

You can implement a retry count, but if this extremely unlikely "0 return with nonzero length" is due to some transient situation - a LapLink queue full maybe; I remember that driver doing weird things - the loop will probably be so fast that any reasonable retry count would be overwhelmed anyway; and a unreasonably large retry count is not advisable in case you have other devices that instead take a non-negligible time to return 0.

So I'd try something like this. You might want to use gettimeofday() instead, for greater precision.

(We're introducing a negligible performance penalty for an event that seems to have a negligible chance of ever happening).

/** write len bytes of buf to fd, returns 0 on success */
int write_fully(int fd, char *buf, size_t len) {
  time_t timeout = 0;
  while (len > 0) {
    ssize_t written = write(fd, buf, len);
    if (written < 0) {
      // some kind of error, probably should try again if its EINTR?
      return written;
    }

      if (!written) {
          if (!timeout) {
              // First time around, set the timeout
              timeout = time(NULL) + 2; // Prepare to wait "between" 1 and 2 seconds
              // Add nanosleep() to reduce CPU load
          } else {
              if (time(NULL) >= timeout) {
                  // Weird status lasted too long
                  return -42;
              }
          }
      } else {
          timeout = 0; // reset timeout at every success, or the second zero-return after a recovery will immediately abort (which could be desirable, at that).
      }

    buf += written;
    len -= written;
  }
  return 0;
}

Answer 5

I personally use several approaches to this problem.

Below are three examples, which all expect to work on a blocking descriptor. (That is, they consider EAGAIN/EWOULDBLOCK an error.)

---

When saving important user data, without a time limit (and thus the write not supposed to be interrupted by signal delivery), I prefer to use

#define _POSIX_C_SOURCE 200809L
#include <stdlib.h>
#include <unistd.h>
#include <fcntl.h>

int write_uninterruptible(const int descriptor, const void *const data, const size_t size)
{
    const unsigned char       *p = (const unsigned char *)data;
    const unsigned char *const q = (const unsigned char *)data + size;
    ssize_t                    n;

    if (descriptor == -1)
        return errno = EBADF;

    while (p < q) {

        n = write(descriptor, p, (size_t)(q - p));
        if (n > 0)
            p += n;
        else
        if (n != -1)
            return errno = EIO;
        else
        if (errno != EINTR)
            return errno;
    }

    if (p != q)
        return errno = EIO;

    return 0;
}

This will abort if an error (other than EINTR) will occur, or if write() returns zero or a negative value other than -1.

Because there is no sane reason for the above to return the partial write count, it instead returns 0 if success, and nonzero errno error code otherwise.

---

When writing important data, but the write is to be interrupted if a signal is delivered, the interface is a bit different:

size_t write_interruptible(const int descriptor, const void *const data, const size_t size)
{
    const unsigned char       *p = (const unsigned char *)data;
    const unsigned char *const q = (const unsigned char *)data + size;
    ssize_t                    n;

    if (descriptor == -1) {
        errno = EBADF;
        return 0;
    }

    while (p < q) {

        n = write(descriptor, p, (size_t)(q - p));
        if (n > 0)
            p += n;
        else
        if (n != -1) {
            errno = EIO;
            return (size_t)(p - (const unsigned char *)data);
        } else
            return (size_t)(p - (const unsigned char *)data);
    }

    errno = 0;
    return (size_t)(p - (const unsigned char *)data);
}

In this case, the amount of data written is always returned. This version also sets errno in all cases -- normally errno is not set except in error cases.

Although this means that if an error occurs partway through, and the function will return the amount of data that was successfully written (with prior write() calls), the reason for always setting errno is to make error detection easier, essentially to separate the status (errno) from the write count.

---

Occasionally, I need a function that writes a debugging message to standard error from a signal handler. (Standard <stdio.h> I/O is not async-signal safe, so a special function is needed then in any case.) I want that function to abort even on signal delivery -- it's no big deal if the write fails, as long as it does not futz with the rest of the program --, but keep errno unchanged. This prints strings exclusively, as it is the intended use case. Note that strlen() is not async-signal safe, so an explicit loop is used instead.

int stderr_note(const char *message)
{
    int retval = 0;

    if (message && *message) {
        int         saved_errno;
        const char *ends = message;
        ssize_t     n;

        saved_errno = errno;
        while (*ends)
            ends++;

        while (message < ends) {
            n = write(STDERR_FILENO, message, (size_t)(ends - message));
            if (n > 0)
                message += n;
            else {
                if (n == -1)
                    retval = errno;
                else
                    retval = EIO;
                break;
            }
        }

        if (!retval && message != ends)
            retval = EIO;

        errno = saved_errno;
    }

    return retval;
}

This version returns 0 if the message was successfully written to standard output, and a nonzero error code otherwise. As mentioned, it always keeps errno unchanged, to avoid unexpected side effects in the main program if used in a signal handler.

---

I use very simple principles when dealing with unexpected errors or return values from syscalls. The main principle is to never silently discard or mangle user data. If data is lost or mangled, the program should always notify the user. Everything unexpected should be considered an error.

Only some of the writes in a program involve user data. A lot is informational, like usage information, or a progress report. For those, I'd prefer to either ignore the unexpected condition, or skip that write altogether. It depends on the nature of the data written.

In summary, I do not care what the standards say about the return values: I handle them all. The response to each (type of) result depends on the data being written -- specifically, the importance of that data to the user. Because of this, I do use several different implementations even in a single program.

Answer 6

I would say that the whole question is unnecessary. You are simply being too careful. You expect the file to be a regular file, not a socket, not a device, not a fifo, etc. I would say that any return from a write to a regular file that isn't equal to len is an unrecoverable error. Don't try to fix it. You probably filled the filesystem, or your disk is broken, or something like that. (this all assumes that you haven't configured your signals to interrupt system calls)

For regular files I don't know any kernel that doesn't already do all the necessary retrying to get your data written and if that fails the error is most likely severe enough that it is beyond the application to fix it. If the user decides to pass a non-regular file as argument, so what? It's their problem. Their foot and their gun, let them shoot it.

By trying to fix this in your code you are much more likely to make things worse by creating an endless loop eating CPU or filling the filesystem journal or just hang.

Don't handle 0 or other short writes, just print an error on any return other than len and exit. Once you get a proper bug report from a user that actually has a legitimate reason for the writes to fail, fix it then. Most likely this will never happen because this is what almost everyone does.

Yes, sometimes it's fun to read POSIX and find the edge cases and write code to deal with them. But operating system developers don't get sent to prison for violating POSIX, so even if your clever code perfectly matches what the standard says that is no guarantee that things will then always work. Sometimes it's better to just get things done and rely of being in good company when they break. If regular file writes start returning short you'll be in such a good company that most likely it will get fixed long before any of your users notice.

N.B. Almost 20 years ago I worked on a filesystem implementation and we tried to be standards lawyers about the behavior of one of the operations (not write, but the same principle applies). Our "it is legal to return the data in this order" was silenced by the deluge of bug reports of broken applications that expected things in a certain way and in the end it was simply faster to just fix it instead of fighting the same fight in each and every bug report. For anyone who wonders, lots of things back then (and probably still today) expected readdir to return . and .. as the first two entries in a directory which (at least back then) wasn't mandated by any standard.