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

<

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

<

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

  • Alex Madden

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

  • http://blogs.sun.com/dp Dan Price

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

  • http://blogs.sun.com/sch/ Stephen

    @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

  • http://blogs.sun.com/dp Dan Price

    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.

    <

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