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
...

Exercises
  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).

Comments:

So - what are the reasons Solaris ships without compiled windexes ?

Posted by Alex Madden on March 29, 2005 at 03:01 PM PST #

Stephen, you forgot step 3. 3. bringover, add this feature, putback :) Very nice :)

Posted by Dan Price on March 30, 2005 at 02:22 PM PST #

@Alex: I think the traditional argument is based in our inability to find all possible valid manual page hierarchies on the system. There's probably a middle ground, if we synthesize the path from a set of defaults plus the values in the various <manpage> tags in the services on the system. @Dan: I believe I was assigning exercises, but yes. &mdash; Stephen

Posted by Stephen on March 30, 2005 at 03:27 PM PST #

Sorry, I meant to say "exercise 3"-- by which I mean to say, a good exercise for someone (if you are too busy) would be to take this and put it back.

Alex, I think the other historical reason has been that people have always talked about building the windex database at pkgadd time, as opposed to at system boot. Stephen, one idea might be to make catman smarter-- detecting new or changed pages (by size and datestamp?) since its last run. Then we could just do a restart once a day, via a cron job (nice'd if needed).

Posted by Dan Price on March 30, 2005 at 05:14 PM PST #

Post a Comment:
Comments are closed for this entry.
About

sch

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today
External blogs