Bespoke services: application/catman

For various reasons—some reasonable, some suspect—Solaris doesn't ship with a compiled set of windex databases for its manual pages. The unfortunate result is that helpful commands like apropos(1) or man -k are unhelpful:

$ apropos sort
/usr/man/windex: No such file or directory

smf(5) provides one way to address this shortcoming, via a transient service to be run during startup. Our service description would be roughly equivalent to the following:

<?xml version="1.0"?>
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">

<service_bundle type='manifest' name='sch:catman'>

<service
        name='application/catman'
        type='service'
        version='1'>

        <create_default_instance enabled='false' />

        <single_instance />

        <!--
          By default, application/catman will run in the background
          during boot.  If you want to run it periodically, execute

             # /usr/sbin/svcadm restart catman

          If you wish to augment the default MANPATH, use the setenv
          subcommand to svccfg(1M).  For instance, to add the Java
          manual pages to the build:

             # /usr/sbin/svccfg -s application/catman
             > setenv MANPATH /usr/share/man:/usr/java/man
             > exit

             # /usr/sbin/svcadm refresh catman

          If MANPATH is not defined, the default manual path is
          /usr/share/man, as per catman(1M).
        -->

        <dependency
                name='local-filesystems'
                type='service'
                grouping='require_all'
                restart_on='none'>
                <service_fmri value='svc:/system/filesystem/local' />
        </dependency>

        <dependency
                name='remote-filesystems'
                type='service'
                grouping='optional_all'
                restart_on='none'>
                <service_fmri value='svc:/network/nfs/client' />
                <service_fmri value='svc:/system/filesystem/autofs' />
        </dependency>

        <exec_method
                type='method'
                name='start'
                exec='/usr/bin/catman -w'
                timeout_seconds='0' />

        <exec_method
                type='method'
                name='stop'
                exec=':true'
                timeout_seconds='0' />

        <property_group name='startd' type='framework'>
                <propval name='duration' type='astring' value='transient' />
        </property_group>

        <stability value='Unstable' />

        <template>
                <common_name>
                        <loctext xml:lang='C'>
                                manual page index generation
                        </loctext>
                </common_name>

                <documentation>
                        <manpage
                                title='catman'
                                section='1M'
                                manpath='/usr/share/man' />
                </documentation>
        </template>
</service>

</service_bundle>

Following my own instructions in the comment block, I defined a value for MANPATH and refreshed the service. My setting can be double-checked with svcprop(1) like so:

$ svcprop -p start application/catman
start/exec astring /usr/bin/catman\ -w
start/timeout_seconds count 0
start/type astring method
start/environment astring MANPATH=/usr/share/man:/usr/openwin/man:/usr/sfw/man:/usr/dt/man:/usr/perl5/man:/usr/java/man:/usr/apache/man:/usr/X11/man:/opt/sfw/man:/opt/csw/man

Issuing "svcadm enable catman" will cause the service to be executed immediately, and upon each subsequent boot. Our earlier query becomes fecund:

$ apropos sort
FcFontSort      FcFontSort (3fontconfig)    - Return list of matching fonts
aclsort         aclsort (3sec)  - sort an ACL
alphasort       scandir (3c)    - scan a directory
alphasort       scandir (3ucb)  - scan a directory
bsearch         bsearch (3c)    - binary search a sorted table
bunzip2         bzip2 (1)       - a block-sorting file compressor and associated utilities
bzcat           bzip2 (1)       - a block-sorting file compressor and associated utilities
bzip2           bzip2 (1)       - a block-sorting file compressor and associated utilities
bzip2recover    bzip2 (1)       - a block-sorting file compressor and associated utilities
disksort        disksort (9f)   - single direction elevator seek sort for buffers
ldap_sort       ldap_sort (3ldap)   - LDAP entry sorting functions
ldap_sort_entries               ldap_sort (3ldap)   - LDAP entry sorting functions
ldap_sort_strcasecmp            ldap_sort (3ldap)   - LDAP entry sorting functions
ldap_sort_values                ldap_sort (3ldap)   - LDAP entry sorting functions
libbz2          libbz2 (3)      - library for block-sorting data compression
look            look (1)        - find words in the system dictionary or lines in a sorted list
qsort           qsort (3c)      - quick sort
sort            sort (1)        - sort, merge, or sequence check text files
sortbib         sortbib (1)     - sort a bibliographic database
tsort           tsort (1)       - topological sort
...

1. Add a configuration property that makes the service also rebuild the nroffed versions of the manual pages, if set to true.
2. Make the service regenerate only in the case that components in the path have changed.

Tie knot: Knot 54 (Hanover).