man−db−thedatabasecachedmanualpagersuite GraemeW.Wilford<eep2gw@ee.surrey.ac.uk> ColinWatson<cjwatson@debian.org> Thisdocumentdescribesthesetup,maintenanceanduseofagenericonline manualpagesystemwithspecialreferencetotheman−dbpackageanditsadvancedfeatures. man−db v2.5.2 December4,2010 UNIXisaregisteredtrademarkoftheX/OpenCompany,Ltd. NFSisaregisteredtrademarkofSunMicrosystems,Inc. PostScriptisaregisteredtrademarkofAdobeintheUnitedStates. Thegeneralconventionsusedthroughoutthismanualinclude •filenamesandpathsinitalic,e.g./usr/share/man. •variablestrings(usuallypathcomponents)enclosedwithin<>andinitalic,eg.<sec>, •programnamesinbold,eg.man. •commandsthatcanbetypedatashellpromptinabox,eg.manfoobar. •environmentvariablesdenotedasfollows:$ENVVAR Copyright◯C1995GraemeW.Wilford Copyright◯C2001,2002,2003,2007ColinWatson Permissionisgrantedtomakeanddistributeverbatimcopiesofthismanualprovidedthecopyrightnoticeandthispermissionnoticearepreservedonallcopies. Permissionisgrantedtocopyanddistributemodifiedversionsofthismanualundertheconditions forverbatimcopying,providedthattheentireresultingderivedworkisdistributedunderthe termsofanoticeidenticaltothisone. Permissionisgrantedtocopyanddistributetranslationsofthismanualintoanotherlanguage, undertheaboveconditionsformodifiedversions,exceptthatthispermissionnoticemaybestated inatranslationapprovedbythecopyrightholder. man−db v2.5.2 December4,2010 1.Introduction 1.1.man−db man−dbisapackagethatisdesignedtoprovideuserswithonlineinformationinafastand friendlymannerwhileatthesametimeofferingflexibilitytothesystemadministrator. Itismadeupofseveraluserprograms: •man−aninterfacetotheon-linereferencemanuals •whatis−searchthemanualpagenames •apropos−searchthemanualpagenamesanddescriptions •manpath−determinesearchpathformanualpages •lexgrog−directlyreadheaderinformationinmanualpages severalmaintenanceprograms: •mandb−createorupdatethemanualpageindexcaches •catman−createorupdatethepre-formattedmanualpages andaspecialpre-formatterthatknowsaboutcompressedmanualpages: •zsoelim−satisfy.sorequestsinroffinput Inadditiontothesecompiledprograms,therearetwoshellscripts,mkcatdirsandcheckmanin thetoolssubdirectory.Thesescriptsaidthecreationofcatdirectoriesandcheckforduplicated manualpages,respectively. Thefollowingmanualpagesareprovidedwiththispackagetoexplaincorrectformatandusage. man(1),whatis(1),apropos(1),manpath(1),lexgrog(1),manpath(5),mandb(8),catman(8)andzsoelim(1). 1.1.1.Theconcept man−dboriginallystartedoutlifeasprogramsuiteman−1.1B,writtenbyJohnW.Eaton <jwe@che.utexas.edu>andmaintainedbyRikFaith<faith@cs.unc.edu>towhichsupportproposedbythenewlyformedFSSTNDcommitteeregardingcatdirectorieswasadded. Sincethen,man−db’smostinnovativefeature:thedatabasecachescheme1hasbeensignificantly developed.Thebasicideawastoreducemanualpagesearchtimestoaminimum.Thefollowing pieceoftextisincludedfromtheman-db-2.2distribution: Thetheory:Ifyougotoalibrarytotakeabookout,whatdoyoudo? a)Goandlookwhereitmightbeonamicro-fiche/terminal,takealookwhereitissupposedtobe ontheshelf,andthengolookatthenewarrivalsifit’snotwhereit’ssupposedtobe? OR b)Startatoneendofthegroundfloor,lookalongeverybookshelfuntilyou’vecompletedthat floor,thengoupalevelandstartagainuntilyou’vefoundwhatyou’relookingfor? Sincethenthedatabaseindexschemehasevolvedgreatly.Everymanualpageandstraycatpage onthesystemisregisteredinanindexdatabasecachewhichstoresvariousdetailsaboutthefile 1originallyconceivedafterobservingtheactionsofthePerl-basedmanualpagersuite,man-plwrittenbyTomChris-tiansen<tchrist@convex.com> 1 man−db v2.5.2 December4,2010 includingthetimestamp,thelocationandthewhatis2information.Thisinformationiskeptupto datebyregularrunsofmandb.Insomeconfigurationsmanalsolooksforfilesystemchanges eachtimeitisinvokedandhelpstokeepthedatabasecachecurrent,butthisimposesapenalty onmanualpagesearchtimes. 1.2.Themanualpagesystem Thesimplestmanualpagesystemwillhaveasinglemanualpagehierarchy.Thiswilltypicallybe /usr/share/man beneathwhichwillbeseveralsubdirectoriesoftheformman<sec>where<sec>is1,2,3,4,5,6, 7or8.Thesearereferredtoassectionsofthemanual.Othersmayexistandtheyarenot restrictedtosinglecharacternames.eg. /usr/share/man/manfoo isavalidsectionsubdirectory.Othercommonsectionsinclude9,n,l,pando. Withinthesesectionsubdirectoriesresidethemanualpagesthemselves.Theirfilenamesfollowthe pattern /usr/share/man/man<sec>/<name>.<sec><ext> whereinmostcases<ext>isanemptystring.Anexampleismanualpagecp /usr/share/man/man1/cp.1 whichresidesinsection1andhasnospecialextension. 1.3.Sectionsofthemanual Themanualissplitupintosectionstoeaseaccessandtocaterformanualpagesthatsharethe samename.Itiscommonforaprogramandfunctiontosharethesamename.killisagood example.Thisisbothaprogramwhichcanbeusedtosendaprocessasignalandanoperating systemcallwithsimilarfunctionality.Theirmanualpagesarestoredundersections1and2 respectively.Thus,sectionsareusedtoseparateouttheprogrammanualpagesfromthefunction manualpagesandsoon.Thetablebelowshowsthesectionnumbersofthemanualfollowedby thetypesofpagestheycontain. SectionSectioncontents 1userexecutableprogramsorshellcommands 2systemcalls(functionsprovidedbythekernel) 3librarycalls(functionswithinsystemlibraries) 4specialfiles(usuallyfoundin/dev) 5fileformatsandconventionseg./etc/passwd 6games 7macropackagesandconventionseg.man(7),groff(7). 8systemadministrationcommands 9kernelroutines[Non-standard] nnew[obsolete] llocal[obsolete] ppublic[obsolete] oold[obsolete] 2onelinedescriptionofthemanualpage 2 man−db v2.5.2 December4,2010 1.4.Theformatofmanualpages TheformatinwhichmanualpagesarestoredisNROFF/TROFFormoregenerallyROFF.This isatypesetterstylelanguage3whichrequiresformattingbeforebeingviewed.Infactsomemanualpagesrequirepre-formatprocessingtocorrectlyformattablesorequations. Ifthepageistobeviewedonscreeninatextenvironment,NROFFisusedastheprimaryformatter.Ifthepageistobeprintedordisplayedinagraphicalenvironment,TROFFisused.Traditionally,TROFFformattedfilesforaC/A/T(ComputeraidedTypesetter)whichisnowobsolete. TheGNUROFF(GROFF4)suiteofprogramsofferachoiceofoutputtypesincludingX,dviand postscript.Whenconfiguringman−db,thepreferenceistouseGROFFratherthanTROFF. 1.5.Argumentstoconfigure Toallowtheconfigurationprogram,configure,tobenon-interactive,itcanbepassedvarious optionstoalterthedefaultsettings.Genericconfigureoptionsarediscussedindocs/INSTALL. Optionsthatarespecifictotheman−dbpackagearedescribedbelow. −−enable−setuid[=ARG] Bydefault,manwillbeinstalledasasetuidprogramtouserman.Usethisoptionwithan argumenttochangethesetuidowner. −−disable−setuid Usethisoptiontoinstallmanasanon-setuidprogramandtochangethedefaultcatand databasefiles’accessflagstoallowuserstomodifythem. −−enable−mandirs=OS Bydefault,man−dbsupportsmanualpagedirectoriesinanyofseverallayoutsusedbyfree andproprietaryversionsofUNIX.However,incertaincases,thiscancauseman−dbto findthewrongpagebymistake,especiallywhenthenamesofsomemanualpagesonthe systemcontainperiods.UsethisoptionwithanargumentofGNU,HPUX,IRIX,Solaris, orBSD(ormorethanoneofthese,separatedbycommas)tosupportonlythelayoutstypicallyusedoneachofthosesystems.Notethatman−dbisnotcurrentlycapableofwriting catpagesintheproperBSDlayout. −−with−device=DEVICE UsethisflagtoalterthedefaultoutputdeviceusedbyNROFF.DEVICEispassedto NROFFwiththe−Toption.configurewilltestthatNROFFwillrunwiththesupplied deviceargument. −−with−db=LIBRARY configurewilllookfordatabaseinterfacelibrariesintheorderBerkeleyDB,gdbmand finallyndbmandwill#defineappropriatevariablesrelativetothefirstonefound.Tooverridethebuilt-inorderonplatformshavingachoiceofinterfacelibrary,usethisoptionto specifywhichlibrarytouse. 3similarinsomeaspectstoTeX 4WrittenbyJamesClark<jjc@jclark.com>andnowmaintainedbyTedHarding<ted.harding@nessie.mcc.ac.uk> andWernerLemberg<wl@gnu.org> 3 man−db v2.5.2 December4,2010 2.ThespecificsofSections 2.1.Packagespecificmanualpagesections Theuseofpackagespecificmanualpagesectionsisdiscouragedaspackageslargeenoughtowarranttheirownsectionprobablycontainmanualpagesthatspanothersections.Anexample mightbepackagefoothathasitsownsection /usr/share/man/manfoo whichcontainsmanualpagesdescribingitsprograms,thelibraryroutinesitoffersandtheformat ofseveralofitsconfigurationfiles.Thesepageswouldnormallybeallocatedtosections1,3and 5respectivelyandthuscombiningthemallundersectionfooismisleading.Subtleproblemswill ariseifthereareanybasename-spaceclasheswithstandardmanualpages,e.g.exit(3),exit(foo) andtheorderinwhichtheyshouldbeshown. Therearetwostandardsolutionstothisproblem. (1)Createaseparatemanualpagehierarchyforthepackage’smanualpagessuchas /usr/local/packages/foo/man (2)Installthepagesintheirrelevantsections,withauniqueextensionappendedtothefilenamesuchthat /usr/share/man/manfoo/exit.foo wouldinsteadbeinstalledas /usr/share/man/man1/exit.1foo Only(2)offersacompletesolutiontomanualpageorderingproblemsandallowsuserstoaccess thedesiredpagedirectly. 2.2.Selectingasectiontype 2.2.1.Specifyingasection Thisisdoneviauseofthesectionargumenttoman man1exit willlookforexit.1*insection1ofthemanual.Ifexit.1exists,itwillbedisplayedinpreference toexit.1foo man1fooexit willlookforexit.1foo*insection1ofthemanual.Theasterisk(*)representsawild-cardofany typeorlength,includinglengthzero. Foranargumenttobeinterpretedasasectionnameratherthanapagename,itmusteither beginwithadigit,orbeincludedinthestandardsectionlist.Thedefaultsectionlistisdefined ininclude/manconfig.htobe1,n,l,8,3,2,5,4,9,6and7.Thisshouldbemodifiedinorder andcontenttomeetthelocalconventions.Itmaybealteredatrun-timeusingtheSECTION directiveintheman−dbconfigurationfile. Everysubdirectorysectionnameintheentiresystemmustbeinthelist,includingsectionsfound inimportedmanualpagehierarchies.Itisnotnecessarytolistsectionswithextensionsunlessa specialorderingforthoseextensionsisdesired.Theorderisimportantbecauseinnormaloperation,manwillonlydisplaythefirstmanualpageitfindsthatmeetsthesearchcriteria.Usingthe −−allargumentwillcausemantoattempttodisplayallmanualpagesthatmeetthecriteria. Seeman(1)forfurtherinformation. Havinganexcessofsectionslistedwillnotslowmandown. 4 man−db v2.5.2 December4,2010 2.2.2.Specifyinganextension Ifthesectionisunknown,butthepackageextensionis,itispossibletousetheextensionargument man−efooexit tosearchinallsectionsformanualpagesnamedexitfrompackagefoo. man−db v2.5.2 December4,2010 3.Filesystemstructure 3.1.Manualpagehierarchies Itisoftencommonformanualpagesystemstohavemorethanonemanualpagehierarchy. IndeedoneofthesystemsIusehasthefollowinggloballyaccessiblehierarchies /usr/man /usr/local/man /usr/local/tex/man /usr/local/pbm/man /usr/X11R6/man /usr/openwin/man /usr/local/packages/pvm/man Afullsystem$MANPATHwouldbeacolonseparatedlistofthesedirectories.Theorderis important,andisobservedbyman−db’ssearchalgorithms.Theorderisverymuchrelatedtothe user’s$PATHenvironmentvariable,andshouldbesetonaperuserbasis,ornotsetatall.Ifa user’s$PATHcauses /usr/local/packages/bin/foobar tobeexecutedinpreferenceto /usr/bin/foobar, itisessentialthat manfoobar displaysthemanualpagelocatedwithin /usr/local/packages/man ratherthanwithin /usr/share/man Toensurecorrectorder,theprogrammanpathmaybeusedtosetthe$MANPATHenvironment variable.Seemanpath(1)andmanpath(5)fordetails. 3.2.SettingtheMANPATH IfusingaBournestyleloginshellsuchasbash,ksh,orzsh,thecommands exportMANPATH MANPATH=‘manpath−q‘ canbeaddedto$HOME/.profile IfusingaCstyleloginshellsuchascshortcsh,thecommands setenvMANPATH‘manpath−q‘ canbeaddedto$HOME/.login N.B.$PATHmustbesetpriortousingmanpath.Thesettingof$MANPATHisactually unnecessaryastheman−dbutilitieswilldynamicallydeterminethemanpathif$MANPATHis unset. 3.3.Determinationoftheinternalmanpath Allman−dbutilities,manpathincluded,willusetheuser’s$MANPATHenvironmentvariableif setandnotequalto"".Otherwisetheuser’s$PATHenvironmentvariableisqueried.Ifthisis unsetorissetto"",thedeterminedmanpathwillsimplybeany 6 man−db v2.5.2 December4,2010 MANDATORYMANPATH elementsdefinedintheman−dbconfigfile. Assumingthata$PATHexists,eachpathelementitcontainsisscannedforintheconfigfile.If found,thecorrespondingmanpathelementisappendedtotheinternalmanpath.However,ifthe elementisnotmentionedintheconfigfile,amandirectoryrelativetoitwillbesought.Thesubdirectories../man,man,../share/man,orshare/manrelativetothepathcomponentare appendedtotheinternalmanpathiftheyexist.Finally,theinternalmanpathisstrippedof duplicatepathsbeforebeingprocessedbytheNLSand‘OtherOS’routines.Thesemayaddto ormodifytheseparatepathelementsgivingprioritytoNLSmanualpagesoraddOS-relative manpaths. 3.4.OtherOS’smanualpages Itiscommontohavecollectionsofheterogeneouscomputersystemslinkedtogetherinanetwork. Insomecircumstances5itisadvantageoustobeabletoaccessthemanualpagesoftheseother systemsdirectlyfromyoursystem.Thisfeatureisknownasalternatesystemsupport.The acceptedwaytosetupthissupportistoNFSmounttherespectivesystems’manualpagehierarchiesunderthenativemanualpagehierarchies.Anexample: SystemManualpagehierarchy <local>/usr/share/man newOS/usr/share/man/newOS userix/usr/share/man/userix <local>/usr/local/man newOS/usr/local/man/newOS userix/usr/local/man/userix RatherthanhavemultipleNFSmountsfromasinglemachine,thismaybeaccomplishedbyNFS mounting <other-sys>:/usr somewhereonthelocalsystemandusingsymboliclinkswithinthemanualhierarchies.Toaccess thesealternatesystemsusingmanusethe−mor−−systemsoption,eg. man−−all−−systemsuserix:newOS5passwd wouldprovidemanualpagesshowingthestructureof/etc/passwdonsystemsuserixandnewOS inthatorder.Amanualpagewouldnotbedisplayedaboutthelocalsystemsconventions.Please readtherelevantman−dbutility’smanualpageforfurtherandmorespecificinformation. 3.5.NLSmanualpages NLSmanualpagesshouldbeinstalledinNLSsubdirectoriesofastandardmanualpagehierarchy. Thesubdirectorynamesshouldbemadeupoflanguage,territory,andcharactersetcomponents asnecessarytospecifythelocaleofthemanualpage. Thecharactersetcomponentdescribestheencodingofthemanualpageitself,andnottheencodinginusebytheuser;amanualpageinstalledunderthefr.UTF-8subdirectorywillbeusedin thefrFR.ISO-8859-1localeaswellasfrFR.UTF-8,andconvertedbetweenencodingsasnec-essary.Ifnocharactersetisspecifiedinthesubdirectoryname,adefaultappropriateforthelan-guagewillbeused;notethat,forcompatibilityreasons,thiswilltypicallybealegacylanguage-5writingportablesoftwareinstantlycomestomind 7 man−db v2.5.2 December4,2010 specificcharactersetratherthanUTF-8. Theterritoryshouldnormallybeomittedunlessitisnecessarytodescribethemanualpagetext. Forexample,BrazilianPortugueseisquitedistinctfromPortugueseandsoshouldbeinstalled undertheptBR.UTF-8subdirectory,butasingleGermanmanualpagewilltypicallysufficein AustriaaswellasinGermanyandsoshouldbeinstalledunderthede.UTF-8subdirectory. Thefollowingtablegivessomeexamples. LanguageTerritoryCharacterSetDirectory FrenchanyISO-8859-1/usr/share/man/fr FrenchCanadaISO8859-1/usr/share/man/frCA FrenchanyUTF-8/usr/share/man/fr.UTF-8 GermanGermanyUTF-8/usr/share/man/deDE.UTF-8 GermanSwitzerlandISO8859-1/usr/share/man/deCH.ISO-8859-1 JapaneseJapanEUC-JP/usr/share/man/jaJP.EUC-JP JapaneseanyUTF-8/usr/share/man/ja.UTF-8 OnsystemssupportingUTF-8,itisrecommendedthatallmanualpagesbeencodedusingUTF-8 wherepossible,inordertosimplifythetaskofeditingavarietyofpageswithoutreconfiguring editorsandterminalsandthelike. Eachofthesedirectoriesaretheninterpretedasmanualpagehierarchiesthemselvesandmaycontaintheusualsectionsubdirectories.AccesstoNLSmanualpagesisachievedviauseofthesetlocale(3)functionwhichqueriesuserenvironmentvariablestodeterminethecurrentlocale. Internallytotheman−dbutilities,thislocalestringisappendedtoeachmanpathelementand theresultantNLSmanpathelementissearchedbeforethestandardmanpathelement.Inthis way,anNLSmanualpagethatmatchesthesearchcriteriawillbeshownbeforeorinplaceofthe standardAmericanEnglishpage. Ifauser’s$MANPATHconsistsoforisdeterminedas /usr/local/man:/usr/share/man:/usr/X11R6/man andtheirlocaleissettodeDE,thecommand man−−systemsuserix:manfoobar wouldproducethefollowinginternalman−dbmanpathelements /usr/local/man/userix/deDE /usr/local/man/userix/de /usr/local/man/userix /usr/share/man/userix/deDE /usr/share/man/userix/de /usr/share/man/userix /usr/X11R6/man/userix/deDE /usr/X11R6/man/userix/de /usr/X11R6/man/userix /usr/local/man/deDE /usr/local/man/de /usr/local/man /usr/share/man/deDE /usr/share/man/de /usr/share/man /usr/X11R6/man/deDE /usr/X11R6/man/de 8 man−db v2.5.2 December4,2010 /usr/X11R6/man foobarwouldbesearchedforintheorderofmanualpagehierarchieslisted.Additionaldirectoriescorrespondingtomanualpagesencodedindifferentcharactersetswouldbeusedifpresent. 3.5.1.ISO8859-1(latin1)manualpages BydefaultNROFFwillformatmanualpagesintoaformsuitableforatypewriterstyledevice, e.g.aterminalscreen.GNUNROFFiscapable6offormattingROFFintoaformsuitablefor8-bit latin1capableoutputdevices.Toenableoutputforsuchadevice,givetheoption −−with−device=DEVICE toconfigurewhereDEVICEisthesuitableandsupportedoutputformat,inthiscaselatin1. 3.5.2.Displayingnon-ASCIIcharactersonaLinuxvirtualterminal Toviewnon-ASCIIcharactersattheLinuxconsole,youmusthaveoneofthekbd7andcon-sole−toolspackagesinstalled.Ifyoursystemdoesnotcomewithsuitableconfigurationalready, thenpleaseseethedocumentationinthekbdorconsole−toolspackagefordetailsonhowtoconfiguretheconsoleforyourlocale.Onmodernsystems,thebestchoiceislikelytobetousethe UTF-8encodingwithafontsuitableforyourlanguage.Makesurethatyourlocaleenvironment variablesmatchtheencodingdisplayedbytheconsole.Fordisplayunderthe“XWindowSystem”,asuitable8-bit-cleanterminalemulatorisrequired. 3.5.3.ViewingASCIIpagesformattedforlatin1outputdevice WhenformattinganASCIImanualpageforalatin1outputdevice,GNUNROFFwilltake advantageoftheextracharactersavailableandwillalwaysproduceatextpagecontainingsome latin1(8-bit)symbols.Thetable8below,takenfromman(1),illustratesthedifferences. DescriptionOctalISO8859-1ASCII continuationhyphen255− bullet(middledot)267•o acuteaccent264´ ’ multiplicationsign327×x Todisplaysuchsymbolsona7bitterminalorterminalemulator,theymustbetranslatedback intostandardASCII.The−7optionwithmanwillenablethissimplereversetranslation. Thisoptionmaybeusefulifyoursitehasboth7and8-bitcapableoutputdevicesandnroffis usingthelatin1outputdevicetoformatmanualpages. 3.6.Catpages Ithasbecomestandardpracticetostoretheformattedmanualpagesondisksothatsubsequent requestsforthemanualpagedonothavetoinvolvetheformattingprocess.Thesepre-formatted manualpagesareknownascatpages.Althoughcatpagesrequireadditionaldiskstoragerequirements,theyprovideasubstantialspeedincreaseandtheiruseisrecommended. 6seenroff(5)fortheoutputdeviceformatsavailablewithyourNROFF 7writtenandmaintainedbyAndriesBrouwer<aeb@cwi.nl>. 8TheISO8859-1andASCIIcolumnsofthistablewillbeidenticalifthismanualwasformattedforanASCIIbased typewriterdisplay,i.e.usingNROFFinitsnativemode. 9 man−db v2.5.2 December4,2010 Theautomaticsupportforstoringandusingcatpagesisbroughtaboutbysimplycreatingsuitabledirectoriesforthem. 3.7.Catpagehierarchies Traditionally,catpageswerestoredunderthesamemanualhierarchyastheirsourcemanual pages,incat<sec>subdirectoriesratherthanman<sec>.Thissituationisratherlimitinginseveral situations: •Whenitisadvantageoustomount/usrasaread-onlyfilesystem.Catpagescannotbesup-portedinthissituationwithoutuseofsymboliclinkstovariousotherareasofthefilesystem. Thissituationisagreaterproblemifthemediaitselfisread-only,suchasCD-ROM. •WhenNFSmountingalternateOS’smanualpagehierarchies.Thealternatesystemmaybe undersomeoneelse’scontrolandtheymaynotwantcatpagesstoredontheirsystem.Infact, itisusuallyagoodideatoexportthemanualpagefilesystemsread-only,orimportthemthat way.Itispossibletoavoidtheproblems,thistimewithevenmoresymboliclinksthatmay needperiodicupdating. •Ifthereisamixtureofnormalcatfilesandstraycats9,itisverydifficulttoperiodicallytrim thecatspacediskusagebyremovingseldomaccessedcatfiles. Toavoidalloftheseproblemssimultaneously,itwasdecidedtosupportlocalcatpagedirectory caches. 3.8.Localcatpagedirectorycaches Anylocationforcatpagehierarchymaybespecifiedintheman−dbconfigurationfile.Thelocationofthedatabasecacheassociatedwitheachmanualpagehierarchywillalwaysbeattheroot ofthecatpagehierarchy.Bydefault,thecatpagehierarchyshadowsthemanualpagehierarchy. TheFHSproposes/var/cache/manasthelocationforsuchdirectories,althoughman−dballows anydirectoryhierarchytobeused.TheFHSpathtransformationruleisasfollows: /usr/<hierarchy>/share/man/<locale>/man<sec>/page.<sec><ext> shouldbeformattedintothecatfile /var/cache/man/<hierarchy>/<locale>/cat<sec>/page.<sec><ext> wherethe<locale>directorycomponentmaybemissingand<ext>maybeanemptystring. Thesuggestionisthatstraycatsarelocatedinthetraditionalhierarchyunder/usrwhereasrecreatablecatpagesarestoredunderthelocalwritablehierarchy/var/cache/man.manfollows strictrulesindeterminingwhichfileisdisplayed. Asanexample,thefollowingrouteistakenifallthreefilesexist. (1)Checkrelativemodificationtimestampsofthemanualfileandthetraditionalcatfile.If thecatfileisuptodate(hasanequaltimestamp),displayit. (2)Thetraditionalcatfileisoutofdate.Checkrelativetimestampsofthemanualfileand thealternatecatfile.Ifthecatfileisuptodate,displayit. (3)Thealternatecatfileisoutofdate.Formatthemanualfileanddisplaytheresultinthe foreground,whileupdatingthealternatecatfileinthebackground. Whenacatfileiscreated,itstimestampissettothatofthecorrespondingmanualfile.Manual filesareoftenstoredintararchives,andtimestampsmaybepreservedwhenthesearchivesare unpacked.Simplycheckingwhetherthecatfileisnewerwouldsometimescausemantodisplay anout-of-datecatfileinthiscase,whenitshouldhavereformattedthemanualfileinstead. 9catfilesthathavenosourcemanualpage,i.e.theycannotberecreated. 10 man−db v2.5.2 December4,2010 4.Compression 4.1.Compressedmanualpages Itispossibletomaintainasystemofcompressedmanualpages.Thisimposesasmalloverhead ontheformattingprocess,butisneverthelessusuallyreasonableinordertoavoidunnecessary consumptionofdiskspace. Presently,thecompressionextension/decompressorpairsmustbeknownatcompiletimealthough anynumbermaybedefinedandused.Thefollowingstructureispredefinedinman−db: ExtensionDecompressor gzgzip−dc zgzip−dc Zcompress−dc Itisarelativelyeasyoperationtoincludefurtherpairsinthisstructure.Seeinclude/compsrc.h fordetailsandanexample. Supportforcompressedmanualpagesiscompiledintotheman−dbutilitiesbydefault.Tocompletelydisablethissupport,editconfig.handcommentoutthefollowingline #defineCOMPSRC1 Thiswillenableaminorspeedincrease,butnotethatsupportforstraycatswithanycompression extensionotherthanthedefaultwillalsobedisabled. 4.2.Compressedcatpages man−dbcompressescatfilesbydefault.Duringconfiguration,configurewilltrytofindgzip and,iffound,allcatfilesproducedbymanwillbecompressedwith gzip−7c andhavea.gzextensionappended.Ifgzipisnotfound, compress−c isusedasthecompressorandtheextension.Zisappended. Tostorecatfilesinanuncompressedstateandtodisablecompressedextensionprocessingcompletely,editconfig.handcommentoutthefollowingline #defineCOMPCAT1 4.2.1.Straycats Normally,manwillonlylookforcatfileswiththedefaultcompressionextension.Thedefault compressionextensionisdependentonthedefaultcompressorandmaybeanemptystringifthe supportforcompressedcatsisdisabled. Itispossibleforasystemtobesuppliedwithstraycatfileslocatedinthetraditionalcatpage hierarchy.Tomakemattersworse,theymayhavecompressionextensionsotherthanthedefault andresideonread-onlymedia.Insuchcircumstances,straycatfileswillbeacceptedwithany compressionextensionthatisalsosupportedformanualpages. Thisspecialtreatmentofstraycatpagesisremovedifsupportforcompressedmanualpagesis turnedoffornotavailable. 11 man−db v2.5.2 December4,2010 5.Formatting Asalreadypointedoutintheintroduction,therearetwoprimaryformatterscommontoUNIX: NROFFandTROFF. Inthefollowingsections,IwillusethetermTROFFtodescribethetypesetterformatterand NROFFtodescribethetypewriterformatter.ThetermROFFwillbeusedtodescribeageneric formatter. 5.1.GROFF IfusingtheGROFFpackage,thereisafurtherchoice,GROFFitself.Essentially,GROFFforms apipelineofprocessorsincludingTROFFandanoutputprocessorwhichtranslatestheditroff producedbyTROFFintotheappropriateoutputformat.Thedefaultoutputformat,ordevice, forGROFFisPostScript.Anythingelsemustbespecifiedusingthedeviceargument.ToillustrateGROFF,thecommand groff−Tdvi/dev/null willformthefollowingpipeline troff−Tdvi/dev/null|grodvi IfGROFFistiedtoman’s−Toption,itisstillpossibleformantoproduceditroffviauseofthe −Zoption. InGROFF1.09,NROFFisbundledasashellscriptthatcallsGROFF,whichinturncalls TROFFwiththedefaultoptions−Wall−mtty-char−Tascii,passingtheresultthrough grottybeforeitfinallyreachesthescreen. Itisimperativethatthescriptdoesnotpasspre-processingoptionstoGROFF’scommandlineas mantakescareofthisseparately. 5.2.Devices BothNROFFandGROFFmayallowoutputdeviceselection.Asmentionedpreviously,classic NROFFproducesoutputsuitableforatypewriterdevice,classicTROFFproducesoutputsuitableforaC/A/TandGROFFproducesoutputsuitableforaPostScriptinterpretingdeviceby default. 5.3.Macros ThereareseveralROFFmacrosetsinexistencethataresuitableformanualpages.Unfortunately,theytendtobeincompatiblewitheachother. Duringconfiguration,configurewillattempttodetermineasuitablemacrosetforthelocalsystem’smanualpagecollection.ItattemptstouseNROFFwiththefollowingthreemacropackages: macropackagemacrofilenamenroffcommand andoctmac.andocorandoc.tmacnroff−mandoc antmac.anoran.tmacnroff−man doctmac.docordoc.tmacnroff−mdoc Thefirstthatsucceedsisused.Theandocmacrosetissuitableformanualpageswrittenusing eitheranordocmacrocommands,butnotacombinationofboth. 12 man−db v2.5.2 December4,2010 5.4.Pre-formatprocessors(pre-processors) Manualpagesmayrequirepre-processingbyanyofthefollowing ProgramIDPre-processes eqneequations tblttables grapggraphs picppictures referrAbibliography vgrindvprogramlistings Itispossibletoassignadefaultpre-processorlistthatallmanualpageswillbepassedthrough priortotheprimaryformatter.Bydefault,thisisempty.Todefineadefaultlist,edit include/manconfig.handun-commentthefollowingline /*#defineDEFAULTMANROFFSEQ"t"*/ whichwillenabletblprocessingbydefault.Tochangethelist,replacethetwithasuitable stringofprocessorID’s. Pre-processoptionsmaybeprovidedatruntimeinvariousforms,butingeneralthepre-proces-sorsrequiredbyeachmanualpageisindicatedinthefirstlineofthemanualpageitself.See man(1)fordetails. Ifamanualpagedoesnotcontainapre-processorstringinitsfirstline,itwillbescannedfor well-knownROFFrequestsusedtopassinputtocertainpre-processors.Thus,thepre-processor stringisoftenunnecessaryforcorrectoutput,butshouldneverthelessbeincludedforefficiency. 5.5.Formatscripts Itisverylikelythatalternatesystemsmanualpagesmayrequirenon-standardmacropackagesor possiblyevenspecialpre-processors.Totacklesuchproblems,specialformatscriptsmaybecre-atedonapermanualhierarchybasis. Ifthefile <manualhierarchy>/mandbnfmt existsandisexecutable,itisexpectedtobeabletocorrectlyformatamanualpageoriginating from<manualhierarchy>toitsstandardoutput.Itwillbesuppliedwitheithertwoorthree arguments: •manualpagefilename •pre-processorstring •outputdevice(optional) Similarly,iftheoption−T<device>or−twassuppliedtomanandthefile <manualhierarchy>/mandbtfmt existsandisexecutable,itwillbeusedinthesameway. Anexampleofsuchascript,suppliedbyMarkusArmbruster<armbru@pond.sub.org>,whoprovidedsupportforexternalformatterscripts,canbefoundastools/mandbfmt-script ThescriptcanbeusedasbothanNROFFandTROFF/GROFFformatscriptandcanbe installedasmandbnfmtandhardlinkedtomandbtfmtaftermodificationappropriateforyour particularsite. 13 man−db v2.5.2 December4,2010 6.Theindexdatabasecaches Asmentionedintheintroduction,man−dbusesdatabaselookupstosearchformanualpagelocationsandinformation.Whenperformingamanualpagelookuporabasicwhatissearch,the databasesaresearchedin key→content modeandareasfastastheunderlyingdatabasescanbe.Whenperformingaproposorspecial whatissearches,thedatabasesaresearchedinalinearway,which,althoughfarmoreexpensive thankeyedlookup,isnoworsethantraditionaltextbasedfilesearching. 6.1.indexdatabaselocation Thedatabasesarealwayslocatedattherootofthecatpagehierarchy,whetherthisisthesame asthemanualpagehierarchyornot.Asfilelockingmechanismsareemployedtoensurethatconcurrentprocessesdonotupdateadatabasesimultaneously,itisalmostimperativethatthe databasesresideonalocalfilesystemsincefilelockingacrossNFSfilesystemsmaybeunavailable orflaky.Toavoidsuchproblems,mancanbecompiledwithoutdatabasemaintenancesupport. Seethesectiontitled"Modesofoperation"fordetails. 6.1.1.Manualhierarchieswithnoindexdatabase Itispossiblefortheman−dbutilitiestooperatewithoutaidfromanindexdatabase.Undersuch circumstances,searchmethodswilluseonlyfileglobbingandwhatistypesearchesareperformed onanytraditionalwhatistextdatabasesthatmayexist.Onlythetraditionalcathierarchyis searchedforcatfiles. 6.1.2.Usermanualpagehierarchies Ausermayhaveanynumberofpersonalmanualpagehierarchieslistedintheir$MANPATH. Bydefault,manwillmaintainmandbcreateddatabasesattherootofusermanualpagehierarchies.Thedefinitionofausermanualhierarchyisthatitdoesnothaveanentryintheman−db configurationfile.Seemanpath(5)fordetails. 6.2.Contentsofanindexdatabase Therearefourkindsofentryinanindexdatabase. (1)Adirectentryregardingaparticularmanualpage.Manualpagesthatareuniqueinterms ofnameusejustasingleentryinthedatabaseandcanbelookedupbysimplyusingthe nameasthekey. (2)Acommonnameindexentrythatliststheextensionsofallofthemanualpagessharing thecommonindexentryname.Manualpagesthatsharecommonnamesbuthavedifferingextensionseachhaveasingledatabaseentry,butthistimetheyarelookedupwitha keycomprisedoftheirnameandtheirextension.Theentiresetofcommonnamedpages alsohasancommonnameindexentrythatinformsoftheextensionsavailable. (3)Anindirectentrythathasapointertotherealentry.Manualpagesthatarewhatisreferencestoaparticularpagedonotphysicallyexistsotheyhaveapointertotheentrycontainingthelocationoftherealmanualpage. (4)Specialidentificationentries.Therearetwospecialkeynames,“$mtime$”thatreferences anintegerdescribingthelastmodificationtimeofthedatabaseand“$version$”thatidentifiesthedatabasestorageschemeversion. Inordertosupportlookingupmanualpagesinacase-insensitivefashion,keysarestoredinlower case.Ifthenameofthepagewasnotalreadyinlowercase,itstruecaseisalsostoredinthe commonnameindexentry. 14 man−db v2.5.2 December4,2010 Inthefollowingentries,thecharacter“|”willbeusedtoseparatethefields.Inrealityatabis used.Directandindirectentriestakestheform: <name>→<realname>|<ext>|<sec>|<mtime>|<ID>|<ref>|<filter>|<comp>|<whatis> Commonnameindexentriestaketheform: <name>→|<realname1>|<ext1>|<realname2>|<ext2>|<realname3>|<ext3>|...<realnamen>|<extn> andcommonnamedirectorindirectentriestaketheform: <name>|<ext>→<realname>|<ext>|<sec>|<mtime>|<ID>|<ref>|<filter>|<comp>|<whatis> whereineachcasethefilenamebeingrepresentedisformedas <manualhierarchy>/man<sec>/<name>.<ext>.<comp> inthecaseofamanualpage,or <cathierarchy>/cat<sec>/<name>.<ext>.<comp> inthecaseofastraycat. Ifanyofthefieldswouldbeempty,asingle“−”isstoredinitsplace.<comp>representsthe compressionextension,<mtime>isanintegerrepresentingthelastmodificationtimeofthemanualpage,<ref>pointstotheentrycontainingthelocationoftherealpage,<ID>isoneofthefollowingidentificationletters,and<filter>representsanypreprocessorsthatareneededtodisplay thepage. ID#defineDescription AULTMANultimatemanualpage,thefullsourcenrofffile BSOMANmanualpagecontaininga.sorequesttoanULTMAN CWHATISMANvirtualwhatisreferencedpagepointingtoanULTMAN DSTRAYCATcatpagewithnosourcemanualpage EWHATISCATvirtualwhatisreferencedpagepointingtoaSTRAYCAT TheIDillustratestheprecedence.Sometypesofmanualpagecanbereferencedbyseveral means,e.g..sorequestedandwhatisreferred.Insuchacase,onlyonereferencemustbestoredin thedatabase,theprecedenceleveldecideswhich. 6.2.1.Favouringstraycats Withtheaboverulesofprecedence,itispossibleforavalidstraycatpagetobereplacedbya whatisreferredpagesharingidenticalname-space. Ifyouwouldliketoseethestraycatpagekill(1)insteadofthebashbuiltins(1)pagereferenced bykill(1),editinclude/manconfig.handun-commentthefollowingline /*#defineFAVOURSTRAYCATS*/ 6.2.2.Accessdb Asimpleprogram,accessdbisincludedwithman−db.Itwilloutputthedatacontainedwithin aman−dbdatabaseinahumanreadableform.Bydefault,itwilldumpthedatafrom /var/cache/man/index.<db-type>,where<db-type>isdependentonthedatabaselibraryinuse. Supplyinganargumenttoaccessdbwilloverridethisdefault.Tabsarereplacedintheoutputby atilde“˜ ”inthekeyfieldandasinglespaceinthecontentfield. 15 man−db v2.5.2 December4,2010 6.2.3.Exampledatabase Asanexampleofbothaccessdbandthedatabasestoragemethod,theoutputof src/accessdbman/index.bt afterfirstrunning src/mandbman fromthetoplevelbuilddirectoryisincludedbelow. $mtime$->"795987034" $version$->"2.3.1" apropos->"11795981542A--searchthemanualpagenamesanddescriptions" catman->"88795981544A--createorupdatethepre-formattedmanualpages" man->"11795981542A--aninterfacetotheon-linereferencemanuals" mandb->"88795981544A--createorupdatethemanualpageindexcaches" manpath->"15" manpath˜ 1->"11795981542A--determinesearchpathformanualpages" manpath˜ 5->"55795981543A--formatofthe/etc/mandb.configfile" whatis->"11795981543A--searchthemanualpagenames" zsoelim->"11795981543A--satisfy.sorequestsinroffinput" 6.3.Databasetypes man−dbhassupportforvariouslowleveldatabaselibrariescommonlyinusetoday.Theinterfacestothelibrariesareknownas •ndbm(UNIX) •gdbm(GNU) •btree(BerkeleyDB) man−dbcurrentlydoesnotholdmorethanonedatabaseopenatanytime,so •dbm(UNIX) supportcouldbeaddedinthefuture. 6.4.Limitations Thegeneraldifferencesandlimitationsarebestcomparedinatable. Contentmemory File Concurrent nametypelimitaccess NameType Shareable ndbmhashindex10static1Kbnoneno gdbmhashindex.dbdynamic−filelockingno btreebinarytreeindex.btstatic−noneyes Thosetypesthathavenobuiltinconcurrentaccessstrategyareprovidedwithflock(2)basedfile lockingbyman−db. Asbtreeisnoticeablyfasterwhendoingmansearches,mainlyduetothefastinitializationof thedatabases,itisthepreferredlibraryinterface.configurewilllookforbtree,gdbmandthen finallyndbmroutineswhenconfiguringman−db. 10ndbmdatabasesarephysicallyrepresentedbytwofiles,index.dirandindex.pag,butarereferredtosimplyasindex bytheinterfaceroutines. 16 man−db v2.5.2 December4,2010 6.5.Sharingdatabasesinaheterogeneousenvironment Itmaybenecessaryoradvantageoustosharedatabasesacrossplatforms,regardlessofthepotentialfilelockingproblems. AnexamplewouldbeauserhavingapersonalmanualpagehierarchyinanNFSbasedhome directoryenvironment,wherebythehomedirectoryisheldonandmountedfromasinglemachine inaheterogeneousnetwork. Inthiscontext,thedatabasecachewillhavethesamenameandresideinthesameplaceonall machines.Thereareatleasttwowaystodealwiththisproblem. •Hacktheinclude/manconfig.hfileoneachplatformtoprovideauniquedatabasenamefor eachsystem.Nodatabaseswillbeshared. •InstallandusetheBerkeleyDBdatabaseinterfacelibraryoneachplatform.Thesedatabases canbesharedacrossbig-endian/little-endianplatformsalthoughadatabasecreatedonabig-endianplatformwillsufferasmallaccesspenaltywhenusedbyalitle-endianmachineand vice-versa. man−db v2.5.2 December4,2010 7.Miscellaneous 7.1.Modesofoperation Theman−dbutilitiescanoperateinmanydifferentmodes,allowingvaryingdegreesoffreedom, functionalityandsecurity.Nomoderequiresthatthemanualpagehierarchiesbewritable. (1)Defaultmode manissetuidtotheuserMANOWNERwhichis‘man’bydefaultandischangeablevia optionstoconfigure.mandb,ifrunbythesuperuserorMANOWNER,createsglobally accessibleindexdatabasesownedbyMANOWNER.Oncethedatabasesarecreated,man willupdateentriesinthemifitfindsnewlyinstalledmanualpages(ifthe−−updateflagis used)ordeleteentriesifmanualpagesareremoved.Inthismodeitispossibleforamaliciousmanusertodeliberatelylockadatabaseasawriter,thusdenyingreadaccesstoother users. Ifcatdirectoriesexistandhavethecorrectpermissions,manwilltakecareofproducingcat files.ThesewillbeownedbyMANOWNER.Thedefaultpermissionsofbothcatfilesand databasesare0644. (2)Nomandatabaseupdates Thismodealsorequiresmantobesetuid,butisfavouredwheredatabasesmustbeshared inanenvironmentunfriendlytokernellockingprocedures,eg.NFS.Italsopreventspossible“denialofservice”attacksbymaliciousmanusersasmanneveropensthedatabasesas awriterinthismode.Toreplacethefunctionalitylostbydisallowingmanwriteaccessto thedatabases,mandbshouldbererunwhenevernewmanualpagesareinstalled.Otherwise,manwillnotbeabletousethedatabasetofindanddisplaythenewlyaddedmanual pages,andwillhavetousethefilesysteminstead.Eachindexdatabasemaybeownedby anarbitraryuserwhowillhavesubsequentwriteaccesstothedatabase.Catfilesarecreatedinthesamewayasformode(1)above. Tousetheman−dbutilitiesinthismode,editinclude/manconfig.handcommentout ‘#defineMANDBUPDATES’. (3)Nomandatabaseupdatesorcatproduction manisinstallednotsetuid.Thismodeofoperationprobablyoffersthehighestlevelof securitybutitrequireshigherlevelsofmaintenancethanothermodesduetotherestrictions imposeduponman.Eachdatabaseisownedbyanarbitraryuserasinmode(2).Eachcat hierarchyisalsoownedbyanarbitraryuserwhoisresponsibleforcreatingcatfilesusing catmanwhenevernewmanualfilesareinstalled.manwillbecompletelypassiveinits action,i.e.noindexdatabaseswillbewrittentoandnocatfilesareeverproduced. Tousetheman−dbutilitiesinthismode,supplytheoption‘−−disable−setuid’toconfigureandeditinclude/manconfig.h,commentingout‘#defineMANDBUPDATES’and ‘#defineMANCATS’afterrunningconfigure,orbuildman−dbasinmode(1)andinstall thebinarieswithoutthesetuidbitset. (4)Wideopen manisinstallednotsetuid.Thismodeissimilarinoperationtothemajorityofvendor supplied,nonsetuid,catfilesupportingmanualpagersuites.Itisnotrecommended.The databasesareownedbyanarbitraryuserwhomaintainsthemusingmandb.mandoes notupdatethedatabases.Catfilesareproducedandstoredinworldwritablecatdirectoriesandhaveworldwriteaccessthemselves. Tousetheman−dbutilitiesinthismode,supplytheoption‘−−disable−setuid’toconfigure,editinclude/manconfig.handcommentout‘#defineMANDBUPDATES’andchange thedefinitionofCATMODEfrom0644to0666. Othervariationscanalsobeused.Infactitispossibleformantoactuallycreateindex databases,usuallythejobofmandb,forusers’privatemanualpagehierarchies.Thisisenabled byeditinginclude/manconfig.handun-commentingthe‘/*#defineMANDBCREATES*/’ 18 man−db v2.5.2 December4,2010 line.man−db−2.2operatedinthismanner. Insummary,include/manconfig.hcontainsdefinitionsfor •MANDBCREATES •MANDBUPDATES •MANCATS •CATMODE •DBMODE andthesetuidinstallationandoperationofmanismodifiedbysupplyingeitherofthefollowing optionstoconfigure: •−−enable−setuid=USER •−−disable−setuid 7.2.NFSrootsquash Ifmanisinstalledsetuidtoanarbitraryuserandisrunbyroot,insteadofgainingtheeffective useridofthesetuiduser,manisrunwithbothuidandeuidasroot.Thisisneccesarydueto infelicitieswiththePOSIXsetuid()functioncall:Allusersexceptrootmaychangetoandfrom theeffective(setuid)user,howeveronceroothassetuid(user),thereisnowayback. AsideeffectofthisisthatNFSmountedcathierarchiesordatabaseswillbeunwritableifthe followingconditionsexist: •man/catman/mandbisrunbyroot •TheNFSmounthastherootsquashflagset Togetaroundthisproblem,therootusermustfirstattaintheIDofthecathierarchyordatabase ownerbeforerunningman/catman/mandbwheneverthedatabasesneedupdatingorcatfiles aretobeproduced. 7.3.NLSmessagecatalogues man−dbhasbuiltinsupportfornativelanguagemessagecatalogues.Thatis,itcanissuemessagesinthelocaleoftheuser’schoice.Thiswillonlyoccurifthelocale’stranslationhasbeen written.Beforeundertakingatranslation,pleasecontacttheTranslationProject(http://translationproject.org/)whoarecoordinatingsuchactivities. 7.4.Credits Theauthorswouldliketothankthefollowingpeoplefortheirtime,effort,support,ideasand codewhichwentintoman−db: MarkusArmbruster<armbru@pond.sub.org> LionelCons&colleages<cons@dxcern.cern.ch> CarlEdman<cedman@princeton.edu> CalebEpstein<epsteincaleb@jpmorgan.com> LarsFenneberg<lf@gimli.comlink.de> ZoltanHidvegi<hzoli@cs.elte.hu> NilsMagnus<magnus@unix-ag.uni-kl.de> DanielQuinlan<quinlan@yggdrasil.com> FabrizioPolacco<fpolacco@debian.org> 19 Glossary manualpage Afilecontainingdescriptionsrelatedtotheuseofafunctionorprogramorthestructureof afile.Thenameofthefileisformedfromthetitleofthemanualpagefollowedbyaperiod followedbythenameofthesectionthatitresidesin,optionallyfollowedbyanextension. TheformatofthefileisNROFFandmaybecompressed,havingasuitablecompression extensionappended. catpage Aformattedmanualpagesuitableforviewingonavt100-typeterminal. straycatpage Acatpagethatdoesnothavearelativemanualpageonthesystem,i.e.onlythecatpage wassuppliedorthemanualpagewasremovedafterthecatpagehadbeencreated. section Eachmanualpageorcatpagehierarchyisdividedintosections,eachsectionhavingitsown directory.Manualpagehierarchysectionnamesbeginwith‘man’andcatpagesections with‘cat’. extension Apackagemayprovidemanualpageswithfilenamesendinginapackage-specificextension name.Thisallowsmanualpageswiththesametitletocoexistinthesamemanualpage hierarchyandsectionwithoutsharingthesamefilename.Italsoprovidesafurthermechanismformantoselectthecorrectmanualpage. manualpagehierarchy Adirectorytreedividedintomanualpagesections,eachcontainingacollectionofmanual pages. catpagehierarchy Adirectorytreedividedintocatpagesections,eachcontainingacollectionofcatpages. traditionalcatpagehierarchy Thesamelocationasthemanualpagehierarchy. alternatecatpagehierarchy Aseparatelocationtothatofthetraditionalcatpagehierarchy. traditionalcatpage Acatpagelocatedinatraditionalcatpagehierarchy. alternatecatpage Acatpagelocatedinanalternatecatpagehierarchy. i Contents 1.Introduction....................................................................................................................1 1.1man−db....................................................................................................................1 1.1.1Theconcept....................................................................................................1 1.2Themanualpagesystem..........................................................................................2 1.3Sectionsofthemanual.............................................................................................2 1.4Theformatofmanualpages.....................................................................................3 1.5Argumentstoconfigure............................................................................................3 2.ThespecificsofSections..................................................................................................4 2.1Packagespecificmanualpagesections.....................................................................4 2.2Selectingasectiontype............................................................................................4 2.2.1Specifyingasection........................................................................................4 2.2.2Specifyinganextension..................................................................................5 3.Filesystemstructure........................................................................................................6 3.1Manualpagehierarchies...........................................................................................6 3.2SettingtheMANPATH............................................................................................6 3.3Determinationoftheinternalmanpath....................................................................6 3.4OtherOS’smanualpages.........................................................................................7 3.5NLSmanualpages....................................................................................................7 3.5.1ISO8859-1(latin1)manualpages..................................................................9 3.5.2Displayingnon-ASCIIcharactersonaLinuxvirtualterminal.......................9 3.5.3ViewingASCIIpagesformattedforlatin1outputdevice...............................9 3.6Catpages..................................................................................................................9 3.7Catpagehierarchies.................................................................................................10 3.8Localcatpagedirectorycaches................................................................................10 4.Compression....................................................................................................................11 4.1Compressedmanualpages........................................................................................11 4.2Compressedcatpages...............................................................................................11 4.2.1Straycats........................................................................................................11 5.Formatting.......................................................................................................................12 5.1GROFF....................................................................................................................12 5.2Devices.....................................................................................................................12 5.3Macros......................................................................................................................12 5.4Pre-formatprocessors(pre-processors).....................................................................13 5.5Formatscripts..........................................................................................................13 6.Theindexdatabasecaches..............................................................................................14 6.1indexdatabaselocation............................................................................................14 6.1.1Manualhierarchieswithnoindexdatabase....................................................14 i 6.1.2Usermanualpagehierarchies.........................................................................14 6.2Contentsofanindexdatabase.................................................................................14 6.2.1Favouringstraycats.......................................................................................15 6.2.2Accessdb.........................................................................................................15 6.2.3Exampledatabase...........................................................................................16 6.3Databasetypes.........................................................................................................16 6.4Limitations...............................................................................................................16 6.5Sharingdatabasesinaheterogeneousenvironment..................................................17 7.Miscellaneous...................................................................................................................18 7.1Modesofoperation...................................................................................................18 7.2NFSrootsquash.......................................................................................................19 7.3NLSmessagecatalogues...........................................................................................19 7.4Credits......................................................................................................................19