From a9165016b8955d5ed48c7a3c58842b579d931fc6 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Fri, 18 Sep 2015 17:45:34 -0400 Subject: Massive documentation and copyright clean-up. --- sd_daemon/doc.go | 16 ++++++++++++++++ sd_daemon/listen_fds.go | 12 ++++++++++-- sd_daemon/logger/logger.go | 32 +++++++++++++++++++++----------- sd_daemon/lsb/exit-status.go | 41 +++++++++++++++++++++++++++++------------ sd_daemon/notify.go | 23 +++++++++++++++++------ 5 files changed, 93 insertions(+), 31 deletions(-) create mode 100644 sd_daemon/doc.go diff --git a/sd_daemon/doc.go b/sd_daemon/doc.go new file mode 100644 index 0000000..665e25e --- /dev/null +++ b/sd_daemon/doc.go @@ -0,0 +1,16 @@ +// Copyright 2015 Luke Shumaker +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package sd provides APIs for systemd new-style daemons. +package sd diff --git a/sd_daemon/listen_fds.go b/sd_daemon/listen_fds.go index 45ef699..fbd2247 100644 --- a/sd_daemon/listen_fds.go +++ b/sd_daemon/listen_fds.go @@ -13,8 +13,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Package activation implements primitives for systemd socket activation. -package sd_daemon +package sd import ( "os" @@ -25,6 +24,15 @@ import ( //#include import "C" +// Returns a list of file descriptors passed in by the service manager +// as part of the socket-based activation logic. +// +// If unsetEnv is true, then (regarless of whether the function call +// itself succeeds or not) it will unset the environmental variables +// LISTEN_FDS and LISTEN_PID, which will cause further calls to this +// function to fail. +// +// In the case of an error, this function returns nil. func ListenFds(unsetEnv bool) []*os.File { if unsetEnv { defer os.Unsetenv("LISTEN_PID") diff --git a/sd_daemon/logger/logger.go b/sd_daemon/logger/logger.go index f8f3bd6..850df1c 100644 --- a/sd_daemon/logger/logger.go +++ b/sd_daemon/logger/logger.go @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +// Package logger implements a simple stderr-based logger with systemd +// log levels. package logger import ( @@ -23,15 +25,23 @@ import ( import "C" func log(level string, format string, a ...interface{}) { - f := level + format + "\n" - fmt.Fprintf(os.Stderr, f, a...) + f := level + format + "\n" + fmt.Fprintf(os.Stderr, f, a...) } - -/* system is unusable */ func Emerg( format string, a ...interface{}) { log(C.SD_EMERG , format, a...); } -/* action must be taken immediately */ func Alert( format string, a ...interface{}) { log(C.SD_ALERT , format, a...); } -/* critical conditions */ func Crit( format string, a ...interface{}) { log(C.SD_CRIT , format, a...); } -/* error conditions */ func Err( format string, a ...interface{}) { log(C.SD_ERR , format, a...); } -/* warning conditions */ func Warning(format string, a ...interface{}) { log(C.SD_WARNING, format, a...); } -/* normal but significant condition */ func Notice( format string, a ...interface{}) { log(C.SD_NOTICE , format, a...); } -/* informational */ func Info( format string, a ...interface{}) { log(C.SD_INFO , format, a...); } -/* debug-level messages */ func Debug( format string, a ...interface{}) { log(C.SD_DEBUG , format, a...); } + +// system is unusable +func Emerg( format string, a ...interface{}) { log(C.SD_EMERG , format, a...); } +// action must be taken immediately +func Alert( format string, a ...interface{}) { log(C.SD_ALERT , format, a...); } +// critical conditions +func Crit( format string, a ...interface{}) { log(C.SD_CRIT , format, a...); } +// error conditions +func Err( format string, a ...interface{}) { log(C.SD_ERR , format, a...); } +// warning conditions +func Warning(format string, a ...interface{}) { log(C.SD_WARNING, format, a...); } +// normal but significant condition +func Notice( format string, a ...interface{}) { log(C.SD_NOTICE , format, a...); } +// informational +func Info( format string, a ...interface{}) { log(C.SD_INFO , format, a...); } +// debug-level messages +func Debug( format string, a ...interface{}) { log(C.SD_DEBUG , format, a...); } diff --git a/sd_daemon/lsb/exit-status.go b/sd_daemon/lsb/exit-status.go index 41eaafd..cc1604d 100644 --- a/sd_daemon/lsb/exit-status.go +++ b/sd_daemon/lsb/exit-status.go @@ -1,3 +1,19 @@ +// Copyright 2015 Luke Shumaker +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package lsb provides constant exit codes specified by the Linux +// Standard Base. package lsb import ( @@ -5,11 +21,10 @@ import ( "sd_daemon/logger" ) -/* systemd daemon(7) recommends using the exit codes defined in the - * "LSB recomendations for SysV init scripts"[1]. - * - * [1]: http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html - */ +// systemd daemon(7) recommends using the exit codes defined in the +// "LSB recomendations for SysV init scripts"[1]. +// +// [1]: http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html const ( EXIT_SUCCESS uint8 = 0 EXIT_FAILURE uint8 = 1 @@ -19,13 +34,13 @@ const ( EXIT_NOTINSTALLED uint8 = 5 EXIT_NOTCONFIGURED uint8 = 6 EXIT_NOTRUNNING uint8 = 7 - /* 8- 99 are reserved for future LSB use */ - /* 100-149 are reserved for distribution use */ - /* 150-199 are reserved for application use */ - /* 200-254 are reserved for init system use */ + // 8- 99 are reserved for future LSB use + // 100-149 are reserved for distribution use + // 150-199 are reserved for application use + // 200-254 are reserved for init system use - /* Therefore, the following are taken from systemd's - /* `src/basic/exit-status.h` */ + // Therefore, the following are taken from systemd's + // `src/basic/exit-status.h` EXIT_CHDIR uint8 = 200 EXIT_NICE uint8 = 201 EXIT_FDS uint8 = 202 @@ -49,7 +64,7 @@ const ( EXIT_SETSID uint8 = 220 EXIT_CONFIRM uint8 = 221 EXIT_STDERR uint8 = 222 - _EXIT_RESERVED uint8 = 223 /* used to be tcpwrap don't reuse! */ + _EXIT_RESERVED uint8 = 223 // used to be tcpwrap don't reuse! EXIT_PAM uint8 = 224 EXIT_NETWORK uint8 = 225 EXIT_NAMESPACE uint8 = 226 @@ -66,6 +81,8 @@ const ( EXIT_SMACK_PROCESS_LABEL uint8 = 237 ) +// This is a utility function to defer at the beginning of a goroutine +// in order to have the correct exit code in the case of a panic. func Recover() { if r := recover(); r != nil { logger.Err("panic: %v", r) diff --git a/sd_daemon/notify.go b/sd_daemon/notify.go index a038f54..8fce6da 100644 --- a/sd_daemon/notify.go +++ b/sd_daemon/notify.go @@ -14,7 +14,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -package sd_daemon +package sd import ( "errors" @@ -22,11 +22,22 @@ import ( "os" ) -// ErrNotifyNoSocket is an error returned if no socket was specified. -var ErrNotifyNoSocket = errors.New("No socket") +// errNotifyNoSocket is an error returned if no socket was specified. +var errNotifyNoSocket = errors.New("No socket") -// Notify sends a message to the init daemon. It is common to ignore -// the error. +// Notify sends a message to the service manager aobout state +// changes. It is common to ignore the error. +// +// If unsetEnv is true, then (regarless of whether the function call +// itself succeeds or not) it will unset the environmental variable +// NOTIFY_SOCKET, which will cause further calls to this function to +// fail. +// +// The state parameter should countain a newline-separated list of +// variable assignments. +// +// See the documentation for sd_notify(3) for well-known variable +// assignments. func Notify(unsetEnv bool, state string) error { if unsetEnv { defer os.Unsetenv("NOTIFY_SOCKET") @@ -38,7 +49,7 @@ func Notify(unsetEnv bool, state string) error { } if socketAddr.Name == "" { - return ErrNotifyNoSocket + return errNotifyNoSocket } conn, err := net.DialUnix(socketAddr.Net, nil, socketAddr) -- cgit v1.1-4-g5e80