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>

diff --git a/src/syscall/exec_bsd.go b/src/syscall/exec_bsd.go
index 30b88eba7a5b301d839cf74841f944758ef85a1e..af6c836961858111e89cfe49be6a2090c986346d 100644 (file)
--- a/src/syscall/exec_bsd.go
+++ b/src/syscall/exec_bsd.go
@@ -15,12 +15,23 @@ type SysProcAttr struct {
        Credential *Credential // Credential.
        Ptrace     bool        // Enable tracing.
        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
-       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)
-       Pgid       int         // Child's process group ID if Setpgid.
+       // 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.
 }
 
 // Implemented in runtime package.

diff --git a/src/syscall/exec_darwin.go b/src/syscall/exec_darwin.go
index ac1ead3a2b3339930e352341b183dd6ac7374ccf..f035d555535609a98b1e8ca9f60ca12212666620 100644 (file)
--- a/src/syscall/exec_darwin.go
+++ b/src/syscall/exec_darwin.go
@@ -13,12 +13,23 @@ type SysProcAttr struct {
        Credential *Credential // Credential.
        Ptrace     bool        // Enable tracing.
        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
-       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)
-       Pgid       int         // Child's process group ID if Setpgid.
+       // 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.
 }
 
 // Implemented in runtime package.

diff --git a/src/syscall/exec_libc.go b/src/syscall/exec_libc.go
index 0133139000b69b1cbdf382f366625809ad267e79..37228583252d5c7f5dba1c1b8541e50e4cc99376 100644 (file)
--- a/src/syscall/exec_libc.go
+++ b/src/syscall/exec_libc.go
@@ -16,12 +16,23 @@ type SysProcAttr struct {
        Chroot     string      // Chroot.
        Credential *Credential // Credential.
        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
-       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)
-       Pgid       int         // Child's process group ID if Setpgid.
+       // 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.
 }
 
 // Implemented in runtime package.

diff --git a/src/syscall/exec_linux.go b/src/syscall/exec_linux.go
index f32d68249388dce66817a300acbaed96467d68ac..23d7343d3adf8bda5403265775eadd75b4ee89d2 100644 (file)
--- 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)