Source string Read only

(itstool) path: important/programlisting
Context English State
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.
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.
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.
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.
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>.
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.
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.
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>.
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:
<prompt>#</prompt> <userinput>/etc/rc.d/mumbled</userinput>
Usage: /etc/rc.d/mumbled [fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll)
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.
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.
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.
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.
The following is the correct usage of <function>checkyesno</function>:
if checkyesno mumbled_enable; then
On the contrary, calling <function>checkyesno</function> as shown below will not work — at least not as expected:
if checkyesno "${mumbled_enable}"; then
<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>.
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.
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.
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>.
Connecting a script to the rc.d framework
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></filename>&gt; and &lt;<filename></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>.
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.
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:
the names of the <quote>conditions</quote> (which means services to us) it <emphasis>provides</emphasis>;
the names of the <quote>conditions</quote> it <emphasis>requires</emphasis>;
the names of the <quote>conditions</quote> this file should run <emphasis>before</emphasis>;
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.)
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.


No matching activity found.

Browse all component changes

Things to check

Multiple failing checks

The translations in several languages have failing checks



English English
No related strings found in the glossary.

Source information

Source string comment
(itstool) path: important/programlisting
no-wrap, read-only
Source string location
String age
a year ago
Source string age
a year ago
Translation file
articles/rc-scripting.pot, string 99