os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Insist on using ${name} as the prefix for global names even

Browse source 
stronger, as suggested by dougb@, but do so in the right context.
I.e., don't fire all the requirements at once in the last section,
but tell each of them where the current topic is most appropriate.

Polish some wording and markup.
This commit is contained in:
Yaroslav Tykhiy 2006-10-27 10:30:52 +00:00
parent ea9c8ce4b8
commit 2ad2c2ecc3
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=28952
1 changed files with 36 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
en_US.ISO8859-1/articles/rc-scripting/article.sgml
View file

@ -240,13 +240,17 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"></programlisting>
(for the system) or <filename>/usr/local/sbin</filename>
(for ports) and call it from a &man.sh.1; script in the
appropriate <filename>rc.d</filename> directory.</para>
</note>
<para>If you would like to know the details about why
<tip>
<para>If you would like to learn the details of why
<filename>rc.d</filename> scripts must be written in
the &man.sh.1; language, see how <filename>/etc/rc</filename>
invokes them, then study the internals of
<function>run_rc_script</function>.</para>
</note>
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>.</para>
</tip>
</callout>
<callout arearefs="rcng-dummy-include">
@ -284,6 +288,11 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"></programlisting>
set <envar>name</envar> before it calls &man.rc.subr.8;
functions.</para>
<para>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.</para>
<note>
<para>The current style of <filename>rc.d</filename>
scripting is to enclose values assigned to variables
@ -331,6 +340,14 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"></programlisting>
<para>The body of a sophisticated method can be implemented
as a function. It is a good idea to make the function
name meaningful.</para>
<important>
<para>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 &man.rc.subr.8; or another common include
file.</para>
</important>
</callout>
<callout arearefs="rcng-dummy-loadconfig">
@ -463,10 +480,19 @@ run_rc_command "$1"</programlisting>
This is a trivial example of how &man.rc.conf.5; variables
can control an <filename>rc.d</filename> script.</para>
<important>
<para>The names of all &man.rc.conf.5; 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.</para>
</important>
<note>
<para>While it is possible to use a shorter name internally,
e.g., just <envar>msg</envar>, prepending a unique
prefix to global names will save us from possible
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 &man.rc.subr.8; namespace.</para>
<para>As long as an &man.rc.conf.5; variable and its
@ -980,7 +1006,7 @@ fi</programlisting>
<informalexample>
<programlisting>#!/bin/sh
# PROVIDE: mumble mumbled<co id="rcng-hookup-provide">
# PROVIDE: mumbled oldmumble <co id="rcng-hookup-provide">
# REQUIRE: DAEMON cleanvar frotz<co id="rcng-hookup-require">
# BEFORE: LOGIN<co id="rcng-hookup-before">
# KEYWORD: nojail shutdown<co id="rcng-hookup-keyword">
@ -1019,27 +1045,9 @@ run_rc_command "$1"</programlisting>
several conditions there, e.g., for compatibility
reasons.</para>
<para>The best style is to use the same name for the
following entities:</para>
<itemizedlist>
<listitem>
<para>the script's file;</para>
</listitem>
<listitem>
<para>its main <literal>PROVIDE:</literal> condition;</para>
</listitem>
<listitem>
<para>its <envar>${name}</envar>;</para>
</listitem>
<listitem>
<para>the prefix of its &man.rc.conf.5; variables,
as well as of its private variables and functions.</para>
</listitem>
</itemizedlist>
<para>In any case, the name of the main, or the only,
<literal>PROVIDE:</literal> condition should be the
same as <envar>${name}</envar>.</para>
</note>
</callout>