include/security_utilities/unixchild.cpp

/*
 * Copyright (c) 2000-2001,2003-2004 Apple Computer, Inc. All Rights Reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */


//
// unixchild - low-level UNIX process child management.
//
// Note that the map-of-children (mChildren) only holds children presumed to
// be alive. Neither unborn nor dead children are included. This is important
// for how children are reaped and death notifications dispatched, and should
// not be changed without prior deep contemplation.
//
// A note on locking:
// All Child objects in this subsystem are mutated under control of a single
// lock (mChildren). This means that children will not step on each other.
// However, death callbacks (Child::dying) are made outside the lock's scope
// to avoid deadlock scenarios with outside locking hierarchies. When Child::dying
// is called, the child has already transitioned to "dead" state and is no longer
// in the (live) children map.
//
#include "unixchild.h"
#include <security_utilities/debugging.h>
#include <signal.h>


namespace Security {
namespace UnixPlusPlus {


//
// All our globals are in a ModuleNexus, for that special lazy-init goodness
//
ModuleNexus<Child::Children> Child::mChildren;


//
// Make and break Children
//
Child::Child()
	: mState(unborn), mPid(0), mStatus(0)
{
}


Child::~Child()
{
	assert(mState != alive);	// not allowed by protocol
}


//
// Take a Child object that is not alive (i.e. is either unborn or dead),
// and reset it to unborn, so you can fork() it again.
// This call forgets everything about the previous process.
//
void Child::reset()
{
	switch (mState) {
	case alive:
		assert(false);		// bad boy; can't do that
	case unborn:
		break;				// s'okay
	default:
		secdebug("unixchild", "%p reset (from state %d)", this, mState);
		mState = unborn;
		mPid = 0;
		mStatus = 0;
		break;
	}
}


//
// Global inquiries and setup
//
void Child::sharedChildren(bool s)
{
	StLock<Mutex> _(mChildren());
	mChildren().shared = s;
}

bool Child::sharedChildren()
{
	StLock<Mutex> _(mChildren());
	return mChildren().shared;
}


//
// Check status for one Child
//
Child::State Child::check()
{
	Child::State state;
	bool reaped = false;
	{
		StLock<Mutex> _(mChildren());
		state = mState;
		switch (mState) {
		case alive:
			reaped = checkStatus(WNOHANG);
			break;
		default:
			break;
		}
	}
	if (reaped)
		this->dying();
	return state;
}


//
// Wait for a particular child to be dead.
// This call cannot wait for multiple children; you'll have
// to program that yourself using whatever event loop you're using.
//
void Child::wait()
{
	bool reaped = false;
	{
		StLock<Mutex> _(mChildren());
		switch (mState) {
		case alive:
			reaped = checkStatus(0);	// wait for it
			break;
		case unborn:
			assert(false);		// don't do that
		default:
			break;
		}
	}
	if (reaped)
		this->dying();
}


//
// Common kill code.
// Requires caller to hold mChildren() lock.
//
void Child::tryKill(int signal)
{
	assert(mState == alive);	// ... or don't bother us
	secdebug("unixchild", "%p (pid %d) sending signal(%d)", this, pid(), signal);
	if (::kill(pid(), signal))
		switch (errno) {
		case ESRCH: // someone else reaped ths child; or things are just wacky
			secdebug("unixchild", "%p (pid %d) has disappeared!", this, pid());
			mState = invalid;
			mChildren().erase(pid());
			// fall through
		default:
			UnixError::throwMe();
		}
}


//
// Send a signal to the Child.
// This will succeed (and do nothing) if the Child is not alive.
//
void Child::kill(int signal)
{
	StLock<Mutex> _(mChildren());
	if (mState == alive)
		tryKill(signal);
	else
		secdebug("unixchild", "%p (pid %d) not alive; cannot send signal %d",
			this, pid(), signal);
}


//
// Kill with prejudice.
// This will make a serious attempt to *synchronously* kill the process before
// returning. If that doesn't work for some reason, abandon the child.
// This is one thing you can do in the destructor of your subclass to legally
// dispose of your Child's process.
//
void Child::kill()
{
	// note that we mustn't hold the lock across these calls
	if (this->state() == alive) {
		this->kill(SIGTERM);				// shoot it once
		checkChildren();					// check for quick death
		if (this->state() == alive) {
			usleep(200000);					// give it some time to die
			if (this->state() == alive) {	// could have been reaped by another thread
				checkChildren();			// check again
				if (this->state() == alive) {	// it... just... won't... die...
					this->kill(SIGKILL);	// take THAT!
					checkChildren();
					if (this->state() == alive) // stuck zombie
						this->abandon();	// leave the body behind
				}
			}
		}
	} else
		secdebug("unixchild", "%p (pid %d) not alive; ignoring request to kill it", this, pid());
}


//
// Take a living child and cut it loose. This sets its state to abandoned
// and removes it from the child registry.
// This is one thing you can do in the destructor of your subclass to legally
// dispose of your child's process.
//
void Child::abandon()
{
	StLock<Mutex> _(mChildren());
	if (mState == alive) {
		secdebug("unixchild", "%p (pid %d) abandoned", this, pid());
		mState = abandoned;
		mChildren().erase(pid());
	} else {
		secdebug("unixchild", "%p (pid %d) is not alive; abandon() ignored",
			this, pid());
	}
}


//
// Forensic examination of the Child's cadaver.
// Not interlocked because you have to check for state() == dead first,
// and these values are const ever after.
//
int Child::waitStatus() const
{
	assert(mState == dead);
	return mStatus;
}

bool Child::bySignal() const
{
	assert(mState == dead);
	return WIFSIGNALED(mStatus);
}

int Child::exitCode() const
{
	assert(mState == dead);
	assert(WIFEXITED(mStatus));
	return WEXITSTATUS(mStatus);
}

int Child::exitSignal() const
{
	assert(mState == dead);
	assert(WIFSIGNALED(mStatus));
	return WTERMSIG(mStatus);
}

bool Child::coreDumped() const
{
	assert(mState == dead);
	assert(WIFSIGNALED(mStatus));
	return WCOREDUMP(mStatus);
}


//
// Find a child in the child map, by pid
// This will only find live children, and return NULL for all others.
//
Child *Child::findGeneric(pid_t pid)
{
	StLock<Mutex> _(mChildren());
	Children::iterator it = mChildren().find(pid);
	if (it == mChildren().end())
		return NULL;
	else
		return it->second;
}


//
// Do the actual fork job.
// At this layer, the client side does nothing but run childAction(). Any plumbing
// or cleanup is up to that function (which runs in the child) and the caller (after
// fork() returns). If childAction() returns at all, we will call exit(1) to get
// rid of the child.
//
void Child::fork()
{
	static const unsigned maxDelay = 30;	// seconds increment, i.e. 5 retries

	assert(mState == unborn);
	for (unsigned delay = 1; ;) {
		switch (pid_t pid = ::fork()) {
		case -1:	// fork failed
			switch (errno) {
			case EINTR:
				secdebug("unixchild", "%p fork EINTR; retrying", this);
				continue;	// no problem
			case EAGAIN:
				if (delay < maxDelay) {
					secdebug("unixchild", "%p fork EAGAIN; delaying %d seconds",
						this, delay);
					sleep(delay);
					delay *= 2;
					continue;
				}
				// fall through
			default:
				UnixError::throwMe();
			}
			assert(false);	// unreached

		case 0:		// child
			//@@@ bother to clean child map?
			secdebug("unixchild", "%p (child pid %d) running child action",
				this, getpid());
			secdelay("/tmp/delay/unixchild");
			try {
				this->childAction();
				secdebug("unixchild", "%p (pid %d) child action returned; exiting",
					this, getpid());
			} catch (...) {
				secdebug("unixchild", "%p (pid %d) child action had uncaught exception",
					this, getpid());
			}
			_exit(1);

		default:	// parent
			{
				StLock<Mutex> _(mChildren());
				mState = alive;
				mPid = pid;
				mChildren().insert(make_pair(pid, this));
			}
			secdebug("unixchild", "%p (parent) running parent action", this);
			this->parentAction();
			break;
		}
		break;
	}
}


//
// Check the status of this child by explicitly probing it.
// Caller must hold master lock.
//
bool Child::checkStatus(int options)
{
	assert(state() == alive);
	secdebug("unixchild", "checking %p (pid %d)", this, this->pid());
	int status;
  again:
	switch (IFDEBUG(pid_t pid =) ::wait4(this->pid(), &status, options, NULL)) {
	case pid_t(-1):
		switch (errno) {
		case EINTR:
			goto again;		// retry
		case ECHILD:
			secdebug("unixchild", "%p (pid=%d) unknown to kernel", this, this->pid());
			mState = invalid;
			mChildren().erase(this->pid());
			return false;
		default:
			UnixError::throwMe();
		}
		break;	// placebo
	case 0:
		return false;	// child not ready (do nothing)
	default:
		assert(pid == this->pid());
		bury(status);
		return true;
	}
}


//
// Perform an idempotent check for dead children, as per the UNIX wait() system calls.
// This can be called at any time, and will reap all children that have died since
// last time. The obvious time to call this is after a SIGCHLD has been received;
// however signal dispatch is so - uh, interesting - in UNIX that we don't even try
// to deal with it at this level. Suffice to say that calling checkChildren directly
// from within a signal handler is NOT generally safe due to locking constraints.
//
// If the shared() flag is on, we explicitly poll each child known to be recently
// alive. That is less efficient than reaping any and all, but leaves any children
// alone that someone else may have created without our knowledge. The default is
// not shared(), which will reap (and discard) any unrelated children without letting
// the caller know about it.
//
void Child::checkChildren()
{
	Bier casualties;
	{
		StLock<Mutex> _(mChildren());
		if (mChildren().shared) {
			for (Children::iterator it = mChildren().begin(); it != mChildren().end(); it++)
				if (it->second->checkStatus(WNOHANG))
					casualties.add(it->second);
		} else if (!mChildren().empty()) {
			int status;
			while (pid_t pid = ::wait4(0, &status, WNOHANG, NULL)) {
				secdebug("unixchild", "universal child check (%ld children known alive)", mChildren().size());
				switch (pid) {
				case pid_t(-1):
					switch (errno) {
					case EINTR:
						secdebug("unixchild", "EINTR on wait4; retrying");
						continue;	// benign, but retry the wait()
					case ECHILD:
						// Should not normally happen (there *is* a child around),
						// but gets returned anyway if the child is stopped in the debugger.
						// Treat like a zero return (no children ready to be buried).
						secdebug("unixchild", "ECHILD with filled nursery (ignored)");
						goto no_more;
					default:
						UnixError::throwMe();
					}
					break;
				default:
					if (Child *child = mChildren()[pid]) {
						child->bury(status);
						casualties.add(child);
					} else
						secdebug("unixchild", "reaping feral child pid=%d", pid);
					if (mChildren().empty())
						goto no_more;	// none left
					break;
				}
			}
		  no_more: ;
		} else {
			secdebug("unixchild", "spurious checkChildren (the nursery is empty)");
		}
	}	// release master lock
	casualties.notify();
}


//
// Perform the canonical last rites for a formerly alive child.
// Requires master lock held throughout.
//
void Child::bury(int status)
{
	assert(mState == alive);
	mState = dead;
	mStatus = status;
	mChildren().erase(mPid);
#if !defined(NDEBUG)
	if (bySignal())
		secdebug("unixchild", "%p (pid %d) died by signal %d%s",
			this, mPid, exitSignal(),
			coreDumped() ? " and dumped core" : "");
	else
		secdebug("unixchild", "%p (pid %d) died by exit(%d)",
			this, mPid, exitCode());
#endif //NDEBUG
}


//
// Default hooks
//
void Child::parentAction()
{ /* nothing */ }

void Child::dying()
{ /* nothing */ }


//
// Biers
//
void Child::Bier::notify()
{
	for (const_iterator it = begin(); it != end(); ++it)
		(*it)->dying();
}


}	// end namespace IPPlusPlus
}	// end namespace Security