godaemon

func Daemonize ¶

func Daemonize(child ...bool)

Daemonize is equivalent to MakeDaemon(&DaemonAttr{}). It is kept only for backwards API compatibility, but it's usage is otherwise discouraged. Use MakeDaemon() instead. The child parameter, previously used to tell whether to reset the environment or not (see MakeDaemon()), is currently ignored. The environment is reset in all cases.

func MakeDaemon ¶

func MakeDaemon(attrs *DaemonAttr) (io.Reader, io.Reader, error)

MakeDaemon turns the process into a daemon. But given the lack of Go's support for fork(), MakeDaemon() is forced to run the process all over again, from the start. Hence, this should probably be your first call after main begins, unless you understand the effects of calling from somewhere else. Keep in mind that the PID changes after this function is called, given that it only returns in the child; the parent will exit without returning.

Options are provided as a DaemonAttr structure. In particular, setting the CaptureOutput member to true will make the function return two io.Reader streams to read the process' standard output and standard error, respectively. That's useful if you want to capture things you'd normally lose given the lack of console output for a daemon. Some libraries can write error conditions to standard error or make use of Go's log package, that defaults to standard error too. Having these streams allows you to capture them as required. (Note that this function takes no action whatsoever on any of the streams.)

NOTE: If you use them, make sure NOT to take one of these readers and write the data back again to standard output/error, or you'll end up with a loop. Also, note that data will be flushed on a line-by-line basis; i.e., partial lines will be buffered until an end-of-line is seen.

By using the Files member of DaemonAttr you can inherit open files that will still be open once the program is running as a daemon. This may be convenient in general, but it's primarily intended to avoid race conditions while forking, in case a lock (flock) was held on that file. Repeatedly releasing and re-locking while forking is subject to race conditions, cause a different process could lock the file in between. But locks held on files declared at DaemonAttr.Files are guaranteed NOT to be released during the whole process, and still be held by the daemon. To use this feature you should open the file(s), lock if required and then call MakeDaemon using pointers to that *os.File objects; i.e., you'd be passing **os.File objects to MakeDaemon(). However, opening the files (and locking if required) should only be attempted at the parent. (Recall that MakeDaemon() will run the code coming "before" it three times; see the explanation above.) You can filter that by calling Stage() and looking for a godaemon.StageParent result. The last call to MakeDaemon() at the daemon itself will actually *load* the *os.File objects for you; that's why you need to provide a pointer to them. So here's how you'd use it:

var (
	f   *os.File
	err error
)

if godaemon.Stage() == godaemon.StageParent {
	f, err = os.OpenFile(name, opts, perm)
	if err != nil {
		os.Exit(1)
	}
	err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX)
	if err != nil {
		os.Exit(1)
	}
}

_, _, err = godaemon.MakeDaemon(&godaemon.DaemonAttr{
	Files: []**os.File{&f},
})

// Only the daemon will reach this point, where f will be a valid descriptor
// pointing to your file "name", still holding the lock (which will have
// never been released during successive forks). You can operate on f as you
// normally would, like:
f.Close()

NOTE: Do not abuse this feature. Even though you could, it's obviously not a good idea to use this mechanism to keep a terminal device open, for instance. Otherwise, what you get is not strictly a daemon.

Daemonizing is a 3-stage process. In stage 0, the program increments the magical environment variable and starts a copy of itself that's a session leader, with its STDIN, STDOUT, and STDERR disconnected from any tty. It then exits.

In stage 1, the (new copy of) the program starts another copy that's not a session leader, and then exits.

In stage 2, the (new copy of) the program chdir's to /, then sets the umask and reestablishes the original value for the environment variable.

func Readlink ¶

func Readlink(name string) (string, error)

Readlink returns the file pointed to by the given soft link, or an error of type PathError otherwise. This mimics the os.Readlink() function, but works around a bug we've seen in CentOS 5.10 (kernel 2.6.27.10 on x86_64) where the underlying OS function readlink() returns a wrong number of bytes for the result (see man readlink). Here we don't rely blindly on that value; if there's a zero byte among that number of bytes, then we keep only up to that point.

NOTE: We chose not to use os.Readlink() and then search on its result to avoid an extra overhead of converting back to []byte. The function to search for a byte over the string itself (strings.IndexByte()) is only available starting with Go 1.2. Also, we're not searching at every iteration to save some CPU time, even though that could mean extra iterations for systems affected with this bug. But it's wiser to optimize for the general case (i.e., those not affected).