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 the system) or <filename>/usr/local/sbin</filename>
(for ports) and call it from a &man.sh.1; script in the (for ports) and call it from a &man.sh.1; script in the
appropriate <filename>rc.d</filename> directory.</para> 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 <filename>rc.d</filename> scripts must be written in
the &man.sh.1; language, see how <filename>/etc/rc</filename> the &man.sh.1; language, see how <filename>/etc/rc</filename>
invokes them, then study the internals of invokes them by means of <function>run_rc_script</function>,
<function>run_rc_script</function>.</para> then study the implementation of
</note> <function>run_rc_script</function> in
<filename>/etc/rc.subr</filename>.</para>
</tip>
</callout> </callout>
<callout arearefs="rcng-dummy-include"> <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; set <envar>name</envar> before it calls &man.rc.subr.8;
functions.</para> 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> <note>
<para>The current style of <filename>rc.d</filename> <para>The current style of <filename>rc.d</filename>
scripting is to enclose values assigned to variables 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 <para>The body of a sophisticated method can be implemented
as a function. It is a good idea to make the function as a function. It is a good idea to make the function
name meaningful.</para> 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>
<callout arearefs="rcng-dummy-loadconfig"> <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 This is a trivial example of how &man.rc.conf.5; variables
can control an <filename>rc.d</filename> script.</para> 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> <note>
<para>While it is possible to use a shorter name internally, <para>While it is possible to use a shorter name internally,
e.g., just <envar>msg</envar>, prepending a unique e.g., just <envar>msg</envar>, adding the unique prefix
prefix to global names will save us from possible <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> collisions with the &man.rc.subr.8; namespace.</para>
<para>As long as an &man.rc.conf.5; variable and its <para>As long as an &man.rc.conf.5; variable and its
@ -980,7 +1006,7 @@ fi</programlisting>
<informalexample> <informalexample>
<programlisting>#!/bin/sh <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"> # REQUIRE: DAEMON cleanvar frotz<co id="rcng-hookup-require">
# BEFORE: LOGIN<co id="rcng-hookup-before"> # BEFORE: LOGIN<co id="rcng-hookup-before">
# KEYWORD: nojail shutdown<co id="rcng-hookup-keyword"> # KEYWORD: nojail shutdown<co id="rcng-hookup-keyword">
@ -1019,27 +1045,9 @@ run_rc_command "$1"</programlisting>
several conditions there, e.g., for compatibility several conditions there, e.g., for compatibility
reasons.</para> reasons.</para>
<para>The best style is to use the same name for the <para>In any case, the name of the main, or the only,
following entities:</para> <literal>PROVIDE:</literal> condition should be the
same as <envar>${name}</envar>.</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>
</note> </note>
</callout> </callout>