3 # SPDX-License-Identifier: BSD-2-Clause-FreeBSD
5 # Copyright (c) 2010 Gordon Tetlow
8 # Redistribution and use in source and binary forms, with or without
9 # modification, are permitted provided that the following conditions
11 # 1. Redistributions of source code must retain the above copyright
12 # notice, this list of conditions and the following disclaimer.
13 # 2. Redistributions in binary form must reproduce the above copyright
14 # notice, this list of conditions and the following disclaimer in the
15 # documentation and/or other materials provided with the distribution.
17 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 # $FreeBSD: head/usr.bin/man/man.sh 340128 2018-11-04 16:58:55Z yuripv $
31 # Usage: add_to_manpath path
32 # Adds a variable to manpath while ensuring we don't have duplicates.
33 # Returns true if we were able to add something. False otherwise.
36 *:$1) decho " Skipping duplicate manpath entry $1" 2 ;;
37 $1:*) decho " Skipping duplicate manpath entry $1" 2 ;;
38 *:$1:*) decho " Skipping duplicate manpath entry $1" 2 ;;
39 *) if [ -d "$1" ]; then
40 decho " Adding $1 to manpath"
50 # Usage: build_manlocales
51 # Builds a correct MANLOCALES variable.
53 # If the user has set manlocales, who are we to argue.
54 if [ -n "$MANLOCALES" ]; then
61 MANLOCALES=${manlocales#:}
63 decho "Available manual locales: $MANLOCALES"
66 # Usage: build_manpath
67 # Builds a correct MANPATH variable.
71 # If the user has set a manpath, who are we to argue.
72 if [ -n "$MANPATH" ]; then
74 *:) PREPEND_MANPATH=${MANPATH} ;;
75 :*) APPEND_MANPATH=${MANPATH} ;;
77 PREPEND_MANPATH=${MANPATH%%::*}
78 APPEND_MANPATH=${MANPATH#*::}
84 if [ -n "$PREPEND_MANPATH" ]; then
86 for path in $PREPEND_MANPATH; do
87 add_to_manpath "$path"
94 decho "Adding default manpath entries"
96 for path in $man_default_path; do
97 add_to_manpath "$path"
103 if [ -n "$APPEND_MANPATH" ]; then
105 for path in $APPEND_MANPATH; do
106 add_to_manpath "$path"
113 decho "Using manual path: $MANPATH"
116 # Usage: check_cat catglob
117 # Checks to see if a cat glob is available.
122 setup_cattool $catpage
123 decho " Found catpage $catpage"
130 # Usage: check_man manglob catglob
131 # Given 2 globs, figures out if the manglob is available, if so, check to
132 # see if the catglob is also available and up to date.
135 # We have a match, check for a cat page
137 setup_cattool $manpage
138 decho " Found manpage $manpage"
140 if [ -n "${use_width}" ]; then
143 decho " Skipping catpage: non-standard page width"
144 elif exists "$2" && is_newer $found $manpage; then
145 # cat page found and is newer, use that
148 setup_cattool $catpage
149 decho " Using catpage $catpage"
151 # no cat page or is older
153 decho " Skipping catpage: not found or old"
161 # Usage: decho "string" [debuglevel]
162 # Echoes to stderr string prefaced with -- if high enough debuglevel.
164 if [ $debug -ge ${2:-1} ]; then
170 # Returns true if glob resolves to a real file.
174 # Don't accidentally inherit callers IFS (breaks perl manpages)
177 # Use some globbing tricks in the shell to determine if a file
183 if [ "$1" != "$2" -a -r "$2" ]; then
191 # Usage: find_file path section subdir pagename
192 # Returns: true if something is matched and found.
193 # Search the given path/section combo for a given page.
195 local manroot catroot mann man0 catn cat0
200 manroot="$manroot/$3"
201 catroot="$catroot/$3"
204 if [ ! -d "$manroot" -a ! -d "$catroot" ]; then
207 decho " Searching directory $manroot" 2
209 mann="$manroot/$4.$2*"
210 man0="$manroot/$4.0*"
211 catn="$catroot/$4.$2*"
212 cat0="$catroot/$4.0*"
214 # This is the behavior as seen by the original man utility.
215 # Let's not change that which doesn't seem broken.
216 if check_man "$mann" "$catn"; then
218 elif check_man "$man0" "$cat0"; then
220 elif check_cat "$catn"; then
222 elif check_cat "$cat0"; then
229 # Usage: is_newer file1 file2
230 # Returns true if file1 is newer than file2 as calculated by mtime.
232 if ! [ "$1" -ot "$2" ]; then
233 decho " mtime: $1 not older than $2" 3
236 decho " mtime: $1 older than $2" 3
241 # Usage: manpath_parse_args "$@"
242 # Parses commandline options for manpath.
243 manpath_parse_args() {
246 while getopts 'Ldq' cmd_arg; do
249 d) debug=$(( $debug + 1 )) ;;
256 # Usage: manpath_usage
257 # Display usage for the manpath(1) utility.
259 echo 'usage: manpath [-Ldq]' >&2
263 # Usage: manpath_warnings
264 # Display some warnings to stderr.
266 if [ -n "$Lflag" -a -n "$MANLOCALES" ]; then
267 echo "(Warning: MANLOCALES environment variable set)" >&2
271 # Usage: man_check_for_so page path
272 # Returns: True if able to resolve the file, false if it ended in tears.
273 # Detects the presence of the .so directive and causes the file to be
274 # redirected to another source file.
279 if [ -n "$catpage" ]; then
283 # We need to loop to accommodate multiple .so directives.
286 line=$($cattool $manpage | head -1)
288 .so*) trim "${line#.so}"
289 decho "$manpage includes $tstr"
290 # Glob and check for the file.
291 if ! check_man "$path/$tstr*" ""; then
292 decho " Unable to find $tstr"
303 # Usage: man_display_page
304 # Display either the manpage or catpage depending on the use_cat variable
306 local IFS pipeline testline
308 # We are called with IFS set to colon. This causes really weird
309 # things to happen for the variables that have spaces in them.
312 # If we are supposed to use a catpage and we aren't using troff(1)
313 # just zcat the catpage and we are done.
314 if [ -z "$tflag" -a -n "$use_cat" ]; then
315 if [ -n "$wflag" ]; then
316 echo "$catpage (source: $manpage)"
319 if [ $debug -gt 0 ]; then
320 decho "Command: $cattool $catpage | $MANPAGER"
323 eval "$cattool $catpage | $MANPAGER"
330 # Okay, we are using the manpage, do we just need to output the
331 # name of the manpage?
332 if [ -n "$wflag" ]; then
338 if [ -n "$use_width" ]; then
339 mandoc_args="-O width=${use_width}"
341 testline="mandoc -Tlint -Wunsupp >/dev/null 2>&1"
342 if [ -n "$tflag" ]; then
343 pipeline="mandoc -Tps $mandoc_args"
345 pipeline="mandoc $mandoc_args | $MANPAGER"
348 if ! eval "$cattool $manpage | $testline" ;then
349 if which -s groff; then
350 man_display_page_groff
352 echo "This manpage needs groff(1) to be rendered" >&2
353 echo "First install groff(1): " >&2
354 echo "pkg install groff " >&2
360 if [ $debug -gt 0 ]; then
361 decho "Command: $cattool $manpage | $pipeline"
364 eval "$cattool $manpage | $pipeline"
369 # Usage: man_display_page_groff
370 # Display the manpage using groff
371 man_display_page_groff() {
372 local EQN NROFF PIC TBL TROFF REFER VGRIND
373 local IFS l nroff_dev pipeline preproc_arg tool
375 # So, we really do need to parse the manpage. First, figure out the
376 # device flag (-T) we have to pass to eqn(1) and groff(1). Then,
377 # setup the pipeline of commands based on the user's request.
379 # If the manpage is from a particular charset, we need to setup nroff
380 # to properly output for the correct device.
383 # I don't pretend to know this; I'm just copying from the
384 # previous version of man(1).
385 case "$man_charset" in
386 KOI8-R) nroff_dev="koi8-r" ;;
387 ISO8859-1) nroff_dev="latin1" ;;
388 ISO8859-15) nroff_dev="latin1" ;;
389 UTF-8) nroff_dev="utf8" ;;
390 *) nroff_dev="ascii" ;;
393 NROFF="$NROFF -T$nroff_dev"
394 EQN="$EQN -T$nroff_dev"
396 # Iff the manpage is from the locale and not just the charset,
397 # then we need to define the locale string.
399 */${man_lang}_${man_country}.${man_charset}/*)
400 NROFF="$NROFF -dlocale=$man_lang.$man_charset"
402 */${man_lang}.${man_charset}/*)
403 NROFF="$NROFF -dlocale=$man_lang.$man_charset"
407 # Allow language specific calls to override the default
409 l=$(echo $man_lang | tr [:lower:] [:upper:])
410 for tool in EQN NROFF PIC TBL TROFF REFER VGRIND; do
411 eval "$tool=\${${tool}_$l:-\$$tool}"
414 *) NROFF="$NROFF -Tascii"
419 if [ -z "$MANCOLOR" ]; then
423 if [ -n "${use_width}" ]; then
424 NROFF="$NROFF -rLL=${use_width}n -rLT=${use_width}n"
427 if [ -n "$MANROFFSEQ" ]; then
429 while getopts 'egprtv' preproc_arg; do
430 case "${preproc_arg}" in
431 e) pipeline="$pipeline | $EQN" ;;
432 g) ;; # Ignore for compatibility.
433 p) pipeline="$pipeline | $PIC" ;;
434 r) pipeline="$pipeline | $REFER" ;;
435 t) pipeline="$pipeline | $TBL" ;;
436 v) pipeline="$pipeline | $VGRIND" ;;
440 # Strip the leading " | " from the resulting pipeline.
441 pipeline="${pipeline#" | "}"
446 if [ -n "$tflag" ]; then
447 pipeline="$pipeline | $TROFF"
449 pipeline="$pipeline | $NROFF | $MANPAGER"
452 if [ $debug -gt 0 ]; then
453 decho "Command: $cattool $manpage | $pipeline"
456 eval "$cattool $manpage | $pipeline"
461 # Usage: man_find_and_display page
462 # Search through the manpaths looking for the given page.
463 man_find_and_display() {
464 local found_page locpath p path sect
466 # Check to see if it's a file. But only if it has a '/' in
469 */*) if [ -f "$1" -a -r "$1" ]; then
470 decho "Found a usable page, displaying that"
473 setup_cattool $manpage
474 if man_check_for_so $manpage $(dirname $manpage); then
484 for sect in $MANSECT; do
485 decho "Searching section $sect" 2
486 for path in $MANPATH; do
487 for locpath in $locpaths; do
489 p=${p%/.} # Rid ourselves of the trailing /.
491 # Check if there is a MACHINE specific manpath.
492 if find_file $p $sect $MACHINE "$1"; then
493 if man_check_for_so $manpage $p; then
496 if [ -n "$aflag" ]; then
504 # Check if there is a MACHINE_ARCH
506 if find_file $p $sect $MACHINE_ARCH "$1"; then
507 if man_check_for_so $manpage $p; then
510 if [ -n "$aflag" ]; then
518 # Check plain old manpath.
519 if find_file $p $sect '' "$1"; then
520 if man_check_for_so $manpage $p; then
523 if [ -n "$aflag" ]; then
535 # Nothing? Well, we are done then.
536 if [ -z "$found_page" ]; then
537 echo "No manual entry for $1" >&2
543 # Usage: man_parse_args "$@"
544 # Parses commandline options for man.
548 while getopts 'M:P:S:adfhkm:op:tw' cmd_arg; do
550 M) MANPATH=$OPTARG ;;
551 P) MANPAGER=$OPTARG ;;
552 S) MANSECT=$OPTARG ;;
554 d) debug=$(( $debug + 1 )) ;;
560 p) MANROFFSEQ=$OPTARG ;;
567 shift $(( $OPTIND - 1 ))
569 # Check the args for incompatible options.
570 case "${fflag}${kflag}${tflag}${wflag}" in
571 fflagkflag*) echo "Incompatible options: -f and -k"; man_usage ;;
572 fflag*tflag*) echo "Incompatible options: -f and -t"; man_usage ;;
573 fflag*wflag) echo "Incompatible options: -f and -w"; man_usage ;;
574 *kflagtflag*) echo "Incompatible options: -k and -t"; man_usage ;;
575 *kflag*wflag) echo "Incompatible options: -k and -w"; man_usage ;;
576 *tflagwflag) echo "Incompatible options: -t and -w"; man_usage ;;
579 # Short circuit for whatis(1) and apropos(1)
580 if [ -n "$fflag" ]; then
585 if [ -n "$kflag" ]; then
591 for sect in $man_default_sections; do
592 if [ "$sect" = "$1" ]; then
593 decho "Detected manual section as first arg: $1"
605 # Setup various trivial but essential variables.
607 # Setup machine and architecture variables.
608 if [ -n "$mflag" ]; then
609 MACHINE_ARCH=${mflag%%:*}
612 if [ -z "$MACHINE_ARCH" ]; then
613 MACHINE_ARCH=$($SYSCTL -n hw.machine_arch)
615 if [ -z "$MACHINE" ]; then
616 MACHINE=$($SYSCTL -n hw.machine)
618 decho "Using architecture: $MACHINE_ARCH:$MACHINE"
622 # Setup manual sections to search.
623 if [ -z "$MANSECT" ]; then
624 MANSECT=$man_default_sections
626 decho "Using manual sections: $MANSECT"
633 # Usage: man_setup_width
641 if [ "$MANWIDTH" -gt 0 2>/dev/null ]; then
646 if { sizes=$($STTY size 0>&3 2>/dev/null); } 3>&1; then
648 if [ $2 -gt 80 ]; then
654 if [ -n "$use_width" ]; then
655 decho "Using non-standard page width: ${use_width}"
657 decho 'Using standard page width'
661 # Usage: man_setup_locale
662 # Setup necessary locale variables.
668 man_charset='US-ASCII'
670 # Setup locale information.
671 if [ -n "$oflag" ]; then
672 decho 'Using non-localized manpages'
674 # Use the locale tool to give us proper locale information
677 if [ -n "$LANG" ]; then
687 [a-z][a-z]_[A-Z][A-Z]\.*)
688 lang_cc="${locstr%.*}"
689 man_lang="${locstr%_*}"
690 man_country="${lang_cc#*_}"
691 man_charset="${locstr#*.}"
693 locpaths="$locpaths:$man_lang.$man_charset"
694 if [ "$man_lang" != "en" ]; then
695 locpaths="$locpaths:en.$man_charset"
697 locpaths="$locpaths:."
699 *) echo 'Unknown locale, assuming C' >&2
704 decho "Using locale paths: $locpaths"
707 # Usage: man_usage [exitcode]
708 # Display usage for the man utility.
711 echo ' man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]'
712 echo ' [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]'
713 echo ' man -f page [...] -- Emulates whatis(1)'
714 echo ' man -k page [...] -- Emulates apropos(1)'
716 # When exit'ing with -h, it's not an error.
720 # Usage: parse_configs
721 # Reads the end-user adjustable config files.
725 if [ -n "$parsed_configs" ]; then
731 # Read the global config first in case the user wants
732 # to override config_local.
733 if [ -r "$config_global" ]; then
734 parse_file "$config_global"
737 # Glob the list of files to parse.
739 files=$(echo $config_local)
742 for file in $files; do
743 if [ -r "$file" ]; then
751 # Usage: parse_file file
752 # Reads the specified config files.
754 local file line tstr var
757 decho "Parsing config file: $file"
761 \#*) decho " Comment" 3
763 MANPATH*) decho " MANPATH" 3
764 trim "${line#MANPATH}"
765 add_to_manpath "$tstr"
767 MANLOCALE*) decho " MANLOCALE" 3
768 trim "${line#MANLOCALE}"
769 manlocales="$manlocales:$tstr"
771 MANCONFIG*) decho " MANCONFIG" 3
772 trim "${line#MANCONFIG}"
775 # Set variables in the form of FOO_BAR
776 *_*[\ \ ]*) var="${line%%[\ \ ]*}"
778 eval "$var=\"$tstr\""
779 decho " Parsed $var" 3
786 # Traverse $PATH looking for manpaths.
790 decho "Searching PATH for man directories"
793 for path in $PATH; do
794 if add_to_manpath "$path/man"; then
796 elif add_to_manpath "$path/MAN"; then
800 */bin) p="${path%/bin}/share/man"
810 if [ -z "$manpath" ]; then
811 decho ' Unable to find any manpaths, using default'
812 manpath=$man_default_path
816 # Usage: search_whatis cmd [arglist]
817 # Do the heavy lifting for apropos/whatis
819 local IFS bad cmd f good key keywords loc opt out path rval wlist
824 whatis_parse_args "$@"
830 if [ "$cmd" = "whatis" ]; then
837 for path in $MANPATH; do
838 if [ \! -d "$path" ]; then
839 decho "Skipping non-existent path: $path" 2
843 if [ -f "$path/$f" -a -r "$path/$f" ]; then
844 decho "Found whatis: $path/$f"
845 wlist="$wlist $path/$f"
848 for loc in $MANLOCALES; do
849 if [ -f "$path/$loc/$f" -a -r "$path/$loc/$f" ]; then
850 decho "Found whatis: $path/$loc/$f"
851 wlist="$wlist $path/$loc/$f"
857 if [ -z "$wlist" ]; then
858 echo "$cmd: no whatis databases in $MANPATH" >&2
863 for key in $keywords; do
864 out=$(grep -Ehi $opt -- "$key" $wlist)
865 if [ -n "$out" ]; then
868 bad="$bad\\n$key: nothing appropriate"
873 # Strip leading carriage return.
877 if [ -n "$good" ]; then
878 echo -e "$good" | $MANPAGER
881 if [ -n "$bad" ]; then
888 # Usage: setup_cattool page
889 # Finds an appropriate decompressor based on extension
892 *.bz) cattool='/usr/bin/bzcat' ;;
893 *.bz2) cattool='/usr/bin/bzcat' ;;
894 *.gz) cattool='/usr/bin/zcat' ;;
895 *.lzma) cattool='/usr/bin/lzcat' ;;
896 *.xz) cattool='/usr/bin/xzcat' ;;
897 *) cattool='/usr/bin/zcat -f' ;;
902 # Correctly sets $MANPAGER
905 if [ -z "$MANPAGER" ]; then
906 if [ -n "$MANCOLOR" ]; then
909 if [ -n "$PAGER" ]; then
916 decho "Using pager: $MANPAGER"
920 # Trims whitespace from beginning and end of a variable
925 [\ \ ]*) tstr="${tstr##[\ \ ]}" ;;
926 *[\ \ ]) tstr="${tstr%%[\ \ ]}" ;;
932 # Usage: whatis_parse_args "$@"
933 # Parse commandline args for whatis and apropos.
934 whatis_parse_args() {
936 while getopts 'd' cmd_arg; do
938 d) debug=$(( $debug + 1 )) ;;
943 shift $(( $OPTIND - 1 ))
948 # Usage: whatis_usage
949 # Display usage for the whatis/apropos utility.
951 echo "usage: $cmd [-d] keyword [...]"
959 [ $(stat -f %i /usr/bin/man) -ne $(stat -f %i /usr/bin/apropos) ] && \
961 search_whatis apropos "$@"
966 if [ -z "$pages" ]; then
967 echo 'What manual page do you want?' >&2
972 for page in $pages; do
973 decho "Searching for $page"
974 man_find_and_display "$page"
981 manpath_parse_args "$@"
982 if [ -z "$qflag" ]; then
985 if [ -n "$Lflag" ]; then
996 [ $(stat -f %i /usr/bin/man) -ne $(stat -f %i /usr/bin/whatis) ] && \
998 search_whatis whatis "$@"
1001 # User's PATH setting decides on the groff-suite to pick up.
1003 NROFF='groff -S -P-h -Wall -mtty-char -man'
1007 TROFF='groff -S -man'
1010 LOCALE=/usr/bin/locale
1015 man_default_sections='1:8:2:3:n:4:5:6:7:9:l'
1016 man_default_path='/usr/share/man:/usr/local/share/man:/usr/local/man:/raven/share/man:/usr/pkg/man'
1017 cattool='/usr/bin/zcat -f'
1019 config_global='/etc/man.conf'
1021 # This can be overridden via a setting in /etc/man.conf.
1022 config_local='/usr/local/etc/man.d/*.conf'
1024 # Set noglobbing for now. I don't want spurious globbing.
1028 *apropos) do_apropos "$@" ;;
1029 *manpath) do_manpath "$@" ;;
1030 *whatis) do_whatis "$@" ;;