Revision: 23904 http://trac.macosforge.org/projects/launchd/changeset/23904 Author: dsorresso@apple.com Date: 2009-04-22 13:16:44 -0700 (Wed, 22 Apr 2009) Log Message: ----------- More documentation updates, typo fixes. Modified Paths: -------------- trunk/launchd/src/launchctl.1 trunk/launchd/src/launchd.8 trunk/launchd/src/launchd.plist.5 Modified: trunk/launchd/src/launchctl.1 =================================================================== --- trunk/launchd/src/launchctl.1 2009-04-22 19:59:41 UTC (rev 23903) +++ trunk/launchd/src/launchctl.1 2009-04-22 20:16:44 UTC (rev 23904) @@ -37,7 +37,7 @@ must not be group- or world-writable. These restrictions are in place for security reasons, as allowing writability to a launchd configuration file allows one to specify which executable will be launched. - +.Pp Note that allowing non-root write access to the /System/Library/LaunchDaemons directory WILL render your system unbootable. .Bl -tag -width -indent .It Fl w @@ -127,7 +127,7 @@ column is negative, it represents the negative of the signal which killed the job. Thus, "-15" would indicate that the job was terminated with SIGTERM. The third column is the job's label. - +.Pp Note that you may see some jobs in the list whose labels are in the style "0xdeadbeef.anonymous.program". These are jobs which are not managed by .Nm launchd , @@ -135,12 +135,12 @@ .Nm launchd claims no ownership and makes no guarantees regarding these jobs. They are stored purely for bookkeeping purposes. - +.Pp Similarly, you may see labels of the style "0xdeadbeef.mach_init.program". These are legacy jobs that run under mach_init emulation. This mechanism will be removed in future versions, and all remaining mach_init jobs should be converted over to .Nm launchd . - +.Pp If .Op Ar label is specified, prints information about the requested job. If @@ -195,11 +195,14 @@ .Nm launchd . .It Xo Ar bslist .Op Ar PID | .. +.Op Ar -j .Xc This prints out Mach bootstrap services and their respective states. While the namespace appears flat, it is in fact hierarchical, thus allowing for certain services to be only available to a subset of processes. The three states a -service can be in are active ("A"), inactive ("I") and on-demand ("D"). If +service can be in are active ("A"), inactive ("I") and on-demand ("D"). +.Pp +If .Op Ar PID is specified, print the Mach bootstrap services available to that PID. If .Op Ar .. @@ -207,11 +210,19 @@ current bootstrap. Note that in Mac OS X v10.6, the per-user Mach bootstrap namespace is flat, so you will only see a different set of services in a per-user bootstrap if you are in an explicitly-created bootstrap subset. +.Pp +If +.Op Ar -j +is specified, each service name will be followed by the name of the job which registered +it. .It Ar bsexec Ar PID command Op Ar args This executes the given command in the same Mach bootstrap namespace hierachy as the given PID. -.It Ar bstree -This prints a hierarchical view of the entire Mach bootstrap tree. Requires root +.It Ar bstree Op Ar -j +This prints a hierarchical view of the entire Mach bootstrap tree. If +.Op Ar -j +is specified, each service name will be followed by the name of the job which registered it. +Requires root privileges. .It Ar managerpid This prints the PID of the launchd which manages the current bootstrap. Modified: trunk/launchd/src/launchd.8 =================================================================== --- trunk/launchd/src/launchd.8 2009-04-22 19:59:41 UTC (rev 23903) +++ trunk/launchd/src/launchd.8 2009-04-22 20:16:44 UTC (rev 23904) @@ -40,10 +40,13 @@ 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 -Also, in the +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. If you wish your service to run as a certain user, in that user's environment, making it a +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 Modified: trunk/launchd/src/launchd.plist.5 =================================================================== --- trunk/launchd/src/launchd.plist.5 2009-04-22 19:59:41 UTC (rev 23903) +++ trunk/launchd/src/launchd.plist.5 2009-04-22 20:16:44 UTC (rev 23904) @@ -98,7 +98,7 @@ .Xr launchctl 1 .Ar list subcommand or use the ServiceManagement framework's SMJobCopyDictionary() method. - +.Pp Note that as of Mac OS X v10.6, this key's value in a configuration file conveys a default value, which is changed with the .Op Ar -w @@ -112,7 +112,7 @@ will apply. See .Xr launchctl 1 for more information. - +.Pp Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a job loaded in