The translation is temporarily closed for contributions due to maintenance, please come back later.

Source string Read only

(itstool) path: note/para
Context English State
Which other services will our service depend on, and vice versa?
From the examples that follow we will see why it is important to know the answers to these questions.
A dummy script
The following script just emits a message each time the system boots up:
#!/bin/sh<co xml:id="rcng-dummy-shebang"/>

. /etc/rc.subr<co xml:id="rcng-dummy-include"/>

name="dummy"<co xml:id="rcng-dummy-name"/>
start_cmd="${name}_start"<co xml:id="rcng-dummy-startcmd"/>
stop_cmd=":"<co xml:id="rcng-dummy-stopcmd"/>

dummy_start()<co xml:id="rcng-dummy-startfn"/>
echo "Nothing started."

load_rc_config $name<co xml:id="rcng-dummy-loadconfig"/>
run_rc_command "$1"<co xml:id="rcng-dummy-runcommand"/>
Things to note are:
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:
<prompt>#</prompt> <userinput>/etc/rc.d/dummy start</userinput>
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.
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>.
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.
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.
Some useful functions related to networking are provided by another include file, <filename>/etc/network.subr</filename>.
<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.
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.
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.
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.
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.
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.
The body of a sophisticated method can be implemented as a function. It is a good idea to make the function name meaningful.
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.
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.
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.
A configurable dummy script
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:

. /etc/rc.subr

rcvar=dummy_enable<co xml:id="rcng-confdummy-rcvar"/>


load_rc_config $name<co xml:id="rcng-confdummy-loadconfig"/>
: ${dummy_enable:=no} <co xml:id="rcng-confdummy-enable"/>
: ${dummy_msg="Nothing started."}<co xml:id="rcng-confdummy-opt"/>

echo "$dummy_msg"<co xml:id="rcng-confdummy-msg"/>

run_rc_command "$1"
What changed in this example?
The variable <envar>rcvar</envar> specifies the name of the ON/OFF knob variable.
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.
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>.
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.


No matching activity found.

Browse all component changes

Source information

Source string comment
(itstool) path: note/para
Source string location
String age
a year ago
Source string age
a year ago
Translation file
articles/rc-scripting.pot, string 39