what errors does net.Conn.Write return

According to the go documentation, the net.Conn.Write() function will return an error, if it could not send all bytes in the given slice.

How do I know which type of error is returned in this case? Should I just check if there is an error, and if n > 0 and n < len(p) ? Or is it enough to just check if n < len(p) alone? Are there unrecoverable errors for which n < len(p) ?

Say I want to send X gigabytes of data for example. What would a "correct" Write() loop look like?

If the output buffers are full, will Write() simply just block until it has sent everything from p? making a check for n < len(p) superfluous?

Well, net.Conn is an interface. This means that it is completely up to the implementation to determine which errors to send back. A TCP connection and UNIX socket connection can have very different reasons why a write can't be fully completed.

The net.Conn.Write signature is exactly the same as the io.Writer signature. Which means that every implementation of net.Conn also implements io.Writer. So you can use any existing method like io.Copy or io.CopyN to write data to a connection.

> How do I know which type of error is returned in this case? Should I just check if there is an error, and if n > 0 and n < len(p) ?

Use n < len(p) to detect the case where the write stopped early. The error is not nil in this case.

> Are there unrecoverable errors for which n < len(p) ?

Yes. A network connection can fail after some data is written.

There are also recoverable errors. If write fails because the write deadline is exceeded, a later write with a new deadline can succeed.

> Say I want to send X gigabytes of data for example. What would a "correct" Write() loop look like?

If you are asking how to write a []byte to a connection, then a loop is not needed in most cases. The Write call blocks until the data is written or an error occurs. Use this code:

_, err := c.Write(p)

If you are asking how to copy an io.Reader to a network connection, the use _, err := io.Copy(conn, r).

Write is different from Read. Read can return before filling the buffer.

> If the output buffers are full, will Write() simply just block until it has sent everything from p?

Write blocks until all data is sent or the write fails with an error (deadline exceeded, network failure, network connection closed in other goroutine, ...).

So, I went digging into the Go source code itself. I tracked the Write() call to a file named src/internal/poll/fd_unix.go.

// Write implements io.Writer.
func (fd *FD) Write(p []byte) (int, error) {
	if err := fd.writeLock(); err != nil {
		return 0, err
	}
	defer fd.writeUnlock()
	if err := fd.pd.prepareWrite(fd.isFile); err != nil {
		return 0, err
	}
	var nn int
	for {
		max := len(p)
		if fd.IsStream && max-nn > maxRW {
			max = nn + maxRW
		}
		n, err := ignoringEINTRIO(syscall.Write, fd.Sysfd, p[nn:max])
		if n > 0 {
			nn += n
		}
		if nn == len(p) {
			return nn, err
		}
		if err == syscall.EAGAIN && fd.pd.pollable() {
			if err = fd.pd.waitWrite(fd.isFile); err == nil {
				continue
			}
		}
		if err != nil {
			return nn, err
		}
		if n == 0 {
			return nn, io.ErrUnexpectedEOF
		}
	}
}

This seems to handle the retransmits already. So, Write() does actually guarantee that either everything is sent, or a fatal error occurs, which is unrecoverable.

It seems to me, that there is no need at all, to care about the value of n, other than for logging purposes. If an error ever occurs, it is severe enough that there is no reason to try and retransmit the remaining len(p)-n bytes.

The net.Conn.Write() is to implement the io.Writer interface, which has the following contract regarding errors:

> Write must return a non-nil error if it returns n < len(p).

There is no single correct write loop. For certain cases, it might be important to know how much data was written. However, for network connections, based on this contract, the following should work:

var err error
for data, done := getNextSegment(); !done&&err==nil; data, done = getNextSegment() {
  _,err=conn.Write(data)
}

To keep the total number of bytes written:

var err error
written:=0
for data, done := getNextSegment(); !done&&err==nil; data, done = getNextSegment() {
  n,err=conn.Write(data)
  written+=n
}