[apple/launchd.git] / launchd / src / launchd.8

.Dd 1 May, 2009
.Dt launchd 8 
.Os Darwin
.Sh NAME
.Nm launchd
.Nd System wide and per-user daemon/agent manager
.Sh SYNOPSIS
.Nm
.Op Fl d
.Op Fl D
.Op Fl s
.Op Fl S Ar SessionType
.Op Ar -- command Op Ar args ...
.Sh DESCRIPTION
.Nm 
manages processes, both for the system as a whole and for individual users.
The primary and preferred interface to
.Nm
is via the
.Xr launchctl 1
tool which (among other options) allows the user or administrator to load and unload jobs.
Where possible, it is preferable for jobs to launch on demand based on criteria specified
in their respective configuration files.
.Pp
During boot 
.Nm
is invoked by the kernel to run as the first process on the system and to further bootstrap the rest of the system.
.Pp
You cannot invoke
.Nm
directly.
.Sh ENVIRONMENTAL VARIABLES
.Bl -tag -width -indent
.It Pa LAUNCHD_SOCKET
This variable is exported when invoking a command via the launchd command line. It informs launchctl how to find the correct launchd to talk to.
.El
.Sh NOTES
In Darwin, the canonical way to launch a daemon is through
.Nm launchd
as opposed to more traditional mechanisms or mechanisms provided in earlier versions of Mac OS X. These alternate methods should
be considered deprecated and not suitable for new projects.
.Pp
In the
.Nm launchd
lexicon, a "daemon" is, by definition, a system-wide service of which there is one instance for all clients. An "agent" is a service that runs on
a per-user basis. Daemons should not attempt to display UI or interact directly with a user's login session. Any and all work that involves interacting
with a user should be done through agents. 
.Pp
If you wish your service to run as a certain user, in that user's environment, making it a
.Nm launchd
agent is the ONLY supported means of accomplishing this on Mac OS X. In other words, it is not sufficient to perform a
.Xr setuid 2
to become a user in the truest sense on Mac OS X.
.Sh FILES
.Bl -tag -width "/System/Library/LaunchDaemons" -compact
.It Pa ~/Library/LaunchAgents
Per-user agents provided by the user.
.It Pa /Library/LaunchAgents
Per-user agents provided by the administrator.
.It Pa /Library/LaunchDaemons
System-wide daemons provided by the administrator.
.It Pa /System/Library/LaunchAgents
Per-user agents provided by Mac OS X.
.It Pa /System/Library/LaunchDaemons
System-wide daemons provided by Mac OS X.
.El
.Sh SEE ALSO 
.Xr launchctl 1 ,
.Xr launchd.plist 5 ,
Commit	Line	Data
ddbbfbc1	1	.Dd 1 May, 2009
e91b9f68 A	2	.Dt launchd 8
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm launchd
	6	.Nd System wide and per-user daemon/agent manager
	7	.Sh SYNOPSIS
	8	.Nm
ab36757d	9	.Op Fl d
ed34e3c3	10	.Op Fl D
e91b9f68	11	.Op Fl s
ed34e3c3	12	.Op Fl S Ar SessionType
e91b9f68 A	13	.Op Ar -- command Op Ar args ...
	14	.Sh DESCRIPTION
	15	.Nm
ed34e3c3 A	16	manages processes, both for the system as a whole and for individual users.
	17	The primary and preferred interface to
	18	.Nm
	19	is via the
	20	.Xr launchctl 1
	21	tool which (among other options) allows the user or administrator to load and unload jobs.
	22	Where possible, it is preferable for jobs to launch on demand based on criteria specified
	23	in their respective configuration files.
e91b9f68	24	.Pp
e91b9f68 A	25	During boot
	26	.Nm
	27	is invoked by the kernel to run as the first process on the system and to further bootstrap the rest of the system.
ddbbfbc1 A	28	.Pp
	29	You cannot invoke
	30	.Nm
	31	directly.
ab36757d A	32	.Sh ENVIRONMENTAL VARIABLES
	33	.Bl -tag -width -indent
	34	.It Pa LAUNCHD_SOCKET
	35	This variable is exported when invoking a command via the launchd command line. It informs launchctl how to find the correct launchd to talk to.
	36	.El
e91b9f68	37	.Sh NOTES
ddbbfbc1 A	38	In Darwin, the canonical way to launch a daemon is through
	39	.Nm launchd
	40	as opposed to more traditional mechanisms or mechanisms provided in earlier versions of Mac OS X. These alternate methods should
	41	be considered deprecated and not suitable for new projects.
e91b9f68	42	.Pp
ddbbfbc1 A	43	In the
	44	.Nm launchd
	45	lexicon, a "daemon" is, by definition, a system-wide service of which there is one instance for all clients. An "agent" is a service that runs on
	46	a per-user basis. Daemons should not attempt to display UI or interact directly with a user's login session. Any and all work that involves interacting
	47	with a user should be done through agents.
	48	.Pp
	49	If you wish your service to run as a certain user, in that user's environment, making it a
	50	.Nm launchd
	51	agent is the ONLY supported means of accomplishing this on Mac OS X. In other words, it is not sufficient to perform a
	52	.Xr setuid 2
	53	to become a user in the truest sense on Mac OS X.
e91b9f68 A	54	.Sh FILES
	55	.Bl -tag -width "/System/Library/LaunchDaemons" -compact
	56	.It Pa ~/Library/LaunchAgents
	57	Per-user agents provided by the user.
	58	.It Pa /Library/LaunchAgents
	59	Per-user agents provided by the administrator.
	60	.It Pa /Library/LaunchDaemons
ddbbfbc1	61	System-wide daemons provided by the administrator.
e91b9f68	62	.It Pa /System/Library/LaunchAgents
ddbbfbc1	63	Per-user agents provided by Mac OS X.
e91b9f68	64	.It Pa /System/Library/LaunchDaemons
ddbbfbc1	65	System-wide daemons provided by Mac OS X.
e91b9f68 A	66	.El
	67	.Sh SEE ALSO
	68	.Xr launchctl 1 ,
	69	.Xr launchd.plist 5 ,