process

package
v1.28.1 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

README

process Package

Documentation

Index

Constants

View Source 
const (
	TCP_ESTABLISHED
	TCP_SYN_SENT
	TCP_SYN_RECV
	TCP_FIN_WAIT1
	TCP_FIN_WAIT2
	TCP_TIME_WAIT
	TCP_CLOSE
	TCP_CLOSE_WAIT
	TCP_LAST_ACK
	TCP_LISTEN
	TCP_CLOSING
	TCP_NEW_SYN_RECV
)

from linux net/tcp_states.h

Variables

This section is empty.

Functions

func AllTCPListenPorts added in v1.27.0 

func AllTCPListenPorts(h host.Host, ports map[int]int) (err error)

AllTCPListenPorts returns a map of inodes to ports for all listening TCP ports from the source (typically /proc/net/tcp or /proc/net/tcp6) on host h. Will only work on Linux hosts.

func Batch added in v1.5.2 

func Batch(h host.Host, batch []Program, options ...ProgramOption) (done chan struct{}, err error)

Batch executes the slice of Program entries using Start. If any stage returns err then Batch returns immediately. Set IgnoreErr in Program to not return errors for each stage. If any stage has Restart set and it is supported then a reaper is run and the done channel returned.

func ClearCache added in v1.28.0 

func ClearCache()

ClearCache clears the process cache for host h. This can be used to force a refresh of the cache on the next call to PID() or GetProcessInfo(). This is useful if processes are expected to have started or stopped since the last cache update, and an up to date check is required. Note that the cache is automatically refreshed every 5 seconds, so this function is only needed if an immediate refresh is required.

func Daemon 

func Daemon(writepid io.WriteCloser, extraArgs []string, processArgs func([]string, ...string) []string, args ...string) (err error)

Daemon backgrounds the current process by re-executing the existing binary (as found by os.Executable, so may there is a small window while the referenced binary can change). The function passed as processArgs is called with any further arguments passed to it as parameters and can be used to remove flags that triggered the daemonisation in the first place. A helper function - RemoveArgs - is available to do this.

The child process is executed with any extraArgs appended to the command line.

If successful the function never returns and the child process PID is written to writepid, if not nil. Remember to only open the file inside the test for daemon mode in the caller, otherwise on re-execution the file will be re-opened and overwrite the one from the parent. writepid is closed in the parent.

On failure the function does return with an error. 

process.Daemon(os.Stdout, process.RemoveArgs, "-D", "--daemon")

func GetGroupname added in v1.27.0 

func GetGroupname(gid int) (groupname string)

func GetProcessInfo added in v1.22.2 

func GetProcessInfo[T any](h host.Host, pid int, options ...ProcessOption) (pi T, err error)

GetProcessInfo returns information about the process pid on host h.

func GetUsername added in v1.27.0 

func GetUsername(uid int) (username string)

func ListeningPorts added in v1.27.0 

func ListeningPorts(h host.Host, pid int) (ports []int)

ListeningPorts returns all TCP ports currently open for the process running as the instance. An empty slice is returned if the process cannot be found. The instance may be on remote host h.

func PID added in v1.27.0 

func PID(h host.Host, executable string, args []string, options ...ProcessOption) (pid int, err error)

PID returns the PID of the process started with executable name and all args (in any order) on host h. If not found then an err of os.ErrProcessDone is returned.

A CustomChecker() function can be passed as an option to validate the args against the each process found. If the function returns true then the process is a match.

By default a process cache is used to avoid repeated calls to the host to get the process entries, which can be expensive. The cache is updated every 5 seconds, or when the cache is empty. The cache can be reset/refreshed by passing the RefreshCache() option.

func ProcessStatusListeningPorts added in v1.27.0 

func ProcessStatusListeningPorts(h host.Host, pid int, fv reflect.Value)

func ProcessStatusOpenFiles added in v1.27.0 

func ProcessStatusOpenFiles(h host.Host, pid int, fv reflect.Value)

func ProcessStatusOpenSockets added in v1.27.0 

func ProcessStatusOpenSockets(h host.Host, pid int, fv reflect.Value)

func RemoveArgs 

func RemoveArgs(in []string, remove ...string) (out []string)

RemoveArgs is a helper function for Daemon(). Daemon calls the function with os.Args[1:] and removes any arguments matching members of the slice `remove` and returns the result. Only bare arguments are removed and no pattern matching or adjacent values are removed. If more complex tests are required then pass Daemon() your own function.

func Start added in v1.5.2 

func Start(h host.Host, program Program, options ...ProgramOption) (pid int, err error)

Start runs a process on host h. It is run detached in the background unless Foreground is true.

TODO: return error windows TODO: look at remote processes

Types

type ProcessFDs added in v1.27.0 

type ProcessFDs struct {
	PID   int
	FD    int
	Path  string
	Lstat fs.FileInfo
	Stat  fs.FileInfo
	Conn  *SocketConnection
}

func OpenFiles added in v1.27.0 

func OpenFiles(h host.Host, pid int) (files []ProcessFDs)

OpenFiles returns a map of file descriptor to file details for all files for the instance. An empty map is returned if the process cannot be found.

type ProcessInfoMinimal added in v1.27.0 

type ProcessInfoMinimal struct {
	PID     int      `proc_pid_stat:"0" json:"-"`
	Exe     string   `json:"-"`
	Cmdline []string `json:"-"`
}

ProcessInfoMinimal is an example of a structure to pass to instance.ProcessStatus, using a field number for `stat` and a line prefix for `status` tags. OpenFiles and OpenSockets fields are counts of their respective names.

type ProcessOption added in v1.27.0 

type ProcessOption func(*processOptions)

func CustomChecker added in v1.27.0 

func CustomChecker(checkFunc func(checkArg any, cmdline []string) bool, checkArg any) ProcessOption

func FetchLazyFields added in v1.27.0 

func FetchLazyFields() ProcessOption

FetchLazyFields is an option to indicate that any lazy fields in the ProcessInfo should be fetched. This is useful when the caller needs to access fields that are expensive to fetch, especially on a remote host, such as the open ports.

func RefreshCache added in v1.27.0 

func RefreshCache() ProcessOption

type Program added in v1.5.2 

type Program struct {
	Executable string        `json:"executable,omitempty"` // Path to program, passed through exec.LookPath
	Username   string        `json:"username,omitempty"`   // The name of the user, if empty use current
	WorkingDir string        `json:"workingdir,omitempty"` // The working directory, defaults to home dir of user
	ErrLog     string        `json:"errlog,omitempty"`     // The name of the logfile, defaults to basename of program+".log" in Dir
	Args       []string      `json:"args,omitempty"`       // Args not including program
	Env        []string      `json:"env,omitempty"`        // Env as key=value pairs
	Foreground bool          `json:"foreground,omitempty"` // Run in foreground, to completion, return if result != 0
	Restart    bool          `json:"restart,omitempty"`    // restart on exit
	IgnoreErr  bool          `json:"ignoreerr,omitempty"`  // If true do not return err on failure
	Wait       time.Duration `json:"wait,omitempty"`       // period to wait after starting, default none
}

Program is a highly simplified representation of a program to manage with Start or Batch.

Args and Env can be either a comma delimited string, which is split by config, or a slice of strings which is used as-is

type ProgramOption added in v1.27.0 

type ProgramOption func(*programOptions)

ProgramOption for Start and Batch

func ExpandArgs added in v1.6.0 

func ExpandArgs() ProgramOption

ExpandArgs controls the expansion of the values in the Args slice. If this option is used then each element of the Args slice is passed to ExpandString with an lookup tables set using LookupTable().

func ExpandEnv added in v1.6.0 

func ExpandEnv() ProgramOption

ExpandEnv controls the expansion of the values in the Env slice. If this option is used then each element of the Env slice is passed to ExpandString with an lookup tables set using LookupTable().

func LookupTable added in v1.6.0 

func LookupTable(table map[string]string) ProgramOption

LookupTable adds a lookup map (string to string) to the set of lookup tables passed to ExpandString.

type SocketConnection added in v1.27.0 

type SocketConnection struct {
	Protocol   string
	LocalAddr  net.IP
	LocalPort  uint16
	RemoteAddr net.IP
	RemotePort uint16
	TxQueue    int64
	RxQueue    int64
	Status     string
}

func SocketToConn added in v1.27.0 

func SocketToConn(h host.Host, socket string) (sc *SocketConnection, err error)

SocketToConn takes the name of a socket from destination of a `/proc/.../fd` link and locates the corresponding connection in one of `/proc/net/tcp[6]` or `/proc/net/ucp[6]`. socket should be of the form `socket:[17126174]`

Source Files

View all Source files

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.