Skip to content

Instantly share code, notes, and snippets.

@bolasblack
Last active March 21, 2024 02:19
Show Gist options
  • Save bolasblack/6423ca4e67dbd35b6beff0b7dcc0ae02 to your computer and use it in GitHub Desktop.
Save bolasblack/6423ca4e67dbd35b6beff0b7dcc0ae02 to your computer and use it in GitHub Desktop.
我的翻译内容基于 CC BY-NC-SA 3.0 协议
https://creativecommons.org/licenses/by-nc-sa/3.0/cn/deed.zh
launchd.plist(5) BSD File Formats Manual launchd.plist(5)
NAME
launchd.plist -- System wide and per-user daemon/agent configuration
files
launchd.plist -- 系统范围和用户级的守护进程/代理程序配置文件。
DESCRIPTION
This document details the parameters that can be given to an XML property
list that can be loaded into launchd with launchctl.
这份文档详细介绍了 launchd 和 launchctl 支持的 plist 文件参数。
EXPECTATIONS
Daemons or agents managed by launchd are expected to behave certain ways.
被 launchd 管理的守护进程或者代理程序会表现为声明的行为。
A daemon or agent launched by launchd MUST NOT do the following in the
process directly launched by launchd:
被 launchd 启动的守护进程或者代理程序 **MUST NOT** 在直接启动的进程里进行
下列行为:
+ Call daemon(3).
+ 调用 daemon(3) 函数
+ Do the moral equivalent of daemon(3) by calling fork(2) and
have the parent process exit(3) or _exit(2).
+ 做类似调用 daemon(3) 函数的事情比如调用 fork(2) 并且对父进程
执行 exit(3) 或者 _exit(3)
A launchd daemon or agent should not perform the following as part of its
initialization, as launchd will always implicitly perform them on behalf
of the process.
被 launchd 启动的守护进程或者代理程序 **SHOULD NOT** 在初始化过程中执行下
列的操作,launchd 会代表进程执行他们。(列表比较简单我就不翻译了)
+ Redirect stdio(3) to /dev/null.
A launchd daemon or agent need not perform the following as part of its
initialization, since launchd can perform them on the process' behalf
with the appropriate launchd.plist keys specified.
被 launchd 启动的守护进程或者代理程序 **NEED NOT** 在初始化过程中执行下
列的操作,launchd 会根据 launchd.plist 里对应的 key 来进行相应的操作。
(列表比较简单我就不翻译了)
+ Setup the user ID or group ID.
+ Setup the working directory.
+ chroot(2)
+ setsid(2)
+ Close "stray" file descriptors.
+ Setup resource limits with setrlimit(2).
+ Setup priority with setpriority(2).
A daemon or agent launched by launchd SHOULD:
被 launchd 启动的守护进程或者代理程序 **SHOULD** :
+ Launch on demand given criteria specified in the XML property
list. More information can be found later in this man page.
+ 根据 plist 中指定的条件按需启动。更多信息可在本手册页的后面部分找到。
+ Handle the SIGTERM signal, preferably with a dispatch(3)
source, and respond to this signal by unwinding any outstanding
work quickly and then exiting.
+ 处理 SIGTERM 信号,最好使用 dispatch(3) 函数,在快速解决所有未完成的
任务后退出进程来响应此信号。(没太懂)
A daemon or agent launched by launchd MAST:
被 launchd 启动的守护进程或者代理程序 **MAST** :
+ check in for any MachServices advertised in its plist, using
xpc_connection_create_mach_service(3) (or
bootstrap_check_in(3)) if it uses MIG or raw Mach for communi-
cation
+ check in for any LaunchEvents advertised in its plist, using
xpc_set_event_stream_handler(3)
XML PROPERTY LIST KEYS
The following keys can be used to describe the configuration details of
your daemon or agent. Property lists are Apple's standard configuration
file format. Please see plist(5) for more information. Please note:
property list files are expected to have their name end in ".plist". Also
please note that it is the expected convention for launchd property list
files to be named <Label>.plist. Thus, if your job label is
"com.apple.sshd", your plist file should be named "com.apple.sshd.plist".
下列的字段用于声明你的守护进程/代理程序的配置。plist 是苹果官方的配置文件
格式。更多信息可以查看 plist(5) 。请注意:plist 文件期待以 ".plist" 为后
缀名。同时注意按照惯例 plist 文件一般命名为 <Label>.plist 。因此,如果你的
文件的 Label 为 "com.apple.sshd" ,你的 plist 文件最好是
"com.apple.sshd.plist" 。
Label <string>
This required key uniquely identifies the job to launchd.
这个必填字段唯一标识要启动的任务。
Disabled <boolean>
This optional key specifies whether the job should be loaded by default.
Note that this key may be overridden through the enable subcommand of
launchctl(3). Previous Darwin operating systems would modify the config-
uration file's value for this key, but now this state is kept externally.
这个可选字段用于声明任务是否需要默认载入。注意这个字段会被 launchctl(3)
的 enable 子命令覆盖。之前的 Darwin 系统可能会修改配置文件里的这个字段。
但现在不会了。
UserName <string>
This optional key specifies the user to run the job as. This key is only
applicable for services that are loaded into the privileged system
domain.
这个可选字段用于声明执行这个任务的用户。这个字段只适用于加载到 the
privileged system domain 的服务。
GroupName <string>
This optional key specifies the group to run the job as. This key is only
applicable for services that are loaded into the privileged system
domain. If UserName is set and GroupName is not, then the group will be
set to the primary group of the user.
这个可选字段用于声明执行这个任务的用户组。这个字段只适用于加载到 the
privileged system domain 的服务。如果设置了 UserName 但没设置 GroupName ,
那么用户组会设置为这个用户的首要用户组。
inetdCompatibility <dictionary>
The presence of this key specifies that the daemon expects to be run as
if it were launched from inetd. For new projects, this key should be
avoided.
这个字段用于声明守护进程需要由 inetd 载入。对于新项目而言,最好不要用这
个字段。
Wait <boolean>
This flag corresponds to the "wait" or "nowait" option of inetd. If
true, then the listening socket is passed via the stdio(3) file
descriptors. If false, then accept(2) is called on behalf of the
job, and the result is passed via the stdio(3) descriptors.
这个字段对应 inetd 的 "wait" 或者 "nowait" 选项。如果为 true ,那么
the listening socket 通过 stdio(3) 传递。如果为 false ,那么这个任务
会被代为调用 accept(2) ,同时结果会通过 stdio(3) 传递。
LimitLoadToHosts <array of strings>
This configuration file only applies to the hosts listed with this key.
This key is no longer supported.
这个字段已经不再支持了。
LimitLoadFromHosts <array of strings>
This configuration file only applies to hosts NOT listed with this key.
This key is no longer supported.
这个字段已经不再支持了。
LimitLoadToSessionType <string or array or strings>
This configuration file only applies to sessions of the type(s) speci-
fied. This key only applies to jobs which are agents. There are no dis-
tinct sessions in the privileged system context.
限制这个配置文件应用的会话类型。只有当任务为代理程序的时候这个字段才会
生效。(这句话不知道怎么翻译)在 the privileged system 上下文里没有不同
的会话。
LimitLoadToHardware <dictionary of arrays>
This configuration file only applies to the hardware listed with this
key. Each key in the dictionary defines a subdomain of the "hw" sysctl(3)
domain. Each value of the value defines valid values for the job to load.
So a key of "model" with an array specifying only "MacBookPro4,2" would
only load on a machine whose "hw.model" value was "MacBookPro4,2".
限制这个配置文件应用的硬件类型。这个字典里的字段是 sysctl(3) 的 "hw" 域的
子域。值用来声明任务载入的条件。比如一个字段为 "model" 值为只有
"MacBookPro4,2" 的数组的任务只会在 "hw.model" 值为 "MacBookPro4,2" 的时候
载入。
Program <string>
This key maps to the first argument of execv(3) and indicates the abso-
lute path to the executable for the job. If this key is missing, then the
first element of the array of strings provided to the ProgramArguments
will be used instead. This key is required in the absence of the
ProgramArguments key.
这个字段用于声明当前任务的可执行文件的绝对路径,会被映射为 execv(3) 的第一
个参数。如果没有这个字段,那么会使用 ProgramArguments 的第一个元素。当
ProgramArguments 不存在时,这个字段必填。
ProgramArguments <array of strings>
This key maps to the second argument of execvp(3) and specifies the argu-
ment vector to be passed to the job when a process is spawned. This key
is required in the absence of the Program key. IMPORTANT: Many people
are confused by this key. Please read execvp(3) very carefully!
这个字段用于声明传给程序的参数,会被映射为 execvp(3) 的第二个参数。当
Program 不存在时,这个字段是必填的。重要: 很多人对这个字段有疑惑。请仔细阅
读 execvp(3) 。
NOTE: The Program key must be an absolute path. Previous versions of
launchd did not enforce this requirement but failed to run the job. In
the absence of the Program key, the first element of the ProgramArguments
array may be either an absolute path, or a relative path which is
resolved using _PATH_STDPATH.
注意:Program 字段的值必须是绝对路径。之前版本的 launchd 没有强制要求这
一点,但是会运行失败。当 Program 字段不存在时,ProgramArguments 的第一个
元素可能是绝对路径,或者是基于 _PATH_STDPATH 的相对路径。
EnableGlobbing <boolean>
This flag causes launchd to use the glob(3) mechanism to update the pro-
gram arguments before invocation.
这个字段会使 launchd 使用 glob(3) 在程序调用前来更新程序的参数。
EnableTransactions <boolean>
This key instructs launchd that the job promises to use
xpc_transaction_begin(3) and xpc_transaction_end(3) to track outstanding
transactions that need to be reconciled before the process can safely
terminate. If no outstanding transactions are in progress, then launchd
will SIGKILL the process when it determines that the job needs to be
stopped.
这个字段要求 launchd 使用 xpc_transaction_begin(3) 和
xpc_transaction_end(3) 来跟踪在进程可以安全终止之前需要协调的未完成事务。
如果所有事务已经完成,则在确定需要停止作业时,launchd 将 SIGKILL 进程。
EnablePressuredExit <boolean>
This key opts the job into the system's Pressured Exit facility. Use of
this key implies the same responsibilities as use of the
EnableTransactions key, but it also enables automatic tracking of activ-
ity based on XPC message lifetime. If the job becomes clean, the system
will consider it eligible for reclamation under memory pressure. See
xpc_main(3) for details.
这个字段用于声明程序允许作为系统的 Pressured Exit 设施。使用这个字段意味
着与使用 EnableTransactions 相同的效果,但它同时也启用了基于 XPC 消息自动
跟踪生命周期。如果任务的所有关联工作完成,系统将认为它允许在有内存压力的
情况下被回收。更多详细信息请参阅 xpc_main(3)。
NOTE: Jobs which opt into Pressured Exit have a more heavily-managed
lifecycle than normal jobs, and they will be automatically relaunched if
they exit while holding open transactions. Therefore, launchd(8) does not
respect KeepAlive criteria for jobs which have opted into Pressured Exit.
注意:位于 Pressured Exit 中的任务相对于普通任务在生命周期上被更严格地管理
,同时,如果他们在一个事务打开的情况下退出,会被自动中期。因此,对于
Pressured Exit 中的任务,launchd(8) 不会遵从 KeepAlive 字段。
IMPORTANT: Jobs which opt into Pressured Exit will ignore SIGTERM rather
than exiting by default, so a dispatch(3) source must be used when han-
dling this signal.
重要:位于 Pressured Exit 中的任务将忽略 SIGTERM 信号而不是默认退出,因此
在处理这个信号的时候必须使用 dispatch(3) 。
OnDemand <boolean>
This key does nothing if set to true. If set to false, this key is equiv-
alent to specifying a true value for the KeepAlive key. This key should
not be used. Please remove this key from your launchd.plist.
这个字段如果设置为 true ,那么什么事情都不会发生。如果设置为 false ,相当
于设置 KeepAlive 字段为 true 。这个字段不应该使用。请从你的 launchd.plist
里移除这个字段。
ServiceIPC <boolean>
Please remove this key from your launchd.plist.
请从你的 launchd.plist 文件里移除这个字段。
KeepAlive <boolean or dictionary of stuff>
This optional key is used to control whether your job is to be kept con-
tinuously running or to let demand and conditions control the invocation.
The default is false and therefore only demand will start the job. The
value may be set to true to unconditionally keep the job alive. Alterna-
tively, a dictionary of conditions may be specified to selectively con-
trol whether launchd keeps a job alive or not. If multiple keys are pro-
vided, launchd ORs them, thus providing maximum flexibility to the job to
refine the logic and stall if necessary. If launchd finds no reason to
restart the job, it falls back on demand based invocation. Jobs that
exit quickly and frequently when configured to be kept alive will be
throttled to conserve system resources.
这个可选字段用于控制你的任务是持续运行还是按需调用。默认值为 false ,因此
只有在有必要时才会启动。该值可以设置为 true 以保持任务始终运行。或者,可
以指定条件字典以选择性地控制 launchd 是否使任务保持存活。如果提供了多个键,
当任何一个条件满足时启动他们,为程序提供最大的灵活性,以便在必要时优化逻辑
和停止。如果 launchd 没有找到重启任务的理由,那么他就退回到按需调用的机制。
配置为保持活动,但是快速且频繁退出的任务将受到限制以节省系统资源。
SuccessfulExit <boolean>
If true, the job will be restarted as long as the program exits and
with an exit status of zero. If false, the job will be restarted
in the inverse condition. This key implies that "RunAtLoad" is set
to true, since the job needs to run at least once before an exit
status can be determined.
如果为 true ,只要程序退出且退出码为 0 ,就会重启任务。如果为 false ,
任务会在相反条件下重新启动。当这个字段存在时,"RunAtLoad" 一定为 true
,因为任务需要至少运行一次才能确定退出码。
NetworkState <boolean>
This key is no longer implemented as it never acted how most users
expected.
这个字段已经不再实现了,因为没多少用户想要它。
PathState <dictionary of booleans>
Each key in this dictionary is a file-system path. If the value of
the key is true, then the job will be kept alive as long as the
path exists. If false, the job will be kept alive in the inverse
condition. The intent of this feature is that two or more jobs may
create semaphores in the file- system namespace. The following
example keeps the job alive as long as the file /path/to/file
exists.
这个字段的字典的每个键都是一条文件系统的路径。如果字典的值为 true ,
则只要路径存在,任务就会保持活跃。如果为 false ,任务会在相反条件下
保持活跃。这个功能的目的是两个或多个任务可以在文件系统命名空间中创建
信号。只要文件 /path/to/file 存在,以下示例就会使任务保持存活。
<key>KeepAlive</key>
<dict>
<key>PathState</key>
<dict>
<key>/path/to/file</key>
<true/>
</dict>
</dict>
IMPORTANT: Filesystem monitoring mechanisms are inherently race-
prone and lossy. This option should be avoided in favor of demand-
based alternatives using IPC.
重要: 文件系统监控机制本质上容易出现竞争和损失。应该避免使用这个字
段,使用 IPC 作为替代方案。
OtherJobEnabled <dictionary of booleans>
Each key in this dictionary is the name of another job. If the
value is true, then the job will be kept alive as long as one of
the specified other jobs is loaded in launchd(8).
这个字段的字典的每个键都是另外一个任务的名称。如果键的值为 true ,
则只要 launchd(8) 加载着指定的任务,任务就会保持活跃。
NOTE: This key only evaluates whether the job is loaded, not
whether it is running. Use of this key is highly discouraged. If
multiple jobs need to coordinate coordinate their lifecycles, they
should establish contracts using IPC.
注意:此字段仅检查任务是否已加载,而不是是否正在运行。强烈建议不要
使用此字段。如果多个任务需要协调协调他们的生命周期,他们应该使用
IPC 。
Crashed <boolean>
If true, the the job will be restarted as long as it exited due to
a signal which is typically associated with a crash (SIGILL,
SIGSEGV, etc.). If false, the job will be restarted in the inverse
condition.
如果为 true ,一旦任务因为一个崩溃相关的信号 (SIGILL, SIGSEGV, 等等)
退出,就会自动重启。如果为 false ,任务会在相反的条件下自动重启。
RunAtLoad <boolean>
This optional key is used to control whether your job is launched once at
the time the job is loaded. The default is false. This key should be
avoided, as speculative job launches have an adverse effect on system-
boot and user-login scenarios.
这个可选字段用于控制任务在加载后是否直接启动。默认为 false 。应避免使用此
字段,因为 推测性(speculative) 任务启动会对系统引导和用户登录产生负面影响。
RootDirectory <string>
This optional key is used to specify a directory to chroot(2) to before
running the job.
这个可选字段用于在运行任务前指定 chroot(2) 的目录。
IMPORTANT: iOS and OS X both make significant use of IPC to implement
features. The details of the communication between a client and server
are typically implemented in dynamic library code that is abstracted away
from the caller beneath the API boundary so that the client of a daemon
is not aware of any IPC that is happening.
重要:iOS 和 OSX 都大量使用 IPC 来实现功能。客户端和服务器之间的通信细节通
常实现在动态库代码中,该动态库代码从 API 边界下方的调用者抽象出来,所以守
护进程的客户端不需要关心 IPC 究竟发生了什么。
So unless the library stack which exists in the jail specified by this
key or a call to chroot(2) is identical to the one shipping on the sys-
tem, there is no guarantee that a process running in that jail will know
how to communicate with the daemons on the system. Mismatches in the
library stack between the jail and the system can manifest as random
failures, hangs and crashes.
因此,除非这个字段指定的 jail 中有 library stack 或 chroot(2) 的调用与系
统运输的 library stack 相同,否则无法保证运行在那个 jail 里的进程会知道如
何与运行在系统上的守护进程通信。jail 和系统之间的 library stack 不匹配可能
表现为随机故障,挂起和崩溃。
For these reasons, it is highly recommended that you avoid making use of
this key unless you have taken special precautions to ensure that the job
in question never attempts any IPC by setting the XPC_NULL_BOOTSTRAP
environment variable to a value of "1". Note that even if you have done
this, you must also take special care to propagate this environment vari-
able to any child processes your job may spawn through fork(2) or
posix_spawn(2). And even if you have done that, there is no guarantee
that any subprocesses spawned by your child processes will take care to
do the same thing unless you completely control all possible chains of
execution, which is unlikely.
基于上述原因,强烈建议避免使用此字段,除非已经采取了特殊预防措施,以确保出
问题的任务不会通过将 XPC_NULL_BOOTSTRAP 环境变量设置为 "1" 的方式来尝试任
何 IPC 。注意即使你已经做了这部分工作,你依旧需要万分注意防止这个环境变量
传播到任何通过 fork(2) 或者 posix_spawn(2) 派生的子进程。以及即使你也已经
做了这部分工作,依旧无法保证你的子进程派生的子进程会同样妥善处理,除非你完
全控制所有可能的执行链,这是不太可能的。
WorkingDirectory <string>
This optional key is used to specify a directory to chdir(2) to before
running the job.
这个可选字段用于在运行任务前指定 chdir(2) 的目录。
EnvironmentVariables <dictionary of strings>
This optional key is used to specify additional environmental variables
to be set before running the job. Each key in the dictionary is the name
of an environment variable, with the corresponding value being a string
representing the desired value. NOTE: Values other than strings will be
ignored.
这个可选字段用于声明运行任务前要设置的额外环境变量。字典里的每个键是环境
变量的名字,相对的值为对应的环境变量的值。注意:不是字符串的值会被忽略。
Umask <integer or string>
This optional key specifies what value should be passed to umask(2)
before running the job. If the value specified is an integer, it must be
a decimal representation of the desired umask, as property lists do not
support encoding integers in octal. If a string is given, the string will
be converted into an integer as per the rules described in strtoul(3),
and an octal value may be specified by prefixing the string with a '0'.
If a string that does not cleanly convert to an integer is specified, the
behavior will be to set a umask(2) according to the strtoul(3) parsing
rules.
这个可选字段用于声明在任务运行前传给 umask(2) 的值。如果值为整数,它必须是
是 umask 所需的十进制表示,因为 plist 不支持以八进制编码整数。如果值为字符
串,则该字符串将根据 strtoul(3) 里的规则转换为整数,也可以在字符串前面加上
"0" 来指定八进制值。如果指定了不能完全转换为整数的字符串,则将根据 strtoul(3)
解析规则设置 umask(2) 。
TimeOut <integer>
The recommended idle time out (in seconds) to pass to the job. This key
never did anything interesting and is no longer implemented. Jobs seeking
to exit when idle should use the EnablePressuredExit key to opt into the
system mechanism for reclaiming killable jobs under memory pressure.
任务的超时时间(秒)。这个字段从来没做过什么有意思的事情,也不会再被实现。
寻求在空闲时间退出的任务应该使用 EnablePressuredExit 字段选择进入系统的对
应机制,以便在内存压力时被回收。
ExitTimeOut <integer>
The amount of time launchd waits between sending the SIGTERM signal and
before sending a SIGKILL signal when the job is to be stopped. The
default value is system-defined. The value zero is interpreted as infin-
ity and should not be used, as it can stall system shutdown forever.
launchd 在尝试结束任务任务时,发送 SIGTERM 信号和 SIGKILL 信号之间等待的
时间。默认值是系统定义的。0 会被当作无限大,不建议使用,因为它会永久性地
阻碍系统关闭。
ThrottleInterval <integer>
This key lets one override the default throttling policy imposed on jobs
by launchd. The value is in seconds, and by default, jobs will not be
spawned more than once every 10 seconds. The principle behind this is
that jobs should linger around just in case they are needed again in the
near future. This not only reduces the latency of responses, but it
encourages developers to amortize the cost of program invocation.
这个字段用于覆盖 launchd 对任务施加的默认 throttling 策略。单位为秒,以及
默认情况下任务至少 10 秒才会启动一次。这背后的原则是,jobs should linger
around,以防万一在不久的将来再次需要它们。这不仅减少了响应的延迟,而且还鼓
励开发人员分摊程序调用的成本。
InitGroups <boolean>
This optional key specifies whether initgroups(3) to initialize the group
list for the job. The default is true. This key will be ignored if the
UserName key is not set. Note that for agents, the UserName key is
ignored.
这个可选字段用于声明是否为任务用 initgroups(3) 初始化 group list 。默认为
true 。当 UserName 没有设置时这个字段会被忽略。注意对于代理程序而言,
UserName 这个字段是被忽略的。
WatchPaths <array of strings>
This optional key causes the job to be started if any one of the listed
paths are modified.
这个可选字段的数组里列出来的任何一个路径被修改时都会启动任务
IMPORTANT: Use of this key is highly discouraged, as filesystem event
monitoring is highly race-prone, and it is entirely possible for modifi-
cations to be missed. When modifications are caught, there is no guaran-
tee that the file will be in a consistent state when the job is launched.
重要:强烈建议不要使用这个字段,因为文件系统事件监控非常容易出现竞争,并且
完全有可能错过修改。无法保证在启动任务时文件将处于和捕获修改时一样的状态。
QueueDirectories <array of strings>
This optional key keeps the job alive as long as the directory or direc-
tories specified are not empty.
只要这个可选字段里列出的目录不空,任务就会保持存活。
StartOnMount <boolean>
This optional key causes the job to be started every time a filesystem is
mounted.
这个可选字段保证在每次新文件系统挂载时会启动任务。
StartInterval <integer>
This optional key causes the job to be started every N seconds. If the
system is asleep during the time of the next scheduled interval firing,
that interval will be missed due to shortcomings in kqueue(3). If the
job is running during an interval firing, that interval firing will like-
wise be missed.
这个可选字段每 N 秒启动一次任务。如果计划任务触发时系统正在休眠,由于
kqueue(3) 的缺陷,那么会错过这次计划任务。如果计划任务触发时任务正在运行
,同样会错过这次计划任务。
StartCalendarInterval <dictionary of integers or array of dictionaries of
integers>
This optional key causes the job to be started every calendar interval as
specified. Missing arguments are considered to be wildcard. The semantics
are similar to crontab(5) in how firing dates are specified. Multiple
dictionaries may be specified in an array to schedule multiple calendar
intervals.
这个可选字段声明任务每次被启动的日历间隔。缺少的参数会被当作通配符。在如何
指定触发日期方面,语义类似于 crontab(5) 。可以在数组中定义多个字典以设定多
个日历间隔。
Unlike cron which skips job invocations when the computer is asleep,
launchd will start the job the next time the computer wakes up. If mul-
tiple intervals transpire before the computer is woken, those events will
be coalesced into one event upon wake from sleep.
不像 cron 在电脑休眠时会跳过调用任务,launchd 会在下次电脑唤醒时启动任务。
如果在电脑唤醒前触发了多次计划任务,这些事件会在从休眠中唤醒后合并为一个。
Note that StartInterval and StartCalendarInterval are not aware of each
other. They are evaluated completely independently by the system.
注意 StartInterval 和 StartCalendarInterval 不会相互影响。他们由系统独立地
执行。
Minute <integer>
The minute (0-59) on which this job will be run.
这个任务会在指定小时的哪分钟 (0-59) 执行。
Hour <integer>
The hour (0-23) on which this job will be run.
这个任务会在当天的哪个小时 (0-23) 执行。
Day <integer>
The day of the month (1-31) on which this job will be run.
这个任务会在当月的哪一天 (1-31) 执行。
Weekday <integer>
The weekday on which this job will be run (0 and 7 are Sunday). If
both Day and Weekday are specificed, then the job will be started
if either one matches the current date.
这个任务会在当周的哪一天(0 和 7 是周日)运行。如果同时声明了 Day
和 Weekday ,那么任务会在任何一个条件满足时启动。
Month <integer>
The month (1-12) on which this job will be run.
这个任务会在当年的哪个月份 (1-12) 启动。
StandardInPath <string>
This optional key specifies that the given path should be mapped to the
job's stdin(4), and that the contents of that file will be readable from
the job's stdin(4). If the file does not exist, no data will be deliv-
ered to the process' stdin(4).
这个可选字段声明的文件会被映射为任务的 stdin(4) ,那个文件已有的内容会被
放入任务的 stdin(4) 。如果文件不存在,那么任务的 stdin(4) 不会放入任何数
据。
StandardOutPath <string>
This optional key specifies that the given path should be mapped to the
job's stdout(4), and that any writes to the job's stdout(4) will go to
the given file. If the file does not exist, it will be created with
writable permissions and ownership reflecting the user and/or group spec-
ified as the UserName and/or GroupName, respectively (if set) and permis-
sions reflecting the umask(2) specified by the Umask key, if set.
这个可选字段声明的文件会被映射为任务的 stdout(4) ,任何写入任务 stdout(4)
的数据都会写入这个文件。如果文件不存在,那么会创建一个写模式的文件,这个文
件被 UserName 字段和/或 GroupName 字段声明的用户和/或用户组拥有,如果设置了
Umask ,那么同时也会设置文件的 umask(2) 。
StandardErrorPath <string>
This optional key specifies that the given path should be mapped to the
job's stderr(4), and that any writes to the job's stderr(4) will go to
the given file. Note that this file is opened as readable and writable as
mandated by the POSIX specification for unclear reasons. If the file
does not exist, it will be created with ownership reflecting the user
and/or group specified as the UserName and/or GroupName, respectively (if
set) and permissions reflecting the umask(2) specified by the Umask key,
if set.
这个可选字段声明的文件会映射为任务的 stderr(4) ,任何写入任务 stderr(4)
的数据都会写入这个文件。注意这个文件不知道什么原因被 POSIX 规范授权打开为
读写模式。如果文件不存在,那么会创建一个被 UserName 字段和/或 GroupName
字段声明的用户和/或用户组拥有的文件,如果设置了 Umask ,那么同时也会设置
文件的 umask(2) 。
Debug <boolean>
This optional key specifies that launchd should adjust its log mask tem-
porarily to LOG_DEBUG while dealing with this job.
这个可选字段指定 launchd 在处理这个任务时临时将其 log mask 设置为
LOG_DEBUG 。
WaitForDebugger <boolean>
This optional key specifies that launchd should launch the job in a sus-
pended state so that a debugger can be attached to the process as early
as possible (at the first instruction).
这个可选字段指定 launchd 在以挂起状态启动任务,以便于尽早将调试其附加到进
程(在第一条指令处)。
SoftResourceLimits <dictionary of integers>
HardResourceLimits <dictionary of integers>
Resource limits to be imposed on the job. These adjust variables set with
setrlimit(2). The following keys apply:
对任务施加的资源限制。 这些调整变量使用 setrlimit(2) 进行设置。
Core <integer>
The largest size (in bytes) core file that may be created.
可以创建的核心文件的最大大小(以字节为单位)。
CPU <integer>
The maximum amount of cpu time (in seconds) to be used by each
process.
每个进程可以使用的最大 CPU 时间(以秒为单位)。
Data <integer>
The maximum size (in bytes) of the data segment for a process; this
defines how far a program may extend its break with the sbrk(2)
system call.
每个进程的最大数据段大小(以字节为单位); 这定义了程序可以通过 sbrk(2)
系统调用延长其中断的时长。
FileSize <integer>
The largest size (in bytes) file that may be created.
可以创建的文件的最大大小(以字节为单位)。
MemoryLock <integer>
The maximum size (in bytes) which a process may lock into memory
using the mlock(2) function.
进程可以使用 mlock(2) 函数锁定到内存中的最大大小(以字节为单位)。
NumberOfFiles <integer>
The maximum number of open files for this process. Setting this
value in a system wide daemon will set the sysctl(3) kern.maxfiles
(SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
value in addition to the setrlimit(2) values.
这个进程可以打开的最大文件数。在系统范围的守护进程中设置此值将设置
sysctl(3) 的 kern.maxfiles (SoftResourceLimits) 或
kern.maxfilesperproc (HardResourceLimits) 值以及 setrlimit(2) 的值。
NumberOfProcesses <integer>
The maximum number of simultaneous processes for this UID. Setting
this value in a system wide daemon will set the sysctl(3) kern.max-
proc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLim-
its) value in addition to the setrlimit(2) values.
这个 UID 的最大并发进程数。在系统范围的守护进程中设置此值将设置
sysctl(3) 的 kern.maxproc (SoftResourceLimits) 或
kern.maxprocperuid (HardResourceLimits) 值以及 setrlimit(2) 的值。
ResidentSetSize <integer>
The maximum size (in bytes) to which a process's resident set size
may grow. This imposes a limit on the amount of physical memory to
be given to a process; if memory is tight, the system will prefer
to take memory from processes that are exceeding their declared
resident set size.
进程驻留集大小可能增长的最大大小(以字节为单位)。这限制了为进程提供
的物理内存量;如果内存紧张,系统将优先从超出其声明的常驻设置大小的进
程中获取内存。
Stack <integer>
The maximum size (in bytes) of the stack segment for a process;
this defines how far a program's stack segment may be extended.
Stack extension is performed automatically by the system.
进程堆栈段的最大大小(以字节为单位);这定义了程序的堆栈段可以扩展到
多远。堆栈扩展由系统自动执行。
Nice <integer>
This optional key specifies what nice(3) value should be applied to the
daemon.
这个可选字段声明了将哪个 nice(3) 值应用到这个守护进程。
ProcessType <string>
This optional key describes, at a high level, the intended purpose of the
job. The system will apply resource limits based on what kind of job it
is. If left unspecified, the system will apply light resource limits to
the job, throttling its CPU usage and I/O bandwidth. This classification
is preferable to using the HardResourceLimits, SoftResourceLimits and
Nice keys. The following are valid values:
这个可选字段在较高层次上描述了任务的预期目的。操作系统会根据任务的类型施加
资源限制。如果未指定,系统会通过限制 CPU 使用和 I/O 带宽来施加轻微的资源限
制。这种分类比使用 HardResourceLimits, SoftResourceLimits 和 Nice 字段更可
取。以下为有效值:
Background
Background jobs are generally processes that do work that was not
directly requested by the user. The resource limits applied to
Background jobs are intended to prevent them from disrupting the
user experience.
后台任务通常是执行不是由用户直接发起的任务的进程。对后台任务的资源限
制主要是为了避免其破坏用户体验。
Standard
Standard jobs are equivalent to no ProcessType being set.
标准任务相当于没有设置 ProcessType 字段。
Adaptive
Adaptive jobs move between the Background and Interactive classifi-
cations based on activity over XPC connections. See
xpc_transaction_begin(3) for details.
自适应任务基于 XPC 连接的活动情况,在后台任务和交互任务分类之间移动
。阅读 xpc_transaction_begin(3) 以获取更多信息。
Interactive
Interactive jobs run with the same resource limitations as apps,
that is to say, none. Interactive jobs are critical to maintaining
a responsive user experience, and this key should only be used if
an app's ability to be responsive depends on it, and cannot be made
Adaptive.
交互任务与 App 具有相同的资源限制,也就是说,没有。交互任务对于维护
响应式用户体验至关重要,只有当 App 的响应能力取决于它并且无法设置为
自适应任务时,才建议使用这个分类。
AbandonProcessGroup <boolean>
When a job dies, launchd kills any remaining processes with the same
process group ID as the job. Setting this key to true disables that
behavior.
当任务中止时,launchd 将使用与作业相同的进程组 ID 杀死所有剩余进程。
将这个字段设置为 true 以禁用该行为。
LowPriorityIO <boolean>
This optional key specifies whether the kernel should consider this dae-
mon to be low priority when doing filesystem I/O.
这个可选字段指定内核在执行文件系统 I/O 时是否应将此守护进程视为低优先级。
LowPriorityBackgroundIO <boolean>
This optional key specifies whether the kernel should consider this dae-
mon to be low priority when doing filesystem I/O when the process is
throttled with the Darwin-background classification.
This optional key specifies whether the kernel should consider this daemon to be low priority when doing filesystem I/O when the process is throttled with the Darwin-background classification.
这个可选字段当使用 Darwin-background 分类限制进程时,内核在执行文件系统
I/O 时是否应将此守护进程视为低优先级。
LaunchOnlyOnce <boolean>
This optional key specifies whether the job can only be run once and only
once. In other words, if the job cannot be safely respawned without a
full machine reboot, then set this key to be true.
这个可选字段声明这个任务是否能且只能运行一次。换句话说,如果这个任务无法在
一次完全重启系统前安全地重启,那么设置这个字段为 true 。
MachServices <dictionary of booleans or a dictionary of dictionaries>
This optional key is used to specify Mach services to be registered with
the Mach bootstrap namespace. Each key in this dictionary should be the
name of a service to be advertised. The value of the key must be a
boolean and set to true or a dictionary in order for the service to be
advertised. Valid keys in this dictionary are:
ResetAtClose <boolean>
The default value for this keyis false, and so the port is recy-
cled, thus leaving clients to remain oblivious to the demand nature
of the job. If the value is set to true, clients receive port death
notifications when the job lets go of the receive right. The port
will be recreated atomically with respect to bootstrap_look_up()
calls, so that clients can trust that after receiving a port-death
notification, the new port will have already been recreated. Set-
ting the value to true should be done with care. Not all clients
may be able to handle this behavior. The default value is false.
Note that this option is not compatible with xpc(3), which automat-
ically handles notifying clients of interrupted connections and
server death.
HideUntilCheckIn <boolean>
Reserve the name in the namespace, but cause bootstrap_look_up() to
fail until the job has checked in with launchd.
This option is incompatible with xpc(3), which relies on the con-
stant availability of services. This option also encourages polling
for service availability and is therefore generally discouraged.
Future implementations will penalize use of this option in subtle
and creative ways.
Jobs can dequeue messages from the MachServices they advertised
with xpc_connection_create_mach_service(3) or bootstrap_check_in()
API (to obtain the underlying port's receive right) and the Mach
APIs to dequeue messages from that port.
Sockets <dictionary of dictionaries... OR dictionary of array of
dictionaries...>
This optional key is used to specify launch on demand sockets that can be
used to let launchd know when to run the job. The job must check-in to
get a copy of the file descriptors using the launch_activate_sockets(3)
API. The keys of the top level Sockets dictionary can be anything. These
keys are meant for the application developer to associate which socket
descriptors correspond to which application level protocols (e.g. http
vs. ftp vs. DNS...).
这个可选字段指定按需启动的套接字文件,用于告知 launchd 什么时候需要启动任
务。任务必须使用 launch_activate_sockets(3) 进行签到以获取文件的拷贝。这个
字段的最上层键可以是任何内容,这些键用于应用程序开发人员将哪些套接字描述符
与哪些应用程序级协议相对应(例如,http vs. ftp vs. DNS...)。
The parameters below are used as inputs to call getaddrinfo(3).
以下参数用作调用 getaddrinfo(3) 的输入。
SockType <string>
This optional key tells launchctl what type of socket to create.
The default is "stream" and other valid values for this key are
"dgram" and "seqpacket" respectively.
这个可选字段告知 launchctl 要创建哪种套接字文件类型。默认为
"stream" ,其他这个字段的合法值分别为 "dgram" 和 "seqpacket" 。
SockPassive <boolean>
This optional key specifies whether listen(2) or connect(2) should
be called on the created file descriptor. The default is true, to
listen for new connections.
这个可选字段指定是否需要对新建的文件描述符调用 listen(2) 或者
connect(2) 。默认值为 true ,以侦听新连接。
SockNodeName <string>
This optional key specifies the node to connect(2) or bind(2) to.
这个可选字段指定要 connect(2) 或者 bind(2) 的 node 。
SockServiceName <string or integer>
This optional key specifies the service on the node to connect(2)
or bind(2) to. It may be a port number represented as an integer or
a service name represented as a string ("ssh", "telnet", etc.)
这个可选字段指定要 connect(2) 或者 bind(2) 的 node 上的服务。可以是
一个表示为整数的端口号或者表示为字符串的服务名称 ("ssh", "telnet"
等)。
SockFamily <string>
This optional key can be used to specifically request that "IPv4"
or "IPv6" socket(s) be created. An additional option, "IPv4v6"
indicates that a single socket that listens for both IPv4 and IPv6
connections should be created.
这个可选字段可用于指定创建 "IPv4" 或 "IPv6" 套接字。另一个选项,
"IPv4v6" 表示应该创建一个同时侦听 IPv4 和 IPv6 连接的套接字文件。
SockProtocol <string>
This optional key specifies the protocol to be passed to socket(2).
The only values understood by this key at the moment are "TCP" and
"UDP".
这个可选字段指定传给 socket(2) 的协议名称。这个字段目前唯一能接受的
值为 "TCP" 和 "UDP" 。
SockPathName <string>
This optional key implies SockFamily is set to "Unix". It specifies
the path to connect(2) or bind(2) to.
这个可选值意味着 SockFamily 被设置为 "Unix" 。它指定传给 connect(2)
或 bind(2) 的路径。
SecureSocketWithKey <string>
This optional key is a variant of SockPathName. Instead of binding
to a known path, a securely generated socket is created and the
path is assigned to the environment variable that is inherited by
all jobs spawned in the job's context.
这个可选字段是 SockPathName 的变体。不是绑定到已知路径,而是创建安全
生成的套接字文件,并将路径分配给环境变量,该变量由当前任务上下文中启
动的所有任务继承。
SockPathOwner <integer>
This optional key specifies the user ID that should be the domain
socket's owner.
这个可选字段指定域套接字所有者的 user ID 。
SockPathGroup <integer>
This optional key specifies the group ID that should be set as the
domain socket's group.
这个可选字段指定域套接字组的 group ID 。
SockPathMode <integer>
This optional key specifies the mode of the socket. Known bug:
Property lists don't support octal, so please convert the value to
decimal.
这个可选字段指定套接字文件的模式。已知 BUG :plist 文件不支持八进制
表示法,所以请把值转成十进制。
Bonjour <boolean or string or array of strings>
This optional key can be used to request that the service be regis-
tered with the the Bonjour subsystem. If the value is boolean, the
service name is inferred from the SockServiceName.
这个可选字段可以用于请求将服务注册到 Bonjour 子系统。如果值为布尔值,
则从 SockServiceName 推断服务名称。
MulticastGroup <string>
This optional key can be used to request that the datagram socket
join a multicast group. If the value is a hostname, then
getaddrinfo(3) will be used to join the correct multicast address
for a given socket family. If an explicit IPv4 or IPv6 address is
given, it is required that the SockFamily family also be set, oth-
erwise the results are undefined.
这个可选字段可用于请求数据报套接字加入多播组。如果该值是主机名,则
getaddrinfo(3) 将用于加入给定套接字系列的正确多播地址。如果是明确的
IPv4 或者 IPv6 地址,则还需要设置 SockFamily family,否则结果是未定
义的。
LaunchEvents <dictionary of dictionaries of dictionaries>
Specifies higher-level event types to be used as launch-on-demand event
sources. Each sub-dictionary defines events for a particular event sub-
system, such as "com.apple.iokit.matching", which can be used to launch
jobs based on the appearance of nodes in the IORegistry. Each dictionary
within the sub-dictionary specifies an event descriptor that is specified
to each event subsystem. With this key, the job promises to use the
xpc_set_event_stream_handler(3) API to consume events. See xpc_events(3)
for more details on event sources.
指定要用作按需启动事件源的更高级别事件类型。每个子字典定义特定事件子系统
的事件,例如 "com.apple.iokit.matching" ,可用于根据 IORegistry 中节点的
外观启动任务。子字典中的每个字典指定为每个事件子系统指定的事件描述符。使
用这个字段,任务承诺使用 xpc_set_event_stream_handler(3) API 来消费事件。
阅读 xpc_events(3) 获取更多关于事件源的信息。
HopefullyExitsLast <string>
This key was a hack for jobs which could not properly keep track of their
clients and is no longer implemented.
这个字段是对无法正确地保持追踪他们的客户端的任务的一个 hack ,已经不再被
实现。
HopefullyExitsFirst <string>
This key was a hack for jobs which could not properly keep track of their
clients and is no longer implemented.
这个字段是对无法正确地保持追踪他们的客户端的任务的一个 hack ,已经不再被
实现。
SessionCreate <boolean>
This key specifies that the job should be spawned into a new security
audit session rather than the default session for the context is belongs
to. See auditon(2) for details.
这个字段声明任务应该启动在一个新的安全审计会话中,而不是上下文从属的默认
会话中。查看 auditon(2) 获取更多信息。
LegacyTimers <boolean>
This optional key controls the behavior of timers created by the job. By
default on OS X Mavericks version 10.9 and later, timers created by
launchd jobs are coalesced. Batching the firing of timers with similar
deadlines improves the overall energy efficiency of the system. If this
key is set to true, timers created by the job will opt into less effi-
cient but more precise behavior and not be coalesced with other timers.
This key may have no effect if the job's ProcessType is not set to Inter-
active.
这个可选字段控制任务创建的定时器的行为。在 OS X Mavericks 10.9 及更高版本
中,由 launchd 任务创建的定时器默认会被合并。对具有类似期限的计时器进行批
量处理可以提高系统的整体能效。如果这个字段设置为 true ,任务创建的定时器效
率变低但行为更精确,也不会和其他定时器合并。如果任务的 ProcessType 不是
Interactive ,这个字段可能无效。
DEPENDENCIES
Unlike many bootstrapping daemons, launchd has no explicit dependency
model. Interdependencies are expected to be solved through the use of
IPC. It is therefore in the best interest of a job developer who expects
dependents to define all of the sockets in the configuration file. This
has the added benefit of making it possible to start the job based on
demand instead of immediately. launchd will continue to place as many
restrictions on jobs that do not conform to this model as possible.
不像很多引导守护进程,launchd 没有明确的依赖管理模型。相互依赖的情况期待
使用 IPC 来解决。因此对于开发者而言最好的情况是依赖的服务在配置文件里定义
好所有的 sockets 文件。这样做的另一个好处是可以按需启动而不是立即启动程序。
launchd 将继续对不符合此模型的任务施加尽可能多的限制。
EXAMPLE XML PROPERTY LISTS
The following XML Property List describes an on-demand daemon that will
only launch when a message arrives on the "com.example.exampled" MachSer-
vice.
下面这个 plist 描述了一个只会在一条消息发送给 "com.example.exampled"
MachService 时按需启动的守护进程
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.example.exampled</string>
<key>Program</key>
<string>/path/tp/exampled</string>
<key>ProgramArguments</key>
<array>
<string>exampled</string>
<string>argv1</string>
<string>argv2</string>
</array>
<key>MachServices</key>
<dict>
<key>com.example.exampled</key>
<true/>
</dict>
</dict>
</plist>
FILES
~/Library/LaunchAgents Per-user agents provided by the user.
只在对应用户登录后生效的任务(由用户自己管理)
/Library/LaunchAgents Per-user agents provided by the adminis-
trator.
任何用户登录后都会生效的任务(由管理员管理)
/Library/LaunchDaemons System-wide daemons provided by the admin-
istrator.
系统启动后就会生效的任务(由管理员管理)
/System/Library/LaunchAgents Per-user agents provided by OS X.
任何用户登录后都会生效的任务(由 macOS 管理)
/System/Library/LaunchDaemons System-wide daemons provided by OS X.
系统启动后就会生效的任务(由 macOS 管理)
CAVEATS
In the description of the OnDemand key, an earlier version of this manual
page said true when it meant false and said false when it meant true. You
may only ask one true/false question to determine which one is correct.
Just kidding! This version of the manual page is definitely telling the
truth.
SEE ALSO
launchctl(1), sysctl(3), launchd(8), plist(5)
Darwin 19 April, 2014 Darwin
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment