syscall: document exact meaning of Ctty field

The Ctty field is a child descriptor number when Setctty is set,
but a parent descriptor when Foreground is set. This is absurd
but changing either behavior breaks existing programs.

With this change we at least document how it works.

For #29458

Change-Id: If9cf0a1a1e6ed0d4a4edae5043016d5b4ee3308b
Reviewed-on: https://go-review.googlesource.com/c/go/+/229768
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>

1 files changed, 18 insertions, 7 deletions

diff --git a/src/syscall/exec_linux.go b/src/syscall/exec_linux.go
index f32d682493..23d7343d3a 100644
--- a/src/syscall/exec_linux.go
+++ b/src/syscall/exec_linux.go
@@ -25,13 +25,24 @@ type SysProcAttr struct {
 	// Ptrace tells the child to call ptrace(PTRACE_TRACEME).
 	// Call runtime.LockOSThread before starting a process with this set,
 	// and don't call UnlockOSThread until done with PtraceSyscall calls.
-	Ptrace       bool
-	Setsid       bool           // Create session.
-	Setpgid      bool           // Set process group ID to Pgid, or, if Pgid == 0, to new pid.
-	Setctty      bool           // Set controlling terminal to fd Ctty (only meaningful if Setsid is set)
-	Noctty       bool           // Detach fd 0 from controlling terminal
-	Ctty         int            // Controlling TTY fd
-	Foreground   bool           // Place child's process group in foreground. (Implies Setpgid. Uses Ctty as fd of controlling TTY)
+	Ptrace bool
+	Setsid bool // Create session.
+	// Setpgid sets the process group ID of the child to Pgid,
+	// or, if Pgid == 0, to the new child's process ID.
+	Setpgid bool
+	// Setctty sets the controlling terminal of the child to
+	// file descriptor Ctty. Ctty must be a descriptor number
+	// in the child process: an index into ProcAttr.Files.
+	// This is only meaningful if Setsid is true.
+	Setctty bool
+	Noctty  bool // Detach fd 0 from controlling terminal
+	Ctty    int  // Controlling TTY fd
+	// Foreground places the child process group in the foreground.
+	// This implies Setpgid. The Ctty field must be set to
+	// the descriptor of the controlling TTY.
+	// Unlike Setctty, in this case Ctty must be a descriptor
+	// number in the parent process.
+	Foreground   bool
 	Pgid         int            // Child's process group ID if Setpgid.
 	Pdeathsig    Signal         // Signal that the process will get when its parent dies (Linux only)
 	Cloneflags   uintptr        // Flags for clone calls (Linux only)