#$FreeBSD$
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2020-06-06 11:08-0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: en_US\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
msgid "translator-credits"
msgstr ""

#. (itstool) path: info/title
#: article.translate.xml:4
msgid "Practical rc.d scripting in BSD"
msgstr ""

#. (itstool) path: affiliation/address
#: article.translate.xml:8
#, no-wrap
msgid "<email>yar@FreeBSD.org</email>"
msgstr ""

#. (itstool) path: info/author
#: article.translate.xml:7
msgid ""
"<personname><firstname>Yar</firstname><surname>Tikhiy</surname></"
"personname><affiliation> <_:address-1/> </affiliation>"
msgstr ""

#. (itstool) path: info/copyright
#: article.translate.xml:11
msgid ""
"<year>2005</year> <year>2006</year> <year>2012</year> <holder>The FreeBSD "
"Project</holder>"
msgstr ""

#. (itstool) path: legalnotice/para
#: article.translate.xml:20
msgid "FreeBSD is a registered trademark of the FreeBSD Foundation."
msgstr ""

#. (itstool) path: legalnotice/para
#: article.translate.xml:22
msgid "NetBSD is a registered trademark of the NetBSD Foundation."
msgstr ""

#. (itstool) path: legalnotice/para
#: article.translate.xml:24
msgid ""
"Many of the designations used by manufacturers and sellers to distinguish "
"their products are claimed as trademarks. Where those designations appear in "
"this document, and the FreeBSD Project was aware of the trademark claim, the "
"designations have been followed by the <quote>™</quote> or the <quote>®</"
"quote> symbol."
msgstr ""

#. (itstool) path: info/pubdate
#. (itstool) path: info/releaseinfo
#: article.translate.xml:32 article.translate.xml:34
msgid ""
"$FreeBSD: head/en_US.ISO8859-1/articles/rc-scripting/article.xml 44709 "
"2014-04-29 21:39:27Z wblock $"
msgstr ""

#. (itstool) path: abstract/para
#: article.translate.xml:37
msgid ""
"Beginners may find it difficult to relate the facts from the formal "
"documentation on the BSD <filename>rc.d</filename> framework with the "
"practical tasks of <filename>rc.d</filename> scripting. In this article, we "
"consider a few typical cases of increasing complexity, show <filename>rc.d</"
"filename> features suited for each case, and discuss how they work. Such an "
"examination should provide reference points for further study of the design "
"and efficient application of <filename>rc.d</filename>."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:50
msgid "Introduction"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:52
msgid ""
"The historical BSD had a monolithic startup script, <filename>/etc/rc</"
"filename>. It was invoked by <citerefentry><refentrytitle>init</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> at system boot time "
"and performed all userland tasks required for multi-user operation: checking "
"and mounting file systems, setting up the network, starting daemons, and so "
"on. The precise list of tasks was not the same in every system; admins "
"needed to customize it. With few exceptions, <filename>/etc/rc</filename> "
"had to be modified, and true hackers liked it."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:62
msgid ""
"The real problem with the monolithic approach was that it provided no "
"control over the individual components started from <filename>/etc/rc</"
"filename>. For instance, <filename>/etc/rc</filename> could not restart a "
"single daemon. The system admin had to find the daemon process by hand, kill "
"it, wait until it actually exited, then browse through <filename>/etc/rc</"
"filename> for the flags, and finally type the full command line to start the "
"daemon again. The task would become even more difficult and prone to errors "
"if the service to restart consisted of more than one daemon or demanded "
"additional actions. In a few words, the single script failed to fulfil what "
"scripts are for: to make the system admin's life easier."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:76
msgid ""
"Later there was an attempt to split out some parts of <filename>/etc/rc</"
"filename> for the sake of starting the most important subsystems separately. "
"The notorious example was <filename>/etc/netstart</filename> to bring up "
"networking. It did allow for accessing the network from single-user mode, "
"but it did not integrate well into the automatic startup process because "
"parts of its code needed to interleave with actions essentially unrelated to "
"networking. That was why <filename>/etc/netstart</filename> mutated into "
"<filename>/etc/rc.network</filename>. The latter was no longer an ordinary "
"script; it comprised of large, tangled <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> functions called from "
"<filename>/etc/rc</filename> at different stages of system startup. However, "
"as the startup tasks grew diverse and sophisticated, the <quote>quasi-"
"modular</quote> approach became even more of a drag than the monolithic "
"<filename>/etc/rc</filename> had been."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:94
msgid ""
"Without a clean and well-designed framework, the startup scripts had to bend "
"over backwards to satisfy the needs of rapidly developing BSD-based "
"operating systems. It became obvious at last that more steps are necessary "
"on the way to a fine-grained and extensible <filename>rc</filename> system. "
"Thus BSD <filename>rc.d</filename> was born. Its acknowledged fathers were "
"Luke Mewburn and the NetBSD community. Later it was imported into FreeBSD. "
"Its name refers to the location of system scripts for individual services, "
"which is in <filename>/etc/rc.d</filename>. Soon we will learn about more "
"components of the <filename>rc.d</filename> system and see how the "
"individual scripts are invoked."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:107
msgid ""
"The basic ideas behind BSD <filename>rc.d</filename> are <emphasis>fine "
"modularity</emphasis> and <emphasis>code reuse</emphasis>. <emphasis>Fine "
"modularity</emphasis> means that each basic <quote>service</quote> such as a "
"system daemon or primitive startup task gets its own "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> script able to start the service, stop it, reload it, check "
"its status. A particular action is chosen by the command-line argument to "
"the script. The <filename>/etc/rc</filename> script still drives system "
"startup, but now it merely invokes the smaller scripts one by one with the "
"<option>start</option> argument. It is easy to perform shutdown tasks as "
"well by running the same set of scripts with the <option>stop</option> "
"argument, which is done by <filename>/etc/rc.shutdown</filename>. Note how "
"closely this follows the Unix way of having a set of small specialized "
"tools, each fulfilling its task as well as possible. <emphasis>Code reuse</"
"emphasis> means that common operations are implemented as "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> functions and collected in <filename>/etc/rc.subr</filename>. "
"Now a typical script can be just a few lines' worth of "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> code. Finally, an important part of the <filename>rc.d</"
"filename> framework is <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry>, which helps "
"<filename>/etc/rc</filename> to run the small scripts orderly with respect "
"to dependencies between them. It can help <filename>/etc/rc.shutdown</"
"filename>, too, because the proper order for the shutdown sequence is "
"opposite to that of startup."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:133
msgid ""
"The BSD <filename>rc.d</filename> design is described in <link linkend="
"\"lukem\">the original article by Luke Mewburn</link>, and the <filename>rc."
"d</filename> components are documented in great detail in <link linkend="
"\"manpages\">the respective manual pages</link>. However, it might not "
"appear obvious to an <filename>rc.d</filename> newbie how to tie the "
"numerous bits and pieces together in order to create a well-styled script "
"for a particular task. Therefore this article will try a different approach "
"to describe <filename>rc.d</filename>. It will show which features should be "
"used in a number of typical cases, and why. Note that this is not a how-to "
"document because our aim is not at giving ready-made recipes, but at showing "
"a few easy entrances into the <filename>rc.d</filename> realm. Neither is "
"this article a replacement for the relevant manual pages. Do not hesitate to "
"refer to them for more formal and complete documentation while reading this "
"article."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:151
msgid ""
"There are prerequisites to understanding this article. First of all, you "
"should be familiar with the <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> scripting language in "
"order to master <filename>rc.d</filename>. In addition, you should know how "
"the system performs userland startup and shutdown tasks, which is described "
"in <citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></"
"citerefentry>."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:158
msgid ""
"This article focuses on the FreeBSD branch of <filename>rc.d</filename>. "
"Nevertheless, it may be useful to NetBSD developers, too, because the two "
"branches of BSD <filename>rc.d</filename> not only share the same design but "
"also stay similar in their aspects visible to script authors."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:167
msgid "Outlining the task"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:169
msgid ""
"A little consideration before starting <envar>$EDITOR</envar> will not hurt. "
"In order to write a well-tempered <filename>rc.d</filename> script for a "
"system service, we should be able to answer the following questions first:"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:177
msgid "Is the service mandatory or optional?"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:181
msgid ""
"Will the script serve a single program, e.g., a daemon, or perform more "
"complex actions?"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:186
msgid "Which other services will our service depend on, and vice versa?"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:191
msgid ""
"From the examples that follow we will see why it is important to know the "
"answers to these questions."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:196
msgid "A dummy script"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:198
msgid ""
"The following script just emits a message each time the system boots up:"
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:202
#, no-wrap
msgid ""
"#!/bin/sh<co xml:id=\"rcng-dummy-shebang\"/>\n"
"\n"
". /etc/rc.subr<co xml:id=\"rcng-dummy-include\"/>\n"
"\n"
"name=\"dummy\"<co xml:id=\"rcng-dummy-name\"/>\n"
"start_cmd=\"${name}_start\"<co xml:id=\"rcng-dummy-startcmd\"/>\n"
"stop_cmd=\":\"<co xml:id=\"rcng-dummy-stopcmd\"/>\n"
"\n"
"dummy_start()<co xml:id=\"rcng-dummy-startfn\"/>\n"
"{\n"
"\techo \"Nothing started.\"\n"
"}\n"
"\n"
"load_rc_config $name<co xml:id=\"rcng-dummy-loadconfig\"/>\n"
"run_rc_command \"$1\"<co xml:id=\"rcng-dummy-runcommand\"/>"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:219
msgid "Things to note are:"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:223
msgid ""
"An interpreted script should begin with the magic <quote>shebang</quote> "
"line. That line specifies the interpreter program for the script. Due to the "
"shebang line, the script can be invoked exactly like a binary program "
"provided that it has the execute bit set. (See "
"<citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry>.) For example, a system admin can run our script manually, "
"from the command line:"
msgstr ""

#. (itstool) path: callout/screen
#: article.translate.xml:232
#, no-wrap
msgid "<prompt>#</prompt> <userinput>/etc/rc.d/dummy start</userinput>"
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:235
msgid ""
"In order to be properly managed by the <filename>rc.d</filename> framework, "
"its scripts need to be written in the <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> language. If you have "
"a service or port that uses a binary control utility or a startup routine "
"written in another language, install that element in <filename>/usr/sbin</"
"filename> (for the system) or <filename>/usr/local/sbin</filename> (for "
"ports) and call it from a <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> script in the "
"appropriate <filename>rc.d</filename> directory."
msgstr ""

#. (itstool) path: tip/para
#: article.translate.xml:247
msgid ""
"If you would like to learn the details of why <filename>rc.d</filename> "
"scripts must be written in the <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> language, see how "
"<filename>/etc/rc</filename> invokes them by means of "
"<function>run_rc_script</function>, then study the implementation of "
"<function>run_rc_script</function> in <filename>/etc/rc.subr</filename>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:258
msgid ""
"In <filename>/etc/rc.subr</filename>, a number of "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> functions are defined for an <filename>rc.d</filename> script "
"to use. The functions are documented in <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry>. While it is "
"theoretically possible to write an <filename>rc.d</filename> script without "
"ever using <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>, its functions prove extremely handy and make the "
"job an order of magnitude easier. So it is no surprise that everybody "
"resorts to <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> in <filename>rc.d</filename> scripts. We are not "
"going to be an exception."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:269
msgid ""
"An <filename>rc.d</filename> script must <quote>source</quote> <filename>/"
"etc/rc.subr</filename> (include it using <quote><command>.</command></"
"quote>) <emphasis>before</emphasis> it calls <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> functions so "
"that <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</"
"manvolnum></citerefentry> has an opportunity to learn the functions. The "
"preferred style is to source <filename>/etc/rc.subr</filename> first of all."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:278
msgid ""
"Some useful functions related to networking are provided by another include "
"file, <filename>/etc/network.subr</filename>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:285
msgid ""
"<anchor xml:id=\"name-var\"/>The mandatory variable <envar>name</envar> "
"specifies the name of our script. It is required by "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>. That is, each <filename>rc.d</filename> script "
"<emphasis>must</emphasis> set <envar>name</envar> before it calls "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> functions."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:292
msgid ""
"Now it is the right time to choose a unique name for our script once and for "
"all. We will use it in a number of places while developing the script. For a "
"start, let us give the same name to the script file, too."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:298
msgid ""
"The current style of <filename>rc.d</filename> scripting is to enclose "
"values assigned to variables in double quotes. Keep in mind that it is just "
"a style issue that may not always be applicable. You can safely omit quotes "
"from around simple words without <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> metacharacters in "
"them, while in certain cases you will need single quotes to prevent any "
"interpretation of the value by <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry>. A programmer should "
"be able to tell the language syntax from style conventions and use both of "
"them wisely."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:312
msgid ""
"The main idea behind <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> is that an "
"<filename>rc.d</filename> script provides handlers, or methods, for "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> to invoke. In particular, <option>start</option>, "
"<option>stop</option>, and other arguments to an <filename>rc.d</filename> "
"script are handled this way. A method is a <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> expression stored in a "
"variable named <envar><replaceable>argument</replaceable>_cmd</envar>, where "
"<replaceable>argument</replaceable> corresponds to what can be specified on "
"the script's command line. We will see later how "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> provides default methods for the standard "
"arguments."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:326
msgid ""
"To make the code in <filename>rc.d</filename> more uniform, it is common to "
"use <envar>${name}</envar> wherever appropriate. Thus a number of lines can "
"be just copied from one script to another."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:334
msgid ""
"We should keep in mind that <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> provides default "
"methods for the standard arguments. Consequently, we must override a "
"standard method with a no-op <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> expression if we want "
"it to do nothing."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:341
msgid ""
"The body of a sophisticated method can be implemented as a function. It is a "
"good idea to make the function name meaningful."
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:346
msgid ""
"It is strongly recommended to add the prefix <envar>${name}</envar> to the "
"names of all functions defined in our script so they never clash with the "
"functions from <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> or another common "
"include file."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:355
msgid ""
"This call to <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> loads "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables. Our script makes no use of them yet, "
"but it still is recommended to load <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry> because there can be "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables controlling "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> itself."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:363
msgid ""
"Usually this is the last command in an <filename>rc.d</filename> script. It "
"invokes the <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> machinery to perform "
"the requested action using the variables and methods our script has provided."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:372
msgid "A configurable dummy script"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:374
msgid ""
"Now let us add some controls to our dummy script. As you may know, "
"<filename>rc.d</filename> scripts are controlled with "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry>. Fortunately, <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> hides all the "
"complications from us. The following script uses "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> via <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> to see whether it is "
"enabled in the first place, and to fetch a message to show at boot time. "
"These two tasks in fact are independent. On the one hand, an <filename>rc.d</"
"filename> script can just support enabling and disabling its service. On the "
"other hand, a mandatory <filename>rc.d</filename> script can have "
"configuration variables. We will do both things in the same script though:"
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:388
#, no-wrap
msgid ""
"#!/bin/sh\n"
"\n"
". /etc/rc.subr\n"
"\n"
"name=dummy\n"
"rcvar=dummy_enable<co xml:id=\"rcng-confdummy-rcvar\"/>\n"
"\n"
"start_cmd=\"${name}_start\"\n"
"stop_cmd=\":\"\n"
"\n"
"load_rc_config $name<co xml:id=\"rcng-confdummy-loadconfig\"/>\n"
": ${dummy_enable:=no} <co xml:id=\"rcng-confdummy-enable\"/>\n"
": ${dummy_msg=\"Nothing started.\"}<co xml:id=\"rcng-confdummy-opt\"/>\n"
"\n"
"dummy_start()\n"
"{\n"
"\techo \"$dummy_msg\"<co xml:id=\"rcng-confdummy-msg\"/>\n"
"}\n"
"\n"
"run_rc_command \"$1\""
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:410
msgid "What changed in this example?"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:414
msgid ""
"The variable <envar>rcvar</envar> specifies the name of the ON/OFF knob "
"variable."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:419
msgid ""
"Now <function>load_rc_config</function> is invoked earlier in the script, "
"before any <citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables are accessed."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:424
msgid ""
"While examining <filename>rc.d</filename> scripts, keep in mind that "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> defers the evaluation of expressions in a function until the "
"latter is called. Therefore it is not an error to invoke "
"<function>load_rc_config</function> as late as just before "
"<function>run_rc_command</function> and still access "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables from the method functions exported to "
"<function>run_rc_command</function>. This is because the method functions "
"are to be called by <function>run_rc_command</function>, which is invoked "
"<emphasis>after</emphasis> <function>load_rc_config</function>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:440
msgid ""
"A warning will be emitted by <function>run_rc_command</function> if "
"<envar>rcvar</envar> itself is set, but the indicated knob variable is "
"unset. If your <filename>rc.d</filename> script is for the base system, you "
"should add a default setting for the knob to <filename>/etc/defaults/rc."
"conf</filename> and document it in <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry>. Otherwise it is your "
"script that should provide a default setting for the knob. The canonical "
"approach to the latter case is shown in the example."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:451
msgid ""
"You can make <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> act as though the knob "
"is set to <literal>ON</literal>, irrespective of its current setting, by "
"prefixing the argument to the script with <literal>one</literal> or "
"<literal>force</literal>, as in <option>onestart</option> or "
"<option>forcestop</option>. Keep in mind though that <literal>force</"
"literal> has other dangerous effects we will touch upon below, while "
"<literal>one</literal> just overrides the ON/OFF knob. E.g., assume that "
"<envar>dummy_enable</envar> is <literal>OFF</literal>. The following command "
"will run the <option>start</option> method in spite of the setting:"
msgstr ""

#. (itstool) path: note/screen
#: article.translate.xml:464
#, no-wrap
msgid "<prompt>#</prompt> <userinput>/etc/rc.d/dummy onestart</userinput>"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:469
msgid ""
"Now the message to be shown at boot time is no longer hard-coded in the "
"script. It is specified by an <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry> variable named "
"<envar>dummy_msg</envar>. This is a trivial example of how "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables can control an <filename>rc.d</filename> "
"script."
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:476
msgid ""
"The names of all <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry> variables used "
"exclusively by our script <emphasis>must</emphasis> have the same prefix: "
"<envar>${name}_</envar>. For example: <envar>dummy_mode</envar>, "
"<envar>dummy_state_file</envar>, and so on."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:484
msgid ""
"While it is possible to use a shorter name internally, e.g., just "
"<envar>msg</envar>, adding the unique prefix <envar>${name}_</envar> to all "
"global names introduced by our script will save us from possible collisions "
"with the <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> namespace."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:490
msgid ""
"As a rule, <filename>rc.d</filename> scripts of the base system need not "
"provide defaults for their <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry> variables because the "
"defaults should be set in <filename>/etc/defaults/rc.conf</filename> "
"instead. On the other hand, <filename>rc.d</filename> scripts for ports "
"should provide the defaults as shown in the example."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:501
msgid ""
"Here we use <envar>dummy_msg</envar> to actually control our script, i.e., "
"to emit a variable message. Use of a shell function is overkill here, since "
"it only runs a single command; an equally valid alternative is:"
msgstr ""

#. (itstool) path: callout/programlisting
#: article.translate.xml:506
#, no-wrap
msgid "start_cmd=\"echo \\\"$dummy_msg\\\"\""
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:512
msgid "Startup and shutdown of a simple daemon"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:514
msgid ""
"We said earlier that <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> could provide default "
"methods. Obviously, such defaults cannot be too general. They are suited for "
"the common case of starting and shutting down a simple daemon program. Let "
"us assume now that we need to write an <filename>rc.d</filename> script for "
"such a daemon called <command>mumbled</command>. Here it is:"
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:522
#, no-wrap
msgid ""
"#!/bin/sh\n"
"\n"
". /etc/rc.subr\n"
"\n"
"name=mumbled\n"
"rcvar=mumbled_enable\n"
"\n"
"command=\"/usr/sbin/${name}\"<co xml:id=\"rcng-daemon-basic-cmd\"/>\n"
"\n"
"load_rc_config $name\n"
"run_rc_command \"$1\""
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:535
msgid ""
"Pleasingly simple, isn't it? Let us examine our little script. The only new "
"thing to note is as follows:"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:540
msgid ""
"The <envar>command</envar> variable is meaningful to "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>. If it is set, <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> will act "
"according to the scenario of serving a conventional daemon. In particular, "
"the default methods will be provided for such arguments: <option>start</"
"option>, <option>stop</option>, <option>restart</option>, <option>poll</"
"option>, and <option>status</option>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:548
msgid ""
"The daemon will be started by running <envar>$command</envar> with command-"
"line flags specified by <envar>$mumbled_flags</envar>. Thus all the input "
"data for the default <option>start</option> method are available in the "
"variables set by our script. Unlike <option>start</option>, other methods "
"may require additional information about the process started. For instance, "
"<option>stop</option> must know the PID of the process to terminate it. In "
"the present case, <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> will scan through the "
"list of all processes, looking for a process with its name equal to <envar>"
"$procname</envar>. The latter is another variable of meaning to "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>, and its value defaults to that of <envar>command</"
"envar>. In other words, when we set <envar>command</envar>, <envar>procname</"
"envar> is effectively set to the same value. This enables our script to kill "
"the daemon and to check if it is running in the first place."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:567
msgid ""
"Some programs are in fact executable scripts. The system runs such a script "
"by starting its interpreter and passing the name of the script to it as a "
"command-line argument. This is reflected in the list of processes, which can "
"confuse <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>. You should additionally set "
"<envar>command_interpreter</envar> to let <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> know the actual "
"name of the process if <envar>$command</envar> is a script."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:576
msgid ""
"For each <filename>rc.d</filename> script, there is an optional "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variable that takes precedence over "
"<envar>command</envar>. Its name is constructed as follows: <envar>${name}"
"_program</envar>, where <envar>name</envar> is the mandatory variable we "
"discussed <link linkend=\"name-var\">earlier</link>. E.g., in this case it "
"will be <envar>mumbled_program</envar>. It is "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> that arranges <envar>${name}_program</envar> to "
"override <envar>command</envar>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:587
msgid ""
"Of course, <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</"
"manvolnum></citerefentry> will permit you to set <envar>${name}_program</"
"envar> from <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry> or the script itself "
"even if <envar>command</envar> is unset. In that case, the special "
"properties of <envar>${name}_program</envar> are lost, and it becomes an "
"ordinary variable your script can use for its own purposes. However, the "
"sole use of <envar>${name}_program</envar> is discouraged because using it "
"together with <envar>command</envar> became an idiom of <filename>rc.d</"
"filename> scripting."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:599
msgid ""
"For more detailed information on default methods, refer to "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:606
msgid "Startup and shutdown of an advanced daemon"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:608
msgid ""
"Let us add some meat onto the bones of the previous script and make it more "
"complex and featureful. The default methods can do a good job for us, but we "
"may need some of their aspects tweaked. Now we will learn how to tune the "
"default methods to our needs."
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:615
#, no-wrap
msgid ""
"#!/bin/sh\n"
"\n"
". /etc/rc.subr\n"
"\n"
"name=mumbled\n"
"rcvar=mumbled_enable\n"
"\n"
"command=\"/usr/sbin/${name}\"\n"
"command_args=\"mock arguments &gt; /dev/null 2&gt;&amp;1\"<co xml:id=\"rcng-daemon-adv-args\"/>\n"
"\n"
"pidfile=\"/var/run/${name}.pid\"<co xml:id=\"rcng-daemon-adv-pid\"/>\n"
"\n"
"required_files=\"/etc/${name}.conf /usr/share/misc/${name}.rules\"<co xml:id=\"rcng-daemon-adv-reqfiles\"/>\n"
"\n"
"sig_reload=\"USR1\"<co xml:id=\"rcng-daemon-adv-sig\"/>\n"
"\n"
"start_precmd=\"${name}_prestart\"<co xml:id=\"rcng-daemon-adv-precmd\"/>\n"
"stop_postcmd=\"echo Bye-bye\"<co xml:id=\"rcng-daemon-adv-postcmd\"/>\n"
"\n"
"extra_commands=\"reload plugh xyzzy\"<co xml:id=\"rcng-daemon-adv-extra\"/>\n"
"\n"
"plugh_cmd=\"mumbled_plugh\"<co xml:id=\"rcng-daemon-adv-methods\"/>\n"
"xyzzy_cmd=\"echo 'Nothing happens.'\"\n"
"\n"
"mumbled_prestart()\n"
"{\n"
"\tif checkyesno mumbled_smart; then<co xml:id=\"rcng-daemon-adv-yn\"/>\n"
"\t\trc_flags=\"-o smart ${rc_flags}\"<co xml:id=\"rcng-daemon-adv-rcflags\"/>\n"
"\tfi\n"
"\tcase \"$mumbled_mode\" in\n"
"\tfoo)\n"
"\t\trc_flags=\"-frotz ${rc_flags}\"\n"
"\t\t;;\n"
"\tbar)\n"
"\t\trc_flags=\"-baz ${rc_flags}\"\n"
"\t\t;;\n"
"\t*)\n"
"\t\twarn \"Invalid value for mumbled_mode\"<co xml:id=\"rcng-daemon-adv-warn\"/>\n"
"\t\treturn 1<co xml:id=\"rcng-daemon-adv-preret\"/>\n"
"\t\t;;\n"
"\tesac\n"
"\trun_rc_command xyzzy<co xml:id=\"rcng-daemon-adv-run\"/>\n"
"\treturn 0\n"
"}\n"
"\n"
"mumbled_plugh()<co xml:id=\"rcng-daemon-adv-plugh\"/>\n"
"{\n"
"\techo 'A hollow voice says \"plugh\".'\n"
"}\n"
"\n"
"load_rc_config $name\n"
"run_rc_command \"$1\""
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:671
msgid ""
"Additional arguments to <envar>$command</envar> can be passed in "
"<envar>command_args</envar>. They will be added to the command line after "
"<envar>$mumbled_flags</envar>. Since the final command line is passed to "
"<command>eval</command> for its actual execution, input and output "
"redirections can be specified in <envar>command_args</envar>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:679
msgid ""
"<emphasis>Never</emphasis> include dashed options, like <option>-X</option> "
"or <option>--foo</option>, in <envar>command_args</envar>. The contents of "
"<envar>command_args</envar> will appear at the end of the final command "
"line, hence they are likely to follow arguments present in <envar>${name}"
"_flags</envar>; but most commands will not recognize dashed options after "
"ordinary arguments. A better way of passing additional options to <envar>"
"$command</envar> is to add them to the beginning of <envar>${name}_flags</"
"envar>. Another way is to modify <envar>rc_flags</envar> <link linkend=\"rc-"
"flags\">as shown later</link>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:695
msgid ""
"A good-mannered daemon should create a <emphasis>pidfile</emphasis> so that "
"its process can be found more easily and reliably. The variable "
"<envar>pidfile</envar>, if set, tells <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> where it can find the "
"pidfile for its default methods to use."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:703
msgid ""
"In fact, <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> will also use the pidfile to see if the daemon is "
"already running before starting it. This check can be skipped by using the "
"<option>faststart</option> argument."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:711
msgid ""
"If the daemon cannot run unless certain files exist, just list them in "
"<envar>required_files</envar>, and <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> will check that those "
"files do exist before starting the daemon. There also are "
"<envar>required_dirs</envar> and <envar>required_vars</envar> for "
"directories and environment variables, respectively. They all are described "
"in detail in <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:720
msgid ""
"The default method from <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> can be forced to skip "
"the prerequisite checks by using <option>forcestart</option> as the argument "
"to the script."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:728
msgid ""
"We can customize signals to send to the daemon in case they differ from the "
"well-known ones. In particular, <envar>sig_reload</envar> specifies the "
"signal that makes the daemon reload its configuration; it is <symbol>SIGHUP</"
"symbol> by default. Another signal is sent to stop the daemon process; the "
"default is <symbol>SIGTERM</symbol>, but this can be changed by setting "
"<envar>sig_stop</envar> appropriately."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:738
msgid ""
"The signal names should be specified to <citerefentry><refentrytitle>rc."
"subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> without the "
"<literal>SIG</literal> prefix, as it is shown in the example. The FreeBSD "
"version of <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>1</"
"manvolnum></citerefentry> can recognize the <literal>SIG</literal> prefix, "
"but the versions from other OS types may not."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:747
msgid ""
"Performing additional tasks before or after the default methods is easy. For "
"each command-argument supported by our script, we can define "
"<envar><replaceable>argument</replaceable>_precmd</envar> and "
"<envar><replaceable>argument</replaceable>_postcmd</envar>. These "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> commands are invoked before and after the respective method, "
"as it is evident from their names."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:757
msgid ""
"Overriding a default method with a custom <envar><replaceable>argument</"
"replaceable>_cmd</envar> still does not prevent us from making use of "
"<envar><replaceable>argument</replaceable>_precmd</envar> or "
"<envar><replaceable>argument</replaceable>_postcmd</envar> if we need to. In "
"particular, the former is good for checking custom, sophisticated conditions "
"that should be met before performing the command itself. Using "
"<envar><replaceable>argument</replaceable>_precmd</envar> along with "
"<envar><replaceable>argument</replaceable>_cmd</envar> lets us logically "
"separate the checks from the action."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:770
msgid ""
"Do not forget that you can cram any valid <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> expressions into the "
"methods, pre-, and post-commands you define. Just invoking a function that "
"makes the real job is a good style in most cases, but never let style limit "
"your understanding of what is going on behind the curtain."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:780
msgid ""
"If we would like to implement custom arguments, which can also be thought of "
"as <emphasis>commands</emphasis> to our script, we need to list them in "
"<envar>extra_commands</envar> and provide methods to handle them."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:787
msgid ""
"The <option>reload</option> command is special. On the one hand, it has a "
"preset method in <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry>. On the other hand, "
"<option>reload</option> is not offered by default. The reason is that not "
"all daemons use the same reload mechanism and some have nothing to reload at "
"all. So we need to ask explicitly that the builtin functionality be "
"provided. We can do so via <envar>extra_commands</envar>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:796
msgid ""
"What do we get from the default method for <option>reload</option>? Quite "
"often daemons reload their configuration upon reception of a signal — "
"typically, <symbol>SIGHUP</symbol>. Therefore "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> attempts to reload the daemon by sending a signal "
"to it. The signal is preset to <symbol>SIGHUP</symbol> but can be customized "
"via <envar>sig_reload</envar> if necessary."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:808
msgid ""
"Our script supports two non-standard commands, <option>plugh</option> and "
"<option>xyzzy</option>. We saw them listed in <envar>extra_commands</envar>, "
"and now it is time to provide methods for them. The method for "
"<option>xyzzy</option> is just inlined while that for <option>plugh</option> "
"is implemented as the <function>mumbled_plugh</function> function."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:816
msgid ""
"Non-standard commands are not invoked during startup or shutdown. Usually "
"they are for the system admin's convenience. They can also be used from "
"other subsystems, e.g., <citerefentry><refentrytitle>devd</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> if specified in "
"<citerefentry><refentrytitle>devd.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:821
msgid ""
"The full list of available commands can be found in the usage line printed "
"by <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> when the script is invoked without arguments. For "
"example, here is the usage line from the script under study:"
msgstr ""

#. (itstool) path: callout/screen
#: article.translate.xml:826
#, no-wrap
msgid ""
"<prompt>#</prompt> <userinput>/etc/rc.d/mumbled</userinput>\n"
"Usage: /etc/rc.d/mumbled [fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll)"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:831
msgid ""
"A script can invoke its own standard or non-standard commands if needed. "
"This may look similar to calling functions, but we know that commands and "
"shell functions are not always the same thing. For instance, <command>xyzzy</"
"command> is not implemented as a function here. In addition, there can be a "
"pre-command and post-command, which should be invoked orderly. So the proper "
"way for a script to run its own command is by means of "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>, as shown in the example."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:843
msgid ""
"A handy function named <function>checkyesno</function> is provided by "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>. It takes a variable name as its argument and "
"returns a zero exit code if and only if the variable is set to <literal>YES</"
"literal>, or <literal>TRUE</literal>, or <literal>ON</literal>, or "
"<literal>1</literal>, case insensitive; a non-zero exit code is returned "
"otherwise. In the latter case, the function tests the variable for being set "
"to <literal>NO</literal>, <literal>FALSE</literal>, <literal>OFF</literal>, "
"or <literal>0</literal>, case insensitive; it prints a warning message if "
"the variable contains anything else, i.e., junk."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:856
msgid ""
"Keep in mind that for <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry> a zero exit code means "
"true and a non-zero exit code means false."
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:860
msgid ""
"The <function>checkyesno</function> function takes a <emphasis>variable "
"name</emphasis>. Do not pass the expanded <emphasis>value</emphasis> of a "
"variable to it; it will not work as expected."
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:865
msgid "The following is the correct usage of <function>checkyesno</function>:"
msgstr ""

#. (itstool) path: important/programlisting
#: article.translate.xml:868
#, no-wrap
msgid ""
"if checkyesno mumbled_enable; then\n"
"        foo\n"
"fi"
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:872
msgid ""
"On the contrary, calling <function>checkyesno</function> as shown below will "
"not work — at least not as expected:"
msgstr ""

#. (itstool) path: important/programlisting
#: article.translate.xml:876
#, no-wrap
msgid ""
"if checkyesno \"${mumbled_enable}\"; then\n"
"        foo\n"
"fi"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:883
msgid ""
"<anchor xml:id=\"rc-flags\"/>We can affect the flags to be passed to <envar>"
"$command</envar> by modifying <envar>rc_flags</envar> in <envar>"
"$start_precmd</envar>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:889
msgid ""
"In certain cases we may need to emit an important message that should go to "
"<application>syslog</application> as well. This can be done easily with the "
"following <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> functions: <function>debug</function>, "
"<function>info</function>, <function>warn</function>, and <function>err</"
"function>. The latter function then exits the script with the code specified."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:899
msgid ""
"The exit codes from methods and their pre-commands are not just ignored by "
"default. If <envar><replaceable>argument</replaceable>_precmd</envar> "
"returns a non-zero exit code, the main method will not be performed. In "
"turn, <envar><replaceable>argument</replaceable>_postcmd</envar> will not be "
"invoked unless the main method returns a zero exit code."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:909
msgid ""
"However, <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> can be instructed from the command line to ignore "
"those exit codes and invoke all commands anyway by prefixing an argument "
"with <literal>force</literal>, as in <option>forcestart</option>."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:920
msgid "Connecting a script to the rc.d framework"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:922
msgid ""
"After a script has been written, it needs to be integrated into <filename>rc."
"d</filename>. The crucial step is to install the script in <filename>/etc/rc."
"d</filename> (for the base system) or <filename>/usr/local/etc/rc.d</"
"filename> (for ports). Both &lt;<filename>bsd.prog.mk</filename>&gt; and &lt;"
"<filename>bsd.port.mk</filename>&gt; provide convenient hooks for that, and "
"usually you do not have to worry about the proper ownership and mode. System "
"scripts should be installed from <filename>src/etc/rc.d</filename> through "
"the <filename>Makefile</filename> found there. Port scripts can be installed "
"using <varname>USE_RC_SUBR</varname> as described <link xlink:href="
"\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook/rc-scripts."
"html\">in the Porter's Handbook</link>."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:936
msgid ""
"However, we should consider beforehand the place of our script in the system "
"startup sequence. The service handled by our script is likely to depend on "
"other services. For instance, a network daemon cannot function without the "
"network interfaces and routing up and running. Even if a service seems to "
"demand nothing, it can hardly start before the basic filesystems have been "
"checked and mounted."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:944
msgid ""
"We mentioned <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> already. Now it is "
"time to have a close look at it. In a nutshell, "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> takes a set of files, examines their contents, and "
"prints a dependency-ordered list of files from the set to <varname>stdout</"
"varname>. The point is to keep dependency information <emphasis>inside</"
"emphasis> the files so that each file can speak for itself only. A file can "
"specify the following information:"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:955
msgid ""
"the names of the <quote>conditions</quote> (which means services to us) it "
"<emphasis>provides</emphasis>;"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:960
msgid ""
"the names of the <quote>conditions</quote> it <emphasis>requires</emphasis>;"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:965
msgid ""
"the names of the <quote>conditions</quote> this file should run "
"<emphasis>before</emphasis>;"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:970
msgid ""
"additional <emphasis>keywords</emphasis> that can be used to select a subset "
"from the whole set of files (<citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> can be instructed via "
"options to include or omit the files having particular keywords listed.)"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:977
msgid ""
"It is no surprise that <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> can handle only text "
"files with a syntax close to that of <citerefentry><refentrytitle>sh</"
"refentrytitle><manvolnum>1</manvolnum></citerefentry>. That is, special "
"lines understood by <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> look like "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> comments. The syntax of such special lines is rather rigid to "
"simplify their processing. See <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> for details."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:984
msgid ""
"Besides using <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> special lines, a "
"script can insist on its dependency upon another service by just starting it "
"forcibly. This can be needed when the other service is optional and will not "
"start by itself because the system admin has disabled it mistakenly in "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry>."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:990
msgid ""
"With this general knowledge in mind, let us consider the simple daemon "
"script enhanced with dependency stuff:"
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:994
#, no-wrap
msgid ""
"#!/bin/sh\n"
"\n"
"# PROVIDE: mumbled oldmumble <co xml:id=\"rcng-hookup-provide\"/>\n"
"# REQUIRE: DAEMON cleanvar frotz<co xml:id=\"rcng-hookup-require\"/>\n"
"# BEFORE:  LOGIN<co xml:id=\"rcng-hookup-before\"/>\n"
"# KEYWORD: nojail shutdown<co xml:id=\"rcng-hookup-keyword\"/>\n"
"\n"
". /etc/rc.subr\n"
"\n"
"name=mumbled\n"
"rcvar=mumbled_enable\n"
"\n"
"command=\"/usr/sbin/${name}\"\n"
"start_precmd=\"${name}_prestart\"\n"
"\n"
"mumbled_prestart()\n"
"{\n"
"\tif ! checkyesno frotz_enable &amp;&amp; \\\n"
"\t    ! /etc/rc.d/frotz forcestatus 1&gt;/dev/null 2&gt;&amp;1; then\n"
"\t\tforce_depend frotz || return 1<co xml:id=\"rcng-hookup-force\"/>\n"
"\tfi\n"
"\treturn 0\n"
"}\n"
"\n"
"load_rc_config $name\n"
"run_rc_command \"$1\""
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1022
msgid "As before, detailed analysis follows:"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1026
msgid ""
"That line declares the names of <quote>conditions</quote> our script "
"provides. Now other scripts can record a dependency on our script by those "
"names."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1031
msgid ""
"Usually a script specifies a single condition provided. However, nothing "
"prevents us from listing several conditions there, e.g., for compatibility "
"reasons."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1036
msgid ""
"In any case, the name of the main, or the only, <literal>PROVIDE:</literal> "
"condition should be the same as <envar>${name}</envar>."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1043
msgid ""
"So our script indicates which <quote>conditions</quote> provided by other "
"scripts it depends on. According to the lines, our script asks "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> to put it after the script(s) providing "
"<filename>DAEMON</filename> and <filename>cleanvar</filename>, but before "
"that providing <filename>LOGIN</filename>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1051
msgid ""
"The <literal>BEFORE:</literal> line should not be abused to work around an "
"incomplete dependency list in the other script. The appropriate case for "
"using <literal>BEFORE:</literal> is when the other script does not care "
"about ours, but our script can do its task better if run before the other "
"one. A typical real-life example is the network interfaces vs. the firewall: "
"While the interfaces do not depend on the firewall in doing their job, the "
"system security will benefit from the firewall being ready before there is "
"any network traffic."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1063
msgid ""
"Besides conditions corresponding to a single service each, there are meta-"
"conditions and their <quote>placeholder</quote> scripts used to ensure that "
"certain groups of operations are performed before others. These are denoted "
"by <filename><replaceable>UPPERCASE</replaceable></filename> names. Their "
"list and purposes can be found in <citerefentry><refentrytitle>rc</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry>."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1072
msgid ""
"Keep in mind that putting a service name in the <literal>REQUIRE:</literal> "
"line does not guarantee that the service will actually be running by the "
"time our script starts. The required service may fail to start or just be "
"disabled in <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry>. Obviously, "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> cannot track such details, and "
"<citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></"
"citerefentry> will not do that either. Consequently, the application started "
"by our script should be able to cope with any required services being "
"unavailable. In certain cases, we can help it as discussed <link linkend="
"\"forcedep\">below.</link>"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1086
msgid ""
"<anchor xml:id=\"keywords\"/>As we remember from the above text, "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> keywords can be used to select or leave out some "
"scripts. Namely any <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> consumer can specify "
"through <option>-k</option> and <option>-s</option> options which keywords "
"are on the <quote>keep list</quote> and <quote>skip list</quote>, "
"respectively. From all the files to be dependency sorted, "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> will pick only those having a keyword from the "
"keep list (unless empty) and not having a keyword from the skip list."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1096
msgid ""
"In FreeBSD, <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> is used by <filename>/"
"etc/rc</filename> and <filename>/etc/rc.shutdown</filename>. These two "
"scripts define the standard list of FreeBSD <filename>rc.d</filename> "
"keywords and their meanings as follows:"
msgstr ""

#. (itstool) path: varlistentry/term
#: article.translate.xml:1104
msgid "<literal>nojail</literal>"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:1107
msgid ""
"The service is not for <citerefentry><refentrytitle>jail</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> environment. The "
"automatic startup and shutdown procedures will ignore the script if inside a "
"jail."
msgstr ""

#. (itstool) path: varlistentry/term
#: article.translate.xml:1114
msgid "<literal>nostart</literal>"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:1117
msgid ""
"The service is to be started manually or not started at all. The automatic "
"startup procedure will ignore the script. In conjunction with the "
"<literal>shutdown</literal> keyword, this can be used to write scripts that "
"do something only at system shutdown."
msgstr ""

#. (itstool) path: varlistentry/term
#: article.translate.xml:1127
msgid "<literal>shutdown</literal>"
msgstr ""

#. (itstool) path: listitem/para
#: article.translate.xml:1130
msgid ""
"This keyword is to be listed <emphasis>explicitly</emphasis> if the service "
"needs to be stopped before system shutdown."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1135
msgid ""
"When the system is going to shut down, <filename>/etc/rc.shutdown</filename> "
"runs. It assumes that most <filename>rc.d</filename> scripts have nothing to "
"do at that time. Therefore <filename>/etc/rc.shutdown</filename> selectively "
"invokes <filename>rc.d</filename> scripts with the <literal>shutdown</"
"literal> keyword, effectively ignoring the rest of the scripts. For even "
"faster shutdown, <filename>/etc/rc.shutdown</filename> passes the "
"<option>faststop</option> command to the scripts it runs so that they skip "
"preliminary checks, e.g., the pidfile check. As dependent services should be "
"stopped before their prerequisites, <filename>/etc/rc.shutdown</filename> "
"runs the scripts in reverse dependency order."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1152
msgid ""
"If writing a real <filename>rc.d</filename> script, you should consider "
"whether it is relevant at system shutdown time. E.g., if your script does "
"its work in response to the <option>start</option> command only, then you "
"need not include this keyword. However, if your script manages a service, it "
"is probably a good idea to stop it before the system proceeds to the final "
"stage of its shutdown sequence described in "
"<citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></"
"citerefentry>. In particular, a service should be stopped explicitly if it "
"needs considerable time or special actions to shut down cleanly. A typical "
"example of such a service is a database engine."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1173
msgid ""
"<anchor xml:id=\"forcedep\"/>To begin with, <function>force_depend</"
"function> should be used with much care. It is generally better to revise "
"the hierarchy of configuration variables for your <filename>rc.d</filename> "
"scripts if they are interdependent."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1179
msgid ""
"If you still cannot do without <function>force_depend</function>, the "
"example offers an idiom of how to invoke it conditionally. In the example, "
"our <command>mumbled</command> daemon requires that another one, "
"<command>frotz</command>, be started in advance. However, <command>frotz</"
"command> is optional, too; and <citerefentry><refentrytitle>rcorder</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> knows nothing about "
"such details. Fortunately, our script has access to all "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> variables. If <envar>frotz_enable</envar> is true, "
"we hope for the best and rely on <filename>rc.d</filename> to have started "
"<command>frotz</command>. Otherwise we forcibly check the status of "
"<command>frotz</command>. Finally, we enforce our dependency on "
"<command>frotz</command> if it is found to be not running. A warning message "
"will be emitted by <function>force_depend</function> because it should be "
"invoked only if a misconfiguration has been detected."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:1201
msgid "Giving more flexibility to an rc.d script"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1203
msgid ""
"When invoked during startup or shutdown, an <filename>rc.d</filename> script "
"is supposed to act on the entire subsystem it is responsible for. E.g., "
"<filename>/etc/rc.d/netif</filename> should start or stop all network "
"interfaces described by <citerefentry><refentrytitle>rc.conf</"
"refentrytitle><manvolnum>5</manvolnum></citerefentry>. Either task can be "
"uniquely indicated by a single command argument such as <option>start</"
"option> or <option>stop</option>. Between startup and shutdown, <filename>rc."
"d</filename> scripts help the admin to control the running system, and it is "
"when the need for more flexibility and precision arises. For instance, the "
"admin may want to add the settings of a new network interface to "
"<citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</"
"manvolnum></citerefentry> and then to start it without interfering with the "
"operation of the existing interfaces. Next time the admin may need to shut "
"down a single network interface. In the spirit of the command line, the "
"respective <filename>rc.d</filename> script calls for an extra argument, the "
"interface name."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1221
msgid ""
"Fortunately, <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> allows for passing any "
"number of arguments to script's methods (within the system limits). Due to "
"that, the changes in the script itself can be minimal."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1225
msgid ""
"How can <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> gain access to the extra command-line arguments. "
"Should it just grab them directly? Not by any means. Firstly, an "
"<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> function has no access to the positional parameters of its "
"caller, but <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> is just a sack of such "
"functions. Secondly, the good manner of <filename>rc.d</filename> dictates "
"that it is for the main script to decide which arguments are to be passed to "
"its methods."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1235
msgid ""
"So the approach adopted by <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry> is as follows: "
"<function>run_rc_command</function> passes on all its arguments but the "
"first one to the respective method verbatim. The first, omitted, argument is "
"the name of the method itself: <option>start</option>, <option>stop</"
"option>, etc. It will be shifted out by <function>run_rc_command</function>, "
"so what is <envar>$2</envar> in the original command line will be presented "
"as <envar>$1</envar> to the method, and so on."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1244
msgid ""
"To illustrate this opportunity, let us modify the primitive dummy script so "
"that its messages depend on the additional arguments supplied. Here we go:"
msgstr ""

#. (itstool) path: informalexample/programlisting
#: article.translate.xml:1249
#, no-wrap
msgid ""
"#!/bin/sh\n"
"\n"
". /etc/rc.subr\n"
"\n"
"name=\"dummy\"\n"
"start_cmd=\"${name}_start\"\n"
"stop_cmd=\":\"\n"
"kiss_cmd=\"${name}_kiss\"\n"
"extra_commands=\"kiss\"\n"
"\n"
"dummy_start()\n"
"{\n"
"        if [ $# -gt 0 ]; then<co xml:id=\"rcng-args-start\"/>\n"
"                echo \"Greeting message: $*\"\n"
"        else\n"
"                echo \"Nothing started.\"\n"
"        fi\n"
"}\n"
"\n"
"dummy_kiss()\n"
"{\n"
"        echo -n \"A ghost gives you a kiss\"\n"
"        if [ $# -gt 0 ]; then<co xml:id=\"rcng-args-kiss\"/>\n"
"                echo -n \" and whispers: $*\"\n"
"        fi\n"
"        case \"$*\" in\n"
"        *[.!?])\n"
"                echo\n"
"                ;;\n"
"        *)\n"
"                echo .\n"
"                ;;\n"
"        esac\n"
"}\n"
"\n"
"load_rc_config $name\n"
"run_rc_command \"$@\"<co xml:id=\"rcng-args-all\"/>"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1288
msgid "What essential changes can we notice in the script?"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1292
msgid ""
"All arguments you type after <option>start</option> can end up as positional "
"parameters to the respective method. We can use them in any way according to "
"our task, skills, and fancy. In the current example, we just pass all of "
"them to <citerefentry><refentrytitle>echo</refentrytitle><manvolnum>1</"
"manvolnum></citerefentry> as one string in the next line — note <envar>$*</"
"envar> within the double quotes. Here is how the script can be invoked now:"
msgstr ""

#. (itstool) path: callout/screen
#: article.translate.xml:1300
#, no-wrap
msgid ""
"<prompt>#</prompt> <userinput>/etc/rc.d/dummy start</userinput>\n"
"Nothing started.\n"
"<prompt>#</prompt> <userinput>/etc/rc.d/dummy start Hello world!</userinput>\n"
"Greeting message: Hello world!"
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1307
msgid ""
"The same applies to any method our script provides, not only to a standard "
"one. We have added a custom method named <option>kiss</option>, and it can "
"take advantage of the extra arguments not less than <option>start</option> "
"does. E.g.:"
msgstr ""

#. (itstool) path: callout/screen
#: article.translate.xml:1313
#, no-wrap
msgid ""
"<prompt>#</prompt> <userinput>/etc/rc.d/dummy kiss</userinput>\n"
"A ghost gives you a kiss.\n"
"<prompt>#</prompt> <userinput>/etc/rc.d/dummy kiss Once I was Etaoin Shrdlu...</userinput>\n"
"A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu..."
msgstr ""

#. (itstool) path: callout/para
#: article.translate.xml:1320
msgid ""
"If we want just to pass all extra arguments to any method, we can merely "
"substitute <literal>\"$@\"</literal> for <literal>\"$1\"</literal> in the "
"last line of our script, where we invoke <function>run_rc_command</function>."
msgstr ""

#. (itstool) path: important/para
#: article.translate.xml:1326
msgid ""
"An <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> programmer ought to understand the subtle difference between "
"<envar>$*</envar> and <envar>$@</envar> as the ways to designate all "
"positional parameters. For its in-depth discussion, refer to a good handbook "
"on <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
"citerefentry> scripting. <emphasis>Do not</emphasis> use the expressions "
"until you fully understand them because their misuse will result in buggy "
"and insecure scripts."
msgstr ""

#. (itstool) path: note/para
#: article.translate.xml:1337
msgid ""
"Currently <function>run_rc_command</function> may have a bug that prevents "
"it from keeping the original boundaries between arguments. That is, "
"arguments with embedded whitespace may not be processed correctly. The bug "
"stems from <envar>$*</envar> misuse."
msgstr ""

#. (itstool) path: sect1/title
#: article.translate.xml:1348
msgid "Further reading"
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1350
msgid ""
"<anchor xml:id=\"lukem\"/><link xlink:href=\"http://www.mewburn.net/luke/"
"papers/rc.d.pdf\">The original article by Luke Mewburn</link> offers a "
"general overview of <filename>rc.d</filename> and detailed rationale for its "
"design decisions. It provides insight on the whole <filename>rc.d</filename> "
"framework and its place in a modern BSD operating system."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1357
msgid ""
"<anchor xml:id=\"manpages\"/>The manual pages "
"<citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></"
"citerefentry>, <citerefentry><refentrytitle>rc.subr</"
"refentrytitle><manvolnum>8</manvolnum></citerefentry>, and "
"<citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry> document the <filename>rc.d</filename> components "
"in great detail. You cannot fully use the <filename>rc.d</filename> power "
"without studying the manual pages and referring to them while writing your "
"own scripts."
msgstr ""

#. (itstool) path: sect1/para
#: article.translate.xml:1364
msgid ""
"The major source of working, real-life examples is <filename>/etc/rc.d</"
"filename> in a live system. Its contents are easy and pleasant to read "
"because most rough corners are hidden deep in "
"<citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</"
"manvolnum></citerefentry>. Keep in mind though that the <filename>/etc/rc.d</"
"filename> scripts were not written by angels, so they might suffer from bugs "
"and suboptimal design decisions. Now you can improve them!"
msgstr ""