shell

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package shell runs external programs. Commands are built as argv values by typed builders (never as shell strings), so paths with spaces or quotes are passed through untouched and nothing is interpreted by a shell.

Index

Constants

View Source 
const MpvpaperAllOutputs = "ALL"

MpvpaperAllOutputs plays on every output.

View Source 
const XwinwrapWID = "WID"

XwinwrapWID is the argument xwinwrap replaces with the ID of its window.

Variables

This section is empty.

Functions

func ExitCode 

func ExitCode(err error) int

ExitCode returns 0 for a nil error, the exit status for an *ExitError, and -1 for any other error (e.g. the program could not be started).

func IsRunning 

func IsRunning(r Runner, name string) bool

IsRunning reports whether this user runs a process named exactly name.

func KillByName 

func KillByName(r Runner, name string) error

KillByName runs Pkill(name) and treats "no process matched" (exit 1) as success.

Types

type Cmd 

type Cmd struct {
	Name string
	Args []string
}

Cmd is an immutable program invocation: a program name and its arguments.

func Command 

func Command(name string, args ...string) Cmd

Command builds a Cmd from a program name and arguments.

func Pgrep 

func Pgrep(name string) Cmd

Pgrep matches this user's processes named exactly name.

func PgrepList 

func PgrepList(name string) Cmd

PgrepList lists this user's processes named exactly name, one per line: the PID, a space, then the command line with its arguments joined by spaces. It is for callers that must see how a process was started.

func Pkill 

func Pkill(name string) Cmd

Pkill kills this user's processes named exactly name.

func XrandrCurrent 

func XrandrCurrent() Cmd

XrandrCurrent lists the current outputs without probing for new ones.

func (Cmd) Argv 

func (c Cmd) Argv() []string

Argv returns the name followed by the arguments.

func (Cmd) String 

func (c Cmd) String() string

String renders the command for logs, quoting arguments a shell would split. It is for humans only: commands are never executed through a shell.

type Exec 

type Exec struct {
	// Log, when set, receives every long-running command started. Short
	// commands (checks, gsettings...) are not logged; their failures are
	// returned as errors.
	Log *log.Logger
}

Exec is the real Runner, backed by os/exec.

func (Exec) KillGroup 

func (Exec) KillGroup(pid int)

func (Exec) LookPath 

func (Exec) LookPath(program string) error

func (Exec) Output 

func (e Exec) Output(c Cmd) (string, error)

func (Exec) ProcessIdentity 

func (Exec) ProcessIdentity(pid int) string

ProcessIdentity is "<boot_id>:<starttime>": the kernel's random ID for this boot and the process's start time in clock ticks since boot, which exec does not change.

func (Exec) ProcessName 

func (Exec) ProcessName(pid int) string

func (Exec) Run 

func (e Exec) Run(c Cmd) error

func (Exec) Start 

func (e Exec) Start(c Cmd) (int, error)

type ExitError 

type ExitError struct {
	Cmd    Cmd
	Code   int
	Output string
}

ExitError reports a command that exited with a non-zero status.

func (*ExitError) Error 

func (e *ExitError) Error() string

type MpvBuilder 

type MpvBuilder struct {
	// contains filtered or unexported fields
}

MpvBuilder builds mpv invocations. Options are kept without their leading "--" so the same set can be handed to mpvpaper's -o.

func Mpv 

func Mpv() MpvBuilder

Mpv starts an mpv command.

func (MpvBuilder) Build 

func (b MpvBuilder) Build() Cmd

Build returns the mpv command. The file comes after "--" so a path that starts with "-" is never parsed as an option.

func (MpvBuilder) Embed 

func (b MpvBuilder) Embed(wid string) MpvBuilder

Embed draws into an existing X11 window. wid may be XwinwrapWID, which xwinwrap replaces with its window ID.

func (MpvBuilder) File 

func (b MpvBuilder) File(path string) MpvBuilder

File sets the media to play.

func (MpvBuilder) Loop 

func (b MpvBuilder) Loop() MpvBuilder

func (MpvBuilder) NoAudio 

func (b MpvBuilder) NoAudio() MpvBuilder

func (MpvBuilder) NoResumePlayback 

func (b MpvBuilder) NoResumePlayback() MpvBuilder

func (MpvBuilder) Option 

func (b MpvBuilder) Option(opt string) MpvBuilder

Option adds a raw mpv option, without the leading "--" (e.g. "hwdec=auto").

func (MpvBuilder) Options 

func (b MpvBuilder) Options() []string

Options returns the options without leading dashes, in insertion order.

func (MpvBuilder) Panscan 

func (b MpvBuilder) Panscan(v float64) MpvBuilder

Panscan sets how much of the video may be cropped to fill the screen (0..1).

type MpvpaperBuilder 

type MpvpaperBuilder struct {
	// contains filtered or unexported fields
}

MpvpaperBuilder builds mpvpaper invocations (wlr-layer-shell compositors).

func Mpvpaper 

func Mpvpaper() MpvpaperBuilder

Mpvpaper starts an mpvpaper command.

func (MpvpaperBuilder) Build 

func (b MpvpaperBuilder) Build() Cmd

func (MpvpaperBuilder) File 

func (b MpvpaperBuilder) File(path string) MpvpaperBuilder

func (MpvpaperBuilder) MpvOptions 

func (b MpvpaperBuilder) MpvOptions(opts ...string) MpvpaperBuilder

MpvOptions passes mpv options (as returned by MpvBuilder.Options) via -o.

func (MpvpaperBuilder) Output 

func (b MpvpaperBuilder) Output(name string) MpvpaperBuilder

Output selects the output (e.g. "DP-1"); defaults to all outputs.

type Runner 

type Runner interface {
	// Run runs c to completion. A non-zero exit returns an *ExitError that
	// carries the combined output.
	Run(c Cmd) error
	// Output runs c and returns its trimmed stdout.
	Output(c Cmd) (string, error)
	// Start launches c detached, in its own process group, with no stdio,
	// and returns its PID without waiting for it.
	Start(c Cmd) (int, error)
	// KillGroup SIGKILLs the process group led by pid. It does nothing when
	// pid no longer leads its own group: Start always creates a group, so
	// such a PID was reused by an unrelated process.
	KillGroup(pid int)
	// ProcessName returns the kernel's name for pid (truncated to 15 bytes,
	// as in /proc/<pid>/comm), or "" when it is unknown or pid is gone.
	ProcessName(pid int) string
	// ProcessIdentity returns a token that tells pid's process apart from
	// any other that has had or will have the same PID, even across a
	// reboot. Unlike the name it survives exec, so it still matches after a
	// wrapper (env, nice, prime-run...) replaces itself with the player. It
	// returns "" when the identity is unknown or pid is gone.
	ProcessIdentity(pid int) string
	// LookPath returns an error when program is not installed.
	LookPath(program string) error
}

Runner is the port through which lazywal touches the operating system. Backends depend on this interface, never on os/exec, so they can be tested with shelltest.Fake and never touch the real desktop in tests.

type Store 

type Store interface {
	Get(key string) string
	Set(key, value string)
}

Store is a persistent string key/value store (bonzai's injson persister satisfies it). It lets a later lazywal process find what an earlier one started.

type Tracker 

type Tracker struct {
	Runner Runner
	Store  Store
	Key    string
	// Legacy lists the kernel process names (as in /proc/<pid>/comm) under
	// which a bare "pid" entry, written by lazywal <= v1.4.3 without an
	// identity, is still killed. Nil drops such entries without killing.
	Legacy []string
}

Tracker starts long-running processes (wallpaper players) and remembers them under Key, so a later Set or Clear can kill them.

Entries are stored as "pid/identity", with the Runner's ProcessIdentity read right after Start. KillAll only kills a PID whose identity is unchanged, so a PID reused by an unrelated process (even after a reboot) is never killed, while a player started through a wrapper that execs it (env, nice, prime-run...) still is.

func (Tracker) KillAll 

func (t Tracker) KillAll()

KillAll kills every tracked process group that is still ours and forgets them all. A process that is gone or whose PID was reused is skipped.

func (Tracker) PIDs 

func (t Tracker) PIDs() []int

PIDs returns the tracked process IDs.

func (Tracker) Spawn 

func (t Tracker) Spawn(c Cmd) (int, error)

Spawn starts c detached and tracks its PID and identity. The identity may be empty (e.g. the process already exited); KillAll then only kills the PID while its identity is still unknown.

type XwinwrapBuilder 

type XwinwrapBuilder struct {
	// contains filtered or unexported fields
}

XwinwrapBuilder builds xwinwrap invocations that wrap another command.

func Xwinwrap 

func Xwinwrap() XwinwrapBuilder

Xwinwrap starts an xwinwrap command.

func (XwinwrapBuilder) Below 

func (b XwinwrapBuilder) Below() XwinwrapBuilder

func (XwinwrapBuilder) Debug 

func (b XwinwrapBuilder) Debug() XwinwrapBuilder

func (XwinwrapBuilder) DesktopType 

func (b XwinwrapBuilder) DesktopType() XwinwrapBuilder

DesktopType marks the window as _NET_WM_WINDOW_TYPE_DESKTOP so a desktop environment's window manager keeps it under its panels.

func (XwinwrapBuilder) Geometry 

func (b XwinwrapBuilder) Geometry(width, height, x, y int) XwinwrapBuilder

Geometry places the window: width x height at x,y.

func (XwinwrapBuilder) IgnoreInput 

func (b XwinwrapBuilder) IgnoreInput() XwinwrapBuilder

func (XwinwrapBuilder) NoFocus 

func (b XwinwrapBuilder) NoFocus() XwinwrapBuilder

func (XwinwrapBuilder) Opacity 

func (b XwinwrapBuilder) Opacity(v float64) XwinwrapBuilder

Opacity sets the window opacity (0..1).

func (XwinwrapBuilder) OverrideRedirect 

func (b XwinwrapBuilder) OverrideRedirect() XwinwrapBuilder

OverrideRedirect makes the window unmanaged by the window manager. Right for bare window managers (xmonad, i3...); on desktops with panels it covers the panels.

func (XwinwrapBuilder) SkipPager 

func (b XwinwrapBuilder) SkipPager() XwinwrapBuilder

func (XwinwrapBuilder) SkipTaskbar 

func (b XwinwrapBuilder) SkipTaskbar() XwinwrapBuilder

func (XwinwrapBuilder) Sticky 

func (b XwinwrapBuilder) Sticky() XwinwrapBuilder

func (XwinwrapBuilder) Undecorated 

func (b XwinwrapBuilder) Undecorated() XwinwrapBuilder

func (XwinwrapBuilder) Wrap 

func (b XwinwrapBuilder) Wrap(inner Cmd) Cmd

Wrap returns xwinwrap running inner inside its window.

Source Files

View all Source files

Directories

Path Synopsis
Package shelltest provides a fake shell.Runner and an in-memory shell.Store so backends can be tested without touching the real system.
 Package shelltest provides a fake shell.Runner and an in-memory shell.Store so backends can be tested without touching the real system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.