os: document that NewFile can return nil for invalid fd

[ghost]

Since the os.NewFile function does not return an error value, one might assume that the function always returns a non-nil value. A line in the docs saying otherwise might save some users a little grief.

[davecheney]

I don't think this is a documentation bug; NewFile can only return nil if someone passes a negative value. Given we cannot change the signature now, I argue this method should panic, as the construction of an invalid value of fd is a programming error.

[ALTree]

panic or nil, the doc should say "panics / returns nil when..". The fact that panicing is better than returning nil is a differe issue IMHO.

[ALTree]

Noting in the doc that NewFile can return nil "when the file descriptor uint is not valid" is band-aid; dave wrote on CL 41211:

I don't think this is an improvement. What is an invalid file descriptor? Is it a number larger than ulimit -n? Is it something that was obtained from os.File.Fd() and since closed? Is it a negative fd number? technically yes, but given the function accepts unsigned values.

I think that rather than getting stuck in a documentation rabbit hole, we should do either:

1. panic, rather than return nil
2. or, return some *os.File that is already closed.

Moving this to Proposal as suggested to decide if a (vague) doc addition is enough or we also should change the function to panic instead.

[gopherbot]

CL https://golang.org/cl/41211 mentions this issue.

[rsc]

It has always behaved this way (return nil for fd < 0, back to 2008), but it does seem weird that fd=-1 is handled differently from fd=1e9. Perhaps we should return a non-nil *File that returns an appropriate error from future operations (whatever happens when you use the fd later).

[rsc]

Actually, all the methods already return ErrInvalid for nil *File and the docs for ErrInvalid already say "methods on File will return this error when the receiver is nil". So maybe this is fine and just a doc update is needed.

[rsc]

Based on discussion with @golang/proposal-review (reflected above), the doc change seems to be the best, least disruptive path forward. Since nil is usable and has been forever, it seems OK to continue that and just document how it happens.