In this section we will see the basic layout of a shellmod script, how to use it and how it communicate with Linuxconf.
The shellmod package provides the following parts:
A script may be used either stand-alone or within Linuxconf. It can be used both ways.
To run a shellmod script, you either do
shellmod path_of_the_script [ arguments ]
Or if the script start with #!/usr/bin/shellmod, you simply
run it like any utility. Note that in all cases, the script must
be executable (chmod +x script).
To be used this way, it must be registered in Linuxconf. This is done
either interactively or using a special command line. The shellmod module
register its configuration menu in the Control files and systems
menu. You will find there a dialog to register your script. Just
enter the path of your script and that's it. The script will be
visible in Linuxconf at the next run.
The script may be registered using the following command line. This is especially useful if you include your script in a package and would like to register the script in Linuxconf at package installation (RPM packagers might consider the trigger facility to do this).
linuxconf --modulemain shellmod --setmod script_path
Note that the linuxconf --modulemain construct is the normal
way to yield control to a module own command line: shellmod is not
different.
You may unregister a script from Linuxconf by doing:
linuxconf --modulemain shellmod --unsetmod script_path
Note that the above syntax replicate the way normal (C++) Linuxconf
modules may be registered and unregistered, by using the linuxconf --setmod
and linuxconf --unsetmod command lines.
This is almost equivalent to the standalone mode, except that linuxconf and all its modules are listening. This mode is necessary if your script uses the virtual registry: Linuxconf and its modules have to be alived to react properly.
linuxconf --modulemain shellmod --exec script_path \
[--debug] [--perl] script arguments
A shellmod script will always look like this:
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
register(){
# Put regmenu and comanager calls here
}
# Put here the various functions referenced above
main(){
# We define a sub-menu or a dialog
}
# The script always end with the dispatch function call. Always
dispatch
The register function is required if the script is used as a Linuxconf module. Linuxconf will call the function expecting the script to pass back the list of menu and dialog in which it want to register. Here is an example of a register function installing two sub-menu and one co-manager.
# Register in the "miscellaneous service" menu
echo regmenu main MENU_MISCSERV \"main menu of the module\"
# Register at the end of the dnsconf menu
echo regmenu function2 dnsconf \"Some title\"
# Register as a co-manager in the user account dialog
echo comanager function-prefix user
The register function is not needed for stand-alone module. It is a good idea to provide a minimal one in case a user try to register this module in Linuxconf. The following one will make it clear the script is not intended to be use this way:
register(){
echo error \"This shellmod script can't be use as a module\"
}
If the script is used stand-alone, it requires a function called main. The shellmod utility will blindly call this function. It is a good idea to always provide one. In the register function we often register in a Linuxconf menu the main function. Done this way, the script provides a consistent interface used either stand-alone or as a Linuxconf module.
The main function will generally define a menu or a dialog. Note that the main function is the one which will receive the script arguments. The arguments will often be used as default values for the dialog fields. Here is a small example.
main(){
echo DIALOG
echo newf_str path \"Document path\" $1
echo newf_str mail \"Email this document to\" $2
echo newf_str fax \"Fax this document to\" $3
echo edit \"Document manager\" \"Fill this form to send the document\"
dispatch
echo end
if [ "$CODE" = "accept" ] ; then
if [ "$mail" != "" ] ; then
cat $path | mail $mail
fi
if [ "$fax" != "" ] ; then
spoolfax $fax $path
fi
fi
}
A module always ends with a call to the dispatch function. A shellmod script may be seen as a set of function waiting to be called (A library). Based on context, Linuxconf (or shellmod for stand-alone scripts) will call the appropriate one.
Note that the script can perform some initialization before calling the dispatch function. As explain later, a script may be seen as a small server which keeps its state between calls to its various functions.
A shellmod script interact with shellmod or Linuxconf by echoing commands on it standard output. It receives directives by simply reading its standard input. The dispatch function takes care of reading and processing (dispatching) the request it receives. We can think of the script as being in sandwich between two shellmod process like this
shellmod | script | shellmod
Everything echoed by the script is grabbed by shellmod and interpreted
as protocol commands. It is important to redirect the output of sub-command
you are using either to the error channel (command >&2) or
to /dev/null. Failing to do so will trigger many error messages from
shellmod.