launchctlutil

README

launchctlutil

A Go library that provides functionality for working with the launchctl application and launchd.

API

The library offers a basic API for interacting with launchd via launchctl. This includes building configurations and installing them:

package main

import (
	"fmt"
	"log"

	"github.com/stephen-fox/launchctlutil"
)

func main() {
	config, err := launchctlutil.NewConfigurationBuilder().
		SetKind(launchctlutil.UserAgent).
		SetLabel("com.testing").
		SetRunAtLoad(true).
		SetCommand("echo").
		AddArgument("Hello world!").
		SetLogParentPath("/tmp").
		Build()
	if err != nil {
		log.Fatal(err.Error())
	}

	fmt.Println("Configuration contents:\n" + config.GetContents())

	err = launchctlutil.Install(config)
	if err != nil {
		log.Fatal(err.Error())
	}

	// Remove by running:
	// launchctl remove com.testing
	// rm ~/Library/LaunchAgents/com.testing.plist 
}

You can also get the status of an agent (or a daemon if running as root):

package main

import (
	"fmt"
	"log"

	"github.com/stephen-fox/launchctlutil"
)

func main() {
	details, err := launchctlutil.CurrentStatus("com.apple.Dock.agent")
	if err != nil {
		log.Fatal(err.Error())
	}

	log.Println("Status:", details.Status)

	if details.GotPid() {
		log.Println("Current PID:", details.Pid)
	}

	if details.GotLastExitStatus() {
		log.Println("Last exit status:", details.LastExitStatus)
	}
}

Documentation

Overview

Package launchctlutil provides functionality for working with the launchctl application and launchd.

Index

• Variables
• func Install(configuration Configuration) error
• func IsInstalled(configuration Configuration) (isInstalled bool, err error)
• func Remove(configPath string, kind Kind) error
• func RemoveService(label string) error
• func Start(label string, kind Kind) error
• func Stop(label string, kind Kind) error
• type Configuration
• type ConfigurationBuilder
  • func NewConfigurationBuilder() ConfigurationBuilder
• type Kind
• type Status
• type StatusDetails
  • func CurrentStatus(label string) (StatusDetails, error)
  • func (o StatusDetails) GotLastExitStatus() bool
  • func (o StatusDetails) GotPid() bool

Variables

var (
	// ExePath is the path to the launchctl CLI application.
	ExePath = defaultLaunchctl
)

Functions

func Install

func Install(configuration Configuration) error

Install installs the provided service Configuration.

func IsInstalled

func IsInstalled(configuration Configuration) (isInstalled bool, err error)

IsInstalled is a wrapper for Configuration.IsInstalled().

func Remove

func Remove(configPath string, kind Kind) error

Remove unloads and removes the specified service configuration file.

func RemoveService

func RemoveService(label string) error

RemoveService unloads the specified service by label. Note, the service will be loaded again after rebooting or logging out.

Warning: This call does not error if the specified service does not exist.

func Start

func Start(label string, kind Kind) error

Start starts the specified launchd service.

func Stop

func Stop(label string, kind Kind) error

Stop stops the specified launchd service.

Types

type Configuration

type Configuration interface {
	// GetLabel returns the Configuration's label.
	GetLabel() string

	// GetContents returns the Configuration as a string.
	GetContents() string

	// GetFilePath returns the path to the Configuration file.
	GetFilePath() (configFilePath string, err error)

	// GetKind returns the Configuration's kind.
	GetKind() Kind

	// IsInstalled returns true and a non-nil error if the Configuration
	// is installed. It returns false and a non-nil error if it is
	// not installed.
	IsInstalled() (bool, error)
}

Configuration represents a launchd configuration.

type ConfigurationBuilder

type ConfigurationBuilder interface {
	// SetLabel sets the label.
	SetLabel(label string) ConfigurationBuilder

	// SetCommand sets the command to execute.
	SetCommand(command string) ConfigurationBuilder

	// AddEnvironmentVariable adds an environment variable with
	// a given value.
	AddEnvironmentVariable(name string, value string) ConfigurationBuilder

	// AddArgument adds an argument for a command.
	AddArgument(value string) ConfigurationBuilder

	// SetLogParentPath sets the directory path where a log
	// file will be saved to. One combined log file is saved
	// containing the output of both stderr and stdout. The
	// file name is formatted as "(launchd-label).log".
	//
	// This setting overrides the settings of SetStandardErrorPath()
	// and SetStandardOutPath().
	SetLogParentPath(logParentPath string) ConfigurationBuilder

	// SetStandardErrorPath sets the file path where stderr
	// output will be saved to.
	//
	// This setting is ignored if SetLogParentPath() is used.
	SetStandardErrorPath(filePath string) ConfigurationBuilder

	// SetStandardOutPath sets the file path where stdout
	// output will be saved to.
	//
	// This setting is ignored if SetLogParentPath() is used.
	SetStandardOutPath(filePath string) ConfigurationBuilder

	// SetKind sets the type.
	SetKind(kind Kind) ConfigurationBuilder

	// SetStartInterval sets the start interval in seconds.
	SetStartInterval(seconds int) ConfigurationBuilder

	// SetStartCalendarIntervalMinute sets the minute of each hour
	// that the command will be executed. For example, setting the
	// minute to 10 will run the command at the 10th minute of each
	// hour: 01:10, 02:10, 03:10, and so on.
	SetStartCalendarIntervalMinute(minuteOfEachHour int) ConfigurationBuilder

	// SetRunAtLoad sets whether or not the service will start
	// when it is loaded.
	SetRunAtLoad(enabled bool) ConfigurationBuilder

	// SetUserName sets whether the service should run as a specific
	// user (by username).
	SetUserName(userName string) ConfigurationBuilder

	// SetGroupName sets whether the service should run as a specific
	// group (by group name).
	SetGroupName(groupName string) ConfigurationBuilder

	// SetInitGroups sets whether launchd should call the function
	// initgroups(3) before starting the servie.
	SetInitGroups(enabled bool) ConfigurationBuilder

	// SetUmask sets the umask for the service.
	SetUmask(umask int) ConfigurationBuilder

	// Build returns the resulting service Configuration.
	Build() (Configuration, error)
}

ConfigurationBuilder is used to build a new launchd service Configuration.

Example:

config, err := launchctlutil.NewConfigurationBuilder().
	SetKind(launchctlutil.UserAgent).
	SetLabel("com.testing").
	SetRunAtLoad(true).
	SetCommand("echo").
	AddArgument("Hello world!").
	SetLogParentPath("/tmp").
	Build()
if err != nil {
	log.Fatal(err.Error())
}

func NewConfigurationBuilder

func NewConfigurationBuilder() ConfigurationBuilder

NewConfigurationBuilder creates a new instance of a ConfigurationBuilder.

type Kind

type Kind int

Kind is the launchd type (e.g., a user agent).

const (
	UserAgent Kind = iota
	Daemon    Kind = iota
)

type Status

type Status string

Status represents the status of a launchd service.

const (
	Unknown      Status = "unknown"
	NotInstalled Status = "not_installed"
	Running      Status = "running"
	NotRunning   Status = "not_running"
)

type StatusDetails

type StatusDetails struct {
	Status            Status
	Pid               int
	LastExitStatus    int
	PidErr            error
	LastExitStatusErr error
}

StatusDetails provides detailed information about the status of a launchd service.

func CurrentStatus

func CurrentStatus(label string) (StatusDetails, error)

CurrentStatus returns the current status of the specified launchd service.

func (StatusDetails) GotLastExitStatus

func (o StatusDetails) GotLastExitStatus() bool

GotLastExitStatus returns true if the launchd service provided an exit status.

func (StatusDetails) GotPid

func (o StatusDetails) GotPid() bool

GotPid returns true if the launchd service provided a PID.