os: add precondition doc for Create and OpenFile

Fixes #69836

Change-Id: Ide243c2aa9c6f9d45976f728f97e32c4fbadb720
Reviewed-on: https://go-review.googlesource.com/c/go/+/619316
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

diff --git a/src/os/file.go b/src/os/file.go
index 48bc4101f660325a311d9c77030da4a5bba1e194..0341469e2d84a2c3e8129df7cde4259a88da10b6 100644 (file)
--- a/src/os/file.go
+++ b/src/os/file.go
@@ -374,6 +374,7 @@ func Open(name string) (*File, error) {
 // it is truncated. If the file does not exist, it is created with mode 0o666
 // (before umask). If successful, methods on the returned File can
 // be used for I/O; the associated file descriptor has mode O_RDWR.
+// The directory containing the file must already exist.
 // If there is an error, it will be of type *PathError.
 func Create(name string) (*File, error) {
        return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
@@ -382,7 +383,8 @@ func Create(name string) (*File, error) {
 // OpenFile is the generalized open call; most users will use Open
 // or Create instead. It opens the named file with specified flag
 // (O_RDONLY etc.). If the file does not exist, and the O_CREATE flag
-// is passed, it is created with mode perm (before umask). If successful,
+// is passed, it is created with mode perm (before umask);
+// the containing directory must exist. If successful,
 // methods on the returned File can be used for I/O.
 // If there is an error, it will be of type *PathError.
 func OpenFile(name string, flag int, perm FileMode) (*File, error) {