1// Copyright 2012 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package exec_test
6
7import (
8	"context"
9	"encoding/json"
10	"fmt"
11	"io"
12	"log"
13	"os"
14	"os/exec"
15	"strings"
16	"time"
17)
18
19func ExampleLookPath() {
20	path, err := exec.LookPath("fortune")
21	if err != nil {
22		log.Fatal("installing fortune is in your future")
23	}
24	fmt.Printf("fortune is available at %s\n", path)
25}
26
27func ExampleCommand() {
28	cmd := exec.Command("tr", "a-z", "A-Z")
29	cmd.Stdin = strings.NewReader("some input")
30	var out strings.Builder
31	cmd.Stdout = &out
32	err := cmd.Run()
33	if err != nil {
34		log.Fatal(err)
35	}
36	fmt.Printf("in all caps: %q\n", out.String())
37}
38
39func ExampleCommand_environment() {
40	cmd := exec.Command("prog")
41	cmd.Env = append(os.Environ(),
42		"FOO=duplicate_value", // ignored
43		"FOO=actual_value",    // this value is used
44	)
45	if err := cmd.Run(); err != nil {
46		log.Fatal(err)
47	}
48}
49
50func ExampleCmd_Output() {
51	out, err := exec.Command("date").Output()
52	if err != nil {
53		log.Fatal(err)
54	}
55	fmt.Printf("The date is %s\n", out)
56}
57
58func ExampleCmd_Run() {
59	cmd := exec.Command("sleep", "1")
60	log.Printf("Running command and waiting for it to finish...")
61	err := cmd.Run()
62	log.Printf("Command finished with error: %v", err)
63}
64
65func ExampleCmd_Start() {
66	cmd := exec.Command("sleep", "5")
67	err := cmd.Start()
68	if err != nil {
69		log.Fatal(err)
70	}
71	log.Printf("Waiting for command to finish...")
72	err = cmd.Wait()
73	log.Printf("Command finished with error: %v", err)
74}
75
76func ExampleCmd_StdoutPipe() {
77	cmd := exec.Command("echo", "-n", `{"Name": "Bob", "Age": 32}`)
78	stdout, err := cmd.StdoutPipe()
79	if err != nil {
80		log.Fatal(err)
81	}
82	if err := cmd.Start(); err != nil {
83		log.Fatal(err)
84	}
85	var person struct {
86		Name string
87		Age  int
88	}
89	if err := json.NewDecoder(stdout).Decode(&person); err != nil {
90		log.Fatal(err)
91	}
92	if err := cmd.Wait(); err != nil {
93		log.Fatal(err)
94	}
95	fmt.Printf("%s is %d years old\n", person.Name, person.Age)
96}
97
98func ExampleCmd_StdinPipe() {
99	cmd := exec.Command("cat")
100	stdin, err := cmd.StdinPipe()
101	if err != nil {
102		log.Fatal(err)
103	}
104
105	go func() {
106		defer stdin.Close()
107		io.WriteString(stdin, "values written to stdin are passed to cmd's standard input")
108	}()
109
110	out, err := cmd.CombinedOutput()
111	if err != nil {
112		log.Fatal(err)
113	}
114
115	fmt.Printf("%s\n", out)
116}
117
118func ExampleCmd_StderrPipe() {
119	cmd := exec.Command("sh", "-c", "echo stdout; echo 1>&2 stderr")
120	stderr, err := cmd.StderrPipe()
121	if err != nil {
122		log.Fatal(err)
123	}
124
125	if err := cmd.Start(); err != nil {
126		log.Fatal(err)
127	}
128
129	slurp, _ := io.ReadAll(stderr)
130	fmt.Printf("%s\n", slurp)
131
132	if err := cmd.Wait(); err != nil {
133		log.Fatal(err)
134	}
135}
136
137func ExampleCmd_CombinedOutput() {
138	cmd := exec.Command("sh", "-c", "echo stdout; echo 1>&2 stderr")
139	stdoutStderr, err := cmd.CombinedOutput()
140	if err != nil {
141		log.Fatal(err)
142	}
143	fmt.Printf("%s\n", stdoutStderr)
144}
145
146func ExampleCmd_Environ() {
147	cmd := exec.Command("pwd")
148
149	// Set Dir before calling cmd.Environ so that it will include an
150	// updated PWD variable (on platforms where that is used).
151	cmd.Dir = ".."
152	cmd.Env = append(cmd.Environ(), "POSIXLY_CORRECT=1")
153
154	out, err := cmd.Output()
155	if err != nil {
156		log.Fatal(err)
157	}
158	fmt.Printf("%s\n", out)
159}
160
161func ExampleCommandContext() {
162	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
163	defer cancel()
164
165	if err := exec.CommandContext(ctx, "sleep", "5").Run(); err != nil {
166		// This will fail after 100 milliseconds. The 5 second sleep
167		// will be interrupted.
168	}
169}
170