helper functions added

README.md

@@ -1,14 +1,17 @@
 # systemctl
 
 This library aims at providing idiomatic `systemctl` bindings for go developers, in order to make it easier to write system tooling using golang.
+This tool tries to take guesswork out of arbitrarily shelling out to `systemctl` by providing a structured, throuroughly-tested wrapper for the `systemctl` functions most-likely to be used in a system program.
+
+If your system isn't running (or targeting another system running) `systemctl`, this library will be of little use to you.
 
 ## What is systemctl
 
-systemctl  is a command-line program which grants the user control over the systemd system and service manager.
+`systemctl` is a command-line program which grants the user control over the systemd system and service manager.
 
-systemctl may be used to introspect and control the state of the "systemd" system and service manager. Please refer to systemd(1) for an introduction into the basic concepts and functionality this tool manages.
+`systemctl` may be used to introspect and control the state of the "systemd" system and service manager. Please refer to `systemd(1)` for an introduction into the basic concepts and functionality this tool manages.
 
-## Supported functions
+## Supported systemctl functions
 
 - [ ] `systemctl is-failed`
 - [ ] `systemctl is-active`
@@ -24,6 +27,22 @@ systemctl may be used to introspect and control the state of the "systemd" syste
 - [ ] `systemctl mask`
 - [ ] `systemctl unmask`
 
+## Helper functionality
+
+- [ ] Get start time of a service (`ExecMainStartTimestamp`) as a `Time` type
+- [ ] Get current memory in bytes (`MemoryCurrent`) an an int
+- [ ] Get the PID of the main process (`MainPID`) as an int
+
+
+## Useful errors
+
+All functions return a predefinied error type, and it is highly recommended these errors are handled properly.
+
+## Context support
+
+All calls into this library support go's `context` functionality.
+Therefore, blocking calls can time out according to the callee's needs, and the returned error should be checked to see if a timeout occurred (`ErrExecTimeout`).
+
 ## TODO
 
 - [ ] Add additional bindings for systemctl options I (the author) don't use frequently (or ever) for others to use.

errors.go

@@ -19,4 +19,6 @@ var (
 	ErrDoesNotExist = errors.New("Unit does not exist")
 	// ErrUnspecified means something in the stderr output contains the word `Failed`, but not a known case
 	ErrUnspecified = errors.New("Unknown error")
+	// ErrUnitNotRunning means a function which requires a unit to be run (such as GetStartTime) was run against an inactive unit
+	ErrUnitNotRunning = errors.New("Unit isn't running")
 )

helpers.go

@@ -0,0 +1,43 @@
+package systemctl
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	"github.com/taigrr/systemctl/properties"
+)
+
+const dateFormat = "Mon 2006-01-02 15:04:05 MST"
+
+// Get start time of a service (`systemctl show [unit] --property ExecMainStartTimestamp`) as a `Time` type
+func GetStartTime(ctx context.Context, unit string, opts Options) (time.Time, error) {
+	value, err := Show(ctx, unit, properties.ExecMainStartTimestamp, opts)
+
+	if err != nil {
+		return time.Unix(0, 0), err
+	}
+	// ExecMainStartTimestamp returns an empty string if the unit is not running
+	if value == "" {
+		return time.Unix(0, 0), ErrUnitNotRunning
+	}
+	return time.Parse(dateFormat, value)
+}
+
+// Get current memory in bytes (`systemctl show [unit] --property MemoryCurrent`) an an int
+func GetMemoryUsage(ctx context.Context, unit string, opts Options) (int, error) {
+	value, err := Show(ctx, unit, properties.MemoryCurrent, opts)
+	if err != nil {
+		return -1, err
+	}
+	return strconv.Atoi(value)
+}
+
+// Get the PID of the main process (`systemctl show [unit] --property MainPID`) as an int
+func GetPID(ctx context.Context, unit string, opts Options) (int, error) {
+	value, err := Show(ctx, unit, properties.MainPID, opts)
+	if err != nil {
+		return -1, err
+	}
+	return strconv.Atoi(value)
+}