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.
The text was updated successfully, but these errors were encountered:
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.
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:
panic, rather than return nil
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.
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).
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.
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.
changed the title
proposal: os: make NewFile panic on bad file descriptorMay 15, 2017
changed the title
proposal: os: document that NewFile can return nil for invalid fdMay 15, 2017