From 22e8f82e8d4b62a4c96a82d4f731606a87db8d09 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Fri, 13 Sep 2013 15:43:54 -0400 Subject: [PATCH] os/exec: add more caveats to StdoutPipe, StderrPipe (StdinPipe was taken care of by CL 13329043.) Fixes #6008. R=golang-dev, iant CC=golang-dev https://golang.org/cl/13606046 --- src/pkg/os/exec/exec.go | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/pkg/os/exec/exec.go b/src/pkg/os/exec/exec.go index 582930f2c4..491cc242bb 100644 --- a/src/pkg/os/exec/exec.go +++ b/src/pkg/os/exec/exec.go @@ -358,8 +358,10 @@ func (c *Cmd) CombinedOutput() ([]byte, error) { // StdinPipe returns a pipe that will be connected to the command's // standard input when the command starts. -// If the returned WriteCloser is not closed before Wait is called, -// Wait will close it. +// The pipe will be closed automatically after Wait sees the command exit. +// A caller need only call Close to force the pipe to close sooner. +// For example, if the command being run will not exit until standard input +// is closed, the caller must close the pipe. func (c *Cmd) StdinPipe() (io.WriteCloser, error) { if c.Stdin != nil { return nil, errors.New("exec: Stdin already set") @@ -394,7 +396,12 @@ func (c *closeOnce) Close() error { // StdoutPipe returns a pipe that will be connected to the command's // standard output when the command starts. -// The pipe will be closed automatically after Wait sees the command exit. +// +// Wait will close the pipe after seeing the command exit, so most callers +// need not close the pipe themselves; however, an implication is that +// it is incorrect to call Wait before all reads from the pipe have completed. +// For the same reason, it is incorrect to call Run when using StdoutPipe. +// See the example for idiomatic usage. func (c *Cmd) StdoutPipe() (io.ReadCloser, error) { if c.Stdout != nil { return nil, errors.New("exec: Stdout already set") @@ -414,7 +421,12 @@ func (c *Cmd) StdoutPipe() (io.ReadCloser, error) { // StderrPipe returns a pipe that will be connected to the command's // standard error when the command starts. -// The pipe will be closed automatically after Wait sees the command exit. +// +// Wait will close the pipe after seeing the command exit, so most callers +// need not close the pipe themselves; however, an implication is that +// it is incorrect to call Wait before all reads from the pipe have completed. +// For the same reason, it is incorrect to use Run when using StderrPipe. +// See the StdoutPipe example for idiomatic usage. func (c *Cmd) StderrPipe() (io.ReadCloser, error) { if c.Stderr != nil { return nil, errors.New("exec: Stderr already set") -- 2.50.0