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

Move the paragraphs on run_rc_command syntax and properties to above

Browse source 
the example so that a reader can understand it better.

Note current $* misuse in run_rc_command so that a reader who understands
$@ and experiments with its application to run_rc_command isn't confused.

Suggested by:	dougb (1st explicitly and 2nd implicitly)
This commit is contained in:
Yaroslav Tykhiy 2007-03-04 13:33:06 +00:00
parent 51a90a53d0
commit 23ef79f4d4
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=29698
1 changed files with 32 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1187,8 +1187,28 @@ run_rc_command "$1"</programlisting>
<para>Fortunately, &man.rc.subr.8; 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.
To illustrate this opportunity, let us modify the primitive
Due to that, the changes in the script itself can be minimal.</para>
<para>How can &man.rc.subr.8; gain
access to the extra command-line arguments. Should it just
grab them directly? Not by any means. Firstly, an &man.sh.1;
function has no access to the positional parameters of
its caller, but &man.rc.subr.8; 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.</para>
<para>So the approach adopted by &man.rc.subr.8; 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.</para>
<para>To illustrate this opportunity, let us modify the primitive
dummy script so that its messages depend on the additional
arguments supplied. Here we go:</para>
@ -1264,23 +1284,10 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen>
</callout>
<callout arearefs="rcng-args-all">
<para>The only question left is how &man.rc.subr.8; can gain
access to the extra command-line arguments. Should it just
grab them directly? Not by any means. Firstly, an &man.sh.1;
function has no access to the positional parameters of
its caller, but &man.rc.subr.8; 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.</para>
<para>So the approach adopted by &man.rc.subr.8; 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.
Consequently, if we want just to pass all extra arguments to
<para>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.</para>
for <literal>"$1"</literal> in the last line of our script,
where we invoke <function>run_rc_command</function>.</para>
<important>
<para>An &man.sh.1; programmer ought to understand the
@ -1293,11 +1300,13 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen>
buggy and insecure scripts.</para>
</important>
<para>The <function>run_rc_command</function> function will
consume its first argument to find the method. Hence an
apparent shift by one argument: What is <envar>$2</envar>
in the command line will be presented as <envar>$1</envar>
to the method, and so on.</para>
<note>
<para>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.</para>
</note>
</callout>
</calloutlist>
</sect1>