From be9135f1880ede5f3d23d917ab8c877b1a531399 Mon Sep 17 00:00:00 2001 From: Tom Laird-McConnell Date: Wed, 4 Nov 2026 08:15:20 -0800 Subject: [PATCH 1/3] Add Background(): start a process that shares nothing with the caller No window, none of the caller's handles or streams (so $(script), pipes and test harnesses are not held open), and cut loose from the terminal: its own process group on Windows (CreateProcess with bInheritHandles=FALSE, CREATE_NO_WINDOW), its own session on Linux (setsid), nohup on macOS. Returns the program's own pid. Co-Authored-By: Claude Opus 5.5 --- CShell.sln | 49 +++- README.md | 31 ++- Tests/BackgroundHost/BackgroundHost.csproj | 14 ++ Tests/BackgroundHost/Program.cs | 55 +++++ Tests/CShell.Tests/Background.Tests.cs | 191 ++++++++++++++ Tests/CShell.Tests/CShell.Tests.csproj | 2 + src/BackgroundOptions.cs | 53 ++++ src/BackgroundProcess.cs | 273 +++++++++++++++++++++ src/CShell.cs | 56 +++++ src/Globals.cs | 20 ++ 10 files changed, 741 insertions(+), 3 deletions(-) create mode 100644 Tests/BackgroundHost/BackgroundHost.csproj create mode 100644 Tests/BackgroundHost/Program.cs create mode 100644 Tests/CShell.Tests/Background.Tests.cs create mode 100644 src/BackgroundOptions.cs create mode 100644 src/BackgroundProcess.cs diff --git a/CShell.sln b/CShell.sln index fe5063c..55c351b 100644 --- a/CShell.sln +++ b/CShell.sln @@ -1,7 +1,7 @@  Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 18 -VisualStudioVersion = 18.6.11822.322 stable +VisualStudioVersion = 18.6.11822.322 MinimumVisualStudioVersion = 10.0.40219.1 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CShell", "src\CShell.csproj", "{9705E191-6CF0-4F55-B3E2-C34A81A7FE28}" EndProject @@ -18,28 +18,75 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sample", "Sample\Sample.csproj", "{945CEB6E-0534-45AE-A63E-AE8F08A850CC}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{0AB3BF05-4346-4AA6-1389-037BE0695223}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BackgroundHost", "Tests\BackgroundHost\BackgroundHost.csproj", "{D7C0AF0C-16BB-4FFF-9706-377A3395FC47}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU + Debug|x64 = Debug|x64 + Debug|x86 = Debug|x86 Release|Any CPU = Release|Any CPU + Release|x64 = Release|x64 + Release|x86 = Release|x86 EndGlobalSection GlobalSection(ProjectConfigurationPlatforms) = postSolution {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|Any CPU.Build.0 = Debug|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|x64.ActiveCfg = Debug|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|x64.Build.0 = Debug|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|x86.ActiveCfg = Debug|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Debug|x86.Build.0 = Debug|Any CPU {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|Any CPU.ActiveCfg = Release|Any CPU {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|Any CPU.Build.0 = Release|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|x64.ActiveCfg = Release|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|x64.Build.0 = Release|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|x86.ActiveCfg = Release|Any CPU + {9705E191-6CF0-4F55-B3E2-C34A81A7FE28}.Release|x86.Build.0 = Release|Any CPU {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|Any CPU.Build.0 = Debug|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|x64.ActiveCfg = Debug|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|x64.Build.0 = Debug|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|x86.ActiveCfg = Debug|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Debug|x86.Build.0 = Debug|Any CPU {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|Any CPU.ActiveCfg = Release|Any CPU {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|Any CPU.Build.0 = Release|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|x64.ActiveCfg = Release|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|x64.Build.0 = Release|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|x86.ActiveCfg = Release|Any CPU + {3EC7173A-D8DB-4CFB-B63E-CBE688AD5C3D}.Release|x86.Build.0 = Release|Any CPU {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|x64.ActiveCfg = Debug|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|x64.Build.0 = Debug|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|x86.ActiveCfg = Debug|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Debug|x86.Build.0 = Debug|Any CPU {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|Any CPU.ActiveCfg = Release|Any CPU {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|Any CPU.Build.0 = Release|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|x64.ActiveCfg = Release|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|x64.Build.0 = Release|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|x86.ActiveCfg = Release|Any CPU + {945CEB6E-0534-45AE-A63E-AE8F08A850CC}.Release|x86.Build.0 = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|Any CPU.Build.0 = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|x64.ActiveCfg = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|x64.Build.0 = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|x86.ActiveCfg = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Debug|x86.Build.0 = Debug|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|Any CPU.ActiveCfg = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|Any CPU.Build.0 = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|x64.ActiveCfg = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|x64.Build.0 = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|x86.ActiveCfg = Release|Any CPU + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47}.Release|x86.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE EndGlobalSection + GlobalSection(NestedProjects) = preSolution + {D7C0AF0C-16BB-4FFF-9706-377A3395FC47} = {0AB3BF05-4346-4AA6-1389-037BE0695223} + EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {F21757E8-6291-4BCC-AAF7-C9C0B805D67C} EndGlobalSection diff --git a/README.md b/README.md index e18a618..cc5f6cd 100644 --- a/README.md +++ b/README.md @@ -262,16 +262,18 @@ to make it even easier to work with the output of processes. | **Run(program, arg1, ..., argN)** | run a program and CAPTURE its output, for reading and piping | | **Exec()/ExecAsync(program, arg1, ..., argN)** | run a program ATTACHED to this console, returning its exit code | | **Start(program, arg1, ..., argN)** | run a DETACHED program directly with the given args (aka Process.Start(program, args)| +| **Background(program, arg1, ..., argN)** | run a program in the BACKGROUND, sharing nothing with this one, returning its process id | | **Cmd(cmd)** | run the cmd inside a cmd.exe, allow you to execute shell commands (like dir /b *.* | | **Bash(bash)** | run the program in bash environment, allow you to execute bash shell commands (like ls -al * | -Three ways to run something, and the difference is where its input and output go: +Four ways to run something, and the difference is where its input and output go: | | Output | Use it for | |---|---|---| | **Run()** | captured | anything you want to read, pipe, or parse | | **Exec()** | your console | anything the user has to see and answer | -| **Start()**| its own window | anything you are not waiting for | +| **Start()**| its own window | apps you open and leave | +| **Background()** | nowhere | servers and daemons that outlive the script | `Exec()` is what a shell does by default. In bash, `ssh host` or `vim` takes over the terminal and you opt into capture with `$(...)`; `Run()` is the other way round, so anything that needs the @@ -297,6 +299,31 @@ stdin pipe nothing will write to. Terminal settings are restored afterwards, so a program killed before it can tidy up does not leave your console with echo switched off. +`Background()` is `program &` with nohup: it returns at once with the process id, and the program +carries on after the script has finished. + +```CSharp +var pid = Background("dotnet", "MyServer.dll", "--port", "8080"); + +Background(opt => opt.WorkingDirectory(site) + .EnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development"), + "dotnet", "run"); +``` + +It shares nothing with the script that started it: + +* **No window**, and no console you can see. +* **None of the script's streams or handles.** A process holding a copy of the script's stdout keeps + whoever is reading it - `$(script)`, a pipe, a CI step, a test harness - waiting until it exits, + which for a server is never. Start() and Run() cannot promise this; Background() can. Its own + output goes nowhere, so have it write a log file if it has something to say. +* **Cut loose from the terminal.** On Windows it is in its own process group, so Ctrl+C does not + reach it; on Linux it is in its own session, so neither Ctrl+C nor closing the terminal does. + macOS has no `setsid`, so there it runs under `nohup`: it survives the terminal closing, but not a + Ctrl+C sent while the script is still running. + +The id is the program's own, for `Process.GetProcessById()` when you want to watch or stop it. + ```CSharp // Invoke multiple commands using fluent style var cmd1= await Run("cmd1", "args1") diff --git a/Tests/BackgroundHost/BackgroundHost.csproj b/Tests/BackgroundHost/BackgroundHost.csproj new file mode 100644 index 0000000..674c799 --- /dev/null +++ b/Tests/BackgroundHost/BackgroundHost.csproj @@ -0,0 +1,14 @@ + + + + + Exe + net10.0 + false + + + + + + + diff --git a/Tests/BackgroundHost/Program.cs b/Tests/BackgroundHost/Program.cs new file mode 100644 index 0000000..de38b71 --- /dev/null +++ b/Tests/BackgroundHost/Program.cs @@ -0,0 +1,55 @@ +// A helper for the Background() tests, run as its own process: +// +// report [args...] writes what it was started with to and exits: +// pid, working folder, CSHELL_BACKGROUND_TEST, Linux session id, args +// launch starts `sleep 60` of itself with Background(), prints the id it +// got back, and exits at once +// sleep sleeps + +using System; +using System.IO; +using System.Linq; +using System.Threading; +using CShellNet; + +switch (args[0]) +{ + case "report": + var lines = new[] + { + Environment.ProcessId.ToString(), + Environment.CurrentDirectory, + Environment.GetEnvironmentVariable("CSHELL_BACKGROUND_TEST") ?? "", + LinuxSession("self"), + }.Concat(args.Skip(2)); + // Written whole and then moved, so the test never reads half a file. + File.WriteAllLines(args[1] + ".tmp", lines); + File.Move(args[1] + ".tmp", args[1]); + return 0; + + case "launch": + var self = typeof(Program).Assembly.Location; + var shell = new CShell { Echo = false }; + Console.WriteLine(shell.Background(Environment.ProcessPath, self, "sleep", "60")); + return 0; + + case "sleep": + Thread.Sleep(TimeSpan.FromSeconds(int.Parse(args[1]))); + return 0; + + default: + return 2; +} + +// The session id from /proc//stat: the fourth field after the parenthesised name. +static string LinuxSession(string pid) +{ + var stat = $"/proc/{pid}/stat"; + if (!File.Exists(stat)) + { + return ""; + } + + var text = File.ReadAllText(stat); + return text.Substring(text.LastIndexOf(')') + 2).Split(' ')[3]; +} diff --git a/Tests/CShell.Tests/Background.Tests.cs b/Tests/CShell.Tests/Background.Tests.cs new file mode 100644 index 0000000..1229196 --- /dev/null +++ b/Tests/CShell.Tests/Background.Tests.cs @@ -0,0 +1,191 @@ +using CShellNet; +using Microsoft.VisualStudio.TestTools.UnitTesting; +using System; +using System.ComponentModel; +using System.Diagnostics; +using System.IO; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; + +namespace CShellLibTests +{ + /// + /// Background() returns at once with nothing to read, so these run the BackgroundHost helper, + /// which writes down what it was started with, and check the file it leaves behind. + /// + [TestClass] + public class BackgroundTests + { + private static string DotNet => Environment.GetEnvironmentVariable("DOTNET_HOST_PATH") ?? "dotnet"; + + private static string Host => Path.Combine(AppContext.BaseDirectory, "BackgroundHost.dll"); + + private string tempFolder; + private string originalFolder; + + [TestInitialize] + public void Init() + { + this.originalFolder = Environment.CurrentDirectory; + this.tempFolder = Path.Combine(Path.GetTempPath(), "cshell-background-" + Guid.NewGuid().ToString("N")); + Directory.CreateDirectory(this.tempFolder); + } + + [TestCleanup] + public void Cleanup() + { + // new CShell(folder) moves this whole process into the folder. Unix lets it be deleted + // from under us, after which every later test fails to read its current directory. + Environment.CurrentDirectory = this.originalFolder; + try + { + Directory.Delete(this.tempFolder, true); + } + catch + { + } + } + + // Report lines: pid, working folder, CSHELL_BACKGROUND_TEST, Linux session, then the args. + private static string[] ReadReport(string file) + { + var deadline = DateTime.UtcNow + TimeSpan.FromSeconds(30); + while (!File.Exists(file)) + { + Assert.IsTrue(DateTime.UtcNow < deadline, "the background process never wrote its report"); + Thread.Sleep(50); + } + + return File.ReadAllLines(file); + } + + private static void TryKill(int pid) + { + try + { + using var process = Process.GetProcessById(pid); + process.Kill(); + } + catch + { + // Already gone. + } + } + + [TestMethod] + public void Background_ReturnsTheProgramsOwnId_InTheShellsFolder_WithItsEnvironment() + { + var shell = new CShell(this.tempFolder) { Echo = false }; + + var pid = shell.Background( + opt => opt.EnvironmentVariable("CSHELL_BACKGROUND_TEST", "hello"), + DotNet, Host, "report", "report.txt"); + + // A relative path, so finding the file at all shows which folder it ran in. + var report = ReadReport(Path.Combine(this.tempFolder, "report.txt")); + Assert.AreEqual(pid.ToString(), report[0], "the id returned should be the program's own"); + StringAssert.EndsWith(report[1], Path.GetFileName(this.tempFolder)); + Assert.AreEqual("hello", report[2]); + } + + [TestMethod] + public void Background_WorkingDirectoryOptionWins() + { + var shell = new CShell() { Echo = false }; + + shell.Background(opt => opt.WorkingDirectory(this.tempFolder), DotNet, Host, "report", "where.txt"); + + ReadReport(Path.Combine(this.tempFolder, "where.txt")); + } + + [TestMethod] + public void Background_ArgumentsArriveExactlyAsGiven() + { + var shell = new CShell(this.tempFolder) { Echo = false }; + var arguments = new[] { "plain", "two words", "", "a \"quoted\" word", "trailing\\", "back\\\\\"slashes", "C:\\Program Files\\x", "tab\there", "ünïcödé" }; + + shell.Background(DotNet, new object[] { Host, "report", "args.txt" }.Concat(arguments).ToArray()); + + var report = ReadReport(Path.Combine(this.tempFolder, "args.txt")); + CollectionAssert.AreEqual(arguments, report.Skip(4).ToArray()); + } + + [TestMethod] + public async Task Background_HoldsNoneOfTheCallersStreams() + { + // The helper starts a 60 second sleep in the background and exits. Reading its output + // to the end only finishes promptly if the sleep holds no copy of that output. + var startInfo = new ProcessStartInfo(DotNet) + { + UseShellExecute = false, + RedirectStandardInput = true, + RedirectStandardOutput = true, + RedirectStandardError = true, + }; + startInfo.ArgumentList.Add(Host); + startInfo.ArgumentList.Add("launch"); + + using var launcher = Process.Start(startInfo); + var stderr = launcher.StandardError.ReadToEndAsync(); + var stdout = launcher.StandardOutput.ReadToEndAsync(); + + var finished = await Task.WhenAny(Task.WhenAll(stdout, stderr), Task.Delay(TimeSpan.FromSeconds(20))); + var pidText = stdout.IsCompleted ? stdout.Result.Trim() : null; + try + { + Assert.IsTrue(stdout.IsCompleted && stderr.IsCompleted, + "reading the caller's output should end when the caller exits, not when the background process does"); + Assert.AreEqual("", await stderr); + + using var sleeper = Process.GetProcessById(int.Parse(pidText)); + Assert.IsFalse(sleeper.HasExited, "the background process should still be running"); + } + finally + { + if (int.TryParse(pidText, out var pid)) + { + TryKill(pid); + } + } + } + + [TestMethod] + public void Background_RunsInItsOwnSessionOnLinux() + { + if (!OperatingSystem.IsLinux()) + { + Assert.Inconclusive("sessions are checked on Linux only"); + } + + var shell = new CShell(this.tempFolder) { Echo = false }; + shell.Background(DotNet, Host, "report", "session.txt"); + + var report = ReadReport(Path.Combine(this.tempFolder, "session.txt")); + var stat = File.ReadAllText("/proc/self/stat"); + var ourSession = stat.Substring(stat.LastIndexOf(')') + 2).Split(' ')[3]; + Assert.AreNotEqual(ourSession, report[3], "the background process should have a session of its own"); + Assert.AreEqual(report[0], report[3], "it should lead its own session, as setsid makes it"); + } + + [TestMethod] + public void Background_UnknownProgramThrows() + { + var shell = new CShell() { Echo = false }; + + Assert.ThrowsExactly(() => shell.Background("this-program-does-not-exist-cshell-test")); + } + + [TestMethod] + public void BackgroundGlobal_ReturnsTheProgramsOwnId() + { + CShellNet.Globals.ResetShell(); + CShellNet.Globals.Echo = false; + var file = Path.Combine(this.tempFolder, "global.txt"); + + var pid = CShellNet.Globals.Background(DotNet, Host, "report", file); + + Assert.AreEqual(pid.ToString(), ReadReport(file)[0]); + } + } +} diff --git a/Tests/CShell.Tests/CShell.Tests.csproj b/Tests/CShell.Tests/CShell.Tests.csproj index 87edf84..68cdef2 100644 --- a/Tests/CShell.Tests/CShell.Tests.csproj +++ b/Tests/CShell.Tests/CShell.Tests.csproj @@ -14,6 +14,8 @@ + + diff --git a/src/BackgroundOptions.cs b/src/BackgroundOptions.cs new file mode 100644 index 0000000..db95a60 --- /dev/null +++ b/src/BackgroundOptions.cs @@ -0,0 +1,53 @@ +using System.Collections.Generic; + +namespace CShellNet +{ + /// + /// Options for . + /// + /// + /// Smaller still than ExecOptions. A background process has no streams to redirect and is not + /// waited for, so there is nothing to cancel either. What is left is where it runs and what + /// environment it gets. + /// + public class BackgroundOptions + { + internal string workingDirectory; + internal Dictionary environment = new Dictionary(); + + /// + /// Run in this folder instead of the shell's current folder. + /// + public BackgroundOptions WorkingDirectory(string path) + { + this.workingDirectory = path; + return this; + } + + /// + /// Set an environment variable for the process, on top of the ones it inherits. A null + /// value removes the variable instead. + /// + public BackgroundOptions EnvironmentVariable(string name, string value) + { + this.environment[name] = value; + return this; + } + + /// + /// Set several environment variables for the process. + /// + public BackgroundOptions EnvironmentVariables(IEnumerable> variables) + { + if (variables != null) + { + foreach (var variable in variables) + { + this.environment[variable.Key] = variable.Value; + } + } + + return this; + } + } +} diff --git a/src/BackgroundProcess.cs b/src/BackgroundProcess.cs new file mode 100644 index 0000000..62bd91a --- /dev/null +++ b/src/BackgroundProcess.cs @@ -0,0 +1,273 @@ +using System; +using System.Collections; +using System.Collections.Generic; +using System.ComponentModel; +using System.Diagnostics; +using System.IO; +using System.Linq; +using System.Runtime.InteropServices; +using System.Text; + +namespace CShellNet +{ + /// + /// Starts a process that shares nothing with the one starting it: no window, none of its open + /// handles or streams, and nothing that ties it to its terminal. + /// + /// + /// Process.Start cannot do this on its own. On Windows it always creates the child with + /// bInheritHandles=TRUE, so the child holds a copy of every inheritable handle the parent has + /// open -- including the stdout pipe of whoever is capturing the parent's output, which then + /// never sees end-of-file until the child exits. On Unix the child gets the parent's stdin, + /// stdout and stderr, and stays in the parent's session, so it is signalled when the terminal + /// closes. + /// + internal static class BackgroundProcess + { + public static int Start(string executable, IEnumerable arguments, string workingDirectory, IDictionary environment) + { + return OperatingSystem.IsWindows() + ? StartWindows(executable, arguments, workingDirectory, environment) + : StartUnix(executable, arguments, workingDirectory, environment); + } + + // ---------------------------------------------------------------- Unix + + // Runs as `sh -c