From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/fedora-40/man1/411toppm.1 | 71 + upstream/fedora-40/man1/AusweisApp.1 | 130 + upstream/fedora-40/man1/ac.1 | 277 + upstream/fedora-40/man1/addftinfo.1 | 236 + upstream/fedora-40/man1/addr2line.1 | 275 + upstream/fedora-40/man1/airscan-discover.1 | 49 + upstream/fedora-40/man1/alpine.1 | 398 + upstream/fedora-40/man1/anytopnm.1 | 100 + upstream/fedora-40/man1/ar.1 | 460 + upstream/fedora-40/man1/arch.1 | 36 + upstream/fedora-40/man1/as.1 | 2976 ++ upstream/fedora-40/man1/asciitopgm.1 | 102 + upstream/fedora-40/man1/at.1 | 334 + upstream/fedora-40/man1/atktopbm.1 | 61 + upstream/fedora-40/man1/autoconf.1 | 128 + upstream/fedora-40/man1/autoheader.1 | 114 + upstream/fedora-40/man1/autom4te.1 | 198 + upstream/fedora-40/man1/autopoint.1 | 47 + upstream/fedora-40/man1/autoreconf.1 | 140 + upstream/fedora-40/man1/autoscan.1 | 70 + upstream/fedora-40/man1/autoupdate.1 | 72 + upstream/fedora-40/man1/avstopam.1 | 63 + upstream/fedora-40/man1/b2sum.1 | 84 + upstream/fedora-40/man1/banner.1 | 101 + upstream/fedora-40/man1/base32.1 | 55 + upstream/fedora-40/man1/base64.1 | 55 + upstream/fedora-40/man1/basename.1 | 64 + upstream/fedora-40/man1/basenc.1 | 106 + upstream/fedora-40/man1/bash.1 | 11779 ++++++ upstream/fedora-40/man1/bashbug.1 | 67 + upstream/fedora-40/man1/bc.1 | 825 + upstream/fedora-40/man1/bioradtopgm.1 | 66 + upstream/fedora-40/man1/bison.1 | 285 + upstream/fedora-40/man1/bmptopnm.1 | 96 + upstream/fedora-40/man1/bmptoppm.1 | 29 + upstream/fedora-40/man1/bootctl.1 | 682 + upstream/fedora-40/man1/brushtopbm.1 | 54 + upstream/fedora-40/man1/busctl.1 | 583 + upstream/fedora-40/man1/bzdiff.1 | 47 + upstream/fedora-40/man1/bzgrep.1 | 56 + upstream/fedora-40/man1/bzip2.1 | 465 + upstream/fedora-40/man1/bzmore.1 | 152 + upstream/fedora-40/man1/c++filt.1 | 298 + upstream/fedora-40/man1/cameratopam.1 | 192 + upstream/fedora-40/man1/captoinfo.1m | 234 + upstream/fedora-40/man1/cat.1 | 75 + upstream/fedora-40/man1/cdda2ogg.1 | 108 + upstream/fedora-40/man1/chattr.1 | 299 + upstream/fedora-40/man1/chcon.1 | 92 + upstream/fedora-40/man1/chgrp.1 | 93 + upstream/fedora-40/man1/chmod.1 | 174 + upstream/fedora-40/man1/chown.1 | 125 + upstream/fedora-40/man1/chroot.1 | 63 + upstream/fedora-40/man1/chvt.1 | 31 + upstream/fedora-40/man1/ci.1 | 944 + upstream/fedora-40/man1/cifsiostat.1 | 154 + upstream/fedora-40/man1/cistopbm.1 | 71 + upstream/fedora-40/man1/cksum.1 | 120 + upstream/fedora-40/man1/clear.1 | 186 + upstream/fedora-40/man1/cmp.1 | 76 + upstream/fedora-40/man1/cmuwmtopbm.1 | 54 + upstream/fedora-40/man1/co.1 | 805 + upstream/fedora-40/man1/comm.1 | 76 + upstream/fedora-40/man1/compress.1 | 295 + upstream/fedora-40/man1/consoletype.1 | 44 + upstream/fedora-40/man1/coredumpctl.1 | 467 + upstream/fedora-40/man1/cp.1 | 197 + upstream/fedora-40/man1/cpio.1 | 438 + upstream/fedora-40/man1/cronnext.1 | 86 + upstream/fedora-40/man1/crontab.1 | 264 + upstream/fedora-40/man1/csplit.1 | 77 + upstream/fedora-40/man1/csv2rec.1 | 51 + upstream/fedora-40/man1/cut.1 | 85 + upstream/fedora-40/man1/date.1 | 269 + upstream/fedora-40/man1/dc.1 | 520 + upstream/fedora-40/man1/dd.1 | 176 + upstream/fedora-40/man1/ddate.1 | 115 + upstream/fedora-40/man1/ddbugtopbm.1 | 117 + upstream/fedora-40/man1/deallocvt.1 | 35 + upstream/fedora-40/man1/debuginfo-install.1 | 78 + upstream/fedora-40/man1/df.1 | 123 + upstream/fedora-40/man1/dialog.1 | 2083 + upstream/fedora-40/man1/diff.1 | 270 + upstream/fedora-40/man1/diff3.1 | 102 + upstream/fedora-40/man1/dir.1 | 265 + upstream/fedora-40/man1/dircolors.1 | 50 + upstream/fedora-40/man1/dirname.1 | 50 + upstream/fedora-40/man1/dnf-utils.1 | 115 + upstream/fedora-40/man1/du.1 | 163 + upstream/fedora-40/man1/dumpkeys.1 | 251 + upstream/fedora-40/man1/echo.1 | 93 + upstream/fedora-40/man1/ed.1 | 91 + upstream/fedora-40/man1/elfedit.1 | 195 + upstream/fedora-40/man1/env.1 | 142 + upstream/fedora-40/man1/epsffit.1 | 63 + upstream/fedora-40/man1/eqn.1 | 2240 ++ upstream/fedora-40/man1/eqn2graph.1 | 188 + upstream/fedora-40/man1/escp2topbm.1 | 96 + upstream/fedora-40/man1/exif.1 | 237 + upstream/fedora-40/man1/expand.1 | 54 + upstream/fedora-40/man1/expr.1 | 107 + upstream/fedora-40/man1/extractres.1 | 70 + upstream/fedora-40/man1/eyuvtoppm.1 | 74 + upstream/fedora-40/man1/factor.1 | 37 + upstream/fedora-40/man1/false.1 | 40 + upstream/fedora-40/man1/faxformat.1 | 105 + upstream/fedora-40/man1/fgconsole.1 | 50 + upstream/fedora-40/man1/fiascotopnm.1 | 231 + upstream/fedora-40/man1/file.1 | 743 + upstream/fedora-40/man1/find.1 | 2777 ++ upstream/fedora-40/man1/finger.1 | 194 + upstream/fedora-40/man1/fitstopnm.1 | 157 + upstream/fedora-40/man1/flex.1 | 163 + upstream/fedora-40/man1/fmt.1 | 60 + upstream/fedora-40/man1/fold.1 | 52 + upstream/fedora-40/man1/formail.1 | 558 + upstream/fedora-40/man1/fstopgm.1 | 98 + upstream/fedora-40/man1/funzip.1 | 127 + upstream/fedora-40/man1/fuse2fs.1 | 79 + upstream/fedora-40/man1/g3topbm.1 | 154 + upstream/fedora-40/man1/gawk.1 | 2513 ++ upstream/fedora-40/man1/gawkbug.1 | 73 + upstream/fedora-40/man1/gcore.1 | 118 + upstream/fedora-40/man1/gdiffmk.1 | 304 + upstream/fedora-40/man1/gemtopbm.1 | 29 + upstream/fedora-40/man1/gemtopnm.1 | 67 + upstream/fedora-40/man1/genhostid.1 | 12 + upstream/fedora-40/man1/genisoimage.1 | 2881 ++ upstream/fedora-40/man1/getent.1 | 387 + upstream/fedora-40/man1/gettext.1 | 74 + upstream/fedora-40/man1/gettextize.1 | 56 + upstream/fedora-40/man1/giftopnm.1 | 235 + upstream/fedora-40/man1/gnumeric.1 | 199 + upstream/fedora-40/man1/gouldtoppm.1 | 52 + upstream/fedora-40/man1/gpm-root.1 | 230 + upstream/fedora-40/man1/gprof.1 | 698 + upstream/fedora-40/man1/grap2graph.1 | 205 + upstream/fedora-40/man1/grep.1 | 1358 + upstream/fedora-40/man1/grn.1 | 978 + upstream/fedora-40/man1/grodvi.1 | 633 + upstream/fedora-40/man1/groff.1 | 2403 ++ upstream/fedora-40/man1/grohtml.1 | 731 + upstream/fedora-40/man1/grolbp.1 | 504 + upstream/fedora-40/man1/grolj4.1 | 896 + upstream/fedora-40/man1/grops.1 | 1831 + upstream/fedora-40/man1/grotty.1 | 810 + upstream/fedora-40/man1/groups.1 | 37 + upstream/fedora-40/man1/grub2-editenv.1 | 62 + upstream/fedora-40/man1/grub2-emu.1 | 68 + upstream/fedora-40/man1/grub2-file.1 | 118 + upstream/fedora-40/man1/grub2-fstest.1 | 88 + upstream/fedora-40/man1/grub2-kbdcomp.1 | 42 + upstream/fedora-40/man1/grub2-menulst2cfg.1 | 23 + upstream/fedora-40/man1/grub2-mkfont.1 | 73 + upstream/fedora-40/man1/grub2-mkimage.1 | 106 + upstream/fedora-40/man1/grub2-mklayout.1 | 52 + upstream/fedora-40/man1/grub2-mknetdir.1 | 100 + upstream/fedora-40/man1/grub2-mkpasswd-pbkdf2.1 | 46 + upstream/fedora-40/man1/grub2-mkrelpath.1 | 37 + upstream/fedora-40/man1/grub2-mkrescue.1 | 131 + upstream/fedora-40/man1/grub2-mkstandalone.1 | 110 + upstream/fedora-40/man1/grub2-mount.1 | 48 + upstream/fedora-40/man1/grub2-script-check.1 | 37 + upstream/fedora-40/man1/grub2-set-bootflag.1 | 23 + upstream/fedora-40/man1/grub2-syslinux2cfg.1 | 68 + upstream/fedora-40/man1/gs.1 | 431 + upstream/fedora-40/man1/gsnd.1 | 19 + upstream/fedora-40/man1/gstack.1 | 48 + upstream/fedora-40/man1/gzexe.1 | 57 + upstream/fedora-40/man1/gzip.1 | 577 + upstream/fedora-40/man1/hdifftopam.1 | 72 + upstream/fedora-40/man1/head.1 | 65 + upstream/fedora-40/man1/hipstopgm.1 | 58 + upstream/fedora-40/man1/homectl.1 | 1371 + upstream/fedora-40/man1/hostid.1 | 36 + upstream/fedora-40/man1/hostname.1 | 280 + upstream/fedora-40/man1/hostnamectl.1 | 217 + upstream/fedora-40/man1/hpftodit.1 | 476 + upstream/fedora-40/man1/icedax.1 | 1025 + upstream/fedora-40/man1/icehelp.1 | 149 + upstream/fedora-40/man1/icesh.1 | 952 + upstream/fedora-40/man1/icesound.1 | 199 + upstream/fedora-40/man1/icewm-menu-fdo.1 | 190 + upstream/fedora-40/man1/icewm-menu-xrandr.1 | 141 + upstream/fedora-40/man1/icewm-session.1 | 185 + upstream/fedora-40/man1/icewm-set-gnomewm.1 | 97 + upstream/fedora-40/man1/icewm.1 | 1418 + upstream/fedora-40/man1/icewmbg.1 | 298 + upstream/fedora-40/man1/icewmhint.1 | 281 + upstream/fedora-40/man1/icontopbm.1 | 48 + upstream/fedora-40/man1/iconv.1 | 204 + upstream/fedora-40/man1/id.1 | 62 + upstream/fedora-40/man1/ident.1 | 224 + upstream/fedora-40/man1/ifnames.1 | 57 + upstream/fedora-40/man1/ilbmtoppm.1 | 160 + upstream/fedora-40/man1/imgtoppm.1 | 55 + upstream/fedora-40/man1/includeres.1 | 65 + upstream/fedora-40/man1/indent.1 | 2185 ++ upstream/fedora-40/man1/indxbib.1 | 347 + upstream/fedora-40/man1/info.1 | 101 + upstream/fedora-40/man1/infocmp.1m | 667 + upstream/fedora-40/man1/infotocap.1m | 97 + upstream/fedora-40/man1/infotopam.1 | 247 + upstream/fedora-40/man1/install-info.1 | 146 + upstream/fedora-40/man1/install.1 | 138 + upstream/fedora-40/man1/intro.1 | 305 + upstream/fedora-40/man1/iostat.1 | 479 + upstream/fedora-40/man1/isodebug.1 | 108 + upstream/fedora-40/man1/isoinfo.1 | 365 + upstream/fedora-40/man1/jbigtopnm.1 | 141 + upstream/fedora-40/man1/jed.1 | 517 + upstream/fedora-40/man1/joe.1 | 6002 +++ upstream/fedora-40/man1/join.1 | 97 + upstream/fedora-40/man1/journalctl.1 | 1374 + upstream/fedora-40/man1/jpeg2ktopam.1 | 164 + upstream/fedora-40/man1/jpegtopnm.1 | 371 + upstream/fedora-40/man1/kbd_mode.1 | 51 + upstream/fedora-40/man1/kbdinfo.1 | 91 + upstream/fedora-40/man1/lastcomm.1 | 166 + upstream/fedora-40/man1/ld.1 | 3532 ++ upstream/fedora-40/man1/ldd.1 | 180 + upstream/fedora-40/man1/leaftoppm.1 | 55 + upstream/fedora-40/man1/less.1 | 2351 ++ upstream/fedora-40/man1/lessecho.1 | 52 + upstream/fedora-40/man1/lesskey.1 | 458 + upstream/fedora-40/man1/link.1 | 39 + upstream/fedora-40/man1/linuxdoc.1 | 388 + upstream/fedora-40/man1/lispmtopgm.1 | 75 + upstream/fedora-40/man1/list_audio_tracks.1 | 54 + upstream/fedora-40/man1/lkbib.1 | 212 + upstream/fedora-40/man1/ln.1 | 119 + upstream/fedora-40/man1/loadkeys.1 | 212 + upstream/fedora-40/man1/locale.1 | 208 + upstream/fedora-40/man1/localectl.1 | 404 + upstream/fedora-40/man1/localedef.1 | 415 + upstream/fedora-40/man1/locate.1 | 270 + upstream/fedora-40/man1/lockfile.1 | 285 + upstream/fedora-40/man1/loginctl.1 | 587 + upstream/fedora-40/man1/logname.1 | 36 + upstream/fedora-40/man1/lookbib.1 | 166 + upstream/fedora-40/man1/ls.1 | 268 + upstream/fedora-40/man1/lsattr.1 | 52 + upstream/fedora-40/man1/lynx.1 | 1421 + upstream/fedora-40/man1/lz4.1 | 249 + upstream/fedora-40/man1/machinectl.1 | 1277 + upstream/fedora-40/man1/macptopbm.1 | 74 + upstream/fedora-40/man1/mailq.sendmail.1 | 135 + upstream/fedora-40/man1/mailstat.1 | 86 + upstream/fedora-40/man1/make.1 | 413 + upstream/fedora-40/man1/makeinfo.1 | 273 + upstream/fedora-40/man1/makepkg-template.1 | 328 + upstream/fedora-40/man1/manweb.1 | 278 + upstream/fedora-40/man1/mattrib.1 | 128 + upstream/fedora-40/man1/mbadblocks.1 | 115 + upstream/fedora-40/man1/mcat.1 | 100 + upstream/fedora-40/man1/mcd.1 | 111 + upstream/fedora-40/man1/mcopy.1 | 178 + upstream/fedora-40/man1/md5sum.1 | 83 + upstream/fedora-40/man1/mdatopbm.1 | 82 + upstream/fedora-40/man1/mdb2rec.1 | 52 + upstream/fedora-40/man1/mdel.1 | 96 + upstream/fedora-40/man1/mdeltree.1 | 96 + upstream/fedora-40/man1/mdiff.1 | 97 + upstream/fedora-40/man1/mdir.1 | 118 + upstream/fedora-40/man1/mdu.1 | 95 + upstream/fedora-40/man1/memusage.1 | 262 + upstream/fedora-40/man1/memusagestat.1 | 73 + upstream/fedora-40/man1/merge.1 | 158 + upstream/fedora-40/man1/mev.1 | 133 + upstream/fedora-40/man1/mformat.1 | 339 + upstream/fedora-40/man1/mgrtopbm.1 | 60 + upstream/fedora-40/man1/minfo.1 | 99 + upstream/fedora-40/man1/mkdir.1 | 56 + upstream/fedora-40/man1/mkfifo.1 | 48 + upstream/fedora-40/man1/mkmanifest.1 | 180 + upstream/fedora-40/man1/mknod.1 | 66 + upstream/fedora-40/man1/mkosi.1 | 1852 + upstream/fedora-40/man1/mktemp.1 | 64 + upstream/fedora-40/man1/mlabel.1 | 118 + upstream/fedora-40/man1/mmd.1 | 91 + upstream/fedora-40/man1/mmount.1 | 96 + upstream/fedora-40/man1/mmove.1 | 99 + upstream/fedora-40/man1/most.1 | 445 + upstream/fedora-40/man1/mouse-test.1 | 44 + upstream/fedora-40/man1/mpartition.1 | 228 + upstream/fedora-40/man1/mpstat.1 | 246 + upstream/fedora-40/man1/mrd.1 | 95 + upstream/fedora-40/man1/mren.1 | 105 + upstream/fedora-40/man1/mrf.1 | 131 + upstream/fedora-40/man1/mrftopbm.1 | 74 + upstream/fedora-40/man1/msgattrib.1 | 172 + upstream/fedora-40/man1/msgcat.1 | 152 + upstream/fedora-40/man1/msgcmp.1 | 79 + upstream/fedora-40/man1/msgcomm.1 | 144 + upstream/fedora-40/man1/msgconv.1 | 123 + upstream/fedora-40/man1/msgen.1 | 123 + upstream/fedora-40/man1/msgexec.1 | 70 + upstream/fedora-40/man1/msgfilter.1 | 139 + upstream/fedora-40/man1/msgfmt.1 | 225 + upstream/fedora-40/man1/msggrep.1 | 182 + upstream/fedora-40/man1/msginit.1 | 95 + upstream/fedora-40/man1/msgmerge.1 | 185 + upstream/fedora-40/man1/msgunfmt.1 | 147 + upstream/fedora-40/man1/msguniq.1 | 138 + upstream/fedora-40/man1/mshortname.1 | 95 + upstream/fedora-40/man1/mshowfat.1 | 96 + upstream/fedora-40/man1/mtools.1 | 503 + upstream/fedora-40/man1/mtoolstest.1 | 90 + upstream/fedora-40/man1/mtrace.1 | 47 + upstream/fedora-40/man1/mtvtoppm.1 | 55 + upstream/fedora-40/man1/mtype.1 | 114 + upstream/fedora-40/man1/mutt.1 | 339 + upstream/fedora-40/man1/mutt_pgpring.1 | 65 + upstream/fedora-40/man1/mv.1 | 118 + upstream/fedora-40/man1/mzip.1 | 147 + upstream/fedora-40/man1/nano.1 | 427 + upstream/fedora-40/man1/ncursesw6-config.1 | 104 + upstream/fedora-40/man1/needs-restarting.1 | 85 + upstream/fedora-40/man1/neotoppm.1 | 56 + upstream/fedora-40/man1/neqn.1 | 92 + upstream/fedora-40/man1/networkctl.1 | 519 + upstream/fedora-40/man1/newaliases.sendmail.1 | 50 + upstream/fedora-40/man1/ngettext.1 | 73 + upstream/fedora-40/man1/nice.1 | 60 + upstream/fedora-40/man1/nl.1 | 103 + upstream/fedora-40/man1/nm.1 | 611 + upstream/fedora-40/man1/nohup.1 | 59 + upstream/fedora-40/man1/nproc.1 | 40 + upstream/fedora-40/man1/nroff.1 | 358 + upstream/fedora-40/man1/numfmt.1 | 185 + upstream/fedora-40/man1/objcopy.1 | 1177 + upstream/fedora-40/man1/objdump.1 | 1396 + upstream/fedora-40/man1/od.1 | 169 + upstream/fedora-40/man1/ogg123.1 | 436 + upstream/fedora-40/man1/oggdec.1 | 120 + upstream/fedora-40/man1/oggenc.1 | 423 + upstream/fedora-40/man1/ogginfo.1 | 60 + upstream/fedora-40/man1/oomctl.1 | 70 + upstream/fedora-40/man1/openvt.1 | 93 + upstream/fedora-40/man1/package-cleanup.1 | 83 + upstream/fedora-40/man1/palmtopnm.1 | 145 + upstream/fedora-40/man1/pamaddnoise.1 | 172 + upstream/fedora-40/man1/pamaltsat.1 | 303 + upstream/fedora-40/man1/pamarith.1 | 386 + upstream/fedora-40/man1/pambackground.1 | 191 + upstream/fedora-40/man1/pambayer.1 | 131 + upstream/fedora-40/man1/pambrighten.1 | 188 + upstream/fedora-40/man1/pamcat.1 | 282 + upstream/fedora-40/man1/pamchannel.1 | 96 + upstream/fedora-40/man1/pamcomp.1 | 379 + upstream/fedora-40/man1/pamcrater.1 | 234 + upstream/fedora-40/man1/pamcut.1 | 244 + upstream/fedora-40/man1/pamdeinterlace.1 | 99 + upstream/fedora-40/man1/pamdepth.1 | 109 + upstream/fedora-40/man1/pamdice.1 | 171 + upstream/fedora-40/man1/pamditherbw.1 | 223 + upstream/fedora-40/man1/pamedge.1 | 91 + upstream/fedora-40/man1/pamendian.1 | 89 + upstream/fedora-40/man1/pamenlarge.1 | 160 + upstream/fedora-40/man1/pamexec.1 | 130 + upstream/fedora-40/man1/pamfile.1 | 174 + upstream/fedora-40/man1/pamfind.1 | 127 + upstream/fedora-40/man1/pamfix.1 | 180 + upstream/fedora-40/man1/pamfixtrunc.1 | 48 + upstream/fedora-40/man1/pamflip.1 | 289 + upstream/fedora-40/man1/pamfunc.1 | 359 + upstream/fedora-40/man1/pamgauss.1 | 182 + upstream/fedora-40/man1/pamgetcolor.1 | 212 + upstream/fedora-40/man1/pamgradient.1 | 115 + upstream/fedora-40/man1/pamhomography.1 | 428 + upstream/fedora-40/man1/pamhue.1 | 125 + upstream/fedora-40/man1/pamlevels.1 | 185 + upstream/fedora-40/man1/pamlookup.1 | 404 + upstream/fedora-40/man1/pammasksharpen.1 | 156 + upstream/fedora-40/man1/pammixinterlace.1 | 109 + upstream/fedora-40/man1/pammixmulti.1 | 239 + upstream/fedora-40/man1/pammosaicknit.1 | 159 + upstream/fedora-40/man1/pamoil.1 | 92 + upstream/fedora-40/man1/pampaintspill.1 | 241 + upstream/fedora-40/man1/pamperspective.1 | 599 + upstream/fedora-40/man1/pampick.1 | 91 + upstream/fedora-40/man1/pampop9.1 | 92 + upstream/fedora-40/man1/pamrecolor.1 | 309 + upstream/fedora-40/man1/pamrestack.1 | 206 + upstream/fedora-40/man1/pamrgbatopng.1 | 45 + upstream/fedora-40/man1/pamrubber.1 | 179 + upstream/fedora-40/man1/pamscale.1 | 770 + upstream/fedora-40/man1/pamseq.1 | 239 + upstream/fedora-40/man1/pamshadedrelief.1 | 139 + upstream/fedora-40/man1/pamsharpmap.1 | 85 + upstream/fedora-40/man1/pamsharpness.1 | 71 + upstream/fedora-40/man1/pamshuffle.1 | 179 + upstream/fedora-40/man1/pamsistoaglyph.1 | 208 + upstream/fedora-40/man1/pamslice.1 | 131 + upstream/fedora-40/man1/pamsplit.1 | 116 + upstream/fedora-40/man1/pamstack.1 | 118 + upstream/fedora-40/man1/pamstereogram.1 | 627 + upstream/fedora-40/man1/pamstretch-gen.1 | 69 + upstream/fedora-40/man1/pamstretch.1 | 143 + upstream/fedora-40/man1/pamsumm.1 | 146 + upstream/fedora-40/man1/pamsummcol.1 | 142 + upstream/fedora-40/man1/pamtable.1 | 147 + upstream/fedora-40/man1/pamthreshold.1 | 192 + upstream/fedora-40/man1/pamtilt.1 | 181 + upstream/fedora-40/man1/pamtoavs.1 | 82 + upstream/fedora-40/man1/pamtodjvurle.1 | 78 + upstream/fedora-40/man1/pamtofits.1 | 118 + upstream/fedora-40/man1/pamtogif.1 | 405 + upstream/fedora-40/man1/pamtohdiff.1 | 106 + upstream/fedora-40/man1/pamtohtmltbl.1 | 103 + upstream/fedora-40/man1/pamtojpeg2k.1 | 354 + upstream/fedora-40/man1/pamtompfont.1 | 74 + upstream/fedora-40/man1/pamtooctaveimg.1 | 122 + upstream/fedora-40/man1/pamtopam.1 | 76 + upstream/fedora-40/man1/pamtopdbimg.1 | 117 + upstream/fedora-40/man1/pamtopfm.1 | 115 + upstream/fedora-40/man1/pamtopng.1 | 434 + upstream/fedora-40/man1/pamtopnm.1 | 126 + upstream/fedora-40/man1/pamtoqoi.1 | 75 + upstream/fedora-40/man1/pamtosrf.1 | 101 + upstream/fedora-40/man1/pamtosvg.1 | 238 + upstream/fedora-40/man1/pamtotga.1 | 169 + upstream/fedora-40/man1/pamtotiff.1 | 622 + upstream/fedora-40/man1/pamtouil.1 | 91 + upstream/fedora-40/man1/pamtowinicon.1 | 194 + upstream/fedora-40/man1/pamtoxvmini.1 | 58 + upstream/fedora-40/man1/pamtris.1 | 808 + upstream/fedora-40/man1/pamundice.1 | 268 + upstream/fedora-40/man1/pamunlookup.1 | 143 + upstream/fedora-40/man1/pamvalidate.1 | 85 + upstream/fedora-40/man1/pamwipeout.1 | 104 + upstream/fedora-40/man1/pamx.1 | 268 + upstream/fedora-40/man1/paste.1 | 47 + upstream/fedora-40/man1/pathchk.1 | 42 + upstream/fedora-40/man1/pbmclean.1 | 167 + upstream/fedora-40/man1/pbmlife.1 | 56 + upstream/fedora-40/man1/pbmmake.1 | 80 + upstream/fedora-40/man1/pbmmask.1 | 131 + upstream/fedora-40/man1/pbmminkowski.1 | 41 + upstream/fedora-40/man1/pbmnoise.1 | 177 + upstream/fedora-40/man1/pbmpage.1 | 108 + upstream/fedora-40/man1/pbmpscale.1 | 79 + upstream/fedora-40/man1/pbmreduce.1 | 109 + upstream/fedora-40/man1/pbmtext.1 | 541 + upstream/fedora-40/man1/pbmtextps.1 | 435 + upstream/fedora-40/man1/pbmto10x.1 | 67 + upstream/fedora-40/man1/pbmto4425.1 | 75 + upstream/fedora-40/man1/pbmtoascii.1 | 85 + upstream/fedora-40/man1/pbmtoatk.1 | 54 + upstream/fedora-40/man1/pbmtobbnbg.1 | 60 + upstream/fedora-40/man1/pbmtocis.1 | 87 + upstream/fedora-40/man1/pbmtocmuwm.1 | 54 + upstream/fedora-40/man1/pbmtodjvurle.1 | 61 + upstream/fedora-40/man1/pbmtoepsi.1 | 109 + upstream/fedora-40/man1/pbmtoepson.1 | 115 + upstream/fedora-40/man1/pbmtoescp2.1 | 179 + upstream/fedora-40/man1/pbmtog3.1 | 112 + upstream/fedora-40/man1/pbmtogem.1 | 60 + upstream/fedora-40/man1/pbmtogo.1 | 58 + upstream/fedora-40/man1/pbmtoibm23xx.1 | 100 + upstream/fedora-40/man1/pbmtoicon.1 | 47 + upstream/fedora-40/man1/pbmtolj.1 | 133 + upstream/fedora-40/man1/pbmtoln03.1 | 76 + upstream/fedora-40/man1/pbmtolps.1 | 89 + upstream/fedora-40/man1/pbmtomacp.1 | 119 + upstream/fedora-40/man1/pbmtomatrixorbital.1 | 65 + upstream/fedora-40/man1/pbmtomda.1 | 82 + upstream/fedora-40/man1/pbmtomgr.1 | 61 + upstream/fedora-40/man1/pbmtomrf.1 | 68 + upstream/fedora-40/man1/pbmtonokia.1 | 164 + upstream/fedora-40/man1/pbmtopgm.1 | 92 + upstream/fedora-40/man1/pbmtopi3.1 | 58 + upstream/fedora-40/man1/pbmtopk.1 | 162 + upstream/fedora-40/man1/pbmtoplot.1 | 55 + upstream/fedora-40/man1/pbmtoppa.1 | 325 + upstream/fedora-40/man1/pbmtopsg3.1 | 93 + upstream/fedora-40/man1/pbmtoptx.1 | 54 + upstream/fedora-40/man1/pbmtosunicon.1 | 61 + upstream/fedora-40/man1/pbmtowbmp.1 | 62 + upstream/fedora-40/man1/pbmtox10bm.1 | 33 + upstream/fedora-40/man1/pbmtoxbm.1 | 83 + upstream/fedora-40/man1/pbmtoybm.1 | 57 + upstream/fedora-40/man1/pbmtozinc.1 | 55 + upstream/fedora-40/man1/pbmupc.1 | 87 + upstream/fedora-40/man1/pc1toppm.1 | 62 + upstream/fedora-40/man1/pcdindex.1 | 26 + upstream/fedora-40/man1/pcdovtoppm.1 | 116 + upstream/fedora-40/man1/pcxtoppm.1 | 105 + upstream/fedora-40/man1/pdbimgtopam.1 | 81 + upstream/fedora-40/man1/pdf2dsc.1 | 33 + upstream/fedora-40/man1/pdf2ps.1 | 20 + upstream/fedora-40/man1/pdfroff.1 | 982 + upstream/fedora-40/man1/perl.1 | 496 + upstream/fedora-40/man1/perl5004delta.1 | 1567 + upstream/fedora-40/man1/perl5005delta.1 | 939 + upstream/fedora-40/man1/perl5100delta.1 | 1500 + upstream/fedora-40/man1/perl5101delta.1 | 1550 + upstream/fedora-40/man1/perl5120delta.1 | 2580 ++ upstream/fedora-40/man1/perl5121delta.1 | 325 + upstream/fedora-40/man1/perl5122delta.1 | 300 + upstream/fedora-40/man1/perl5123delta.1 | 166 + upstream/fedora-40/man1/perl5124delta.1 | 151 + upstream/fedora-40/man1/perl5125delta.1 | 266 + upstream/fedora-40/man1/perl5140delta.1 | 3862 ++ upstream/fedora-40/man1/perl5141delta.1 | 304 + upstream/fedora-40/man1/perl5142delta.1 | 243 + upstream/fedora-40/man1/perl5143delta.1 | 278 + upstream/fedora-40/man1/perl5144delta.1 | 255 + upstream/fedora-40/man1/perl5160delta.1 | 3342 ++ upstream/fedora-40/man1/perl5161delta.1 | 207 + upstream/fedora-40/man1/perl5162delta.1 | 157 + upstream/fedora-40/man1/perl5163delta.1 | 168 + upstream/fedora-40/man1/perl5180delta.1 | 3014 ++ upstream/fedora-40/man1/perl5181delta.1 | 221 + upstream/fedora-40/man1/perl5182delta.1 | 188 + upstream/fedora-40/man1/perl5184delta.1 | 177 + upstream/fedora-40/man1/perl5200delta.1 | 2722 ++ upstream/fedora-40/man1/perl5201delta.1 | 340 + upstream/fedora-40/man1/perl5202delta.1 | 357 + upstream/fedora-40/man1/perl5203delta.1 | 283 + upstream/fedora-40/man1/perl5220delta.1 | 3128 ++ upstream/fedora-40/man1/perl5221delta.1 | 305 + upstream/fedora-40/man1/perl5222delta.1 | 354 + upstream/fedora-40/man1/perl5223delta.1 | 289 + upstream/fedora-40/man1/perl5224delta.1 | 163 + upstream/fedora-40/man1/perl5240delta.1 | 1628 + upstream/fedora-40/man1/perl5241delta.1 | 285 + upstream/fedora-40/man1/perl5242delta.1 | 158 + upstream/fedora-40/man1/perl5243delta.1 | 315 + upstream/fedora-40/man1/perl5244delta.1 | 166 + upstream/fedora-40/man1/perl5260delta.1 | 2481 ++ upstream/fedora-40/man1/perl5261delta.1 | 256 + upstream/fedora-40/man1/perl5262delta.1 | 247 + upstream/fedora-40/man1/perl5263delta.1 | 228 + upstream/fedora-40/man1/perl5280delta.1 | 1863 + upstream/fedora-40/man1/perl5281delta.1 | 176 + upstream/fedora-40/man1/perl5282delta.1 | 227 + upstream/fedora-40/man1/perl5283delta.1 | 186 + upstream/fedora-40/man1/perl5300delta.1 | 1073 + upstream/fedora-40/man1/perl5301delta.1 | 206 + upstream/fedora-40/man1/perl5302delta.1 | 192 + upstream/fedora-40/man1/perl5303delta.1 | 184 + upstream/fedora-40/man1/perl5320delta.1 | 1401 + upstream/fedora-40/man1/perl5321delta.1 | 264 + upstream/fedora-40/man1/perl5340delta.1 | 1052 + upstream/fedora-40/man1/perl5341delta.1 | 179 + upstream/fedora-40/man1/perl5342delta.1 | 160 + upstream/fedora-40/man1/perl5343delta.1 | 161 + upstream/fedora-40/man1/perl5360delta.1 | 1254 + upstream/fedora-40/man1/perl5361delta.1 | 181 + upstream/fedora-40/man1/perl5362delta.1 | 160 + upstream/fedora-40/man1/perl5363delta.1 | 161 + upstream/fedora-40/man1/perl5380delta.1 | 1750 + upstream/fedora-40/man1/perl5381delta.1 | 160 + upstream/fedora-40/man1/perl5382delta.1 | 161 + upstream/fedora-40/man1/perl561delta.1 | 3386 ++ upstream/fedora-40/man1/perl56delta.1 | 2870 ++ upstream/fedora-40/man1/perl581delta.1 | 1089 + upstream/fedora-40/man1/perl582delta.1 | 197 + upstream/fedora-40/man1/perl583delta.1 | 251 + upstream/fedora-40/man1/perl584delta.1 | 299 + upstream/fedora-40/man1/perl585delta.1 | 233 + upstream/fedora-40/man1/perl586delta.1 | 190 + upstream/fedora-40/man1/perl587delta.1 | 303 + upstream/fedora-40/man1/perl588delta.1 | 1142 + upstream/fedora-40/man1/perl589delta.1 | 1656 + upstream/fedora-40/man1/perl58delta.1 | 2906 ++ upstream/fedora-40/man1/perlaix.1 | 587 + upstream/fedora-40/man1/perlamiga.1 | 250 + upstream/fedora-40/man1/perlandroid.1 | 274 + upstream/fedora-40/man1/perlapi.1 | 29981 +++++++++++++++ upstream/fedora-40/man1/perlapio.1 | 548 + upstream/fedora-40/man1/perlartistic.1 | 238 + upstream/fedora-40/man1/perlbook.1 | 367 + upstream/fedora-40/man1/perlboot.1 | 71 + upstream/fedora-40/man1/perlbot.1 | 71 + upstream/fedora-40/man1/perlbs2000.1 | 290 + upstream/fedora-40/man1/perlcall.1 | 2001 + upstream/fedora-40/man1/perlcheat.1 | 157 + upstream/fedora-40/man1/perlclass.1 | 382 + upstream/fedora-40/man1/perlclassguts.1 | 466 + upstream/fedora-40/man1/perlclib.1 | 327 + upstream/fedora-40/man1/perlcn.1 | 189 + upstream/fedora-40/man1/perlcommunity.1 | 221 + upstream/fedora-40/man1/perlcygwin.1 | 797 + upstream/fedora-40/man1/perldata.1 | 1482 + upstream/fedora-40/man1/perldbmfilter.1 | 219 + upstream/fedora-40/man1/perldebguts.1 | 1131 + upstream/fedora-40/man1/perldebtut.1 | 871 + upstream/fedora-40/man1/perldelta.1 | 161 + upstream/fedora-40/man1/perldeprecation.1 | 750 + upstream/fedora-40/man1/perldocstyle.1 | 1118 + upstream/fedora-40/man1/perldsc.1 | 964 + upstream/fedora-40/man1/perldtrace.1 | 278 + upstream/fedora-40/man1/perlebcdic.1 | 1998 + upstream/fedora-40/man1/perlembed.1 | 1246 + upstream/fedora-40/man1/perlexperiment.1 | 479 + upstream/fedora-40/man1/perlfork.1 | 388 + upstream/fedora-40/man1/perlform.1 | 514 + upstream/fedora-40/man1/perlfreebsd.1 | 94 + upstream/fedora-40/man1/perlfunc.1 | 10931 ++++++ upstream/fedora-40/man1/perlgit.1 | 1076 + upstream/fedora-40/man1/perlgov.1 | 519 + upstream/fedora-40/man1/perlgpl.1 | 348 + upstream/fedora-40/man1/perlguts.1 | 4465 +++ upstream/fedora-40/man1/perlhack.1 | 1259 + upstream/fedora-40/man1/perlhacktips.1 | 2067 + upstream/fedora-40/man1/perlhacktut.1 | 264 + upstream/fedora-40/man1/perlhaiku.1 | 109 + upstream/fedora-40/man1/perlhist.1 | 1414 + upstream/fedora-40/man1/perlhpux.1 | 784 + upstream/fedora-40/man1/perlhurd.1 | 110 + upstream/fedora-40/man1/perlintern.1 | 5045 +++ upstream/fedora-40/man1/perlinterp.1 | 1024 + upstream/fedora-40/man1/perlintro.1 | 845 + upstream/fedora-40/man1/perliol.1 | 1074 + upstream/fedora-40/man1/perlipc.1 | 1956 + upstream/fedora-40/man1/perlirix.1 | 206 + upstream/fedora-40/man1/perljp.1 | 234 + upstream/fedora-40/man1/perlko.1 | 358 + upstream/fedora-40/man1/perllexwarn.1 | 70 + upstream/fedora-40/man1/perllinux.1 | 105 + upstream/fedora-40/man1/perllocale.1 | 1764 + upstream/fedora-40/man1/perllol.1 | 464 + upstream/fedora-40/man1/perlmacosx.1 | 337 + upstream/fedora-40/man1/perlmod.1 | 740 + upstream/fedora-40/man1/perlmodinstall.1 | 400 + upstream/fedora-40/man1/perlmodlib.1 | 2368 ++ upstream/fedora-40/man1/perlmodstyle.1 | 668 + upstream/fedora-40/man1/perlmroapi.1 | 155 + upstream/fedora-40/man1/perlnewmod.1 | 319 + upstream/fedora-40/man1/perlnumber.1 | 244 + upstream/fedora-40/man1/perlobj.1 | 1203 + upstream/fedora-40/man1/perlootut.1 | 785 + upstream/fedora-40/man1/perlop.1 | 4136 ++ upstream/fedora-40/man1/perlopenbsd.1 | 84 + upstream/fedora-40/man1/perlopentut.1 | 472 + upstream/fedora-40/man1/perlos2.1 | 2600 ++ upstream/fedora-40/man1/perlos390.1 | 506 + upstream/fedora-40/man1/perlos400.1 | 175 + upstream/fedora-40/man1/perlpacktut.1 | 1413 + upstream/fedora-40/man1/perlperf.1 | 1292 + upstream/fedora-40/man1/perlplan9.1 | 206 + upstream/fedora-40/man1/perlpod.1 | 831 + upstream/fedora-40/man1/perlpodspec.1 | 1884 + upstream/fedora-40/man1/perlpolicy.1 | 573 + upstream/fedora-40/man1/perlport.1 | 2552 ++ upstream/fedora-40/man1/perlpragma.1 | 230 + upstream/fedora-40/man1/perlqnx.1 | 251 + upstream/fedora-40/man1/perlre.1 | 3711 ++ upstream/fedora-40/man1/perlreapi.1 | 925 + upstream/fedora-40/man1/perlrebackslash.1 | 859 + upstream/fedora-40/man1/perlrecharclass.1 | 1301 + upstream/fedora-40/man1/perlref.1 | 1123 + upstream/fedora-40/man1/perlreftut.1 | 594 + upstream/fedora-40/man1/perlreguts.1 | 1092 + upstream/fedora-40/man1/perlrepository.1 | 76 + upstream/fedora-40/man1/perlrequick.1 | 651 + upstream/fedora-40/man1/perlreref.1 | 476 + upstream/fedora-40/man1/perlretut.1 | 3219 ++ upstream/fedora-40/man1/perlriscos.1 | 109 + upstream/fedora-40/man1/perlrun.1 | 1630 + upstream/fedora-40/man1/perlsec.1 | 673 + upstream/fedora-40/man1/perlsecpolicy.1 | 537 + upstream/fedora-40/man1/perlsolaris.1 | 784 + upstream/fedora-40/man1/perlsource.1 | 270 + upstream/fedora-40/man1/perlstyle.1 | 312 + upstream/fedora-40/man1/perlsub.1 | 2352 ++ upstream/fedora-40/man1/perlsyn.1 | 1630 + upstream/fedora-40/man1/perlsynology.1 | 373 + upstream/fedora-40/man1/perlthrtut.1 | 1232 + upstream/fedora-40/man1/perltie.1 | 1361 + upstream/fedora-40/man1/perltoc.1 | 37640 +++++++++++++++++++ upstream/fedora-40/man1/perltodo.1 | 71 + upstream/fedora-40/man1/perltooc.1 | 71 + upstream/fedora-40/man1/perltoot.1 | 71 + upstream/fedora-40/man1/perltrap.1 | 363 + upstream/fedora-40/man1/perltru64.1 | 240 + upstream/fedora-40/man1/perltw.1 | 189 + upstream/fedora-40/man1/perlunicode.1 | 2232 ++ upstream/fedora-40/man1/perlunicook.1 | 968 + upstream/fedora-40/man1/perlunifaq.1 | 389 + upstream/fedora-40/man1/perluniintro.1 | 1073 + upstream/fedora-40/man1/perluniprops.1 | 7880 ++++ upstream/fedora-40/man1/perlunitut.1 | 285 + upstream/fedora-40/man1/perlvar.1 | 2893 ++ upstream/fedora-40/man1/perlvms.1 | 1197 + upstream/fedora-40/man1/perlvos.1 | 165 + upstream/fedora-40/man1/perlwin32.1 | 821 + upstream/fedora-40/man1/pfbtops.1 | 129 + upstream/fedora-40/man1/pfmtopam.1 | 91 + upstream/fedora-40/man1/pgmabel.1 | 132 + upstream/fedora-40/man1/pgmbentley.1 | 60 + upstream/fedora-40/man1/pgmcrater.1 | 100 + upstream/fedora-40/man1/pgmdeshadow.1 | 81 + upstream/fedora-40/man1/pgmedge.1 | 30 + upstream/fedora-40/man1/pgmenhance.1 | 74 + upstream/fedora-40/man1/pgmhist.1 | 148 + upstream/fedora-40/man1/pgmkernel.1 | 127 + upstream/fedora-40/man1/pgmmake.1 | 90 + upstream/fedora-40/man1/pgmmedian.1 | 161 + upstream/fedora-40/man1/pgmminkowski.1 | 113 + upstream/fedora-40/man1/pgmmorphconv.1 | 141 + upstream/fedora-40/man1/pgmnoise.1 | 101 + upstream/fedora-40/man1/pgmnorm.1 | 29 + upstream/fedora-40/man1/pgmoil.1 | 29 + upstream/fedora-40/man1/pgmramp.1 | 139 + upstream/fedora-40/man1/pgmslice.1 | 27 + upstream/fedora-40/man1/pgmtexture.1 | 117 + upstream/fedora-40/man1/pgmtofs.1 | 59 + upstream/fedora-40/man1/pgmtolispm.1 | 77 + upstream/fedora-40/man1/pgmtopbm.1 | 104 + upstream/fedora-40/man1/pgmtopgm.1 | 73 + upstream/fedora-40/man1/pgmtoppm.1 | 180 + upstream/fedora-40/man1/pgmtosbig.1 | 79 + upstream/fedora-40/man1/pgmtost4.1 | 81 + upstream/fedora-40/man1/pgpewrap.1 | 46 + upstream/fedora-40/man1/pi1toppm.1 | 62 + upstream/fedora-40/man1/pi3topbm.1 | 60 + upstream/fedora-40/man1/pic.1 | 1569 + upstream/fedora-40/man1/pic2graph.1 | 234 + upstream/fedora-40/man1/pico.1 | 258 + upstream/fedora-40/man1/pidstat.1 | 452 + upstream/fedora-40/man1/pilot.1 | 84 + upstream/fedora-40/man1/pinky.1 | 62 + upstream/fedora-40/man1/pitchplay.1 | 59 + upstream/fedora-40/man1/pjtoppm.1 | 62 + upstream/fedora-40/man1/pktopbm.1 | 77 + upstream/fedora-40/man1/pldd.1 | 105 + upstream/fedora-40/man1/pm-gawk.1 | 208 + upstream/fedora-40/man1/pngtopam.1 | 327 + upstream/fedora-40/man1/pngtopnm.1 | 70 + upstream/fedora-40/man1/pnmalias.1 | 114 + upstream/fedora-40/man1/pnmarith.1 | 32 + upstream/fedora-40/man1/pnmcat.1 | 33 + upstream/fedora-40/man1/pnmcolormap.1 | 307 + upstream/fedora-40/man1/pnmcomp.1 | 39 + upstream/fedora-40/man1/pnmconvol.1 | 486 + upstream/fedora-40/man1/pnmcrop.1 | 427 + upstream/fedora-40/man1/pnmcut.1 | 37 + upstream/fedora-40/man1/pnmdepth.1 | 35 + upstream/fedora-40/man1/pnmenlarge.1 | 28 + upstream/fedora-40/man1/pnmfile.1 | 29 + upstream/fedora-40/man1/pnmflip.1 | 42 + upstream/fedora-40/man1/pnmgamma.1 | 339 + upstream/fedora-40/man1/pnmhisteq.1 | 222 + upstream/fedora-40/man1/pnmhistmap.1 | 192 + upstream/fedora-40/man1/pnmindex.1 | 148 + upstream/fedora-40/man1/pnminterp.1 | 29 + upstream/fedora-40/man1/pnminvert.1 | 61 + upstream/fedora-40/man1/pnmmargin.1 | 114 + upstream/fedora-40/man1/pnmmercator.1 | 154 + upstream/fedora-40/man1/pnmmontage.1 | 192 + upstream/fedora-40/man1/pnmnlfilt.1 | 190 + upstream/fedora-40/man1/pnmnoraw.1 | 34 + upstream/fedora-40/man1/pnmnorm.1 | 356 + upstream/fedora-40/man1/pnmpad.1 | 283 + upstream/fedora-40/man1/pnmpaste.1 | 129 + upstream/fedora-40/man1/pnmpsnr.1 | 212 + upstream/fedora-40/man1/pnmquant.1 | 186 + upstream/fedora-40/man1/pnmquantall.1 | 93 + upstream/fedora-40/man1/pnmremap.1 | 370 + upstream/fedora-40/man1/pnmrotate.1 | 148 + upstream/fedora-40/man1/pnmscale.1 | 37 + upstream/fedora-40/man1/pnmscalefixed.1 | 138 + upstream/fedora-40/man1/pnmshear.1 | 141 + upstream/fedora-40/man1/pnmsmooth.1 | 143 + upstream/fedora-40/man1/pnmsplit.1 | 31 + upstream/fedora-40/man1/pnmstitch.1 | 138 + upstream/fedora-40/man1/pnmtile.1 | 74 + upstream/fedora-40/man1/pnmtoddif.1 | 93 + upstream/fedora-40/man1/pnmtofiasco.1 | 403 + upstream/fedora-40/man1/pnmtofits.1 | 28 + upstream/fedora-40/man1/pnmtojbig.1 | 293 + upstream/fedora-40/man1/pnmtojpeg.1 | 560 + upstream/fedora-40/man1/pnmtopalm.1 | 316 + upstream/fedora-40/man1/pnmtopclxl.1 | 258 + upstream/fedora-40/man1/pnmtoplainpnm.1 | 33 + upstream/fedora-40/man1/pnmtopng.1 | 566 + upstream/fedora-40/man1/pnmtopnm.1 | 89 + upstream/fedora-40/man1/pnmtops.1 | 532 + upstream/fedora-40/man1/pnmtorast.1 | 78 + upstream/fedora-40/man1/pnmtorle.1 | 133 + upstream/fedora-40/man1/pnmtosgi.1 | 81 + upstream/fedora-40/man1/pnmtosir.1 | 59 + upstream/fedora-40/man1/pnmtotiff.1 | 28 + upstream/fedora-40/man1/pnmtotiffcmyk.1 | 211 + upstream/fedora-40/man1/pnmtoxwd.1 | 83 + upstream/fedora-40/man1/pod2texi.1 | 249 + upstream/fedora-40/man1/portablectl.1 | 799 + upstream/fedora-40/man1/ppm3d.1 | 135 + upstream/fedora-40/man1/ppmbrighten.1 | 45 + upstream/fedora-40/man1/ppmchange.1 | 178 + upstream/fedora-40/man1/ppmcie.1 | 372 + upstream/fedora-40/man1/ppmcolormask.1 | 149 + upstream/fedora-40/man1/ppmcolors.1 | 33 + upstream/fedora-40/man1/ppmdcfont.1 | 59 + upstream/fedora-40/man1/ppmddumpfont.1 | 50 + upstream/fedora-40/man1/ppmdim.1 | 63 + upstream/fedora-40/man1/ppmdist.1 | 89 + upstream/fedora-40/man1/ppmdither.1 | 109 + upstream/fedora-40/man1/ppmdmkfont.1 | 52 + upstream/fedora-40/man1/ppmdraw.1 | 294 + upstream/fedora-40/man1/ppmfade.1 | 158 + upstream/fedora-40/man1/ppmflash.1 | 79 + upstream/fedora-40/man1/ppmforge.1 | 392 + upstream/fedora-40/man1/ppmglobe.1 | 161 + upstream/fedora-40/man1/ppmhist.1 | 217 + upstream/fedora-40/man1/ppmlabel.1 | 214 + upstream/fedora-40/man1/ppmmake.1 | 96 + upstream/fedora-40/man1/ppmmix.1 | 79 + upstream/fedora-40/man1/ppmnorm.1 | 29 + upstream/fedora-40/man1/ppmntsc.1 | 122 + upstream/fedora-40/man1/ppmpat.1 | 235 + upstream/fedora-40/man1/ppmquant.1 | 89 + upstream/fedora-40/man1/ppmquantall.1 | 33 + upstream/fedora-40/man1/ppmrainbow.1 | 135 + upstream/fedora-40/man1/ppmrelief.1 | 73 + upstream/fedora-40/man1/ppmrough.1 | 190 + upstream/fedora-40/man1/ppmshadow.1 | 294 + upstream/fedora-40/man1/ppmshift.1 | 100 + upstream/fedora-40/man1/ppmspread.1 | 80 + upstream/fedora-40/man1/ppmtoacad.1 | 173 + upstream/fedora-40/man1/ppmtoapplevol.1 | 74 + upstream/fedora-40/man1/ppmtoarbtxt.1 | 278 + upstream/fedora-40/man1/ppmtoascii.1 | 92 + upstream/fedora-40/man1/ppmtobmp.1 | 167 + upstream/fedora-40/man1/ppmtoeyuv.1 | 60 + upstream/fedora-40/man1/ppmtogif.1 | 95 + upstream/fedora-40/man1/ppmtoicr.1 | 159 + upstream/fedora-40/man1/ppmtoilbm.1 | 249 + upstream/fedora-40/man1/ppmtojpeg.1 | 30 + upstream/fedora-40/man1/ppmtoleaf.1 | 59 + upstream/fedora-40/man1/ppmtolj.1 | 96 + upstream/fedora-40/man1/ppmtomap.1 | 50 + upstream/fedora-40/man1/ppmtomitsu.1 | 138 + upstream/fedora-40/man1/ppmtompeg.1 | 1213 + upstream/fedora-40/man1/ppmtoneo.1 | 57 + upstream/fedora-40/man1/ppmtopcx.1 | 204 + upstream/fedora-40/man1/ppmtopgm.1 | 96 + upstream/fedora-40/man1/ppmtopi1.1 | 60 + upstream/fedora-40/man1/ppmtopict.1 | 74 + upstream/fedora-40/man1/ppmtopj.1 | 150 + upstream/fedora-40/man1/ppmtopjxl.1 | 144 + upstream/fedora-40/man1/ppmtoppm.1 | 78 + upstream/fedora-40/man1/ppmtopuzz.1 | 57 + upstream/fedora-40/man1/ppmtorgb3.1 | 71 + upstream/fedora-40/man1/ppmtosixel.1 | 98 + upstream/fedora-40/man1/ppmtospu.1 | 115 + upstream/fedora-40/man1/ppmtoterm.1 | 112 + upstream/fedora-40/man1/ppmtouil.1 | 26 + upstream/fedora-40/man1/ppmtowinicon.1 | 149 + upstream/fedora-40/man1/ppmtoxpm.1 | 188 + upstream/fedora-40/man1/ppmtoyuv.1 | 104 + upstream/fedora-40/man1/ppmtoyuvsplit.1 | 77 + upstream/fedora-40/man1/ppmtv.1 | 67 + upstream/fedora-40/man1/ppmwheel.1 | 134 + upstream/fedora-40/man1/pr.1 | 132 + upstream/fedora-40/man1/preconv.1 | 559 + upstream/fedora-40/man1/printenv.1 | 41 + upstream/fedora-40/man1/printf.1 | 104 + upstream/fedora-40/man1/procmail.1 | 933 + upstream/fedora-40/man1/ps2ascii.1 | 30 + upstream/fedora-40/man1/ps2epsi.1 | 65 + upstream/fedora-40/man1/ps2pdf.1 | 96 + upstream/fedora-40/man1/ps2pdfwr.1 | 31 + upstream/fedora-40/man1/ps2ps.1 | 28 + upstream/fedora-40/man1/psbook.1 | 57 + upstream/fedora-40/man1/psc.1 | 120 + upstream/fedora-40/man1/psfaddtable.1 | 47 + upstream/fedora-40/man1/psfgettable.1 | 22 + upstream/fedora-40/man1/psfstriptable.1 | 23 + upstream/fedora-40/man1/psfxtable.1 | 55 + upstream/fedora-40/man1/psidtopgm.1 | 71 + upstream/fedora-40/man1/psjoin.1 | 49 + upstream/fedora-40/man1/psnup.1 | 118 + upstream/fedora-40/man1/psresize.1 | 60 + upstream/fedora-40/man1/psselect.1 | 60 + upstream/fedora-40/man1/pstopnm.1 | 562 + upstream/fedora-40/man1/pstops.1 | 213 + upstream/fedora-40/man1/psutils.1 | 41 + upstream/fedora-40/man1/ptx.1 | 91 + upstream/fedora-40/man1/pwd.1 | 48 + upstream/fedora-40/man1/python3.12.1 | 629 + upstream/fedora-40/man1/pzstd.1 | 388 + upstream/fedora-40/man1/qoitopam.1 | 75 + upstream/fedora-40/man1/qrttoppm.1 | 54 + upstream/fedora-40/man1/quota.1 | 238 + upstream/fedora-40/man1/quotasync.1 | 75 + upstream/fedora-40/man1/ranlib.1 | 149 + upstream/fedora-40/man1/rasttopnm.1 | 85 + upstream/fedora-40/man1/rawtopgm.1 | 168 + upstream/fedora-40/man1/rawtoppm.1 | 111 + upstream/fedora-40/man1/rcs.1 | 521 + upstream/fedora-40/man1/rcsclean.1 | 256 + upstream/fedora-40/man1/rcsdiff.1 | 219 + upstream/fedora-40/man1/rcsmerge.1 | 250 + upstream/fedora-40/man1/readelf.1 | 828 + upstream/fedora-40/man1/readlink.1 | 67 + upstream/fedora-40/man1/readmult.1 | 52 + upstream/fedora-40/man1/realpath.1 | 64 + upstream/fedora-40/man1/rec2csv.1 | 51 + upstream/fedora-40/man1/recdel.1 | 79 + upstream/fedora-40/man1/recfix.1 | 70 + upstream/fedora-40/man1/recfmt.1 | 44 + upstream/fedora-40/man1/recinf.1 | 56 + upstream/fedora-40/man1/recins.1 | 90 + upstream/fedora-40/man1/recode-sr-latin.1 | 43 + upstream/fedora-40/man1/recsel.1 | 104 + upstream/fedora-40/man1/recset.1 | 95 + upstream/fedora-40/man1/refer.1 | 2020 + upstream/fedora-40/man1/repo-graph.1 | 92 + upstream/fedora-40/man1/repoclosure.1 | 120 + upstream/fedora-40/man1/repodiff.1 | 109 + upstream/fedora-40/man1/repomanage.1 | 112 + upstream/fedora-40/man1/reposync.1 | 116 + upstream/fedora-40/man1/resolvectl.1 | 727 + upstream/fedora-40/man1/rgb3toppm.1 | 63 + upstream/fedora-40/man1/rlatopam.1 | 67 + upstream/fedora-40/man1/rletopnm.1 | 157 + upstream/fedora-40/man1/rlog.1 | 377 + upstream/fedora-40/man1/rm.1 | 108 + upstream/fedora-40/man1/rmdir.1 | 46 + upstream/fedora-40/man1/rnano.1 | 60 + upstream/fedora-40/man1/rpdump.1 | 38 + upstream/fedora-40/man1/rpload.1 | 49 + upstream/fedora-40/man1/rsync-ssl.1 | 144 + upstream/fedora-40/man1/rsync.1 | 5051 +++ upstream/fedora-40/man1/rtf2rtf.1 | 70 + upstream/fedora-40/man1/runcon.1 | 80 + upstream/fedora-40/man1/rup.1 | 110 + upstream/fedora-40/man1/ruptime.1 | 87 + upstream/fedora-40/man1/rusers.1 | 95 + upstream/fedora-40/man1/rwall.1 | 81 + upstream/fedora-40/man1/rwho.1 | 85 + upstream/fedora-40/man1/sadf.1 | 395 + upstream/fedora-40/man1/sane-find-scanner.1 | 134 + upstream/fedora-40/man1/sar.1 | 1728 + upstream/fedora-40/man1/sbattach.1 | 32 + upstream/fedora-40/man1/sbigtopgm.1 | 73 + upstream/fedora-40/man1/sbkeysync.1 | 33 + upstream/fedora-40/man1/sbsiglist.1 | 22 + upstream/fedora-40/man1/sbsign.1 | 31 + upstream/fedora-40/man1/sbvarsign.1 | 44 + upstream/fedora-40/man1/sbverify.1 | 20 + upstream/fedora-40/man1/sc.1 | 4547 +++ upstream/fedora-40/man1/scanimage.1 | 524 + upstream/fedora-40/man1/scp.1 | 332 + upstream/fedora-40/man1/sdiff.1 | 104 + upstream/fedora-40/man1/sed.1 | 443 + upstream/fedora-40/man1/seq.1 | 62 + upstream/fedora-40/man1/setleds.1 | 84 + upstream/fedora-40/man1/setmetamode.1 | 61 + upstream/fedora-40/man1/sftp.1 | 728 + upstream/fedora-40/man1/sgitopnm.1 | 111 + upstream/fedora-40/man1/sgml2html.1 | 92 + upstream/fedora-40/man1/sgml2info.1 | 48 + upstream/fedora-40/man1/sgml2latex.1 | 133 + upstream/fedora-40/man1/sgml2lyx.1 | 48 + upstream/fedora-40/man1/sgml2rtf.1 | 54 + upstream/fedora-40/man1/sgml2txt.1 | 64 + upstream/fedora-40/man1/sgmlcheck.1 | 43 + upstream/fedora-40/man1/sgmlpre.1 | 60 + upstream/fedora-40/man1/sgmlsasp.1 | 30 + upstream/fedora-40/man1/sha1sum.1 | 83 + upstream/fedora-40/man1/sha224sum.1 | 78 + upstream/fedora-40/man1/sha256sum.1 | 78 + upstream/fedora-40/man1/sha384sum.1 | 78 + upstream/fedora-40/man1/sha512sum.1 | 78 + upstream/fedora-40/man1/shar.1 | 635 + upstream/fedora-40/man1/showkey.1 | 104 + upstream/fedora-40/man1/showrgb.1 | 45 + upstream/fedora-40/man1/shred.1 | 81 + upstream/fedora-40/man1/shuf.1 | 64 + upstream/fedora-40/man1/sirtopnm.1 | 59 + upstream/fedora-40/man1/size.1 | 234 + upstream/fedora-40/man1/sldtoppm.1 | 187 + upstream/fedora-40/man1/sleep.1 | 42 + upstream/fedora-40/man1/smime_keys.1 | 73 + upstream/fedora-40/man1/soelim.groff.1 | 456 + upstream/fedora-40/man1/sort.1 | 158 + upstream/fedora-40/man1/spctoppm.1 | 56 + upstream/fedora-40/man1/split.1 | 108 + upstream/fedora-40/man1/spottopgm.1 | 101 + upstream/fedora-40/man1/sprof.1 | 282 + upstream/fedora-40/man1/sputoppm.1 | 58 + upstream/fedora-40/man1/srftopam.1 | 91 + upstream/fedora-40/man1/ssconvert.1 | 424 + upstream/fedora-40/man1/ssdiff.1 | 81 + upstream/fedora-40/man1/ssgrep.1 | 139 + upstream/fedora-40/man1/ssh-add.1 | 350 + upstream/fedora-40/man1/ssh-agent.1 | 274 + upstream/fedora-40/man1/ssh-copy-id.1 | 221 + upstream/fedora-40/man1/ssh-keyscan.1 | 193 + upstream/fedora-40/man1/ssh.1 | 1815 + upstream/fedora-40/man1/ssindex.1 | 88 + upstream/fedora-40/man1/st4topgm.1 | 81 + upstream/fedora-40/man1/startx.1 | 208 + upstream/fedora-40/man1/stat.1 | 223 + upstream/fedora-40/man1/stdbuf.1 | 81 + upstream/fedora-40/man1/strfile.1 | 220 + upstream/fedora-40/man1/strings.1 | 268 + upstream/fedora-40/man1/strip.1 | 437 + upstream/fedora-40/man1/stty.1 | 413 + upstream/fedora-40/man1/sum.1 | 41 + upstream/fedora-40/man1/sunicontopnm.1 | 103 + upstream/fedora-40/man1/svgtopam.1 | 98 + upstream/fedora-40/man1/sync.1 | 48 + upstream/fedora-40/man1/systemctl.1 | 3040 ++ upstream/fedora-40/man1/systemd-ac-power.1 | 66 + upstream/fedora-40/man1/systemd-analyze.1 | 1885 + upstream/fedora-40/man1/systemd-ask-password.1 | 251 + upstream/fedora-40/man1/systemd-bootchart.1 | 197 + upstream/fedora-40/man1/systemd-cat.1 | 140 + upstream/fedora-40/man1/systemd-cgls.1 | 116 + upstream/fedora-40/man1/systemd-cgtop.1 | 290 + upstream/fedora-40/man1/systemd-creds.1 | 554 + upstream/fedora-40/man1/systemd-cryptenroll.1 | 749 + upstream/fedora-40/man1/systemd-delta.1 | 169 + upstream/fedora-40/man1/systemd-detect-virt.1 | 358 + upstream/fedora-40/man1/systemd-dissect.1 | 629 + upstream/fedora-40/man1/systemd-escape.1 | 223 + upstream/fedora-40/man1/systemd-firstboot.1 | 475 + upstream/fedora-40/man1/systemd-id128.1 | 185 + upstream/fedora-40/man1/systemd-inhibit.1 | 333 + upstream/fedora-40/man1/systemd-machine-id-setup.1 | 185 + upstream/fedora-40/man1/systemd-measure.1 | 429 + upstream/fedora-40/man1/systemd-mount.1 | 405 + upstream/fedora-40/man1/systemd-notify.1 | 275 + upstream/fedora-40/man1/systemd-nspawn.1 | 2276 ++ upstream/fedora-40/man1/systemd-path.1 | 70 + upstream/fedora-40/man1/systemd-run.1 | 759 + upstream/fedora-40/man1/systemd-socket-activate.1 | 176 + upstream/fedora-40/man1/systemd-stdio-bridge.1 | 105 + upstream/fedora-40/man1/systemd-swap.1 | 18 + .../man1/systemd-tty-ask-password-agent.1 | 116 + upstream/fedora-40/man1/systemd-vmspawn.1 | 378 + upstream/fedora-40/man1/systemd.1 | 1566 + upstream/fedora-40/man1/tabs.1 | 358 + upstream/fedora-40/man1/tac.1 | 49 + upstream/fedora-40/man1/tail.1 | 99 + upstream/fedora-40/man1/talk.1 | 170 + upstream/fedora-40/man1/tapestat.1 | 235 + upstream/fedora-40/man1/tar.1 | 1337 + upstream/fedora-40/man1/tbl.1 | 2018 + upstream/fedora-40/man1/tee.1 | 64 + upstream/fedora-40/man1/telnet.1 | 1511 + upstream/fedora-40/man1/test.1 | 179 + upstream/fedora-40/man1/texi2dvi.1 | 170 + upstream/fedora-40/man1/texindex.1 | 43 + upstream/fedora-40/man1/tfmtodit.1 | 415 + upstream/fedora-40/man1/tgatoppm.1 | 88 + upstream/fedora-40/man1/thinkfan.1 | 207 + upstream/fedora-40/man1/thinkjettopbm.1 | 86 + upstream/fedora-40/man1/tic.1m | 622 + upstream/fedora-40/man1/tifftopnm.1 | 354 + upstream/fedora-40/man1/time.1 | 329 + upstream/fedora-40/man1/timedatectl.1 | 551 + upstream/fedora-40/man1/timeout.1 | 99 + upstream/fedora-40/man1/toe.1m | 239 + upstream/fedora-40/man1/touch.1 | 84 + upstream/fedora-40/man1/tput.1 | 999 + upstream/fedora-40/man1/tr.1 | 143 + upstream/fedora-40/man1/tree.1 | 505 + upstream/fedora-40/man1/troff.1 | 1047 + upstream/fedora-40/man1/true.1 | 40 + upstream/fedora-40/man1/truncate.1 | 64 + upstream/fedora-40/man1/tset.1 | 462 + upstream/fedora-40/man1/tsort.1 | 35 + upstream/fedora-40/man1/tty.1 | 36 + upstream/fedora-40/man1/ukify.1 | 673 + upstream/fedora-40/man1/uname.1 | 64 + upstream/fedora-40/man1/unexpand.1 | 57 + upstream/fedora-40/man1/unicode_start.1 | 39 + upstream/fedora-40/man1/unicode_stop.1 | 20 + upstream/fedora-40/man1/unify.1 | 65 + upstream/fedora-40/man1/uniq.1 | 83 + upstream/fedora-40/man1/unlink.1 | 39 + upstream/fedora-40/man1/unshar.1 | 184 + upstream/fedora-40/man1/unzip.1 | 1042 + upstream/fedora-40/man1/unzipsfx.1 | 336 + upstream/fedora-40/man1/usb-devices.1 | 55 + upstream/fedora-40/man1/userdbctl.1 | 595 + upstream/fedora-40/man1/users.1 | 37 + upstream/fedora-40/man1/usleep.1 | 30 + upstream/fedora-40/man1/uucp.1 | 197 + upstream/fedora-40/man1/uudecode.1 | 170 + upstream/fedora-40/man1/uuencode.1 | 132 + upstream/fedora-40/man1/uuname.1 | 33 + upstream/fedora-40/man1/uustat.1 | 542 + upstream/fedora-40/man1/uux.1 | 254 + upstream/fedora-40/man1/varlinkctl.1 | 324 + upstream/fedora-40/man1/vcut.1 | 30 + upstream/fedora-40/man1/vdir.1 | 265 + upstream/fedora-40/man1/vlock.1 | 49 + upstream/fedora-40/man1/vorbiscomment.1 | 110 + upstream/fedora-40/man1/wbmptopbm.1 | 64 + upstream/fedora-40/man1/wc.1 | 67 + upstream/fedora-40/man1/wdiff.1 | 98 + upstream/fedora-40/man1/wdiff2.1 | 89 + upstream/fedora-40/man1/wget2.1 | 2726 ++ upstream/fedora-40/man1/which.1 | 155 + upstream/fedora-40/man1/who.1 | 84 + upstream/fedora-40/man1/whoami.1 | 34 + upstream/fedora-40/man1/whois.md.1 | 307 + upstream/fedora-40/man1/winicon.1 | 130 + upstream/fedora-40/man1/winicontopam.1 | 157 + upstream/fedora-40/man1/winicontoppm.1 | 116 + upstream/fedora-40/man1/xargs.1 | 511 + upstream/fedora-40/man1/xbmtopbm.1 | 58 + upstream/fedora-40/man1/xgettext.1 | 249 + upstream/fedora-40/man1/ximtoppm.1 | 85 + upstream/fedora-40/man1/xinit.1 | 199 + upstream/fedora-40/man1/xload.1 | 109 + upstream/fedora-40/man1/xpmtoppm.1 | 111 + upstream/fedora-40/man1/xvidtune.1 | 178 + upstream/fedora-40/man1/xvminitoppm.1 | 63 + upstream/fedora-40/man1/xwdtopnm.1 | 144 + upstream/fedora-40/man1/ybmtopbm.1 | 57 + upstream/fedora-40/man1/yes.1 | 36 + upstream/fedora-40/man1/yum-builddep.1 | 100 + upstream/fedora-40/man1/yum-changelog.1 | 101 + upstream/fedora-40/man1/yum-config-manager.1 | 122 + upstream/fedora-40/man1/yum-debug-dump.1 | 107 + upstream/fedora-40/man1/yum-debug-restore.1 | 107 + upstream/fedora-40/man1/yum-groups-manager.1 | 105 + upstream/fedora-40/man1/yum-utils.1 | 115 + upstream/fedora-40/man1/yumdownloader.1 | 109 + upstream/fedora-40/man1/yuvsplittoppm.1 | 74 + upstream/fedora-40/man1/yuvtoppm.1 | 72 + upstream/fedora-40/man1/yuy2topam.1 | 74 + upstream/fedora-40/man1/zdiff.1 | 50 + upstream/fedora-40/man1/zeisstopnm.1 | 72 + upstream/fedora-40/man1/zforce.1 | 24 + upstream/fedora-40/man1/zgrep.1 | 58 + upstream/fedora-40/man1/zipinfo.1 | 517 + upstream/fedora-40/man1/zless.1 | 58 + upstream/fedora-40/man1/zmore.1 | 148 + upstream/fedora-40/man1/znew.1 | 55 + upstream/fedora-40/man1/zstd.1 | 388 + upstream/fedora-40/man1/zstdgrep.1 | 17 + upstream/fedora-40/man1/zstdless.1 | 9 + 1142 files changed, 502941 insertions(+) create mode 100644 upstream/fedora-40/man1/411toppm.1 create mode 100644 upstream/fedora-40/man1/AusweisApp.1 create mode 100644 upstream/fedora-40/man1/ac.1 create mode 100644 upstream/fedora-40/man1/addftinfo.1 create mode 100644 upstream/fedora-40/man1/addr2line.1 create mode 100644 upstream/fedora-40/man1/airscan-discover.1 create mode 100644 upstream/fedora-40/man1/alpine.1 create mode 100644 upstream/fedora-40/man1/anytopnm.1 create mode 100644 upstream/fedora-40/man1/ar.1 create mode 100644 upstream/fedora-40/man1/arch.1 create mode 100644 upstream/fedora-40/man1/as.1 create mode 100644 upstream/fedora-40/man1/asciitopgm.1 create mode 100644 upstream/fedora-40/man1/at.1 create mode 100644 upstream/fedora-40/man1/atktopbm.1 create mode 100644 upstream/fedora-40/man1/autoconf.1 create mode 100644 upstream/fedora-40/man1/autoheader.1 create mode 100644 upstream/fedora-40/man1/autom4te.1 create mode 100644 upstream/fedora-40/man1/autopoint.1 create mode 100644 upstream/fedora-40/man1/autoreconf.1 create mode 100644 upstream/fedora-40/man1/autoscan.1 create mode 100644 upstream/fedora-40/man1/autoupdate.1 create mode 100644 upstream/fedora-40/man1/avstopam.1 create mode 100644 upstream/fedora-40/man1/b2sum.1 create mode 100644 upstream/fedora-40/man1/banner.1 create mode 100644 upstream/fedora-40/man1/base32.1 create mode 100644 upstream/fedora-40/man1/base64.1 create mode 100644 upstream/fedora-40/man1/basename.1 create mode 100644 upstream/fedora-40/man1/basenc.1 create mode 100644 upstream/fedora-40/man1/bash.1 create mode 100644 upstream/fedora-40/man1/bashbug.1 create mode 100644 upstream/fedora-40/man1/bc.1 create mode 100644 upstream/fedora-40/man1/bioradtopgm.1 create mode 100644 upstream/fedora-40/man1/bison.1 create mode 100644 upstream/fedora-40/man1/bmptopnm.1 create mode 100644 upstream/fedora-40/man1/bmptoppm.1 create mode 100644 upstream/fedora-40/man1/bootctl.1 create mode 100644 upstream/fedora-40/man1/brushtopbm.1 create mode 100644 upstream/fedora-40/man1/busctl.1 create mode 100644 upstream/fedora-40/man1/bzdiff.1 create mode 100644 upstream/fedora-40/man1/bzgrep.1 create mode 100644 upstream/fedora-40/man1/bzip2.1 create mode 100644 upstream/fedora-40/man1/bzmore.1 create mode 100644 upstream/fedora-40/man1/c++filt.1 create mode 100644 upstream/fedora-40/man1/cameratopam.1 create mode 100644 upstream/fedora-40/man1/captoinfo.1m create mode 100644 upstream/fedora-40/man1/cat.1 create mode 100644 upstream/fedora-40/man1/cdda2ogg.1 create mode 100644 upstream/fedora-40/man1/chattr.1 create mode 100644 upstream/fedora-40/man1/chcon.1 create mode 100644 upstream/fedora-40/man1/chgrp.1 create mode 100644 upstream/fedora-40/man1/chmod.1 create mode 100644 upstream/fedora-40/man1/chown.1 create mode 100644 upstream/fedora-40/man1/chroot.1 create mode 100644 upstream/fedora-40/man1/chvt.1 create mode 100644 upstream/fedora-40/man1/ci.1 create mode 100644 upstream/fedora-40/man1/cifsiostat.1 create mode 100644 upstream/fedora-40/man1/cistopbm.1 create mode 100644 upstream/fedora-40/man1/cksum.1 create mode 100644 upstream/fedora-40/man1/clear.1 create mode 100644 upstream/fedora-40/man1/cmp.1 create mode 100644 upstream/fedora-40/man1/cmuwmtopbm.1 create mode 100644 upstream/fedora-40/man1/co.1 create mode 100644 upstream/fedora-40/man1/comm.1 create mode 100644 upstream/fedora-40/man1/compress.1 create mode 100644 upstream/fedora-40/man1/consoletype.1 create mode 100644 upstream/fedora-40/man1/coredumpctl.1 create mode 100644 upstream/fedora-40/man1/cp.1 create mode 100644 upstream/fedora-40/man1/cpio.1 create mode 100644 upstream/fedora-40/man1/cronnext.1 create mode 100644 upstream/fedora-40/man1/crontab.1 create mode 100644 upstream/fedora-40/man1/csplit.1 create mode 100644 upstream/fedora-40/man1/csv2rec.1 create mode 100644 upstream/fedora-40/man1/cut.1 create mode 100644 upstream/fedora-40/man1/date.1 create mode 100644 upstream/fedora-40/man1/dc.1 create mode 100644 upstream/fedora-40/man1/dd.1 create mode 100644 upstream/fedora-40/man1/ddate.1 create mode 100644 upstream/fedora-40/man1/ddbugtopbm.1 create mode 100644 upstream/fedora-40/man1/deallocvt.1 create mode 100644 upstream/fedora-40/man1/debuginfo-install.1 create mode 100644 upstream/fedora-40/man1/df.1 create mode 100644 upstream/fedora-40/man1/dialog.1 create mode 100644 upstream/fedora-40/man1/diff.1 create mode 100644 upstream/fedora-40/man1/diff3.1 create mode 100644 upstream/fedora-40/man1/dir.1 create mode 100644 upstream/fedora-40/man1/dircolors.1 create mode 100644 upstream/fedora-40/man1/dirname.1 create mode 100644 upstream/fedora-40/man1/dnf-utils.1 create mode 100644 upstream/fedora-40/man1/du.1 create mode 100644 upstream/fedora-40/man1/dumpkeys.1 create mode 100644 upstream/fedora-40/man1/echo.1 create mode 100644 upstream/fedora-40/man1/ed.1 create mode 100644 upstream/fedora-40/man1/elfedit.1 create mode 100644 upstream/fedora-40/man1/env.1 create mode 100644 upstream/fedora-40/man1/epsffit.1 create mode 100644 upstream/fedora-40/man1/eqn.1 create mode 100644 upstream/fedora-40/man1/eqn2graph.1 create mode 100644 upstream/fedora-40/man1/escp2topbm.1 create mode 100644 upstream/fedora-40/man1/exif.1 create mode 100644 upstream/fedora-40/man1/expand.1 create mode 100644 upstream/fedora-40/man1/expr.1 create mode 100644 upstream/fedora-40/man1/extractres.1 create mode 100644 upstream/fedora-40/man1/eyuvtoppm.1 create mode 100644 upstream/fedora-40/man1/factor.1 create mode 100644 upstream/fedora-40/man1/false.1 create mode 100644 upstream/fedora-40/man1/faxformat.1 create mode 100644 upstream/fedora-40/man1/fgconsole.1 create mode 100644 upstream/fedora-40/man1/fiascotopnm.1 create mode 100644 upstream/fedora-40/man1/file.1 create mode 100644 upstream/fedora-40/man1/find.1 create mode 100644 upstream/fedora-40/man1/finger.1 create mode 100644 upstream/fedora-40/man1/fitstopnm.1 create mode 100644 upstream/fedora-40/man1/flex.1 create mode 100644 upstream/fedora-40/man1/fmt.1 create mode 100644 upstream/fedora-40/man1/fold.1 create mode 100644 upstream/fedora-40/man1/formail.1 create mode 100644 upstream/fedora-40/man1/fstopgm.1 create mode 100644 upstream/fedora-40/man1/funzip.1 create mode 100644 upstream/fedora-40/man1/fuse2fs.1 create mode 100644 upstream/fedora-40/man1/g3topbm.1 create mode 100644 upstream/fedora-40/man1/gawk.1 create mode 100644 upstream/fedora-40/man1/gawkbug.1 create mode 100644 upstream/fedora-40/man1/gcore.1 create mode 100644 upstream/fedora-40/man1/gdiffmk.1 create mode 100644 upstream/fedora-40/man1/gemtopbm.1 create mode 100644 upstream/fedora-40/man1/gemtopnm.1 create mode 100644 upstream/fedora-40/man1/genhostid.1 create mode 100644 upstream/fedora-40/man1/genisoimage.1 create mode 100644 upstream/fedora-40/man1/getent.1 create mode 100644 upstream/fedora-40/man1/gettext.1 create mode 100644 upstream/fedora-40/man1/gettextize.1 create mode 100644 upstream/fedora-40/man1/giftopnm.1 create mode 100644 upstream/fedora-40/man1/gnumeric.1 create mode 100644 upstream/fedora-40/man1/gouldtoppm.1 create mode 100644 upstream/fedora-40/man1/gpm-root.1 create mode 100644 upstream/fedora-40/man1/gprof.1 create mode 100644 upstream/fedora-40/man1/grap2graph.1 create mode 100644 upstream/fedora-40/man1/grep.1 create mode 100644 upstream/fedora-40/man1/grn.1 create mode 100644 upstream/fedora-40/man1/grodvi.1 create mode 100644 upstream/fedora-40/man1/groff.1 create mode 100644 upstream/fedora-40/man1/grohtml.1 create mode 100644 upstream/fedora-40/man1/grolbp.1 create mode 100644 upstream/fedora-40/man1/grolj4.1 create mode 100644 upstream/fedora-40/man1/grops.1 create mode 100644 upstream/fedora-40/man1/grotty.1 create mode 100644 upstream/fedora-40/man1/groups.1 create mode 100644 upstream/fedora-40/man1/grub2-editenv.1 create mode 100644 upstream/fedora-40/man1/grub2-emu.1 create mode 100644 upstream/fedora-40/man1/grub2-file.1 create mode 100644 upstream/fedora-40/man1/grub2-fstest.1 create mode 100644 upstream/fedora-40/man1/grub2-kbdcomp.1 create mode 100644 upstream/fedora-40/man1/grub2-menulst2cfg.1 create mode 100644 upstream/fedora-40/man1/grub2-mkfont.1 create mode 100644 upstream/fedora-40/man1/grub2-mkimage.1 create mode 100644 upstream/fedora-40/man1/grub2-mklayout.1 create mode 100644 upstream/fedora-40/man1/grub2-mknetdir.1 create mode 100644 upstream/fedora-40/man1/grub2-mkpasswd-pbkdf2.1 create mode 100644 upstream/fedora-40/man1/grub2-mkrelpath.1 create mode 100644 upstream/fedora-40/man1/grub2-mkrescue.1 create mode 100644 upstream/fedora-40/man1/grub2-mkstandalone.1 create mode 100644 upstream/fedora-40/man1/grub2-mount.1 create mode 100644 upstream/fedora-40/man1/grub2-script-check.1 create mode 100644 upstream/fedora-40/man1/grub2-set-bootflag.1 create mode 100644 upstream/fedora-40/man1/grub2-syslinux2cfg.1 create mode 100644 upstream/fedora-40/man1/gs.1 create mode 100644 upstream/fedora-40/man1/gsnd.1 create mode 100644 upstream/fedora-40/man1/gstack.1 create mode 100644 upstream/fedora-40/man1/gzexe.1 create mode 100644 upstream/fedora-40/man1/gzip.1 create mode 100644 upstream/fedora-40/man1/hdifftopam.1 create mode 100644 upstream/fedora-40/man1/head.1 create mode 100644 upstream/fedora-40/man1/hipstopgm.1 create mode 100644 upstream/fedora-40/man1/homectl.1 create mode 100644 upstream/fedora-40/man1/hostid.1 create mode 100644 upstream/fedora-40/man1/hostname.1 create mode 100644 upstream/fedora-40/man1/hostnamectl.1 create mode 100644 upstream/fedora-40/man1/hpftodit.1 create mode 100644 upstream/fedora-40/man1/icedax.1 create mode 100644 upstream/fedora-40/man1/icehelp.1 create mode 100644 upstream/fedora-40/man1/icesh.1 create mode 100644 upstream/fedora-40/man1/icesound.1 create mode 100644 upstream/fedora-40/man1/icewm-menu-fdo.1 create mode 100644 upstream/fedora-40/man1/icewm-menu-xrandr.1 create mode 100644 upstream/fedora-40/man1/icewm-session.1 create mode 100644 upstream/fedora-40/man1/icewm-set-gnomewm.1 create mode 100644 upstream/fedora-40/man1/icewm.1 create mode 100644 upstream/fedora-40/man1/icewmbg.1 create mode 100644 upstream/fedora-40/man1/icewmhint.1 create mode 100644 upstream/fedora-40/man1/icontopbm.1 create mode 100644 upstream/fedora-40/man1/iconv.1 create mode 100644 upstream/fedora-40/man1/id.1 create mode 100644 upstream/fedora-40/man1/ident.1 create mode 100644 upstream/fedora-40/man1/ifnames.1 create mode 100644 upstream/fedora-40/man1/ilbmtoppm.1 create mode 100644 upstream/fedora-40/man1/imgtoppm.1 create mode 100644 upstream/fedora-40/man1/includeres.1 create mode 100644 upstream/fedora-40/man1/indent.1 create mode 100644 upstream/fedora-40/man1/indxbib.1 create mode 100644 upstream/fedora-40/man1/info.1 create mode 100644 upstream/fedora-40/man1/infocmp.1m create mode 100644 upstream/fedora-40/man1/infotocap.1m create mode 100644 upstream/fedora-40/man1/infotopam.1 create mode 100644 upstream/fedora-40/man1/install-info.1 create mode 100644 upstream/fedora-40/man1/install.1 create mode 100644 upstream/fedora-40/man1/intro.1 create mode 100644 upstream/fedora-40/man1/iostat.1 create mode 100644 upstream/fedora-40/man1/isodebug.1 create mode 100644 upstream/fedora-40/man1/isoinfo.1 create mode 100644 upstream/fedora-40/man1/jbigtopnm.1 create mode 100644 upstream/fedora-40/man1/jed.1 create mode 100644 upstream/fedora-40/man1/joe.1 create mode 100644 upstream/fedora-40/man1/join.1 create mode 100644 upstream/fedora-40/man1/journalctl.1 create mode 100644 upstream/fedora-40/man1/jpeg2ktopam.1 create mode 100644 upstream/fedora-40/man1/jpegtopnm.1 create mode 100644 upstream/fedora-40/man1/kbd_mode.1 create mode 100644 upstream/fedora-40/man1/kbdinfo.1 create mode 100644 upstream/fedora-40/man1/lastcomm.1 create mode 100644 upstream/fedora-40/man1/ld.1 create mode 100644 upstream/fedora-40/man1/ldd.1 create mode 100644 upstream/fedora-40/man1/leaftoppm.1 create mode 100644 upstream/fedora-40/man1/less.1 create mode 100644 upstream/fedora-40/man1/lessecho.1 create mode 100644 upstream/fedora-40/man1/lesskey.1 create mode 100644 upstream/fedora-40/man1/link.1 create mode 100644 upstream/fedora-40/man1/linuxdoc.1 create mode 100644 upstream/fedora-40/man1/lispmtopgm.1 create mode 100644 upstream/fedora-40/man1/list_audio_tracks.1 create mode 100644 upstream/fedora-40/man1/lkbib.1 create mode 100644 upstream/fedora-40/man1/ln.1 create mode 100644 upstream/fedora-40/man1/loadkeys.1 create mode 100644 upstream/fedora-40/man1/locale.1 create mode 100644 upstream/fedora-40/man1/localectl.1 create mode 100644 upstream/fedora-40/man1/localedef.1 create mode 100644 upstream/fedora-40/man1/locate.1 create mode 100644 upstream/fedora-40/man1/lockfile.1 create mode 100644 upstream/fedora-40/man1/loginctl.1 create mode 100644 upstream/fedora-40/man1/logname.1 create mode 100644 upstream/fedora-40/man1/lookbib.1 create mode 100644 upstream/fedora-40/man1/ls.1 create mode 100644 upstream/fedora-40/man1/lsattr.1 create mode 100644 upstream/fedora-40/man1/lynx.1 create mode 100644 upstream/fedora-40/man1/lz4.1 create mode 100644 upstream/fedora-40/man1/machinectl.1 create mode 100644 upstream/fedora-40/man1/macptopbm.1 create mode 100644 upstream/fedora-40/man1/mailq.sendmail.1 create mode 100644 upstream/fedora-40/man1/mailstat.1 create mode 100644 upstream/fedora-40/man1/make.1 create mode 100644 upstream/fedora-40/man1/makeinfo.1 create mode 100644 upstream/fedora-40/man1/makepkg-template.1 create mode 100644 upstream/fedora-40/man1/manweb.1 create mode 100644 upstream/fedora-40/man1/mattrib.1 create mode 100644 upstream/fedora-40/man1/mbadblocks.1 create mode 100644 upstream/fedora-40/man1/mcat.1 create mode 100644 upstream/fedora-40/man1/mcd.1 create mode 100644 upstream/fedora-40/man1/mcopy.1 create mode 100644 upstream/fedora-40/man1/md5sum.1 create mode 100644 upstream/fedora-40/man1/mdatopbm.1 create mode 100644 upstream/fedora-40/man1/mdb2rec.1 create mode 100644 upstream/fedora-40/man1/mdel.1 create mode 100644 upstream/fedora-40/man1/mdeltree.1 create mode 100644 upstream/fedora-40/man1/mdiff.1 create mode 100644 upstream/fedora-40/man1/mdir.1 create mode 100644 upstream/fedora-40/man1/mdu.1 create mode 100644 upstream/fedora-40/man1/memusage.1 create mode 100644 upstream/fedora-40/man1/memusagestat.1 create mode 100644 upstream/fedora-40/man1/merge.1 create mode 100644 upstream/fedora-40/man1/mev.1 create mode 100644 upstream/fedora-40/man1/mformat.1 create mode 100644 upstream/fedora-40/man1/mgrtopbm.1 create mode 100644 upstream/fedora-40/man1/minfo.1 create mode 100644 upstream/fedora-40/man1/mkdir.1 create mode 100644 upstream/fedora-40/man1/mkfifo.1 create mode 100644 upstream/fedora-40/man1/mkmanifest.1 create mode 100644 upstream/fedora-40/man1/mknod.1 create mode 100644 upstream/fedora-40/man1/mkosi.1 create mode 100644 upstream/fedora-40/man1/mktemp.1 create mode 100644 upstream/fedora-40/man1/mlabel.1 create mode 100644 upstream/fedora-40/man1/mmd.1 create mode 100644 upstream/fedora-40/man1/mmount.1 create mode 100644 upstream/fedora-40/man1/mmove.1 create mode 100644 upstream/fedora-40/man1/most.1 create mode 100644 upstream/fedora-40/man1/mouse-test.1 create mode 100644 upstream/fedora-40/man1/mpartition.1 create mode 100644 upstream/fedora-40/man1/mpstat.1 create mode 100644 upstream/fedora-40/man1/mrd.1 create mode 100644 upstream/fedora-40/man1/mren.1 create mode 100644 upstream/fedora-40/man1/mrf.1 create mode 100644 upstream/fedora-40/man1/mrftopbm.1 create mode 100644 upstream/fedora-40/man1/msgattrib.1 create mode 100644 upstream/fedora-40/man1/msgcat.1 create mode 100644 upstream/fedora-40/man1/msgcmp.1 create mode 100644 upstream/fedora-40/man1/msgcomm.1 create mode 100644 upstream/fedora-40/man1/msgconv.1 create mode 100644 upstream/fedora-40/man1/msgen.1 create mode 100644 upstream/fedora-40/man1/msgexec.1 create mode 100644 upstream/fedora-40/man1/msgfilter.1 create mode 100644 upstream/fedora-40/man1/msgfmt.1 create mode 100644 upstream/fedora-40/man1/msggrep.1 create mode 100644 upstream/fedora-40/man1/msginit.1 create mode 100644 upstream/fedora-40/man1/msgmerge.1 create mode 100644 upstream/fedora-40/man1/msgunfmt.1 create mode 100644 upstream/fedora-40/man1/msguniq.1 create mode 100644 upstream/fedora-40/man1/mshortname.1 create mode 100644 upstream/fedora-40/man1/mshowfat.1 create mode 100644 upstream/fedora-40/man1/mtools.1 create mode 100644 upstream/fedora-40/man1/mtoolstest.1 create mode 100644 upstream/fedora-40/man1/mtrace.1 create mode 100644 upstream/fedora-40/man1/mtvtoppm.1 create mode 100644 upstream/fedora-40/man1/mtype.1 create mode 100644 upstream/fedora-40/man1/mutt.1 create mode 100644 upstream/fedora-40/man1/mutt_pgpring.1 create mode 100644 upstream/fedora-40/man1/mv.1 create mode 100644 upstream/fedora-40/man1/mzip.1 create mode 100644 upstream/fedora-40/man1/nano.1 create mode 100644 upstream/fedora-40/man1/ncursesw6-config.1 create mode 100644 upstream/fedora-40/man1/needs-restarting.1 create mode 100644 upstream/fedora-40/man1/neotoppm.1 create mode 100644 upstream/fedora-40/man1/neqn.1 create mode 100644 upstream/fedora-40/man1/networkctl.1 create mode 100644 upstream/fedora-40/man1/newaliases.sendmail.1 create mode 100644 upstream/fedora-40/man1/ngettext.1 create mode 100644 upstream/fedora-40/man1/nice.1 create mode 100644 upstream/fedora-40/man1/nl.1 create mode 100644 upstream/fedora-40/man1/nm.1 create mode 100644 upstream/fedora-40/man1/nohup.1 create mode 100644 upstream/fedora-40/man1/nproc.1 create mode 100644 upstream/fedora-40/man1/nroff.1 create mode 100644 upstream/fedora-40/man1/numfmt.1 create mode 100644 upstream/fedora-40/man1/objcopy.1 create mode 100644 upstream/fedora-40/man1/objdump.1 create mode 100644 upstream/fedora-40/man1/od.1 create mode 100644 upstream/fedora-40/man1/ogg123.1 create mode 100644 upstream/fedora-40/man1/oggdec.1 create mode 100644 upstream/fedora-40/man1/oggenc.1 create mode 100644 upstream/fedora-40/man1/ogginfo.1 create mode 100644 upstream/fedora-40/man1/oomctl.1 create mode 100644 upstream/fedora-40/man1/openvt.1 create mode 100644 upstream/fedora-40/man1/package-cleanup.1 create mode 100644 upstream/fedora-40/man1/palmtopnm.1 create mode 100644 upstream/fedora-40/man1/pamaddnoise.1 create mode 100644 upstream/fedora-40/man1/pamaltsat.1 create mode 100644 upstream/fedora-40/man1/pamarith.1 create mode 100644 upstream/fedora-40/man1/pambackground.1 create mode 100644 upstream/fedora-40/man1/pambayer.1 create mode 100644 upstream/fedora-40/man1/pambrighten.1 create mode 100644 upstream/fedora-40/man1/pamcat.1 create mode 100644 upstream/fedora-40/man1/pamchannel.1 create mode 100644 upstream/fedora-40/man1/pamcomp.1 create mode 100644 upstream/fedora-40/man1/pamcrater.1 create mode 100644 upstream/fedora-40/man1/pamcut.1 create mode 100644 upstream/fedora-40/man1/pamdeinterlace.1 create mode 100644 upstream/fedora-40/man1/pamdepth.1 create mode 100644 upstream/fedora-40/man1/pamdice.1 create mode 100644 upstream/fedora-40/man1/pamditherbw.1 create mode 100644 upstream/fedora-40/man1/pamedge.1 create mode 100644 upstream/fedora-40/man1/pamendian.1 create mode 100644 upstream/fedora-40/man1/pamenlarge.1 create mode 100644 upstream/fedora-40/man1/pamexec.1 create mode 100644 upstream/fedora-40/man1/pamfile.1 create mode 100644 upstream/fedora-40/man1/pamfind.1 create mode 100644 upstream/fedora-40/man1/pamfix.1 create mode 100644 upstream/fedora-40/man1/pamfixtrunc.1 create mode 100644 upstream/fedora-40/man1/pamflip.1 create mode 100644 upstream/fedora-40/man1/pamfunc.1 create mode 100644 upstream/fedora-40/man1/pamgauss.1 create mode 100644 upstream/fedora-40/man1/pamgetcolor.1 create mode 100644 upstream/fedora-40/man1/pamgradient.1 create mode 100644 upstream/fedora-40/man1/pamhomography.1 create mode 100644 upstream/fedora-40/man1/pamhue.1 create mode 100644 upstream/fedora-40/man1/pamlevels.1 create mode 100644 upstream/fedora-40/man1/pamlookup.1 create mode 100644 upstream/fedora-40/man1/pammasksharpen.1 create mode 100644 upstream/fedora-40/man1/pammixinterlace.1 create mode 100644 upstream/fedora-40/man1/pammixmulti.1 create mode 100644 upstream/fedora-40/man1/pammosaicknit.1 create mode 100644 upstream/fedora-40/man1/pamoil.1 create mode 100644 upstream/fedora-40/man1/pampaintspill.1 create mode 100644 upstream/fedora-40/man1/pamperspective.1 create mode 100644 upstream/fedora-40/man1/pampick.1 create mode 100644 upstream/fedora-40/man1/pampop9.1 create mode 100644 upstream/fedora-40/man1/pamrecolor.1 create mode 100644 upstream/fedora-40/man1/pamrestack.1 create mode 100644 upstream/fedora-40/man1/pamrgbatopng.1 create mode 100644 upstream/fedora-40/man1/pamrubber.1 create mode 100644 upstream/fedora-40/man1/pamscale.1 create mode 100644 upstream/fedora-40/man1/pamseq.1 create mode 100644 upstream/fedora-40/man1/pamshadedrelief.1 create mode 100644 upstream/fedora-40/man1/pamsharpmap.1 create mode 100644 upstream/fedora-40/man1/pamsharpness.1 create mode 100644 upstream/fedora-40/man1/pamshuffle.1 create mode 100644 upstream/fedora-40/man1/pamsistoaglyph.1 create mode 100644 upstream/fedora-40/man1/pamslice.1 create mode 100644 upstream/fedora-40/man1/pamsplit.1 create mode 100644 upstream/fedora-40/man1/pamstack.1 create mode 100644 upstream/fedora-40/man1/pamstereogram.1 create mode 100644 upstream/fedora-40/man1/pamstretch-gen.1 create mode 100644 upstream/fedora-40/man1/pamstretch.1 create mode 100644 upstream/fedora-40/man1/pamsumm.1 create mode 100644 upstream/fedora-40/man1/pamsummcol.1 create mode 100644 upstream/fedora-40/man1/pamtable.1 create mode 100644 upstream/fedora-40/man1/pamthreshold.1 create mode 100644 upstream/fedora-40/man1/pamtilt.1 create mode 100644 upstream/fedora-40/man1/pamtoavs.1 create mode 100644 upstream/fedora-40/man1/pamtodjvurle.1 create mode 100644 upstream/fedora-40/man1/pamtofits.1 create mode 100644 upstream/fedora-40/man1/pamtogif.1 create mode 100644 upstream/fedora-40/man1/pamtohdiff.1 create mode 100644 upstream/fedora-40/man1/pamtohtmltbl.1 create mode 100644 upstream/fedora-40/man1/pamtojpeg2k.1 create mode 100644 upstream/fedora-40/man1/pamtompfont.1 create mode 100644 upstream/fedora-40/man1/pamtooctaveimg.1 create mode 100644 upstream/fedora-40/man1/pamtopam.1 create mode 100644 upstream/fedora-40/man1/pamtopdbimg.1 create mode 100644 upstream/fedora-40/man1/pamtopfm.1 create mode 100644 upstream/fedora-40/man1/pamtopng.1 create mode 100644 upstream/fedora-40/man1/pamtopnm.1 create mode 100644 upstream/fedora-40/man1/pamtoqoi.1 create mode 100644 upstream/fedora-40/man1/pamtosrf.1 create mode 100644 upstream/fedora-40/man1/pamtosvg.1 create mode 100644 upstream/fedora-40/man1/pamtotga.1 create mode 100644 upstream/fedora-40/man1/pamtotiff.1 create mode 100644 upstream/fedora-40/man1/pamtouil.1 create mode 100644 upstream/fedora-40/man1/pamtowinicon.1 create mode 100644 upstream/fedora-40/man1/pamtoxvmini.1 create mode 100644 upstream/fedora-40/man1/pamtris.1 create mode 100644 upstream/fedora-40/man1/pamundice.1 create mode 100644 upstream/fedora-40/man1/pamunlookup.1 create mode 100644 upstream/fedora-40/man1/pamvalidate.1 create mode 100644 upstream/fedora-40/man1/pamwipeout.1 create mode 100644 upstream/fedora-40/man1/pamx.1 create mode 100644 upstream/fedora-40/man1/paste.1 create mode 100644 upstream/fedora-40/man1/pathchk.1 create mode 100644 upstream/fedora-40/man1/pbmclean.1 create mode 100644 upstream/fedora-40/man1/pbmlife.1 create mode 100644 upstream/fedora-40/man1/pbmmake.1 create mode 100644 upstream/fedora-40/man1/pbmmask.1 create mode 100644 upstream/fedora-40/man1/pbmminkowski.1 create mode 100644 upstream/fedora-40/man1/pbmnoise.1 create mode 100644 upstream/fedora-40/man1/pbmpage.1 create mode 100644 upstream/fedora-40/man1/pbmpscale.1 create mode 100644 upstream/fedora-40/man1/pbmreduce.1 create mode 100644 upstream/fedora-40/man1/pbmtext.1 create mode 100644 upstream/fedora-40/man1/pbmtextps.1 create mode 100644 upstream/fedora-40/man1/pbmto10x.1 create mode 100644 upstream/fedora-40/man1/pbmto4425.1 create mode 100644 upstream/fedora-40/man1/pbmtoascii.1 create mode 100644 upstream/fedora-40/man1/pbmtoatk.1 create mode 100644 upstream/fedora-40/man1/pbmtobbnbg.1 create mode 100644 upstream/fedora-40/man1/pbmtocis.1 create mode 100644 upstream/fedora-40/man1/pbmtocmuwm.1 create mode 100644 upstream/fedora-40/man1/pbmtodjvurle.1 create mode 100644 upstream/fedora-40/man1/pbmtoepsi.1 create mode 100644 upstream/fedora-40/man1/pbmtoepson.1 create mode 100644 upstream/fedora-40/man1/pbmtoescp2.1 create mode 100644 upstream/fedora-40/man1/pbmtog3.1 create mode 100644 upstream/fedora-40/man1/pbmtogem.1 create mode 100644 upstream/fedora-40/man1/pbmtogo.1 create mode 100644 upstream/fedora-40/man1/pbmtoibm23xx.1 create mode 100644 upstream/fedora-40/man1/pbmtoicon.1 create mode 100644 upstream/fedora-40/man1/pbmtolj.1 create mode 100644 upstream/fedora-40/man1/pbmtoln03.1 create mode 100644 upstream/fedora-40/man1/pbmtolps.1 create mode 100644 upstream/fedora-40/man1/pbmtomacp.1 create mode 100644 upstream/fedora-40/man1/pbmtomatrixorbital.1 create mode 100644 upstream/fedora-40/man1/pbmtomda.1 create mode 100644 upstream/fedora-40/man1/pbmtomgr.1 create mode 100644 upstream/fedora-40/man1/pbmtomrf.1 create mode 100644 upstream/fedora-40/man1/pbmtonokia.1 create mode 100644 upstream/fedora-40/man1/pbmtopgm.1 create mode 100644 upstream/fedora-40/man1/pbmtopi3.1 create mode 100644 upstream/fedora-40/man1/pbmtopk.1 create mode 100644 upstream/fedora-40/man1/pbmtoplot.1 create mode 100644 upstream/fedora-40/man1/pbmtoppa.1 create mode 100644 upstream/fedora-40/man1/pbmtopsg3.1 create mode 100644 upstream/fedora-40/man1/pbmtoptx.1 create mode 100644 upstream/fedora-40/man1/pbmtosunicon.1 create mode 100644 upstream/fedora-40/man1/pbmtowbmp.1 create mode 100644 upstream/fedora-40/man1/pbmtox10bm.1 create mode 100644 upstream/fedora-40/man1/pbmtoxbm.1 create mode 100644 upstream/fedora-40/man1/pbmtoybm.1 create mode 100644 upstream/fedora-40/man1/pbmtozinc.1 create mode 100644 upstream/fedora-40/man1/pbmupc.1 create mode 100644 upstream/fedora-40/man1/pc1toppm.1 create mode 100644 upstream/fedora-40/man1/pcdindex.1 create mode 100644 upstream/fedora-40/man1/pcdovtoppm.1 create mode 100644 upstream/fedora-40/man1/pcxtoppm.1 create mode 100644 upstream/fedora-40/man1/pdbimgtopam.1 create mode 100644 upstream/fedora-40/man1/pdf2dsc.1 create mode 100644 upstream/fedora-40/man1/pdf2ps.1 create mode 100644 upstream/fedora-40/man1/pdfroff.1 create mode 100644 upstream/fedora-40/man1/perl.1 create mode 100644 upstream/fedora-40/man1/perl5004delta.1 create mode 100644 upstream/fedora-40/man1/perl5005delta.1 create mode 100644 upstream/fedora-40/man1/perl5100delta.1 create mode 100644 upstream/fedora-40/man1/perl5101delta.1 create mode 100644 upstream/fedora-40/man1/perl5120delta.1 create mode 100644 upstream/fedora-40/man1/perl5121delta.1 create mode 100644 upstream/fedora-40/man1/perl5122delta.1 create mode 100644 upstream/fedora-40/man1/perl5123delta.1 create mode 100644 upstream/fedora-40/man1/perl5124delta.1 create mode 100644 upstream/fedora-40/man1/perl5125delta.1 create mode 100644 upstream/fedora-40/man1/perl5140delta.1 create mode 100644 upstream/fedora-40/man1/perl5141delta.1 create mode 100644 upstream/fedora-40/man1/perl5142delta.1 create mode 100644 upstream/fedora-40/man1/perl5143delta.1 create mode 100644 upstream/fedora-40/man1/perl5144delta.1 create mode 100644 upstream/fedora-40/man1/perl5160delta.1 create mode 100644 upstream/fedora-40/man1/perl5161delta.1 create mode 100644 upstream/fedora-40/man1/perl5162delta.1 create mode 100644 upstream/fedora-40/man1/perl5163delta.1 create mode 100644 upstream/fedora-40/man1/perl5180delta.1 create mode 100644 upstream/fedora-40/man1/perl5181delta.1 create mode 100644 upstream/fedora-40/man1/perl5182delta.1 create mode 100644 upstream/fedora-40/man1/perl5184delta.1 create mode 100644 upstream/fedora-40/man1/perl5200delta.1 create mode 100644 upstream/fedora-40/man1/perl5201delta.1 create mode 100644 upstream/fedora-40/man1/perl5202delta.1 create mode 100644 upstream/fedora-40/man1/perl5203delta.1 create mode 100644 upstream/fedora-40/man1/perl5220delta.1 create mode 100644 upstream/fedora-40/man1/perl5221delta.1 create mode 100644 upstream/fedora-40/man1/perl5222delta.1 create mode 100644 upstream/fedora-40/man1/perl5223delta.1 create mode 100644 upstream/fedora-40/man1/perl5224delta.1 create mode 100644 upstream/fedora-40/man1/perl5240delta.1 create mode 100644 upstream/fedora-40/man1/perl5241delta.1 create mode 100644 upstream/fedora-40/man1/perl5242delta.1 create mode 100644 upstream/fedora-40/man1/perl5243delta.1 create mode 100644 upstream/fedora-40/man1/perl5244delta.1 create mode 100644 upstream/fedora-40/man1/perl5260delta.1 create mode 100644 upstream/fedora-40/man1/perl5261delta.1 create mode 100644 upstream/fedora-40/man1/perl5262delta.1 create mode 100644 upstream/fedora-40/man1/perl5263delta.1 create mode 100644 upstream/fedora-40/man1/perl5280delta.1 create mode 100644 upstream/fedora-40/man1/perl5281delta.1 create mode 100644 upstream/fedora-40/man1/perl5282delta.1 create mode 100644 upstream/fedora-40/man1/perl5283delta.1 create mode 100644 upstream/fedora-40/man1/perl5300delta.1 create mode 100644 upstream/fedora-40/man1/perl5301delta.1 create mode 100644 upstream/fedora-40/man1/perl5302delta.1 create mode 100644 upstream/fedora-40/man1/perl5303delta.1 create mode 100644 upstream/fedora-40/man1/perl5320delta.1 create mode 100644 upstream/fedora-40/man1/perl5321delta.1 create mode 100644 upstream/fedora-40/man1/perl5340delta.1 create mode 100644 upstream/fedora-40/man1/perl5341delta.1 create mode 100644 upstream/fedora-40/man1/perl5342delta.1 create mode 100644 upstream/fedora-40/man1/perl5343delta.1 create mode 100644 upstream/fedora-40/man1/perl5360delta.1 create mode 100644 upstream/fedora-40/man1/perl5361delta.1 create mode 100644 upstream/fedora-40/man1/perl5362delta.1 create mode 100644 upstream/fedora-40/man1/perl5363delta.1 create mode 100644 upstream/fedora-40/man1/perl5380delta.1 create mode 100644 upstream/fedora-40/man1/perl5381delta.1 create mode 100644 upstream/fedora-40/man1/perl5382delta.1 create mode 100644 upstream/fedora-40/man1/perl561delta.1 create mode 100644 upstream/fedora-40/man1/perl56delta.1 create mode 100644 upstream/fedora-40/man1/perl581delta.1 create mode 100644 upstream/fedora-40/man1/perl582delta.1 create mode 100644 upstream/fedora-40/man1/perl583delta.1 create mode 100644 upstream/fedora-40/man1/perl584delta.1 create mode 100644 upstream/fedora-40/man1/perl585delta.1 create mode 100644 upstream/fedora-40/man1/perl586delta.1 create mode 100644 upstream/fedora-40/man1/perl587delta.1 create mode 100644 upstream/fedora-40/man1/perl588delta.1 create mode 100644 upstream/fedora-40/man1/perl589delta.1 create mode 100644 upstream/fedora-40/man1/perl58delta.1 create mode 100644 upstream/fedora-40/man1/perlaix.1 create mode 100644 upstream/fedora-40/man1/perlamiga.1 create mode 100644 upstream/fedora-40/man1/perlandroid.1 create mode 100644 upstream/fedora-40/man1/perlapi.1 create mode 100644 upstream/fedora-40/man1/perlapio.1 create mode 100644 upstream/fedora-40/man1/perlartistic.1 create mode 100644 upstream/fedora-40/man1/perlbook.1 create mode 100644 upstream/fedora-40/man1/perlboot.1 create mode 100644 upstream/fedora-40/man1/perlbot.1 create mode 100644 upstream/fedora-40/man1/perlbs2000.1 create mode 100644 upstream/fedora-40/man1/perlcall.1 create mode 100644 upstream/fedora-40/man1/perlcheat.1 create mode 100644 upstream/fedora-40/man1/perlclass.1 create mode 100644 upstream/fedora-40/man1/perlclassguts.1 create mode 100644 upstream/fedora-40/man1/perlclib.1 create mode 100644 upstream/fedora-40/man1/perlcn.1 create mode 100644 upstream/fedora-40/man1/perlcommunity.1 create mode 100644 upstream/fedora-40/man1/perlcygwin.1 create mode 100644 upstream/fedora-40/man1/perldata.1 create mode 100644 upstream/fedora-40/man1/perldbmfilter.1 create mode 100644 upstream/fedora-40/man1/perldebguts.1 create mode 100644 upstream/fedora-40/man1/perldebtut.1 create mode 100644 upstream/fedora-40/man1/perldelta.1 create mode 100644 upstream/fedora-40/man1/perldeprecation.1 create mode 100644 upstream/fedora-40/man1/perldocstyle.1 create mode 100644 upstream/fedora-40/man1/perldsc.1 create mode 100644 upstream/fedora-40/man1/perldtrace.1 create mode 100644 upstream/fedora-40/man1/perlebcdic.1 create mode 100644 upstream/fedora-40/man1/perlembed.1 create mode 100644 upstream/fedora-40/man1/perlexperiment.1 create mode 100644 upstream/fedora-40/man1/perlfork.1 create mode 100644 upstream/fedora-40/man1/perlform.1 create mode 100644 upstream/fedora-40/man1/perlfreebsd.1 create mode 100644 upstream/fedora-40/man1/perlfunc.1 create mode 100644 upstream/fedora-40/man1/perlgit.1 create mode 100644 upstream/fedora-40/man1/perlgov.1 create mode 100644 upstream/fedora-40/man1/perlgpl.1 create mode 100644 upstream/fedora-40/man1/perlguts.1 create mode 100644 upstream/fedora-40/man1/perlhack.1 create mode 100644 upstream/fedora-40/man1/perlhacktips.1 create mode 100644 upstream/fedora-40/man1/perlhacktut.1 create mode 100644 upstream/fedora-40/man1/perlhaiku.1 create mode 100644 upstream/fedora-40/man1/perlhist.1 create mode 100644 upstream/fedora-40/man1/perlhpux.1 create mode 100644 upstream/fedora-40/man1/perlhurd.1 create mode 100644 upstream/fedora-40/man1/perlintern.1 create mode 100644 upstream/fedora-40/man1/perlinterp.1 create mode 100644 upstream/fedora-40/man1/perlintro.1 create mode 100644 upstream/fedora-40/man1/perliol.1 create mode 100644 upstream/fedora-40/man1/perlipc.1 create mode 100644 upstream/fedora-40/man1/perlirix.1 create mode 100644 upstream/fedora-40/man1/perljp.1 create mode 100644 upstream/fedora-40/man1/perlko.1 create mode 100644 upstream/fedora-40/man1/perllexwarn.1 create mode 100644 upstream/fedora-40/man1/perllinux.1 create mode 100644 upstream/fedora-40/man1/perllocale.1 create mode 100644 upstream/fedora-40/man1/perllol.1 create mode 100644 upstream/fedora-40/man1/perlmacosx.1 create mode 100644 upstream/fedora-40/man1/perlmod.1 create mode 100644 upstream/fedora-40/man1/perlmodinstall.1 create mode 100644 upstream/fedora-40/man1/perlmodlib.1 create mode 100644 upstream/fedora-40/man1/perlmodstyle.1 create mode 100644 upstream/fedora-40/man1/perlmroapi.1 create mode 100644 upstream/fedora-40/man1/perlnewmod.1 create mode 100644 upstream/fedora-40/man1/perlnumber.1 create mode 100644 upstream/fedora-40/man1/perlobj.1 create mode 100644 upstream/fedora-40/man1/perlootut.1 create mode 100644 upstream/fedora-40/man1/perlop.1 create mode 100644 upstream/fedora-40/man1/perlopenbsd.1 create mode 100644 upstream/fedora-40/man1/perlopentut.1 create mode 100644 upstream/fedora-40/man1/perlos2.1 create mode 100644 upstream/fedora-40/man1/perlos390.1 create mode 100644 upstream/fedora-40/man1/perlos400.1 create mode 100644 upstream/fedora-40/man1/perlpacktut.1 create mode 100644 upstream/fedora-40/man1/perlperf.1 create mode 100644 upstream/fedora-40/man1/perlplan9.1 create mode 100644 upstream/fedora-40/man1/perlpod.1 create mode 100644 upstream/fedora-40/man1/perlpodspec.1 create mode 100644 upstream/fedora-40/man1/perlpolicy.1 create mode 100644 upstream/fedora-40/man1/perlport.1 create mode 100644 upstream/fedora-40/man1/perlpragma.1 create mode 100644 upstream/fedora-40/man1/perlqnx.1 create mode 100644 upstream/fedora-40/man1/perlre.1 create mode 100644 upstream/fedora-40/man1/perlreapi.1 create mode 100644 upstream/fedora-40/man1/perlrebackslash.1 create mode 100644 upstream/fedora-40/man1/perlrecharclass.1 create mode 100644 upstream/fedora-40/man1/perlref.1 create mode 100644 upstream/fedora-40/man1/perlreftut.1 create mode 100644 upstream/fedora-40/man1/perlreguts.1 create mode 100644 upstream/fedora-40/man1/perlrepository.1 create mode 100644 upstream/fedora-40/man1/perlrequick.1 create mode 100644 upstream/fedora-40/man1/perlreref.1 create mode 100644 upstream/fedora-40/man1/perlretut.1 create mode 100644 upstream/fedora-40/man1/perlriscos.1 create mode 100644 upstream/fedora-40/man1/perlrun.1 create mode 100644 upstream/fedora-40/man1/perlsec.1 create mode 100644 upstream/fedora-40/man1/perlsecpolicy.1 create mode 100644 upstream/fedora-40/man1/perlsolaris.1 create mode 100644 upstream/fedora-40/man1/perlsource.1 create mode 100644 upstream/fedora-40/man1/perlstyle.1 create mode 100644 upstream/fedora-40/man1/perlsub.1 create mode 100644 upstream/fedora-40/man1/perlsyn.1 create mode 100644 upstream/fedora-40/man1/perlsynology.1 create mode 100644 upstream/fedora-40/man1/perlthrtut.1 create mode 100644 upstream/fedora-40/man1/perltie.1 create mode 100644 upstream/fedora-40/man1/perltoc.1 create mode 100644 upstream/fedora-40/man1/perltodo.1 create mode 100644 upstream/fedora-40/man1/perltooc.1 create mode 100644 upstream/fedora-40/man1/perltoot.1 create mode 100644 upstream/fedora-40/man1/perltrap.1 create mode 100644 upstream/fedora-40/man1/perltru64.1 create mode 100644 upstream/fedora-40/man1/perltw.1 create mode 100644 upstream/fedora-40/man1/perlunicode.1 create mode 100644 upstream/fedora-40/man1/perlunicook.1 create mode 100644 upstream/fedora-40/man1/perlunifaq.1 create mode 100644 upstream/fedora-40/man1/perluniintro.1 create mode 100644 upstream/fedora-40/man1/perluniprops.1 create mode 100644 upstream/fedora-40/man1/perlunitut.1 create mode 100644 upstream/fedora-40/man1/perlvar.1 create mode 100644 upstream/fedora-40/man1/perlvms.1 create mode 100644 upstream/fedora-40/man1/perlvos.1 create mode 100644 upstream/fedora-40/man1/perlwin32.1 create mode 100644 upstream/fedora-40/man1/pfbtops.1 create mode 100644 upstream/fedora-40/man1/pfmtopam.1 create mode 100644 upstream/fedora-40/man1/pgmabel.1 create mode 100644 upstream/fedora-40/man1/pgmbentley.1 create mode 100644 upstream/fedora-40/man1/pgmcrater.1 create mode 100644 upstream/fedora-40/man1/pgmdeshadow.1 create mode 100644 upstream/fedora-40/man1/pgmedge.1 create mode 100644 upstream/fedora-40/man1/pgmenhance.1 create mode 100644 upstream/fedora-40/man1/pgmhist.1 create mode 100644 upstream/fedora-40/man1/pgmkernel.1 create mode 100644 upstream/fedora-40/man1/pgmmake.1 create mode 100644 upstream/fedora-40/man1/pgmmedian.1 create mode 100644 upstream/fedora-40/man1/pgmminkowski.1 create mode 100644 upstream/fedora-40/man1/pgmmorphconv.1 create mode 100644 upstream/fedora-40/man1/pgmnoise.1 create mode 100644 upstream/fedora-40/man1/pgmnorm.1 create mode 100644 upstream/fedora-40/man1/pgmoil.1 create mode 100644 upstream/fedora-40/man1/pgmramp.1 create mode 100644 upstream/fedora-40/man1/pgmslice.1 create mode 100644 upstream/fedora-40/man1/pgmtexture.1 create mode 100644 upstream/fedora-40/man1/pgmtofs.1 create mode 100644 upstream/fedora-40/man1/pgmtolispm.1 create mode 100644 upstream/fedora-40/man1/pgmtopbm.1 create mode 100644 upstream/fedora-40/man1/pgmtopgm.1 create mode 100644 upstream/fedora-40/man1/pgmtoppm.1 create mode 100644 upstream/fedora-40/man1/pgmtosbig.1 create mode 100644 upstream/fedora-40/man1/pgmtost4.1 create mode 100644 upstream/fedora-40/man1/pgpewrap.1 create mode 100644 upstream/fedora-40/man1/pi1toppm.1 create mode 100644 upstream/fedora-40/man1/pi3topbm.1 create mode 100644 upstream/fedora-40/man1/pic.1 create mode 100644 upstream/fedora-40/man1/pic2graph.1 create mode 100644 upstream/fedora-40/man1/pico.1 create mode 100644 upstream/fedora-40/man1/pidstat.1 create mode 100644 upstream/fedora-40/man1/pilot.1 create mode 100644 upstream/fedora-40/man1/pinky.1 create mode 100644 upstream/fedora-40/man1/pitchplay.1 create mode 100644 upstream/fedora-40/man1/pjtoppm.1 create mode 100644 upstream/fedora-40/man1/pktopbm.1 create mode 100644 upstream/fedora-40/man1/pldd.1 create mode 100644 upstream/fedora-40/man1/pm-gawk.1 create mode 100644 upstream/fedora-40/man1/pngtopam.1 create mode 100644 upstream/fedora-40/man1/pngtopnm.1 create mode 100644 upstream/fedora-40/man1/pnmalias.1 create mode 100644 upstream/fedora-40/man1/pnmarith.1 create mode 100644 upstream/fedora-40/man1/pnmcat.1 create mode 100644 upstream/fedora-40/man1/pnmcolormap.1 create mode 100644 upstream/fedora-40/man1/pnmcomp.1 create mode 100644 upstream/fedora-40/man1/pnmconvol.1 create mode 100644 upstream/fedora-40/man1/pnmcrop.1 create mode 100644 upstream/fedora-40/man1/pnmcut.1 create mode 100644 upstream/fedora-40/man1/pnmdepth.1 create mode 100644 upstream/fedora-40/man1/pnmenlarge.1 create mode 100644 upstream/fedora-40/man1/pnmfile.1 create mode 100644 upstream/fedora-40/man1/pnmflip.1 create mode 100644 upstream/fedora-40/man1/pnmgamma.1 create mode 100644 upstream/fedora-40/man1/pnmhisteq.1 create mode 100644 upstream/fedora-40/man1/pnmhistmap.1 create mode 100644 upstream/fedora-40/man1/pnmindex.1 create mode 100644 upstream/fedora-40/man1/pnminterp.1 create mode 100644 upstream/fedora-40/man1/pnminvert.1 create mode 100644 upstream/fedora-40/man1/pnmmargin.1 create mode 100644 upstream/fedora-40/man1/pnmmercator.1 create mode 100644 upstream/fedora-40/man1/pnmmontage.1 create mode 100644 upstream/fedora-40/man1/pnmnlfilt.1 create mode 100644 upstream/fedora-40/man1/pnmnoraw.1 create mode 100644 upstream/fedora-40/man1/pnmnorm.1 create mode 100644 upstream/fedora-40/man1/pnmpad.1 create mode 100644 upstream/fedora-40/man1/pnmpaste.1 create mode 100644 upstream/fedora-40/man1/pnmpsnr.1 create mode 100644 upstream/fedora-40/man1/pnmquant.1 create mode 100644 upstream/fedora-40/man1/pnmquantall.1 create mode 100644 upstream/fedora-40/man1/pnmremap.1 create mode 100644 upstream/fedora-40/man1/pnmrotate.1 create mode 100644 upstream/fedora-40/man1/pnmscale.1 create mode 100644 upstream/fedora-40/man1/pnmscalefixed.1 create mode 100644 upstream/fedora-40/man1/pnmshear.1 create mode 100644 upstream/fedora-40/man1/pnmsmooth.1 create mode 100644 upstream/fedora-40/man1/pnmsplit.1 create mode 100644 upstream/fedora-40/man1/pnmstitch.1 create mode 100644 upstream/fedora-40/man1/pnmtile.1 create mode 100644 upstream/fedora-40/man1/pnmtoddif.1 create mode 100644 upstream/fedora-40/man1/pnmtofiasco.1 create mode 100644 upstream/fedora-40/man1/pnmtofits.1 create mode 100644 upstream/fedora-40/man1/pnmtojbig.1 create mode 100644 upstream/fedora-40/man1/pnmtojpeg.1 create mode 100644 upstream/fedora-40/man1/pnmtopalm.1 create mode 100644 upstream/fedora-40/man1/pnmtopclxl.1 create mode 100644 upstream/fedora-40/man1/pnmtoplainpnm.1 create mode 100644 upstream/fedora-40/man1/pnmtopng.1 create mode 100644 upstream/fedora-40/man1/pnmtopnm.1 create mode 100644 upstream/fedora-40/man1/pnmtops.1 create mode 100644 upstream/fedora-40/man1/pnmtorast.1 create mode 100644 upstream/fedora-40/man1/pnmtorle.1 create mode 100644 upstream/fedora-40/man1/pnmtosgi.1 create mode 100644 upstream/fedora-40/man1/pnmtosir.1 create mode 100644 upstream/fedora-40/man1/pnmtotiff.1 create mode 100644 upstream/fedora-40/man1/pnmtotiffcmyk.1 create mode 100644 upstream/fedora-40/man1/pnmtoxwd.1 create mode 100644 upstream/fedora-40/man1/pod2texi.1 create mode 100644 upstream/fedora-40/man1/portablectl.1 create mode 100644 upstream/fedora-40/man1/ppm3d.1 create mode 100644 upstream/fedora-40/man1/ppmbrighten.1 create mode 100644 upstream/fedora-40/man1/ppmchange.1 create mode 100644 upstream/fedora-40/man1/ppmcie.1 create mode 100644 upstream/fedora-40/man1/ppmcolormask.1 create mode 100644 upstream/fedora-40/man1/ppmcolors.1 create mode 100644 upstream/fedora-40/man1/ppmdcfont.1 create mode 100644 upstream/fedora-40/man1/ppmddumpfont.1 create mode 100644 upstream/fedora-40/man1/ppmdim.1 create mode 100644 upstream/fedora-40/man1/ppmdist.1 create mode 100644 upstream/fedora-40/man1/ppmdither.1 create mode 100644 upstream/fedora-40/man1/ppmdmkfont.1 create mode 100644 upstream/fedora-40/man1/ppmdraw.1 create mode 100644 upstream/fedora-40/man1/ppmfade.1 create mode 100644 upstream/fedora-40/man1/ppmflash.1 create mode 100644 upstream/fedora-40/man1/ppmforge.1 create mode 100644 upstream/fedora-40/man1/ppmglobe.1 create mode 100644 upstream/fedora-40/man1/ppmhist.1 create mode 100644 upstream/fedora-40/man1/ppmlabel.1 create mode 100644 upstream/fedora-40/man1/ppmmake.1 create mode 100644 upstream/fedora-40/man1/ppmmix.1 create mode 100644 upstream/fedora-40/man1/ppmnorm.1 create mode 100644 upstream/fedora-40/man1/ppmntsc.1 create mode 100644 upstream/fedora-40/man1/ppmpat.1 create mode 100644 upstream/fedora-40/man1/ppmquant.1 create mode 100644 upstream/fedora-40/man1/ppmquantall.1 create mode 100644 upstream/fedora-40/man1/ppmrainbow.1 create mode 100644 upstream/fedora-40/man1/ppmrelief.1 create mode 100644 upstream/fedora-40/man1/ppmrough.1 create mode 100644 upstream/fedora-40/man1/ppmshadow.1 create mode 100644 upstream/fedora-40/man1/ppmshift.1 create mode 100644 upstream/fedora-40/man1/ppmspread.1 create mode 100644 upstream/fedora-40/man1/ppmtoacad.1 create mode 100644 upstream/fedora-40/man1/ppmtoapplevol.1 create mode 100644 upstream/fedora-40/man1/ppmtoarbtxt.1 create mode 100644 upstream/fedora-40/man1/ppmtoascii.1 create mode 100644 upstream/fedora-40/man1/ppmtobmp.1 create mode 100644 upstream/fedora-40/man1/ppmtoeyuv.1 create mode 100644 upstream/fedora-40/man1/ppmtogif.1 create mode 100644 upstream/fedora-40/man1/ppmtoicr.1 create mode 100644 upstream/fedora-40/man1/ppmtoilbm.1 create mode 100644 upstream/fedora-40/man1/ppmtojpeg.1 create mode 100644 upstream/fedora-40/man1/ppmtoleaf.1 create mode 100644 upstream/fedora-40/man1/ppmtolj.1 create mode 100644 upstream/fedora-40/man1/ppmtomap.1 create mode 100644 upstream/fedora-40/man1/ppmtomitsu.1 create mode 100644 upstream/fedora-40/man1/ppmtompeg.1 create mode 100644 upstream/fedora-40/man1/ppmtoneo.1 create mode 100644 upstream/fedora-40/man1/ppmtopcx.1 create mode 100644 upstream/fedora-40/man1/ppmtopgm.1 create mode 100644 upstream/fedora-40/man1/ppmtopi1.1 create mode 100644 upstream/fedora-40/man1/ppmtopict.1 create mode 100644 upstream/fedora-40/man1/ppmtopj.1 create mode 100644 upstream/fedora-40/man1/ppmtopjxl.1 create mode 100644 upstream/fedora-40/man1/ppmtoppm.1 create mode 100644 upstream/fedora-40/man1/ppmtopuzz.1 create mode 100644 upstream/fedora-40/man1/ppmtorgb3.1 create mode 100644 upstream/fedora-40/man1/ppmtosixel.1 create mode 100644 upstream/fedora-40/man1/ppmtospu.1 create mode 100644 upstream/fedora-40/man1/ppmtoterm.1 create mode 100644 upstream/fedora-40/man1/ppmtouil.1 create mode 100644 upstream/fedora-40/man1/ppmtowinicon.1 create mode 100644 upstream/fedora-40/man1/ppmtoxpm.1 create mode 100644 upstream/fedora-40/man1/ppmtoyuv.1 create mode 100644 upstream/fedora-40/man1/ppmtoyuvsplit.1 create mode 100644 upstream/fedora-40/man1/ppmtv.1 create mode 100644 upstream/fedora-40/man1/ppmwheel.1 create mode 100644 upstream/fedora-40/man1/pr.1 create mode 100644 upstream/fedora-40/man1/preconv.1 create mode 100644 upstream/fedora-40/man1/printenv.1 create mode 100644 upstream/fedora-40/man1/printf.1 create mode 100644 upstream/fedora-40/man1/procmail.1 create mode 100644 upstream/fedora-40/man1/ps2ascii.1 create mode 100644 upstream/fedora-40/man1/ps2epsi.1 create mode 100644 upstream/fedora-40/man1/ps2pdf.1 create mode 100644 upstream/fedora-40/man1/ps2pdfwr.1 create mode 100644 upstream/fedora-40/man1/ps2ps.1 create mode 100644 upstream/fedora-40/man1/psbook.1 create mode 100644 upstream/fedora-40/man1/psc.1 create mode 100644 upstream/fedora-40/man1/psfaddtable.1 create mode 100644 upstream/fedora-40/man1/psfgettable.1 create mode 100644 upstream/fedora-40/man1/psfstriptable.1 create mode 100644 upstream/fedora-40/man1/psfxtable.1 create mode 100644 upstream/fedora-40/man1/psidtopgm.1 create mode 100644 upstream/fedora-40/man1/psjoin.1 create mode 100644 upstream/fedora-40/man1/psnup.1 create mode 100644 upstream/fedora-40/man1/psresize.1 create mode 100644 upstream/fedora-40/man1/psselect.1 create mode 100644 upstream/fedora-40/man1/pstopnm.1 create mode 100644 upstream/fedora-40/man1/pstops.1 create mode 100644 upstream/fedora-40/man1/psutils.1 create mode 100644 upstream/fedora-40/man1/ptx.1 create mode 100644 upstream/fedora-40/man1/pwd.1 create mode 100644 upstream/fedora-40/man1/python3.12.1 create mode 100644 upstream/fedora-40/man1/pzstd.1 create mode 100644 upstream/fedora-40/man1/qoitopam.1 create mode 100644 upstream/fedora-40/man1/qrttoppm.1 create mode 100644 upstream/fedora-40/man1/quota.1 create mode 100644 upstream/fedora-40/man1/quotasync.1 create mode 100644 upstream/fedora-40/man1/ranlib.1 create mode 100644 upstream/fedora-40/man1/rasttopnm.1 create mode 100644 upstream/fedora-40/man1/rawtopgm.1 create mode 100644 upstream/fedora-40/man1/rawtoppm.1 create mode 100644 upstream/fedora-40/man1/rcs.1 create mode 100644 upstream/fedora-40/man1/rcsclean.1 create mode 100644 upstream/fedora-40/man1/rcsdiff.1 create mode 100644 upstream/fedora-40/man1/rcsmerge.1 create mode 100644 upstream/fedora-40/man1/readelf.1 create mode 100644 upstream/fedora-40/man1/readlink.1 create mode 100644 upstream/fedora-40/man1/readmult.1 create mode 100644 upstream/fedora-40/man1/realpath.1 create mode 100644 upstream/fedora-40/man1/rec2csv.1 create mode 100644 upstream/fedora-40/man1/recdel.1 create mode 100644 upstream/fedora-40/man1/recfix.1 create mode 100644 upstream/fedora-40/man1/recfmt.1 create mode 100644 upstream/fedora-40/man1/recinf.1 create mode 100644 upstream/fedora-40/man1/recins.1 create mode 100644 upstream/fedora-40/man1/recode-sr-latin.1 create mode 100644 upstream/fedora-40/man1/recsel.1 create mode 100644 upstream/fedora-40/man1/recset.1 create mode 100644 upstream/fedora-40/man1/refer.1 create mode 100644 upstream/fedora-40/man1/repo-graph.1 create mode 100644 upstream/fedora-40/man1/repoclosure.1 create mode 100644 upstream/fedora-40/man1/repodiff.1 create mode 100644 upstream/fedora-40/man1/repomanage.1 create mode 100644 upstream/fedora-40/man1/reposync.1 create mode 100644 upstream/fedora-40/man1/resolvectl.1 create mode 100644 upstream/fedora-40/man1/rgb3toppm.1 create mode 100644 upstream/fedora-40/man1/rlatopam.1 create mode 100644 upstream/fedora-40/man1/rletopnm.1 create mode 100644 upstream/fedora-40/man1/rlog.1 create mode 100644 upstream/fedora-40/man1/rm.1 create mode 100644 upstream/fedora-40/man1/rmdir.1 create mode 100644 upstream/fedora-40/man1/rnano.1 create mode 100644 upstream/fedora-40/man1/rpdump.1 create mode 100644 upstream/fedora-40/man1/rpload.1 create mode 100644 upstream/fedora-40/man1/rsync-ssl.1 create mode 100644 upstream/fedora-40/man1/rsync.1 create mode 100644 upstream/fedora-40/man1/rtf2rtf.1 create mode 100644 upstream/fedora-40/man1/runcon.1 create mode 100644 upstream/fedora-40/man1/rup.1 create mode 100644 upstream/fedora-40/man1/ruptime.1 create mode 100644 upstream/fedora-40/man1/rusers.1 create mode 100644 upstream/fedora-40/man1/rwall.1 create mode 100644 upstream/fedora-40/man1/rwho.1 create mode 100644 upstream/fedora-40/man1/sadf.1 create mode 100644 upstream/fedora-40/man1/sane-find-scanner.1 create mode 100644 upstream/fedora-40/man1/sar.1 create mode 100644 upstream/fedora-40/man1/sbattach.1 create mode 100644 upstream/fedora-40/man1/sbigtopgm.1 create mode 100644 upstream/fedora-40/man1/sbkeysync.1 create mode 100644 upstream/fedora-40/man1/sbsiglist.1 create mode 100644 upstream/fedora-40/man1/sbsign.1 create mode 100644 upstream/fedora-40/man1/sbvarsign.1 create mode 100644 upstream/fedora-40/man1/sbverify.1 create mode 100644 upstream/fedora-40/man1/sc.1 create mode 100644 upstream/fedora-40/man1/scanimage.1 create mode 100644 upstream/fedora-40/man1/scp.1 create mode 100644 upstream/fedora-40/man1/sdiff.1 create mode 100644 upstream/fedora-40/man1/sed.1 create mode 100644 upstream/fedora-40/man1/seq.1 create mode 100644 upstream/fedora-40/man1/setleds.1 create mode 100644 upstream/fedora-40/man1/setmetamode.1 create mode 100644 upstream/fedora-40/man1/sftp.1 create mode 100644 upstream/fedora-40/man1/sgitopnm.1 create mode 100644 upstream/fedora-40/man1/sgml2html.1 create mode 100644 upstream/fedora-40/man1/sgml2info.1 create mode 100644 upstream/fedora-40/man1/sgml2latex.1 create mode 100644 upstream/fedora-40/man1/sgml2lyx.1 create mode 100644 upstream/fedora-40/man1/sgml2rtf.1 create mode 100644 upstream/fedora-40/man1/sgml2txt.1 create mode 100644 upstream/fedora-40/man1/sgmlcheck.1 create mode 100644 upstream/fedora-40/man1/sgmlpre.1 create mode 100644 upstream/fedora-40/man1/sgmlsasp.1 create mode 100644 upstream/fedora-40/man1/sha1sum.1 create mode 100644 upstream/fedora-40/man1/sha224sum.1 create mode 100644 upstream/fedora-40/man1/sha256sum.1 create mode 100644 upstream/fedora-40/man1/sha384sum.1 create mode 100644 upstream/fedora-40/man1/sha512sum.1 create mode 100644 upstream/fedora-40/man1/shar.1 create mode 100644 upstream/fedora-40/man1/showkey.1 create mode 100644 upstream/fedora-40/man1/showrgb.1 create mode 100644 upstream/fedora-40/man1/shred.1 create mode 100644 upstream/fedora-40/man1/shuf.1 create mode 100644 upstream/fedora-40/man1/sirtopnm.1 create mode 100644 upstream/fedora-40/man1/size.1 create mode 100644 upstream/fedora-40/man1/sldtoppm.1 create mode 100644 upstream/fedora-40/man1/sleep.1 create mode 100644 upstream/fedora-40/man1/smime_keys.1 create mode 100644 upstream/fedora-40/man1/soelim.groff.1 create mode 100644 upstream/fedora-40/man1/sort.1 create mode 100644 upstream/fedora-40/man1/spctoppm.1 create mode 100644 upstream/fedora-40/man1/split.1 create mode 100644 upstream/fedora-40/man1/spottopgm.1 create mode 100644 upstream/fedora-40/man1/sprof.1 create mode 100644 upstream/fedora-40/man1/sputoppm.1 create mode 100644 upstream/fedora-40/man1/srftopam.1 create mode 100644 upstream/fedora-40/man1/ssconvert.1 create mode 100644 upstream/fedora-40/man1/ssdiff.1 create mode 100644 upstream/fedora-40/man1/ssgrep.1 create mode 100644 upstream/fedora-40/man1/ssh-add.1 create mode 100644 upstream/fedora-40/man1/ssh-agent.1 create mode 100644 upstream/fedora-40/man1/ssh-copy-id.1 create mode 100644 upstream/fedora-40/man1/ssh-keyscan.1 create mode 100644 upstream/fedora-40/man1/ssh.1 create mode 100644 upstream/fedora-40/man1/ssindex.1 create mode 100644 upstream/fedora-40/man1/st4topgm.1 create mode 100644 upstream/fedora-40/man1/startx.1 create mode 100644 upstream/fedora-40/man1/stat.1 create mode 100644 upstream/fedora-40/man1/stdbuf.1 create mode 100644 upstream/fedora-40/man1/strfile.1 create mode 100644 upstream/fedora-40/man1/strings.1 create mode 100644 upstream/fedora-40/man1/strip.1 create mode 100644 upstream/fedora-40/man1/stty.1 create mode 100644 upstream/fedora-40/man1/sum.1 create mode 100644 upstream/fedora-40/man1/sunicontopnm.1 create mode 100644 upstream/fedora-40/man1/svgtopam.1 create mode 100644 upstream/fedora-40/man1/sync.1 create mode 100644 upstream/fedora-40/man1/systemctl.1 create mode 100644 upstream/fedora-40/man1/systemd-ac-power.1 create mode 100644 upstream/fedora-40/man1/systemd-analyze.1 create mode 100644 upstream/fedora-40/man1/systemd-ask-password.1 create mode 100644 upstream/fedora-40/man1/systemd-bootchart.1 create mode 100644 upstream/fedora-40/man1/systemd-cat.1 create mode 100644 upstream/fedora-40/man1/systemd-cgls.1 create mode 100644 upstream/fedora-40/man1/systemd-cgtop.1 create mode 100644 upstream/fedora-40/man1/systemd-creds.1 create mode 100644 upstream/fedora-40/man1/systemd-cryptenroll.1 create mode 100644 upstream/fedora-40/man1/systemd-delta.1 create mode 100644 upstream/fedora-40/man1/systemd-detect-virt.1 create mode 100644 upstream/fedora-40/man1/systemd-dissect.1 create mode 100644 upstream/fedora-40/man1/systemd-escape.1 create mode 100644 upstream/fedora-40/man1/systemd-firstboot.1 create mode 100644 upstream/fedora-40/man1/systemd-id128.1 create mode 100644 upstream/fedora-40/man1/systemd-inhibit.1 create mode 100644 upstream/fedora-40/man1/systemd-machine-id-setup.1 create mode 100644 upstream/fedora-40/man1/systemd-measure.1 create mode 100644 upstream/fedora-40/man1/systemd-mount.1 create mode 100644 upstream/fedora-40/man1/systemd-notify.1 create mode 100644 upstream/fedora-40/man1/systemd-nspawn.1 create mode 100644 upstream/fedora-40/man1/systemd-path.1 create mode 100644 upstream/fedora-40/man1/systemd-run.1 create mode 100644 upstream/fedora-40/man1/systemd-socket-activate.1 create mode 100644 upstream/fedora-40/man1/systemd-stdio-bridge.1 create mode 100644 upstream/fedora-40/man1/systemd-swap.1 create mode 100644 upstream/fedora-40/man1/systemd-tty-ask-password-agent.1 create mode 100644 upstream/fedora-40/man1/systemd-vmspawn.1 create mode 100644 upstream/fedora-40/man1/systemd.1 create mode 100644 upstream/fedora-40/man1/tabs.1 create mode 100644 upstream/fedora-40/man1/tac.1 create mode 100644 upstream/fedora-40/man1/tail.1 create mode 100644 upstream/fedora-40/man1/talk.1 create mode 100644 upstream/fedora-40/man1/tapestat.1 create mode 100644 upstream/fedora-40/man1/tar.1 create mode 100644 upstream/fedora-40/man1/tbl.1 create mode 100644 upstream/fedora-40/man1/tee.1 create mode 100644 upstream/fedora-40/man1/telnet.1 create mode 100644 upstream/fedora-40/man1/test.1 create mode 100644 upstream/fedora-40/man1/texi2dvi.1 create mode 100644 upstream/fedora-40/man1/texindex.1 create mode 100644 upstream/fedora-40/man1/tfmtodit.1 create mode 100644 upstream/fedora-40/man1/tgatoppm.1 create mode 100644 upstream/fedora-40/man1/thinkfan.1 create mode 100644 upstream/fedora-40/man1/thinkjettopbm.1 create mode 100644 upstream/fedora-40/man1/tic.1m create mode 100644 upstream/fedora-40/man1/tifftopnm.1 create mode 100644 upstream/fedora-40/man1/time.1 create mode 100644 upstream/fedora-40/man1/timedatectl.1 create mode 100644 upstream/fedora-40/man1/timeout.1 create mode 100644 upstream/fedora-40/man1/toe.1m create mode 100644 upstream/fedora-40/man1/touch.1 create mode 100644 upstream/fedora-40/man1/tput.1 create mode 100644 upstream/fedora-40/man1/tr.1 create mode 100644 upstream/fedora-40/man1/tree.1 create mode 100644 upstream/fedora-40/man1/troff.1 create mode 100644 upstream/fedora-40/man1/true.1 create mode 100644 upstream/fedora-40/man1/truncate.1 create mode 100644 upstream/fedora-40/man1/tset.1 create mode 100644 upstream/fedora-40/man1/tsort.1 create mode 100644 upstream/fedora-40/man1/tty.1 create mode 100644 upstream/fedora-40/man1/ukify.1 create mode 100644 upstream/fedora-40/man1/uname.1 create mode 100644 upstream/fedora-40/man1/unexpand.1 create mode 100644 upstream/fedora-40/man1/unicode_start.1 create mode 100644 upstream/fedora-40/man1/unicode_stop.1 create mode 100644 upstream/fedora-40/man1/unify.1 create mode 100644 upstream/fedora-40/man1/uniq.1 create mode 100644 upstream/fedora-40/man1/unlink.1 create mode 100644 upstream/fedora-40/man1/unshar.1 create mode 100644 upstream/fedora-40/man1/unzip.1 create mode 100644 upstream/fedora-40/man1/unzipsfx.1 create mode 100644 upstream/fedora-40/man1/usb-devices.1 create mode 100644 upstream/fedora-40/man1/userdbctl.1 create mode 100644 upstream/fedora-40/man1/users.1 create mode 100644 upstream/fedora-40/man1/usleep.1 create mode 100644 upstream/fedora-40/man1/uucp.1 create mode 100644 upstream/fedora-40/man1/uudecode.1 create mode 100644 upstream/fedora-40/man1/uuencode.1 create mode 100644 upstream/fedora-40/man1/uuname.1 create mode 100644 upstream/fedora-40/man1/uustat.1 create mode 100644 upstream/fedora-40/man1/uux.1 create mode 100644 upstream/fedora-40/man1/varlinkctl.1 create mode 100644 upstream/fedora-40/man1/vcut.1 create mode 100644 upstream/fedora-40/man1/vdir.1 create mode 100644 upstream/fedora-40/man1/vlock.1 create mode 100644 upstream/fedora-40/man1/vorbiscomment.1 create mode 100644 upstream/fedora-40/man1/wbmptopbm.1 create mode 100644 upstream/fedora-40/man1/wc.1 create mode 100644 upstream/fedora-40/man1/wdiff.1 create mode 100644 upstream/fedora-40/man1/wdiff2.1 create mode 100644 upstream/fedora-40/man1/wget2.1 create mode 100644 upstream/fedora-40/man1/which.1 create mode 100644 upstream/fedora-40/man1/who.1 create mode 100644 upstream/fedora-40/man1/whoami.1 create mode 100644 upstream/fedora-40/man1/whois.md.1 create mode 100644 upstream/fedora-40/man1/winicon.1 create mode 100644 upstream/fedora-40/man1/winicontopam.1 create mode 100644 upstream/fedora-40/man1/winicontoppm.1 create mode 100644 upstream/fedora-40/man1/xargs.1 create mode 100644 upstream/fedora-40/man1/xbmtopbm.1 create mode 100644 upstream/fedora-40/man1/xgettext.1 create mode 100644 upstream/fedora-40/man1/ximtoppm.1 create mode 100644 upstream/fedora-40/man1/xinit.1 create mode 100644 upstream/fedora-40/man1/xload.1 create mode 100644 upstream/fedora-40/man1/xpmtoppm.1 create mode 100644 upstream/fedora-40/man1/xvidtune.1 create mode 100644 upstream/fedora-40/man1/xvminitoppm.1 create mode 100644 upstream/fedora-40/man1/xwdtopnm.1 create mode 100644 upstream/fedora-40/man1/ybmtopbm.1 create mode 100644 upstream/fedora-40/man1/yes.1 create mode 100644 upstream/fedora-40/man1/yum-builddep.1 create mode 100644 upstream/fedora-40/man1/yum-changelog.1 create mode 100644 upstream/fedora-40/man1/yum-config-manager.1 create mode 100644 upstream/fedora-40/man1/yum-debug-dump.1 create mode 100644 upstream/fedora-40/man1/yum-debug-restore.1 create mode 100644 upstream/fedora-40/man1/yum-groups-manager.1 create mode 100644 upstream/fedora-40/man1/yum-utils.1 create mode 100644 upstream/fedora-40/man1/yumdownloader.1 create mode 100644 upstream/fedora-40/man1/yuvsplittoppm.1 create mode 100644 upstream/fedora-40/man1/yuvtoppm.1 create mode 100644 upstream/fedora-40/man1/yuy2topam.1 create mode 100644 upstream/fedora-40/man1/zdiff.1 create mode 100644 upstream/fedora-40/man1/zeisstopnm.1 create mode 100644 upstream/fedora-40/man1/zforce.1 create mode 100644 upstream/fedora-40/man1/zgrep.1 create mode 100644 upstream/fedora-40/man1/zipinfo.1 create mode 100644 upstream/fedora-40/man1/zless.1 create mode 100644 upstream/fedora-40/man1/zmore.1 create mode 100644 upstream/fedora-40/man1/znew.1 create mode 100644 upstream/fedora-40/man1/zstd.1 create mode 100644 upstream/fedora-40/man1/zstdgrep.1 create mode 100644 upstream/fedora-40/man1/zstdless.1 (limited to 'upstream/fedora-40/man1') diff --git a/upstream/fedora-40/man1/411toppm.1 b/upstream/fedora-40/man1/411toppm.1 new file mode 100644 index 00000000..ed1d5533 --- /dev/null +++ b/upstream/fedora-40/man1/411toppm.1 @@ -0,0 +1,71 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "411toppm User Manual" 0 "03 March 2001" "netpbm documentation" + +.SH NAME +411toppm - convert Sony Mavica .411 image to PPM + +.UN synopsis +.SH SYNOPSIS + +\fB411toppm\fP +[\fB-width \fP\fIwidth\fP] +[\fB-height \fP\fIheight\fP] +[\fI411file\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP + \fB411toppm\fP reads a .411 file, such as from a Sony Mavic +camera, and converts it to a PPM image as output. +.PP +Output is to Standard Output. +.PP +The originator of this program and decipherer of the .411 format, +Steve Allen +<\fIsla@alumni.caltech.edu\fP>, +has this to say about the +utility of this program: "There's so little image in a 64x48 thumbnail +(especially when you have the full size JPG file) that the only point +in doing this was to answer the implicit challenge posed by the manual +stating that only the camera can use these files." + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fB411toppm\fP recognizes the following +command line options: +.PP +All options may be abbreviated to the shortest unique prefix. + + +.TP +\fB-width\fP +The width (number of columns) of the input image. Default is 64. +.TP +\fB-height\fP +The height (number of rows) of the input image. Default is 48. + + +.UN seealso +.SH SEE ALSO +.BR "ppm" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/411toppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/AusweisApp.1 b/upstream/fedora-40/man1/AusweisApp.1 new file mode 100644 index 00000000..b3e585f9 --- /dev/null +++ b/upstream/fedora-40/man1/AusweisApp.1 @@ -0,0 +1,130 @@ +.TH AusweisApp 1 +.SH NAME +AusweisApp \- Official authentication app for German ID cards and residence permits +.SH SYNOPSIS + +AusweisApp [-h|--help] +.br +AusweisApp [--help-all] +.br +AusweisApp [-v|--version] +.br +AusweisApp [--show] +.br +AusweisApp +[--keep] +[--no-logfile] +[--no-loghandler] +[--show] +[--no-proxy] +[--ui { qml|websocket }] +[--port \fI\,PORT\/\fR] +[--address \fI\,ADDRESS\/\fR] + +.SH DESCRIPTION +AusweisApp allows you to authenticate yourself against websites via your German +ID card and residence permits. + +You will need: +.br +* an ID card that is enabled for online identification +.br +* A compatible NFC device (most NFC readers should work, NFC-enabled phones can +* also be used) +.br +* AusweisApp +.br +* A browser +.br +* A website that supports authentication via German ID card + +When you visit such a website, AusweisApp will be triggered and will ask you if +you want to authenticate against the website. + +This program will provide a local webserver for your browser to interface against. + +.SH OPTIONS + +.TP +.B -h, --help +Displays a short help message. + +.TP +.B --help-all +Displays help including Qt specific options. + +.TP +.B -v, --version +Displays version information. + +.TP +.B --keep +.br +By default, AusweisApp writes a log to a file matching +${TMP}/AusweisApp.*.log. When the program terminates, it will be deleted. This +setting prevents deletion. + +.TP +.B --no-logfile +Suppress writing a log file to ${TMP}/AusweisApp.*.log. Logs will still be +written to STDOUT. + +.TP +.B --no-loghandler +Disable default log handler. This disables logging to STDOUT. + +.TP +.B --show +Show window on startup. + +.TP +.B --no-proxy +Disable system proxy. + +.TP +.B --ui { qml|webservice|websocket } +This option allows multiple values. +- "qml" will start the program with a visible UI. +- "websocket" will let it start in the background as an SDK. This is only useful when integrating +AusweisApp into other programs. +- "webservice" starts listening on given port/address. + +Default is "qml,webservice,websocket". + +.TP +.B --port \fI\,PORT\/\fR +Change the listening port for the WebSocket. Default is 24727. Selecting "0" is +a special case. AusweisApp will then select a random port and write the port +number to a file in ${TMP}/AusweisApp..port. + +.TP +.B --address \fI\,ADDRESS\/\fR +Use given addresses for interface binding. Normally AusweisApp is bound to +localhost only as it is a security requirement. Useful for testing only. +This option allows multiple values. + +.SH "RETURN VALUE" +AusweisApp will return 0 when successfully terminated. +.SH ENVIRONMENT +.TP +.B QT_QPA_PLATFORM={ wayland|X11 } +You may force the session type to wayland or X11. This is only needed for +debugging purposes. XDG_SESSION_TYPE will be ignored on gnome. + +.SH FILES + +\fI~/.config/AusweisApp_CE/AusweisApp2.conf\fR +File path where the user config is saved. + +.SH CAVEATS +Currently there is no way to terminate the program on gnome as the TrayIcon +is mandatory. + +.SH AUTHOR +This man page was written by Lee Garrett (debian@rocketjump.eu) for Debian (but +may be used by others). + +.SH "SEE ALSO" +https://www.ausweisapp.bund.de/en +.br +https://www.ausweisapp.bund.de/sdk diff --git a/upstream/fedora-40/man1/ac.1 b/upstream/fedora-40/man1/ac.1 new file mode 100644 index 00000000..bd9a6a99 --- /dev/null +++ b/upstream/fedora-40/man1/ac.1 @@ -0,0 +1,277 @@ +.TH AC 1 "2010 August 16" +.SH NAME +ac \- print statistics about users' connect time +.SH SYNOPSIS +.hy 0 +.na +.TP +.B ac +[ +.B \-d +| +.B \-\-daily-totals +] +[ +.B \-y +| +.B \-\-print-year +] +.br +[ +.B \-p +| +.B \-\-individual-totals +] +[ +.I people +] +.br +[ +.B \-f +| +.B \-\-file +.I filename +] +[ +.B \-a +| +.B \-\-all-days +] +.br +[ +.B \-\-complain +] +[ +.B \-\-reboots +] +[ +.B \-\-supplants +] +.br +[ +.B \-\-timewarps +] +[ +.B \-\-compatibility +] +.br +[ +.B \-\-tw-leniency +.I num +] +[ +.B \-\-tw-suspicious +.I num +] +.br +[ +.B \-z +| +.B \-\-print-zeros +] +[ +.B \-\-debug +] +.br +[ +.B \-V +| +.B \-\-version +] +[ +.B \-h +| +.B \-\-help +] +.ad b +.hy 1 +.SH DESCRIPTION +.LP +.B ac +prints out a report of connect time (in hours) based on the +logins/logouts in the current +.I wtmp +file. A total is also printed out. +.LP +The accounting file +.I wtmp +is maintained by +.BR init (8) +and +.BR login (1). +Neither +.B ac +nor +.B login +creates the +.I wtmp +if it doesn't exist, no accounting is done. To begin accounting, create +the file with a length of zero. +.LP +NOTE: The +.I wtmp +file can get really big, really fast. You might want to trim it every +once and a while. +.LP +GNU +.B ac +works nearly the same UNIX +.BR ac , +though it's a little +smarter in several ways. You should therefore expect differences in +the output of GNU +.B ac +and the output of +.BR ac 's +on other systems. +Use the command +.BI info " accounting" +to get additional information. +.SH OPTIONS +.PD 0 +.TP +.B \-d, \-\-daily-totals +Print totals for each day rather than just one big total at the +end. The output looks like this: + Jul 3 total 1.17 + Jul 4 total 2.10 + Jul 5 total 8.23 + Jul 6 total 2.10 + Jul 7 total 0.30 +.TP +.B \-p, \-\-individual-totals +Print time totals for each user in addition to the usual +everything-lumped-into-one value. It looks like: + bob 8.06 + goff 0.60 + maley 7.37 + root 0.12 + total 16.15 +.TP +.I people +Print out the sum total of the connect time used by all of the +users included in +.I people. +Note that +.I people +is a space separated list of valid user names; wildcards are not allowed. +.TP +.BI "\-f, \-\-file " filename +Read from the file +.I filename +instead of the system's +.I wtmp +file. +.TP +.B \-\-complain +When the +.I wtmp +file has a problem (a time-warp, missing record, or +whatever), print out an appropriate error. +.TP +.B \-\-reboots +Reboot records are NOT written at the time of a reboot, but when +the system restarts; therefore, it is impossible to know exactly +when the reboot occurred. Users may have been logged into the +system at the time of the reboot, and many +.B ac's +automatically +count the time between the login and the reboot record +against the user (even though all of that time shouldn't be, perhaps, +if the system is down for a long time, for instance). If you want to +count this time, include the flag. +*For vanilla +.B ac +compatibility, include this flag.* +.TP +.B \-\-supplants +Sometimes, a logout record is not written for a specific terminal, +so the time that the last user accrued cannot be calculated. If +you want to include the time from the user's login to the next +login on the terminal (though probably incorrect), include this +you want to include the time from the user's login to the next +login on the terminal (though probably incorrect), include this +flag. +*For vanilla +.B ac +compatibility, include this flag.* +.TP +.B \-\-timewarps +Sometimes, entries in a +.I wtmp +file will suddenly jump back into the past without a clock change +record occurring. It is impossible to know how long a user was logged +in when this occurs. If you want to count the time between the login +and the time warp against the user, include this flag. *For vanilla +.B ac +compatibility, include this flag.* +.TP +.B \-\-compatibility +This is shorthand for typing out the three above options. +.TP +.B \-a, \-\-all-days +If we're printing daily totals, print a record for every day instead of +skipping intervening days where there is no login activity. Without +this flag, time accrued during those intervening days gets listed under +the next day where there is login activity. +.TP +.BI \-\-tw-leniency " num" +Set the time warp leniency to +.I num +seconds. Records in +.I wtmp +files might be slightly out of order (most notably when two logins +occur within a one-second period - the second one gets written first). +By default, this value is set to 60. If the program notices this +problem, time is not assigned to users unless the +.B \-\-timewarps +flag is used. +.TP +.BI \-\-tw-suspicious " num" +Set the time warp suspicious value to +.I num +seconds. If two records in the +.I wtmp +file are farther than this number of seconds apart, there is a problem +with the +.I wtmp +file (or your machine hasn't been used in a year). If the program +notices this problem, time is not assigned to users unless the +.B \-\-timewarps +flag is used. +.TP +.B \-y, \-\-print-year +Print year when displaying dates. +.TP +.B \-z, \-\-print-zeros +If a total for any category (save the grand total) is zero, print it. +The default is to suppress printing. +.TP +.B \-\-debug +Print verbose internal information. +.TP +.B \-V, \-\-version +Print the version number of +.B ac +to standard output and quit. +.TP +.B \-h, \-\-help +Prints the usage string and default locations of system files to +standard output and exits. +.SH FILES +.I wtmp +.RS +The system wide login record file. See +.BR wtmp (5) +for further details. +.LP + +.SH AUTHOR +The GNU accounting utilities were written by Noel Cragg +. The man page was adapted from the accounting +texinfo page by Susan Kleinmann . +.SH "SEE ALSO" +.BR login (1), +.BR wtmp (5), +.BR init (8), +.BR sa (8) diff --git a/upstream/fedora-40/man1/addftinfo.1 b/upstream/fedora-40/man1/addftinfo.1 new file mode 100644 index 00000000..e9f426ac --- /dev/null +++ b/upstream/fedora-40/man1/addftinfo.1 @@ -0,0 +1,236 @@ +.TH addftinfo 1 "24 January 2024" "groff 1.23.0" +.SH Name +addftinfo \- add font metrics to +.I troff +fonts for use with +.I groff +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_addftinfo_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY addftinfo +.RB [ \-asc\-height\~\c +.IR n ] +.RB [ \-body\-depth\~\c +.IR n ] +.RB [ \-body\-height\~\c +.IR n ] +.RB [ \-cap\-height\~\c +.IR n ] +.RB [ \-comma\-depth\~\c +.IR n ] +.RB [ \-desc\-depth\~\c +.IR n ] +.RB [ \-fig\-height\~\c +.IR n ] +.RB [ \-x\-height\~\c +.IR n ] +.I resolution +.I unit-width +.I font +.YS +. +. +.SY addftinfo +.B \-\-help +.YS +. +. +.SY addftinfo +.B \-v +. +.SY addftinfo +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I addftinfo +reads an +.RI AT&T \~troff +font description file +.IR font , +adds additional font metric information required by +.\" We need the "GNU" below because the \% prefix might be empty. +.RI GNU \~\%troff (1), +and writes the combined result to the standard output. +. +The information added is derived from the font's existing parameters and +assumptions about traditional +.I troff +names for characters. +. +Among the font metrics added are the heights and depths of characters +(how far each extends vertically above and below the baseline). +. +The +.I resolution +and +.I unit-width +arguments should be the same as the corresponding parameters in the +.I DESC +file. +. +.I font +is the name of the file describing the font; +if +.I font +ends with +.RB \[lq] I \[rq], +the font is assumed to be oblique +(or italic). +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.P +All other options change parameters that are used to derive the heights +and depths. +. +Like the existing quantities in the font description file, +each +.RI value\~ n +is in +.I "scaled points," +.RI inches/ resolution +for a font whose type size is +.IR unit-width ; +see +.MR groff_font 5 . +. +. +.TP +.BI \-asc\-height \~n +height of characters with ascenders, +such as \[lq]b\[rq], +\[lq]d\[rq], +or \[lq]l\[rq] +. +. +.TP +.BI \-body\-depth \~n +depth of characters such as parentheses +. +. +.TP +.BI \-body\-height \~n +height of characters such as parentheses +. +. +.TP +.BI \-cap\-height \~n +height of uppercase letters such as \[lq]A\[rq] +. +. +.TP +.BI \-comma\-depth \~n +depth of a comma +. +. +.TP +.BI \-desc\-depth \~n +depth of characters with descenders, +such as \[lq]p\[rq], +\[lq]q\[rq], +or \[lq]y\[rq] +. +. +.TP +.B \-fig\-height +height of figures (numerals) +. +. +.TP +.BI \-x\-height \~n +height of lowercase letters without ascenders such as \[lq]x\[rq] +. +. +.P +.I addftinfo +makes no attempt to use the specified parameters to infer unspecified +parameters. +. +If a parameter is not specified, +the default will be used. +. +The defaults are chosen to produce reasonable values for a Times font. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR groff_font 5 , +.MR groff 1 , +.MR groff_char 7 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_addftinfo_1_man_C] +.do rr *groff_addftinfo_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/addr2line.1 b/upstream/fedora-40/man1/addr2line.1 new file mode 100644 index 00000000..7cfacaa0 --- /dev/null +++ b/upstream/fedora-40/man1/addr2line.1 @@ -0,0 +1,275 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ADDR2LINE 1" +.TH ADDR2LINE 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +addr2line \- convert addresses or symbol+offset into file names and line numbers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +addr2line [\fB\-a\fR|\fB\-\-addresses\fR] + [\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]] + [\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR] + [\fB\-R\fR|\fB\-\-recurse\-limit\fR] + [\fB\-e\fR \fIfilename\fR|\fB\-\-exe=\fR\fIfilename\fR] + [\fB\-f\fR|\fB\-\-functions\fR] [\fB\-s\fR|\fB\-\-basename\fR] + [\fB\-i\fR|\fB\-\-inlines\fR] + [\fB\-p\fR|\fB\-\-pretty\-print\fR] + [\fB\-j\fR|\fB\-\-section=\fR\fIname\fR] + [\fB\-H\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] + [addr addr ...] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBaddr2line\fR translates addresses or symbol+offset into file names and line numbers. +Given an address or symbol+offset in an executable or an offset in a section of a relocatable +object, it uses the debugging information to figure out which file name and +line number are associated with it. +.PP +The executable or relocatable object to use is specified with the \fB\-e\fR +option. The default is the file \fIa.out\fR. The section in the relocatable +object to use is specified with the \fB\-j\fR option. +.PP +\&\fBaddr2line\fR has two modes of operation. +.PP +In the first, hexadecimal addresses or symbol+offset are specified on the command line, +and \fBaddr2line\fR displays the file name and line number for each +address. +.PP +In the second, \fBaddr2line\fR reads hexadecimal addresses or symbol+offset from +standard input, and prints the file name and line number for each +address on standard output. In this mode, \fBaddr2line\fR may be used +in a pipe to convert dynamically chosen addresses. +.PP +The format of the output is \fBFILENAME:LINENO\fR. By default +each input address generates one line of output. +.PP +Two options can generate additional lines before each +\&\fBFILENAME:LINENO\fR line (in that order). +.PP +If the \fB\-a\fR option is used then a line with the input address +is displayed. +.PP +If the \fB\-f\fR option is used, then a line with the +\&\fBFUNCTIONNAME\fR is displayed. This is the name of the function +containing the address. +.PP +One option can generate additional lines after the +\&\fBFILENAME:LINENO\fR line. +.PP +If the \fB\-i\fR option is used and the code at the given address is +present there because of inlining by the compiler then additional +lines are displayed afterwards. One or two extra lines (if the +\&\fB\-f\fR option is used) are displayed for each inlined function. +.PP +Alternatively if the \fB\-p\fR option is used then each input +address generates a single, long, output line containing the address, +the function name, the file name and the line number. If the +\&\fB\-i\fR option has also been used then any inlined functions will +be displayed in the same manner, but on separate lines, and prefixed +by the text \fB(inlined by)\fR. +.PP +If the file name or function name can not be determined, +\&\fBaddr2line\fR will print two question marks in their place. If the +line number can not be determined, \fBaddr2line\fR will print 0. +.PP +When symbol+offset is used, +offset is optional, except when the symbol +is ambigious with a hex number. The resolved symbols can be mangled +or unmangled, except unmangled symbols with + are not allowed. +.SH OPTIONS +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. +.IP \fB\-a\fR 4 +.IX Item "-a" +.PD 0 +.IP \fB\-\-addresses\fR 4 +.IX Item "--addresses" +.PD +Display the address before the function name, file and line number +information. The address is printed with a \fB0x\fR prefix to easily +identify it. +.IP "\fB\-b\fR \fIbfdname\fR" 4 +.IX Item "-b bfdname" +.PD 0 +.IP \fB\-\-target=\fR\fIbfdname\fR 4 +.IX Item "--target=bfdname" +.PD +Specify that the object-code format for the object files is +\&\fIbfdname\fR. +.IP \fB\-C\fR 4 +.IX Item "-C" +.PD 0 +.IP \fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR 4 +.IX Item "--demangle[=style]" +.PD +Decode (\fIdemangle\fR) low-level symbol names into user-level names. +Besides removing any initial underscore prepended by the system, this +makes C++ function names readable. Different compilers have different +mangling styles. The optional demangling style argument can be used to +choose an appropriate demangling style for your compiler. +.IP "\fB\-e\fR \fIfilename\fR" 4 +.IX Item "-e filename" +.PD 0 +.IP \fB\-\-exe=\fR\fIfilename\fR 4 +.IX Item "--exe=filename" +.PD +Specify the name of the executable for which addresses should be +translated. The default file is \fIa.out\fR. +.IP \fB\-f\fR 4 +.IX Item "-f" +.PD 0 +.IP \fB\-\-functions\fR 4 +.IX Item "--functions" +.PD +Display function names as well as file and line number information. +.IP \fB\-s\fR 4 +.IX Item "-s" +.PD 0 +.IP \fB\-\-basenames\fR 4 +.IX Item "--basenames" +.PD +Display only the base of each file name. +.IP \fB\-i\fR 4 +.IX Item "-i" +.PD 0 +.IP \fB\-\-inlines\fR 4 +.IX Item "--inlines" +.PD +If the address belongs to a function that was inlined, the source +information for all enclosing scopes back to the first non-inlined +function will also be printed. For example, if \f(CW\*(C`main\*(C'\fR inlines +\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from +\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR +will also be printed. +.IP \fB\-j\fR 4 +.IX Item "-j" +.PD 0 +.IP \fB\-\-section\fR 4 +.IX Item "--section" +.PD +Read offsets relative to the specified section instead of absolute addresses. +.IP \fB\-p\fR 4 +.IX Item "-p" +.PD 0 +.IP \fB\-\-pretty\-print\fR 4 +.IX Item "--pretty-print" +.PD +Make the output more human friendly: each location are printed on one line. +If option \fB\-i\fR is specified, lines for all enclosing scopes are +prefixed with \fB(inlined by)\fR. +.IP \fB\-r\fR 4 +.IX Item "-r" +.PD 0 +.IP \fB\-R\fR 4 +.IX Item "-R" +.IP \fB\-\-recurse\-limit\fR 4 +.IX Item "--recurse-limit" +.IP \fB\-\-no\-recurse\-limit\fR 4 +.IX Item "--no-recurse-limit" +.IP \fB\-\-recursion\-limit\fR 4 +.IX Item "--recursion-limit" +.IP \fB\-\-no\-recursion\-limit\fR 4 +.IX Item "--no-recursion-limit" +.PD +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an infinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. +.Sp +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. +.Sp +The \fB\-r\fR option is a synonym for the +\&\fB\-\-no\-recurse\-limit\fR option. The \fB\-R\fR option is a +synonym for the \fB\-\-recurse\-limit\fR option. +.Sp +Note this option is only effective if the \fB\-C\fR or +\&\fB\-\-demangle\fR option has been enabled. +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Info entries for \fIbinutils\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/airscan-discover.1 b/upstream/fedora-40/man1/airscan-discover.1 new file mode 100644 index 00000000..3ea3beea --- /dev/null +++ b/upstream/fedora-40/man1/airscan-discover.1 @@ -0,0 +1,49 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "AIRSCAN\-DISCOVER" "1" "May 2020" "" "SANE Scanner Access Now Easy" +. +.SH "NAME" +\fBairscan\-discover\fR \- Discover sane\-airscan compatible scanners +. +.SH "SYNOPSIS" +\fBairscan\-discover [\-h] [\-d] [\-t]\fR +. +.SH "DESCRIPTION" +\fBairscan\-discover\fR is a command\-line tool to find eSCL and WSD scanners on a local network +. +.P +It uses Avahi to discover DNS\-SD devices and its own implementation of WS\-Discovery to discover WSD devices\. +. +.P +On success, it outputs a fragment of sane\-airscan configuration file, that can be directly added to \fB/etc/sane\.d/airscan\.conf\fR +. +.SH "OPTIONS" +. +.TP +\fB\-h\fR +Print help screen +. +.TP +\fB\-d\fR +Print debug messages to console +. +.TP +\fB\-t\fR +Write a very detailed protocol trace to \fBairscan\-discover\-zeroconf\.log\fR and \fBairscan\-discover\-zeroconf\.tar\fR +. +.SH "FILES" +. +.TP +\fBairscan\-discover\-zeroconf\.log\fR +Protocol trace +. +.TP +\fBairscan\-discover\-zeroconf\.tar\fR +Non\-textual messages, if any, saved here\. Textual (i\.e\., XML) messages included directly into the \.log file +. +.SH "SEE ALSO" +sane(7), sane\-airscan(5) +. +.SH "AUTHOR" +Alexander Pevzner diff --git a/upstream/fedora-40/man1/alpine.1 b/upstream/fedora-40/man1/alpine.1 new file mode 100644 index 00000000..794a238c --- /dev/null +++ b/upstream/fedora-40/man1/alpine.1 @@ -0,0 +1,398 @@ +.TH alpine 1 "Version 2.26" +.SH NAME +alpine \- an Alternatively Licensed Program for Internet News and Email +.SH SYNTAX + +.B alpine +[ +.I options +] [ +.I address +, +.I address +] + +.B alpinef +[ +.I options +] [ +.I address +, +.I address +] +.SH DESCRIPTION + +Alpine is a screen-oriented message-handling tool. In its default +configuration, Alpine offers an intentionally limited set of +functions geared toward the novice user, but it also has a large +list of optional "power-user" and personal-preference features. +.I alpinef +is a variant of Alpine that uses function keys rather than mnemonic +single-letter commands. +Alpine's basic feature set includes: +.IP +View, Save, Export, Delete, Print, Reply and Forward messages. +.IP +Compose messages in a simple editor (Pico) with word-wrap and a spelling +checker. Messages may be postponed for later completion. +.IP +Full-screen selection and management of message folders. +.IP +Address book to keep a list of long or frequently-used addresses. +Personal distribution lists may be defined. +Addresses may be taken into the address book from +incoming mail without retyping them. +.IP +New mail checking and notification occurs automatically every 2.5 minutes +and after certain commands, e.g. refresh-screen (Ctrl-L). +.IP +On-line, context-sensitive help screens. +.PP +Alpine supports MIME (Multipurpose Internet Mail Extensions), an Internet +Standard for representing multipart and multimedia data in email. +Alpine allows you to save MIME objects to files, and in some +cases, can also initiate the correct program for viewing the object. +It uses the system's +.I mailcap +configuration file to determine what program can process a particular MIME +object type. +Alpine's message composer does not have integral multimedia capability, but +any type of data file --including multimedia-- can be attached to a text +message and sent using MIME's encoding rules. This allows any group of +individuals with MIME-capable mail software (e.g. Alpine, PC-Alpine, or many +other programs) to exchange formatted documents, spread-sheets, image +files, etc, via Internet email. +.PP +Alpine uses the +.I c-client +messaging API to access local and remote mail folders. This +library provides a variety of low-level message-handling functions, +including drivers +for a variety of different mail file formats, as well as routines +to access remote mail and news servers, using IMAP (Internet Message +Access Protocol) and NNTP (Network News Transport Protocol). Outgoing mail +is usually posted directly via SMTP +(Simple Mail Transfer Protocol). +.SH OPTIONS +.if n .ta 2.8i +.if t .ta 2.1i + +The command line options/arguments are: +.IP \fIaddress\fR 20 +Send mail to +.I address. +This will cause Alpine to go directly into the message composer. +.IP \fB-attach\ \fIfile\fR 20 +Send mail with the listed +.I file +as an attachment. +.IP \fB-attachlist\ \fIfile-list\fR 20 +Send mail with the listed +.I file-list +as an attachments. +.IP \fB-attach_and_delete\ \fIfile\fR 20 +Send mail with the listed +.I file +as an attachment, and remove the file +after the message is sent. +.IP \fB-aux\ \fIlocal_directory\fR 20 +PC-Alpine only. When using a remote configuration (-p ) this tells +PC-Alpine the local directory to use for storing auxiliary files, like debug +files, address books, and signature files. +.IP \fB-bail\fR 20 +Exit if the pinerc file does not exist. This might be useful if the config +file is accessed using some remote filesystem protocol. If the remote mount +is missing this will cause Alpine to quit instead of creating a new pinerc. +.IP \fB-c\ \fIcontext-number\fR 20 +context-number is the number corresponding to the +folder-collection to which the +.I -f +command line argument should be applied. By default the +.I -f +argument is applied to the first defined folder-collection. +.IP \fB-conf\fR 20 +Produce a sample/fresh copy of the +system-wide configuration file, +.I pine.conf, +on the standard output. This is distinct from the per-user +.I .pinerc +file. +.IP \fB-convert_sigs\ \fI-p\ pinerc\fR 20 +Convert signature files into literal signatures. +.IP \fB-copy_abook\ <\fIlocal_abook\fR>\ <\fIremote_abook\fR> 20 +Copy the local address book file to a remote address book folder. +.IP \fB-copy_pinerc\ <\fIlocal_pinerc\fR>\ <\fIremote_pinerc\fR> 20 +Copy the local pinerc file to a remote pinerc folder. +.IP \fB-d\ \fIdebug-level\fR 20 +Output diagnostic info at +.I debug-level +(0-9) to the current +.I .pine-debug[1-4] +file. A value of 0 turns debugging off and suppresses the +.I .pine-debug +file. +.IP \fB-d\ \fIkey[=val]\fR 20 +Fine tuned output of diagnostic messages where "flush" causes +debug file writing without buffering, "timestamp" appends +each message with a timestamp, "imap=n" where n is between +0 and 4 representing none to verbose IMAP telemetry reporting, +"numfiles=n" where n is between 0 and 31 corresponding to the +number of debug files to maintain, and "verbose=n" where n is +between 0 and 9 indicating an inverse threshold for message +output. +.IP \fB-f\ \fIfolder\fR 20 +Open +.I folder +(in first defined folder collection, use +.I -c n +to specify another collection) instead of INBOX. +.IP \fB-F\ \fIfile\fR 20 +Open named text file and view with Alpine's browser. +.IP \fB-h\fR 20 +Help: list valid command-line options. +.IP \fB-i\fR 20 +Start up in the FOLDER INDEX screen. +.IP \fB-I\ \fIkeystrokes\fR 20 +Initial (comma separated list of) keystrokes which Alpine should execute +on startup. +.IP \fB-install\fR 20 +For PC-Alpine only, this option causes PC-Alpine to prompt for some basic +setup information, then exits. +.IP \fB-k\fR 20 +Use function keys for commands. This is the same as running the command +.IR alpinef . +.IP \fB-n\ \fInumber\fR 20 +Start up with current message-number set to +.I number. +.IP \fB-nowrite_password_cache\fR 20 +Read from a password cache if there is one, but +never offer to write a password to the cache +.IP \fB-o\fR 20 +Open first folder read-only. +.IP \fB-p\ \fIconfig-file\fR 20 +Use +.I config-file +as the personal configuration file instead of the default +.IR .pinerc . +.IP \fB-P\ \fIconfig-file\fR 20 +Use +.I config-file +as the configuration file instead of default +system-wide configuration file +.IR pine.conf . +.IP \fB-passfile\ \fI\fR 20 +When password file support is compiled in, use the file specified in +.I +instead of the default. +.IP \fB-pinerc\ \fIfile\fR 20 +Output fresh pinerc configuration to +.I file, preserving the settings of variables that the user has made. +Use \fIfile\fR set to ``-'' to make output go to standard out. +.IP \fB-pwdcertdir\ \fI\fR 20 +When SMIME and password file support are compiled in, this variable sets +the directory to store your personal key and certificate to encrypt and +decrypt your password file. +.IP \fB-r\fR 20 +Use restricted/demo mode. +.I Alpine +will only send mail to itself +and functions like save and export are restricted. +.IP \fB-registry\ \fIcmd\fR 20 +For PC-Alpine only, this option affects the values of +Alpine's registry entries. +Possible values for \fIcmd\fR are set, clear, and dump. +\fISet\fR will always reset Alpine's registry +entries according to its current settings. +\fIClear\fR will clear the registry values. +\fIClearsilent\fR will silently clear the registry values. +\fIDump\fR will display the values of current registry settings. +Note that the dump command is currently disabled. +Without the -registry option, PC-Alpine will write values into +the registry only if there currently aren't any values set. +.IP \fB-smimedir\ \fI\fR +If SMIME is compiled in, this argument sets the directory where the +public, private, and certificate authorities certificates and keys +are stored. If not set by the command line the default is +~/.alpine-smime +.IP \fB-sort\ \fIorder\fR +Sort the FOLDER INDEX display in one of the following orders: +.I arrival, date, subject, orderedsubj, thread, from, size, score, to, cc, +or +.I reverse. Arrival +order is the default. +The OrderedSubj choice simulates a threaded sort. +Any sort may be reversed by adding +.I /reverse +to it. +.I Reverse +by itself is the same as +.IR arrival/reverse . +.IP \fB-supported\fR 20 +Some options may or may not be supported depending on how Alpine +was compiled. +This is a way to determine which options are supported in the particular +copy of Alpine you are using. +.IP \fB-uninstall\fR 20 +For PC-Alpine only, this option causes PC-Alpine to remove references to +Alpine in Windows settings. +.IP \fB-url\ \fIurl\fR 20 +Open the given +.I url. +Cannot be used with +.I -f +or +.I -F +options. +.IP \fB-v\fR 20 +Version: Print version information. +.IP \fB-version\fR 20 +Version: Print version information. +.IP \fB-x\ \fIconfig\fR 20 +Use configuration exceptions in +.I config. +Exceptions are used to override your default pinerc +settings for a particular platform, can be a local file or +a remote folder. +.IP \fB-xoauth2-server\ \fIServerName\fR 20 +Name of the service that XOAUTH2 authentication will be attempted. +The only service supported as of this writing is Gmail. Note that +all of the options -xoauth2-server, -xoauth2-client-id and +-xoauth2-client-secret must be used simultaneously. Example: +-xoauth2-server Gmail. +.IP \fB-xoauth2-client-id\ \fIClient-Id\fR 20 +String that identifies Alpine with the service provider that provides +XOAUTH2 authentication. Note that +all of the options -xoauth2-server, -xoauth2-client-id and +-xoauth2-client-secret must be used simultaneously. +.IP \fB-xoauth2-client-secret\ \fIClient-Secret\fR 20 +Secret string that identifies the Alpine with +the service provider that provides XOAUTH2 authentication. +Note that +all of the options -xoauth2-server, -xoauth2-client-id and +-xoauth2-client-secret must be used simultaneously. +.IP \fB-z\fR 20 +Enable ^Z and SIGTSTP so alpine may be suspended. +.IP \fI-option\=\fIvalue\fR 20 +Assign +.I value +to the config option +.I option +e.g. -signature-file=sig1 or -feature-list=signature-at-bottom +(Note: feature-list values are additive) +.SH CONFIGURATION + +There are several levels of Alpine configuration. Configuration values at +a given level over-ride corresponding values at lower levels. In order of +increasing precedence: + + o built-in defaults. +.br + o system-wide +.I pine.conf +file. +.br + o personal +.I .pinerc +file (may be set via built-in Setup/Config menu.) +.br + o command-line options. +.br + o system-wide +.I pine.conf.fixed +file. + +There is one exception to the rule that configuration values are replaced +by the value of the same option in a higher-precedence file: the +feature-list variable has values that are additive, but can be negated by +prepending "no-" in front of an individual feature name. Unix Alpine also +uses the following environment variables: + + TERM +.br + DISPLAY (determines if Alpine can display IMAGE attachments.) +.br + SHELL (if not set, default is /bin/sh ) +.br + MAILCAPS (semicolon delimited list of path names to mailcap files) +.SH FILES +.if n .ta 2.8i +.if t .ta 2.1i + +/usr/spool/mail/xxxx Default folder for incoming mail. +.br +~/mail Default directory for mail folders. +.br +~/.addressbook Default address book file. +.br +~/.signature File used for signature, appended to every message. +.br +~/.pine-debug[1-4] Diagnostic log for debugging. +.br +~/.pinerc Personal alpine config file. +.br +~/.pine-crash Debug information useful to debug a crash. +.br +~/.newsrc News subscription/state file. +.br +~/.mailcap Personal mail capabilities file. +.br +~/.mime.types Personal file extension to MIME type mapping +.br +/etc/mailcap System-wide mail capabilities file. +.br +/etc/mime.types System-wide file ext. to MIME type mapping +.br +/usr/local/lib/pine.info Local pointer to system administrator. +.br +/usr/local/lib/pine.conf System-wide configuration file. +.br +/usr/local/lib/pine.conf.fixed Non-overridable configuration file. +.br +~/.alpine-smime/ca Directory that contains Certificate Authority files. +.br +~/.alpine-smime/private Directory that contains private key(s). +.br +~/.alpine-smime/public Directory that contains public key(s). +.br +/tmp/.\\usr\\spool\\mail\\xxxx Per-folder mailbox lock files. +.br +~/.pine-interrupted-mail Message which was interrupted. +.br +~/mail/postponed-msgs For postponed messages (drafts) +.br +~/mail/sent-mail Outgoing message archive (FCC). +.br +~/mail/saved-messages Default destination for Saving messages. +.SH "SEE ALSO" + +pico(1), binmail(1), aliases(5), mailaddr(7), sendmail(8), spell(1), imapd(8) + +.br +Newsgroup: comp.mail.pine + +.br +Mailing List: +.br +Alpine-info, at https://www.washington.edu/alpine/alpine-info/ + +.br +Main Alpine distribution site: +.br +http://repo.or.cz/alpine.git + +.br +Alpine Technical Notes, included in the source distribution. + +.br +C-Client messaging API library, included in the source distribution. +.SH ACKNOWLEDGMENTS +.na +.nf + +This software is the result of the contribution of many individuals +who have dedicated their time to support, improve and suggest ways +to improve Alpine through the years. This software would not be +possible without the support of the University of Washington in +Seattle, Washington. The Alpine community extends its most sincere +thanks to all contributors and invites everyone to join in and +contribute to this project. diff --git a/upstream/fedora-40/man1/anytopnm.1 b/upstream/fedora-40/man1/anytopnm.1 new file mode 100644 index 00000000..e588de7a --- /dev/null +++ b/upstream/fedora-40/man1/anytopnm.1 @@ -0,0 +1,100 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Anytopnm User Manual" 0 "15 November 2014" "netpbm documentation" + +.SH NAME +anytopnm - convert an arbitrary type of image file to PBM, PGM, or PPM + +.UN synopsis +.SH SYNOPSIS + +\fBanytopnm\fP [\fIfile\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBanytopnm\fP converts the input image, which may be in any of +about 100 graphics formats, to PBM, PGM, or PPM format, depending on +that nature of the input image, and outputs it to Standard Output. +.PP +To determine the format of the input, \fBanytopnm\fP uses the +\fBfile\fP program (possibly assisted by the magic numbers file +fragment included with Netpbm). If that fails (very few image formats +have magic numbers), \fBanytopnm\fP looks at the filename extension. +If that fails, \fBanytopnm\fP punts. +.PP +The type of the output file depends on the input image. +.PP +\fBanytopnm\fP uses the converters for particular graphics formats +that are in the Netpbm package, so it can't convert any format that +you couldn't convert with some other Netpbm program. What +\fBanytopnm\fP adds is the ability to recognize the format and choose +the appropriate Netpbm program to convert it. For example, if you +invoke \fBanytopnm\fP on a GIF file, \fBanytopnm\fP will recognize +that it is a GIF file and therefore \fBgiftopnm\fP knows how to +convert it to PNM, so \fBanytopnm\fP invokes \fBgiftopnm\fP. +.PP +\fBanytopnm\fP cannot recognize every possible input format, so you +may still be able to convert an image with a specific Netpbm program when +\fBanytopnm\fP fails to convert it. +.PP +If \fBfile\fP indicates that the input file is compressed (either +via Unix compress, gzip, or bzip compression), \fBanytopnm\fP +uncompresses it and proceeds as above with the uncompressed result. +.PP +If \fBfile\fP indicates that the input file is encoded by uuencode +or btoa, \fBanytopnm\fP decodes it and proceeds as above with the +decoded result. +.PP +If \fIfile\fP is \fB-\fP or not given, \fBanytopnm\fP takes its +input from Standard Input. +.PP +Many image formats are capable of representing multiple images. In +most cases, \fBanytopnm\fP converts these to multi-image Netpbm images, +but for some formats, \fBanytopnm\fP converts only the first image and +ignores the rest. +.PP +In the case of a multi-image GIF input, \fBanytopnm\fP converts all the +images starting with Netpbm 10.69 (December 2014), but only the first in +earlier releases. + + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBanytopnm\fP. + +\fBanytopnm\fP does not recognize the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) However, the \fB-version\fP option works. + +.UN seealso +.SH SEE ALSO +.BR "pamfile" (1)\c +\&, +.BR "pnm" (1)\c +\&, +\fBfile\fP man page + +.UN author +.SH AUTHOR + +Copyright (C) 1991 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/anytopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/ar.1 b/upstream/fedora-40/man1/ar.1 new file mode 100644 index 00000000..7830327c --- /dev/null +++ b/upstream/fedora-40/man1/ar.1 @@ -0,0 +1,460 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "AR 1" +.TH AR 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ar \- create, modify, and extract from archives +.SH SYNOPSIS +.IX Header "SYNOPSIS" +ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The GNU \fBar\fR program creates, modifies, and extracts from +archives. An \fIarchive\fR is a single file holding a collection of +other files in a structure that makes it possible to retrieve +the original individual files (called \fImembers\fR of the archive). +.PP +The original files' contents, mode (permissions), timestamp, owner, and +group are preserved in the archive, and can be restored on +extraction. +.PP +GNU \fBar\fR can maintain archives whose members have names of any +length; however, depending on how \fBar\fR is configured on your +system, a limit on member-name length may be imposed for compatibility +with archive formats maintained with other tools. If it exists, the +limit is often 15 characters (typical of formats related to a.out) or 16 +characters (typical of formats related to coff). +.PP +\&\fBar\fR is considered a binary utility because archives of this sort +are most often used as \fIlibraries\fR holding commonly needed +subroutines. Since libraries often will depend on other libraries, +\&\fBar\fR can also record the dependencies of a library when the +\&\fB\-\-record\-libdeps\fR option is specified. +.PP +\&\fBar\fR creates an index to the symbols defined in relocatable +object modules in the archive when you specify the modifier \fBs\fR. +Once created, this index is updated in the archive whenever \fBar\fR +makes a change to its contents (save for the \fBq\fR update operation). +An archive with such an index speeds up linking to the library, and +allows routines in the library to call each other without regard to +their placement in the archive. +.PP +You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index +table. If an archive lacks the table, another form of \fBar\fR called +\&\fBranlib\fR can be used to add just the table. +.PP +GNU \fBar\fR can optionally create a \fIthin\fR archive, +which contains a symbol index and references to the original copies +of the member files of the archive. This is useful for building +libraries for use within a local build tree, where the relocatable +objects are expected to remain available, and copying the contents of +each object would only waste time and space. +.PP +An archive can either be \fIthin\fR or it can be normal. It cannot +be both at the same time. Once an archive is created its format +cannot be changed without first deleting it and then creating a new +archive in its place. +.PP +Thin archives are also \fIflattened\fR, so that adding one thin +archive to another thin archive does not nest it, as would happen with +a normal archive. Instead the elements of the first archive are added +individually to the second archive. +.PP +The paths to the elements of the archive are stored relative to the +archive itself. +.PP +GNU \fBar\fR is designed to be compatible with two different +facilities. You can control its activity using command-line options, +like the different varieties of \fBar\fR on Unix systems; or, if you +specify the single command-line option \fB\-M\fR, you can control it +with a script supplied via standard input, like the MRI "librarian" +program. +.SH OPTIONS +.IX Header "OPTIONS" +GNU \fBar\fR allows you to mix the operation code \fIp\fR and modifier +flags \fImod\fR in any order, within the first command-line argument. +.PP +If you wish, you may begin the first command-line argument with a +dash. +.PP +The \fIp\fR keyletter specifies what operation to execute; it may be +any of the following, but you must specify only one of them: +.IP \fBd\fR 4 +.IX Item "d" +\&\fIDelete\fR modules from the archive. Specify the names of modules to +be deleted as \fImember\fR...; the archive is untouched if you +specify no files to delete. +.Sp +If you specify the \fBv\fR modifier, \fBar\fR lists each module +as it is deleted. +.IP \fBm\fR 4 +.IX Item "m" +Use this operation to \fImove\fR members in an archive. +.Sp +The ordering of members in an archive can make a difference in how +programs are linked using the library, if a symbol is defined in more +than one member. +.Sp +If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the +\&\fImember\fR arguments are moved to the \fIend\fR of the archive; +you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a +specified place instead. +.IP \fBp\fR 4 +.IX Item "p" +\&\fIPrint\fR the specified members of the archive, to the standard +output file. If the \fBv\fR modifier is specified, show the member +name before copying its contents to standard output. +.Sp +If you specify no \fImember\fR arguments, all the files in the archive are +printed. +.IP \fBq\fR 4 +.IX Item "q" +\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of +\&\fIarchive\fR, without checking for replacement. +.Sp +The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this +operation; new members are always placed at the end of the archive. +.Sp +The modifier \fBv\fR makes \fBar\fR list each file as it is appended. +.Sp +Since the point of this operation is speed, implementations of +\&\fBar\fR have the option of not updating the archive's symbol +table if one exists. Too many different systems however assume that +symbol tables are always up-to-date, so GNU \fBar\fR will +rebuild the table even with a quick append. +.Sp +Note \- GNU \fBar\fR treats the command \fBqs\fR as a +synonym for \fBr\fR \- replacing already existing files in the +archive and appending new ones at the end. +.IP \fBr\fR 4 +.IX Item "r" +Insert the files \fImember\fR... into \fIarchive\fR (with +\&\fIreplacement\fR). This operation differs from \fBq\fR in that any +previously existing members are deleted if their names match those being +added. +.Sp +If one of the files named in \fImember\fR... does not exist, \fBar\fR +displays an error message, and leaves undisturbed any existing members +of the archive matching that name. +.Sp +By default, new members are added at the end of the file; but you may +use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request +placement relative to some existing member. +.Sp +The modifier \fBv\fR used with this operation elicits a line of +output for each file inserted, along with one of the letters \fBa\fR or +\&\fBr\fR to indicate whether the file was appended (no old member +deleted) or replaced. +.IP \fBs\fR 4 +.IX Item "s" +Add an index to the archive, or update it if it already exists. Note +this command is an exception to the rule that there can only be one +command letter, as it is possible to use it as either a command or a +modifier. In either case it does the same thing. +.IP \fBt\fR 4 +.IX Item "t" +Display a \fItable\fR listing the contents of \fIarchive\fR, or those +of the files listed in \fImember\fR... that are present in the +archive. Normally only the member name is shown, but if the modifier +\&\fBO\fR is specified, then the corresponding offset of the member is also +displayed. Finally, in order to see the modes (permissions), timestamp, +owner, group, and size the \fBv\fR modifier should be included. +.Sp +If you do not specify a \fImember\fR, all files in the archive +are listed. +.Sp +If there is more than one file with the same name (say, \fBfie\fR) in +an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the +first instance; to see them all, you must ask for a complete +listing\-\-\-in our example, \fBar t b.a\fR. +.IP \fBx\fR 4 +.IX Item "x" +\&\fIExtract\fR members (named \fImember\fR) from the archive. You can +use the \fBv\fR modifier with this operation, to request that +\&\fBar\fR list each name as it extracts it. +.Sp +If you do not specify a \fImember\fR, all files in the archive +are extracted. +.Sp +Files cannot be extracted from a thin archive, and there are +restrictions on extracting from archives created with \fBP\fR: The +paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any +subdirectories in the paths must exist. If it is desired to avoid +these restrictions then used the \fB\-\-output\fR option to specify +an output directory. +.PP +A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR +keyletter, to specify variations on an operation's behavior: +.IP \fBa\fR 4 +.IX Item "a" +Add new files \fIafter\fR an existing member of the +archive. If you use the modifier \fBa\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. +.IP \fBb\fR 4 +.IX Item "b" +Add new files \fIbefore\fR an existing member of the +archive. If you use the modifier \fBb\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. (same as \fBi\fR). +.IP \fBc\fR 4 +.IX Item "c" +\&\fICreate\fR the archive. The specified \fIarchive\fR is always +created if it did not exist, when you request an update. But a warning is +issued unless you specify in advance that you expect to create it, by +using this modifier. +.IP \fBD\fR 4 +.IX Item "D" +Operate in \fIdeterministic\fR mode. When adding files and the archive +index use zero for UIDs, GIDs, timestamps, and use consistent file modes +for all files. When this option is used, if \fBar\fR is used with +identical options and identical input files, multiple runs will create +identical output files regardless of the input files' owners, groups, +file modes, or modification times. +.Sp +If \fIbinutils\fR was configured with +\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default. +It can be disabled with the \fBU\fR modifier, below. +.IP \fBf\fR 4 +.IX Item "f" +Truncate names in the archive. GNU \fBar\fR will normally permit file +names of any length. This will cause it to create archives which are +not compatible with the native \fBar\fR program on some systems. If +this is a concern, the \fBf\fR modifier may be used to truncate file +names when putting them in the archive. +.IP \fBi\fR 4 +.IX Item "i" +Insert new files \fIbefore\fR an existing member of the +archive. If you use the modifier \fBi\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. (same as \fBb\fR). +.IP \fBl\fR 4 +.IX Item "l" +Specify dependencies of this library. The dependencies must immediately +follow this option character, must use the same syntax as the linker +command line, and must be specified within a single argument. I.e., if +multiple items are needed, they must be quoted to form a single command +line argument. For example \fBL "\-L/usr/local/lib \-lmydep1 \-lmydep2"\fR +.IP \fBN\fR 4 +.IX Item "N" +Uses the \fIcount\fR parameter. This is used if there are multiple +entries in the archive with the same name. Extract or delete instance +\&\fIcount\fR of the given name from the archive. +.IP \fBo\fR 4 +.IX Item "o" +Preserve the \fIoriginal\fR dates of members when extracting them. If +you do not specify this modifier, files extracted from the archive +are stamped with the time of extraction. +.IP \fBO\fR 4 +.IX Item "O" +Display member offsets inside the archive. Use together with the \fBt\fR +option. +.IP \fBP\fR 4 +.IX Item "P" +Use the full path name when matching or storing names in the archive. +Archives created with full path names are not POSIX compliant, and +thus may not work with tools other than up to date GNU tools. +Modifying such archives with GNU \fBar\fR without using +\&\fBP\fR will remove the full path names unless the archive is a +thin archive. Note that \fBP\fR may be useful when adding files to +a thin archive since \fBr\fR without \fBP\fR ignores the path +when choosing which element to replace. Thus +.Sp +.Vb 1 +\& ar rcST archive.a subdir/file1 subdir/file2 file1 +.Ve +.Sp +will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with +\&\f(CW\*(C`file1\*(C'\fR from the current directory. Adding \fBP\fR will +prevent this replacement. +.IP \fBs\fR 4 +.IX Item "s" +Write an object-file index into the archive, or update an existing one, +even if no other change is made to the archive. You may use this modifier +flag either with any operation, or alone. Running \fBar s\fR on an +archive is equivalent to running \fBranlib\fR on it. +.IP \fBS\fR 4 +.IX Item "S" +Do not generate an archive symbol table. This can speed up building a +large library in several steps. The resulting archive can not be used +with the linker. In order to build a symbol table, you must omit the +\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run +\&\fBranlib\fR on the archive. +.IP \fBT\fR 4 +.IX Item "T" +Deprecated alias for \fB\-\-thin\fR. \fBT\fR is not recommended because in +many ar implementations \fBT\fR has a different meaning, as specified by +X/Open System Interface. +.IP \fBu\fR 4 +.IX Item "u" +Normally, \fBar r\fR... inserts all files +listed into the archive. If you would like to insert \fIonly\fR those +of the files you list that are newer than existing members of the same +names, use this modifier. The \fBu\fR modifier is allowed only for the +operation \fBr\fR (replace). In particular, the combination \fBqu\fR is +not allowed, since checking the timestamps would lose any speed +advantage from the operation \fBq\fR. +.IP \fBU\fR 4 +.IX Item "U" +Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse +of the \fBD\fR modifier, above: added files and the archive index will +get their actual UID, GID, timestamp, and file mode values. +.Sp +This is the default unless \fIbinutils\fR was configured with +\&\fB\-\-enable\-deterministic\-archives\fR. +.IP \fBv\fR 4 +.IX Item "v" +This modifier requests the \fIverbose\fR version of an operation. Many +operations display additional information, such as filenames processed, +when the modifier \fBv\fR is appended. +.IP \fBV\fR 4 +.IX Item "V" +This modifier shows the version number of \fBar\fR. +.PP +The \fBar\fR program also supports some command-line options which +are neither modifiers nor actions, but which do change its behaviour +in specific ways: +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Displays the list of command-line options supported by \fBar\fR +and then exits. +.IP \fB\-\-version\fR 4 +.IX Item "--version" +Displays the version information of \fBar\fR and then exits. +.IP \fB\-X32_64\fR 4 +.IX Item "-X32_64" +\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for +compatibility with AIX. The behaviour produced by this option is the +default for GNU \fBar\fR. \fBar\fR does not support any +of the other \fB\-X\fR options; in particular, it does not support +\&\fB\-X32\fR which is the default for AIX \fBar\fR. +.IP "\fB\-\-plugin\fR \fIname\fR" 4 +.IX Item "--plugin name" +The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes +\&\fBar\fR to load the plugin called \fIname\fR which adds support +for more file formats, including object files with link-time +optimization information. +.Sp +This option is only available if the toolchain has been built with +plugin support enabled. +.Sp +If \fB\-\-plugin\fR is not provided, but plugin support has been +enabled then \fBar\fR iterates over the files in +\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first +plugin that claims the object in question is used. +.Sp +Please note that this plugin search directory is \fInot\fR the one +used by \fBld\fR's \fB\-plugin\fR option. In order to make +\&\fBar\fR use the linker plugin it must be copied into the +\&\fI${libdir}/bfd\-plugins\fR directory. For GCC based compilations +the linker plugin is called \fIliblto_plugin.so.0.0.0\fR. For Clang +based compilations it is called \fILLVMgold.so\fR. The GCC plugin +is always backwards compatible with earlier versions, so it is +sufficient to just copy the newest one. +.IP "\fB\-\-target\fR \fItarget\fR" 4 +.IX Item "--target target" +The optional command-line switch \fB\-\-target\fR \fIbfdname\fR +specifies that the archive members are in an object code format +different from your system's default format. See +.IP "\fB\-\-output\fR \fIdirname\fR" 4 +.IX Item "--output dirname" +The \fB\-\-output\fR option can be used to specify a path to a +directory into which archive members should be extracted. If this +option is not specified then the current directory will be used. +.Sp +Note \- although the presence of this option does imply a \fBx\fR +extraction operation that option must still be included on the command +line. +.IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4 +.IX Item "--record-libdeps libdeps" +The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier, +just handled in long form. +.IP \fB\-\-thin\fR 4 +.IX Item "--thin" +Make the specified \fIarchive\fR a \fIthin\fR archive. If it already +exists and is a regular archive, the existing members must be present +in the same directory as \fIarchive\fR. +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/arch.1 b/upstream/fedora-40/man1/arch.1 new file mode 100644 index 00000000..c416a09c --- /dev/null +++ b/upstream/fedora-40/man1/arch.1 @@ -0,0 +1,36 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH ARCH "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +arch \- print machine hardware name (same as uname -m) +.SH SYNOPSIS +.B arch +[\fI\,OPTION\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print machine architecture. +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by David MacKenzie and Karel Zak. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBuname\fP(1), \fBuname\fP(2) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) arch invocation\(aq diff --git a/upstream/fedora-40/man1/as.1 b/upstream/fedora-40/man1/as.1 new file mode 100644 index 00000000..f20b75a9 --- /dev/null +++ b/upstream/fedora-40/man1/as.1 @@ -0,0 +1,2976 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "AS 1" +.TH AS 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +AS \- the portable GNU assembler. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +as [\fB\-a\fR[\fBcdghlns\fR][=\fIfile\fR]] + [\fB\-\-alternate\fR] + [\fB\-\-compress\-debug\-sections\fR] [\fB\-\-nocompress\-debug\-sections\fR] + [\fB\-D\fR] + [\fB\-\-dump\-config\fR] + [\fB\-\-debug\-prefix\-map\fR \fIold\fR=\fInew\fR] + [\fB\-\-defsym\fR \fIsym\fR=\fIval\fR] + [\fB\-\-elf\-stt\-common=[no|yes]\fR] + [\fB\-\-emulation\fR=\fIname\fR] + [\fB\-f\fR] + [\fB\-g\fR] [\fB\-\-gstabs\fR] [\fB\-\-gstabs+\fR] + [\fB\-\-gdwarf\-\fR] [\fB\-\-gdwarf\-sections\fR] + [\fB\-\-gdwarf\-cie\-version\fR=\fIVERSION\fR] + [\fB\-\-generate\-missing\-build\-notes=[no|yes]\fR] + [\fB\-\-gsframe\fR] + [\fB\-\-hash\-size\fR=\fIN\fR] + [\fB\-\-help\fR] [\fB\-\-target\-help\fR] + [\fB\-I\fR \fIdir\fR] + [\fB\-J\fR] + [\fB\-K\fR] + [\fB\-\-keep\-locals\fR] + [\fB\-L\fR] + [\fB\-\-listing\-lhs\-width\fR=\fINUM\fR] + [\fB\-\-listing\-lhs\-width2\fR=\fINUM\fR] + [\fB\-\-listing\-rhs\-width\fR=\fINUM\fR] + [\fB\-\-listing\-cont\-lines\fR=\fINUM\fR] + [\fB\-\-multibyte\-handling=[allow|warn|warn\-sym\-only]\fR] + [\fB\-\-no\-pad\-sections\fR] + [\fB\-o\fR \fIobjfile\fR] [\fB\-R\fR] + [\fB\-\-sectname\-subst\fR] + [\fB\-\-size\-check=[error|warning]\fR] + [\fB\-\-statistics\fR] + [\fB\-v\fR] [\fB\-version\fR] [\fB\-\-version\fR] + [\fB\-W\fR] [\fB\-\-warn\fR] [\fB\-\-fatal\-warnings\fR] [\fB\-w\fR] [\fB\-x\fR] + [\fB\-Z\fR] [\fB@\fR\fIFILE\fR] + [\fItarget-options\fR] + [\fB\-\-\fR|\fIfiles\fR ...] +.SH TARGET +.IX Header "TARGET" +\&\fITarget AArch64 options:\fR + [\fB\-EB\fR|\fB\-EL\fR] + [\fB\-mabi\fR=\fIABI\fR] +.PP +\&\fITarget Alpha options:\fR + [\fB\-m\fR\fIcpu\fR] + [\fB\-mdebug\fR | \fB\-no\-mdebug\fR] + [\fB\-replace\fR | \fB\-noreplace\fR] + [\fB\-relax\fR] [\fB\-g\fR] [\fB\-G\fR\fIsize\fR] + [\fB\-F\fR] [\fB\-32addr\fR] +.PP +\&\fITarget ARC options:\fR + [\fB\-mcpu=\fR\fIcpu\fR] + [\fB\-mA6\fR|\fB\-mARC600\fR|\fB\-mARC601\fR|\fB\-mA7\fR|\fB\-mARC700\fR|\fB\-mEM\fR|\fB\-mHS\fR] + [\fB\-mcode\-density\fR] + [\fB\-mrelax\fR] + [\fB\-EB\fR|\fB\-EL\fR] +.PP +\&\fITarget ARM options:\fR + [\fB\-mcpu\fR=\fIprocessor\fR[+\fIextension\fR...]] + [\fB\-march\fR=\fIarchitecture\fR[+\fIextension\fR...]] + [\fB\-mfpu\fR=\fIfloating-point-format\fR] + [\fB\-mfloat\-abi\fR=\fIabi\fR] + [\fB\-meabi\fR=\fIver\fR] + [\fB\-mthumb\fR] + [\fB\-EB\fR|\fB\-EL\fR] + [\fB\-mapcs\-32\fR|\fB\-mapcs\-26\fR|\fB\-mapcs\-float\fR| + \fB\-mapcs\-reentrant\fR] + [\fB\-mthumb\-interwork\fR] [\fB\-k\fR] +.PP +\&\fITarget Blackfin options:\fR + [\fB\-mcpu\fR=\fIprocessor\fR[\-\fIsirevision\fR]] + [\fB\-mfdpic\fR] + [\fB\-mno\-fdpic\fR] + [\fB\-mnopic\fR] +.PP +\&\fITarget BPF options:\fR + [\fB\-EL\fR] [\fB\-EB\fR] +.PP +\&\fITarget CRIS options:\fR + [\fB\-\-underscore\fR | \fB\-\-no\-underscore\fR] + [\fB\-\-pic\fR] [\fB\-N\fR] + [\fB\-\-emulation=criself\fR | \fB\-\-emulation=crisaout\fR] + [\fB\-\-march=v0_v10\fR | \fB\-\-march=v10\fR | \fB\-\-march=v32\fR | \fB\-\-march=common_v10_v32\fR] +.PP +\&\fITarget C\-SKY options:\fR + [\fB\-march=\fR\fIarch\fR] [\fB\-mcpu=\fR\fIcpu\fR] + [\fB\-EL\fR] [\fB\-mlittle\-endian\fR] [\fB\-EB\fR] [\fB\-mbig\-endian\fR] + [\fB\-fpic\fR] [\fB\-pic\fR] + [\fB\-mljump\fR] [\fB\-mno\-ljump\fR] + [\fB\-force2bsr\fR] [\fB\-mforce2bsr\fR] [\fB\-no\-force2bsr\fR] [\fB\-mno\-force2bsr\fR] + [\fB\-jsri2bsr\fR] [\fB\-mjsri2bsr\fR] [\fB\-no\-jsri2bsr\fR ] [\fB\-mno\-jsri2bsr\fR] + [\fB\-mnolrw\fR ] [\fB\-mno\-lrw\fR] + [\fB\-melrw\fR] [\fB\-mno\-elrw\fR] + [\fB\-mlaf\fR ] [\fB\-mliterals\-after\-func\fR] + [\fB\-mno\-laf\fR] [\fB\-mno\-literals\-after\-func\fR] + [\fB\-mlabr\fR] [\fB\-mliterals\-after\-br\fR] + [\fB\-mno\-labr\fR] [\fB\-mnoliterals\-after\-br\fR] + [\fB\-mistack\fR] [\fB\-mno\-istack\fR] + [\fB\-mhard\-float\fR] [\fB\-mmp\fR] [\fB\-mcp\fR] [\fB\-mcache\fR] + [\fB\-msecurity\fR] [\fB\-mtrust\fR] + [\fB\-mdsp\fR] [\fB\-medsp\fR] [\fB\-mvdsp\fR] +.PP +\&\fITarget D10V options:\fR + [\fB\-O\fR] +.PP +\&\fITarget D30V options:\fR + [\fB\-O\fR|\fB\-n\fR|\fB\-N\fR] +.PP +\&\fITarget EPIPHANY options:\fR + [\fB\-mepiphany\fR|\fB\-mepiphany16\fR] +.PP +\&\fITarget H8/300 options:\fR + [\-h\-tick\-hex] +.PP +\&\fITarget i386 options:\fR + [\fB\-\-32\fR|\fB\-\-x32\fR|\fB\-\-64\fR] [\fB\-n\fR] + [\fB\-march\fR=\fICPU\fR[+\fIEXTENSION\fR...]] [\fB\-mtune\fR=\fICPU\fR] +.PP +\&\fITarget IA\-64 options:\fR + [\fB\-mconstant\-gp\fR|\fB\-mauto\-pic\fR] + [\fB\-milp32\fR|\fB\-milp64\fR|\fB\-mlp64\fR|\fB\-mp64\fR] + [\fB\-mle\fR|\fBmbe\fR] + [\fB\-mtune=itanium1\fR|\fB\-mtune=itanium2\fR] + [\fB\-munwind\-check=warning\fR|\fB\-munwind\-check=error\fR] + [\fB\-mhint.b=ok\fR|\fB\-mhint.b=warning\fR|\fB\-mhint.b=error\fR] + [\fB\-x\fR|\fB\-xexplicit\fR] [\fB\-xauto\fR] [\fB\-xdebug\fR] +.PP +\&\fITarget IP2K options:\fR + [\fB\-mip2022\fR|\fB\-mip2022ext\fR] +.PP +\&\fITarget M32C options:\fR + [\fB\-m32c\fR|\fB\-m16c\fR] [\-relax] [\-h\-tick\-hex] +.PP +\&\fITarget M32R options:\fR + [\fB\-\-m32rx\fR|\fB\-\-[no\-]warn\-explicit\-parallel\-conflicts\fR| + \fB\-\-W[n]p\fR] +.PP +\&\fITarget M680X0 options:\fR + [\fB\-l\fR] [\fB\-m68000\fR|\fB\-m68010\fR|\fB\-m68020\fR|...] +.PP +\&\fITarget M68HC11 options:\fR + [\fB\-m68hc11\fR|\fB\-m68hc12\fR|\fB\-m68hcs12\fR|\fB\-mm9s12x\fR|\fB\-mm9s12xg\fR] + [\fB\-mshort\fR|\fB\-mlong\fR] + [\fB\-mshort\-double\fR|\fB\-mlong\-double\fR] + [\fB\-\-force\-long\-branches\fR] [\fB\-\-short\-branches\fR] + [\fB\-\-strict\-direct\-mode\fR] [\fB\-\-print\-insn\-syntax\fR] + [\fB\-\-print\-opcodes\fR] [\fB\-\-generate\-example\fR] +.PP +\&\fITarget MCORE options:\fR + [\fB\-jsri2bsr\fR] [\fB\-sifilter\fR] [\fB\-relax\fR] + [\fB\-mcpu=[210|340]\fR] +.PP +\&\fITarget Meta options:\fR + [\fB\-mcpu=\fR\fIcpu\fR] [\fB\-mfpu=\fR\fIcpu\fR] [\fB\-mdsp=\fR\fIcpu\fR] +\&\fITarget MICROBLAZE options:\fR +.PP +\&\fITarget MIPS options:\fR + [\fB\-nocpp\fR] [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR[\fIoptimization level\fR]] + [\fB\-g\fR[\fIdebug level\fR]] [\fB\-G\fR \fInum\fR] [\fB\-KPIC\fR] [\fB\-call_shared\fR] + [\fB\-non_shared\fR] [\fB\-xgot\fR [\fB\-mvxworks\-pic\fR] + [\fB\-mabi\fR=\fIABI\fR] [\fB\-32\fR] [\fB\-n32\fR] [\fB\-64\fR] [\fB\-mfp32\fR] [\fB\-mgp32\fR] + [\fB\-mfp64\fR] [\fB\-mgp64\fR] [\fB\-mfpxx\fR] + [\fB\-modd\-spreg\fR] [\fB\-mno\-odd\-spreg\fR] + [\fB\-march\fR=\fICPU\fR] [\fB\-mtune\fR=\fICPU\fR] [\fB\-mips1\fR] [\fB\-mips2\fR] + [\fB\-mips3\fR] [\fB\-mips4\fR] [\fB\-mips5\fR] [\fB\-mips32\fR] [\fB\-mips32r2\fR] + [\fB\-mips32r3\fR] [\fB\-mips32r5\fR] [\fB\-mips32r6\fR] [\fB\-mips64\fR] [\fB\-mips64r2\fR] + [\fB\-mips64r3\fR] [\fB\-mips64r5\fR] [\fB\-mips64r6\fR] + [\fB\-construct\-floats\fR] [\fB\-no\-construct\-floats\fR] + [\fB\-mignore\-branch\-isa\fR] [\fB\-mno\-ignore\-branch\-isa\fR] + [\fB\-mnan=\fR\fIencoding\fR] + [\fB\-trap\fR] [\fB\-no\-break\fR] [\fB\-break\fR] [\fB\-no\-trap\fR] + [\fB\-mips16\fR] [\fB\-no\-mips16\fR] + [\fB\-mmips16e2\fR] [\fB\-mno\-mips16e2\fR] + [\fB\-mmicromips\fR] [\fB\-mno\-micromips\fR] + [\fB\-msmartmips\fR] [\fB\-mno\-smartmips\fR] + [\fB\-mips3d\fR] [\fB\-no\-mips3d\fR] + [\fB\-mdmx\fR] [\fB\-no\-mdmx\fR] + [\fB\-mdsp\fR] [\fB\-mno\-dsp\fR] + [\fB\-mdspr2\fR] [\fB\-mno\-dspr2\fR] + [\fB\-mdspr3\fR] [\fB\-mno\-dspr3\fR] + [\fB\-mmsa\fR] [\fB\-mno\-msa\fR] + [\fB\-mxpa\fR] [\fB\-mno\-xpa\fR] + [\fB\-mmt\fR] [\fB\-mno\-mt\fR] + [\fB\-mmcu\fR] [\fB\-mno\-mcu\fR] + [\fB\-mcrc\fR] [\fB\-mno\-crc\fR] + [\fB\-mginv\fR] [\fB\-mno\-ginv\fR] + [\fB\-mloongson\-mmi\fR] [\fB\-mno\-loongson\-mmi\fR] + [\fB\-mloongson\-cam\fR] [\fB\-mno\-loongson\-cam\fR] + [\fB\-mloongson\-ext\fR] [\fB\-mno\-loongson\-ext\fR] + [\fB\-mloongson\-ext2\fR] [\fB\-mno\-loongson\-ext2\fR] + [\fB\-minsn32\fR] [\fB\-mno\-insn32\fR] + [\fB\-mfix7000\fR] [\fB\-mno\-fix7000\fR] + [\fB\-mfix\-rm7000\fR] [\fB\-mno\-fix\-rm7000\fR] + [\fB\-mfix\-vr4120\fR] [\fB\-mno\-fix\-vr4120\fR] + [\fB\-mfix\-vr4130\fR] [\fB\-mno\-fix\-vr4130\fR] + [\fB\-mfix\-r5900\fR] [\fB\-mno\-fix\-r5900\fR] + [\fB\-mdebug\fR] [\fB\-no\-mdebug\fR] + [\fB\-mpdr\fR] [\fB\-mno\-pdr\fR] +.PP +\&\fITarget MMIX options:\fR + [\fB\-\-fixed\-special\-register\-names\fR] [\fB\-\-globalize\-symbols\fR] + [\fB\-\-gnu\-syntax\fR] [\fB\-\-relax\fR] [\fB\-\-no\-predefined\-symbols\fR] + [\fB\-\-no\-expand\fR] [\fB\-\-no\-merge\-gregs\fR] [\fB\-x\fR] + [\fB\-\-linker\-allocated\-gregs\fR] +.PP +\&\fITarget Nios II options:\fR + [\fB\-relax\-all\fR] [\fB\-relax\-section\fR] [\fB\-no\-relax\fR] + [\fB\-EB\fR] [\fB\-EL\fR] +.PP +\&\fITarget NDS32 options:\fR + [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR] [\fB\-Os\fR] [\fB\-mcpu=\fR\fIcpu\fR] + [\fB\-misa=\fR\fIisa\fR] [\fB\-mabi=\fR\fIabi\fR] [\fB\-mall\-ext\fR] + [\fB\-m[no\-]16\-bit\fR] [\fB\-m[no\-]perf\-ext\fR] [\fB\-m[no\-]perf2\-ext\fR] + [\fB\-m[no\-]string\-ext\fR] [\fB\-m[no\-]dsp\-ext\fR] [\fB\-m[no\-]mac\fR] [\fB\-m[no\-]div\fR] + [\fB\-m[no\-]audio\-isa\-ext\fR] [\fB\-m[no\-]fpu\-sp\-ext\fR] [\fB\-m[no\-]fpu\-dp\-ext\fR] + [\fB\-m[no\-]fpu\-fma\fR] [\fB\-mfpu\-freg=\fR\fIFREG\fR] [\fB\-mreduced\-regs\fR] + [\fB\-mfull\-regs\fR] [\fB\-m[no\-]dx\-regs\fR] [\fB\-mpic\fR] [\fB\-mno\-relax\fR] + [\fB\-mb2bb\fR] +.PP +\&\fITarget PDP11 options:\fR + [\fB\-mpic\fR|\fB\-mno\-pic\fR] [\fB\-mall\fR] [\fB\-mno\-extensions\fR] + [\fB\-m\fR\fIextension\fR|\fB\-mno\-\fR\fIextension\fR] + [\fB\-m\fR\fIcpu\fR] [\fB\-m\fR\fImachine\fR] +.PP +\&\fITarget picoJava options:\fR + [\fB\-mb\fR|\fB\-me\fR] +.PP +\&\fITarget PowerPC options:\fR + [\fB\-a32\fR|\fB\-a64\fR] + [\fB\-mpwrx\fR|\fB\-mpwr2\fR|\fB\-mpwr\fR|\fB\-m601\fR|\fB\-mppc\fR|\fB\-mppc32\fR|\fB\-m603\fR|\fB\-m604\fR|\fB\-m403\fR|\fB\-m405\fR| + \fB\-m440\fR|\fB\-m464\fR|\fB\-m476\fR|\fB\-m7400\fR|\fB\-m7410\fR|\fB\-m7450\fR|\fB\-m7455\fR|\fB\-m750cl\fR|\fB\-mgekko\fR| + \fB\-mbroadway\fR|\fB\-mppc64\fR|\fB\-m620\fR|\fB\-me500\fR|\fB\-e500x2\fR|\fB\-me500mc\fR|\fB\-me500mc64\fR|\fB\-me5500\fR| + \fB\-me6500\fR|\fB\-mppc64bridge\fR|\fB\-mbooke\fR|\fB\-mpower4\fR|\fB\-mpwr4\fR|\fB\-mpower5\fR|\fB\-mpwr5\fR|\fB\-mpwr5x\fR| + \fB\-mpower6\fR|\fB\-mpwr6\fR|\fB\-mpower7\fR|\fB\-mpwr7\fR|\fB\-mpower8\fR|\fB\-mpwr8\fR|\fB\-mpower9\fR|\fB\-mpwr9\fR\fB\-ma2\fR| + \fB\-mcell\fR|\fB\-mspe\fR|\fB\-mspe2\fR|\fB\-mtitan\fR|\fB\-me300\fR|\fB\-mcom\fR] + [\fB\-many\fR] [\fB\-maltivec\fR|\fB\-mvsx\fR|\fB\-mhtm\fR|\fB\-mvle\fR] + [\fB\-mregnames\fR|\fB\-mno\-regnames\fR] + [\fB\-mrelocatable\fR|\fB\-mrelocatable\-lib\fR|\fB\-K PIC\fR] [\fB\-memb\fR] + [\fB\-mlittle\fR|\fB\-mlittle\-endian\fR|\fB\-le\fR|\fB\-mbig\fR|\fB\-mbig\-endian\fR|\fB\-be\fR] + [\fB\-msolaris\fR|\fB\-mno\-solaris\fR] + [\fB\-nops=\fR\fIcount\fR] +.PP +\&\fITarget PRU options:\fR + [\fB\-link\-relax\fR] + [\fB\-mnolink\-relax\fR] + [\fB\-mno\-warn\-regname\-label\fR] +.PP +\&\fITarget RISC-V options:\fR + [\fB\-fpic\fR|\fB\-fPIC\fR|\fB\-fno\-pic\fR] + [\fB\-march\fR=\fIISA\fR] + [\fB\-mabi\fR=\fIABI\fR] + [\fB\-mlittle\-endian\fR|\fB\-mbig\-endian\fR] +.PP +\&\fITarget RL78 options:\fR + [\fB\-mg10\fR] + [\fB\-m32bit\-doubles\fR|\fB\-m64bit\-doubles\fR] +.PP +\&\fITarget RX options:\fR + [\fB\-mlittle\-endian\fR|\fB\-mbig\-endian\fR] + [\fB\-m32bit\-doubles\fR|\fB\-m64bit\-doubles\fR] + [\fB\-muse\-conventional\-section\-names\fR] + [\fB\-msmall\-data\-limit\fR] + [\fB\-mpid\fR] + [\fB\-mrelax\fR] + [\fB\-mint\-register=\fR\fInumber\fR] + [\fB\-mgcc\-abi\fR|\fB\-mrx\-abi\fR] +.PP +\&\fITarget s390 options:\fR + [\fB\-m31\fR|\fB\-m64\fR] [\fB\-mesa\fR|\fB\-mzarch\fR] [\fB\-march\fR=\fICPU\fR] + [\fB\-mregnames\fR|\fB\-mno\-regnames\fR] + [\fB\-mwarn\-areg\-zero\fR] +.PP +\&\fITarget SCORE options:\fR + [\fB\-EB\fR][\fB\-EL\fR][\fB\-FIXDD\fR][\fB\-NWARN\fR] + [\fB\-SCORE5\fR][\fB\-SCORE5U\fR][\fB\-SCORE7\fR][\fB\-SCORE3\fR] + [\fB\-march=score7\fR][\fB\-march=score3\fR] + [\fB\-USE_R1\fR][\fB\-KPIC\fR][\fB\-O0\fR][\fB\-G\fR \fInum\fR][\fB\-V\fR] +.PP +\&\fITarget SPARC options:\fR + [\fB\-Av6\fR|\fB\-Av7\fR|\fB\-Av8\fR|\fB\-Aleon\fR|\fB\-Asparclet\fR|\fB\-Asparclite\fR + \fB\-Av8plus\fR|\fB\-Av8plusa\fR|\fB\-Av8plusb\fR|\fB\-Av8plusc\fR|\fB\-Av8plusd\fR + \fB\-Av8plusv\fR|\fB\-Av8plusm\fR|\fB\-Av9\fR|\fB\-Av9a\fR|\fB\-Av9b\fR|\fB\-Av9c\fR + \fB\-Av9d\fR|\fB\-Av9e\fR|\fB\-Av9v\fR|\fB\-Av9m\fR|\fB\-Asparc\fR|\fB\-Asparcvis\fR + \fB\-Asparcvis2\fR|\fB\-Asparcfmaf\fR|\fB\-Asparcima\fR|\fB\-Asparcvis3\fR + \fB\-Asparcvisr\fR|\fB\-Asparc5\fR] + [\fB\-xarch=v8plus\fR|\fB\-xarch=v8plusa\fR]|\fB\-xarch=v8plusb\fR|\fB\-xarch=v8plusc\fR + \fB\-xarch=v8plusd\fR|\fB\-xarch=v8plusv\fR|\fB\-xarch=v8plusm\fR|\fB\-xarch=v9\fR + \fB\-xarch=v9a\fR|\fB\-xarch=v9b\fR|\fB\-xarch=v9c\fR|\fB\-xarch=v9d\fR|\fB\-xarch=v9e\fR + \fB\-xarch=v9v\fR|\fB\-xarch=v9m\fR|\fB\-xarch=sparc\fR|\fB\-xarch=sparcvis\fR + \fB\-xarch=sparcvis2\fR|\fB\-xarch=sparcfmaf\fR|\fB\-xarch=sparcima\fR + \fB\-xarch=sparcvis3\fR|\fB\-xarch=sparcvisr\fR|\fB\-xarch=sparc5\fR + \fB\-bump\fR] + [\fB\-32\fR|\fB\-64\fR] + [\fB\-\-enforce\-aligned\-data\fR][\fB\-\-dcti\-couples\-detect\fR] +.PP +\&\fITarget TIC54X options:\fR + [\fB\-mcpu=54[123589]\fR|\fB\-mcpu=54[56]lp\fR] [\fB\-mfar\-mode\fR|\fB\-mf\fR] + [\fB\-merrors\-to\-file\fR \fI\fR|\fB\-me\fR \fI\fR] +.PP +\&\fITarget TIC6X options:\fR + [\fB\-march=\fR\fIarch\fR] [\fB\-mbig\-endian\fR|\fB\-mlittle\-endian\fR] + [\fB\-mdsbt\fR|\fB\-mno\-dsbt\fR] [\fB\-mpid=no\fR|\fB\-mpid=near\fR|\fB\-mpid=far\fR] + [\fB\-mpic\fR|\fB\-mno\-pic\fR] +.PP +\&\fITarget TILE-Gx options:\fR + [\fB\-m32\fR|\fB\-m64\fR][\fB\-EB\fR][\fB\-EL\fR] +.PP +\&\fITarget Visium options:\fR + [\fB\-mtune=\fR\fIarch\fR] +.PP +\&\fITarget Xtensa options:\fR + [\fB\-\-[no\-]text\-section\-literals\fR] [\fB\-\-[no\-]auto\-litpools\fR] + [\fB\-\-[no\-]absolute\-literals\fR] + [\fB\-\-[no\-]target\-align\fR] [\fB\-\-[no\-]longcalls\fR] + [\fB\-\-[no\-]transform\fR] + [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR] + [\fB\-\-[no\-]trampolines\fR] + [\fB\-\-abi\-windowed\fR|\fB\-\-abi\-call0\fR] +.PP +\&\fITarget Z80 options:\fR + [\fB\-march=\fR\fICPU\fR\fI[\-EXT]\fR\fI[+EXT]\fR] + [\fB\-local\-prefix=\fR\fIPREFIX\fR] + [\fB\-colonless\fR] + [\fB\-sdcc\fR] + [\fB\-fp\-s=\fR\fIFORMAT\fR] + [\fB\-fp\-d=\fR\fIFORMAT\fR] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +GNU \fBas\fR is really a family of assemblers. +If you use (or have used) the GNU assembler on one architecture, you +should find a fairly similar environment when you use it on another +architecture. Each version has much in common with the others, +including object file formats, most assembler directives (often called +\&\fIpseudo-ops\fR) and assembler syntax. +.PP +\&\fBas\fR is primarily intended to assemble the output of the +GNU C compiler \f(CW\*(C`gcc\*(C'\fR for use by the linker +\&\f(CW\*(C`ld\*(C'\fR. Nevertheless, we've tried to make \fBas\fR +assemble correctly everything that other assemblers for the same +machine would assemble. +Any exceptions are documented explicitly. +This doesn't mean \fBas\fR always uses the same syntax as another +assembler for the same architecture; for example, we know of several +incompatible versions of 680x0 assembly language syntax. +.PP +Each time you run \fBas\fR it assembles exactly one source +program. The source program is made up of one or more files. +(The standard input is also a file.) +.PP +You give \fBas\fR a command line that has zero or more input file +names. The input files are read (from left file name to right). A +command-line argument (in any position) that has no special meaning +is taken to be an input file name. +.PP +If you give \fBas\fR no file names it attempts to read one input file +from the \fBas\fR standard input, which is normally your terminal. You +may have to type \fBctl-D\fR to tell \fBas\fR there is no more program +to assemble. +.PP +Use \fB\-\-\fR if you need to explicitly name the standard input file +in your command line. +.PP +If the source is empty, \fBas\fR produces a small, empty object +file. +.PP +\&\fBas\fR may write warnings and error messages to the standard error +file (usually your terminal). This should not happen when a compiler +runs \fBas\fR automatically. Warnings report an assumption made so +that \fBas\fR could keep assembling a flawed program; errors report a +grave problem that stops the assembly. +.PP +If you are invoking \fBas\fR via the GNU C compiler, +you can use the \fB\-Wa\fR option to pass arguments through to the assembler. +The assembler arguments must be separated from each other (and the \fB\-Wa\fR) +by commas. For example: +.PP +.Vb 1 +\& gcc \-c \-g \-O \-Wa,\-alh,\-L file.c +.Ve +.PP +This passes two options to the assembler: \fB\-alh\fR (emit a listing to +standard output with high-level and assembly source) and \fB\-L\fR (retain +local symbols in the symbol table). +.PP +Usually you do not need to use this \fB\-Wa\fR mechanism, since many compiler +command-line options are automatically passed to the assembler by the compiler. +(You can call the GNU compiler driver with the \fB\-v\fR option to see +precisely what options it passes to each compilation pass, including the +assembler.) +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.IP \fB\-a[cdghlmns]\fR 4 +.IX Item "-a[cdghlmns]" +Turn on listings, in any of a variety of ways: +.RS 4 +.IP \fB\-ac\fR 4 +.IX Item "-ac" +omit false conditionals +.IP \fB\-ad\fR 4 +.IX Item "-ad" +omit debugging directives +.IP \fB\-ag\fR 4 +.IX Item "-ag" +include general information, like as version and options passed +.IP \fB\-ah\fR 4 +.IX Item "-ah" +include high-level source +.IP \fB\-al\fR 4 +.IX Item "-al" +include assembly +.IP \fB\-am\fR 4 +.IX Item "-am" +include macro expansions +.IP \fB\-an\fR 4 +.IX Item "-an" +omit forms processing +.IP \fB\-as\fR 4 +.IX Item "-as" +include symbols +.IP \fB=file\fR 4 +.IX Item "=file" +set the name of the listing file +.RE +.RS 4 +.Sp +You may combine these options; for example, use \fB\-aln\fR for assembly +listing without forms processing. The \fB=file\fR option, if used, must be +the last one. By itself, \fB\-a\fR defaults to \fB\-ahls\fR. +.RE +.IP \fB\-\-alternate\fR 4 +.IX Item "--alternate" +Begin in alternate macro mode. +.IP \fB\-\-compress\-debug\-sections\fR 4 +.IX Item "--compress-debug-sections" +Compress DWARF debug sections using zlib with SHF_COMPRESSED from the +ELF ABI. The resulting object file may not be compatible with older +linkers and object file utilities. Note if compression would make a +given section \fIlarger\fR then it is not compressed. +.IP \fB\-\-compress\-debug\-sections=none\fR 4 +.IX Item "--compress-debug-sections=none" +.PD 0 +.IP \fB\-\-compress\-debug\-sections=zlib\fR 4 +.IX Item "--compress-debug-sections=zlib" +.IP \fB\-\-compress\-debug\-sections=zlib\-gnu\fR 4 +.IX Item "--compress-debug-sections=zlib-gnu" +.IP \fB\-\-compress\-debug\-sections=zlib\-gabi\fR 4 +.IX Item "--compress-debug-sections=zlib-gabi" +.IP \fB\-\-compress\-debug\-sections=zstd\fR 4 +.IX Item "--compress-debug-sections=zstd" +.PD +These options control how DWARF debug sections are compressed. +\&\fB\-\-compress\-debug\-sections=none\fR is equivalent to +\&\fB\-\-nocompress\-debug\-sections\fR. +\&\fB\-\-compress\-debug\-sections=zlib\fR and +\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR are equivalent to +\&\fB\-\-compress\-debug\-sections\fR. +\&\fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses DWARF debug sections +using the obsoleted zlib-gnu format. The debug sections are renamed to begin +with \fB.zdebug\fR. +\&\fB\-\-compress\-debug\-sections=zstd\fR compresses DWARF debug +sections using zstd. Note \- if compression would actually make a section +\&\fIlarger\fR, then it is not compressed nor renamed. +.IP \fB\-\-nocompress\-debug\-sections\fR 4 +.IX Item "--nocompress-debug-sections" +Do not compress DWARF debug sections. This is usually the default for all +targets except the x86/x86_64, but a configure time option can be used to +override this. +.IP \fB\-D\fR 4 +.IX Item "-D" +Enable denugging in target specific backends, if supported. Otherwise ignored. +Even if ignored, this option is accepted for script compatibility with calls to +other assemblers. +.IP "\fB\-\-debug\-prefix\-map\fR \fIold\fR\fB=\fR\fInew\fR" 4 +.IX Item "--debug-prefix-map old=new" +When assembling files in directory \fIold\fR, record debugging +information describing them as in \fInew\fR instead. +.IP "\fB\-\-defsym\fR \fIsym\fR\fB=\fR\fIvalue\fR" 4 +.IX Item "--defsym sym=value" +Define the symbol \fIsym\fR to be \fIvalue\fR before assembling the input file. +\&\fIvalue\fR must be an integer constant. As in C, a leading \fB0x\fR +indicates a hexadecimal value, and a leading \fB0\fR indicates an octal +value. The value of the symbol can be overridden inside a source file via the +use of a \f(CW\*(C`.set\*(C'\fR pseudo-op. +.IP \fB\-\-dump\-config\fR 4 +.IX Item "--dump-config" +Displays how the assembler is configured and then exits. +.IP \fB\-\-elf\-stt\-common=no\fR 4 +.IX Item "--elf-stt-common=no" +.PD 0 +.IP \fB\-\-elf\-stt\-common=yes\fR 4 +.IX Item "--elf-stt-common=yes" +.PD +These options control whether the ELF assembler should generate common +symbols with the \f(CW\*(C`STT_COMMON\*(C'\fR type. The default can be controlled +by a configure option \fB\-\-enable\-elf\-stt\-common\fR. +.IP \fB\-\-emulation=\fR\fIname\fR 4 +.IX Item "--emulation=name" +If the assembler is configured to support multiple different target +configurations then this option can be used to select the desired form. +.IP \fB\-f\fR 4 +.IX Item "-f" +"fast"\-\-\-skip whitespace and comment preprocessing (assume source is +compiler output). +.IP \fB\-g\fR 4 +.IX Item "-g" +.PD 0 +.IP \fB\-\-gen\-debug\fR 4 +.IX Item "--gen-debug" +.PD +Generate debugging information for each assembler source line using whichever +debug format is preferred by the target. This currently means either STABS, +ECOFF or DWARF2. When the debug format is DWARF then a \f(CW\*(C`.debug_info\*(C'\fR and +\&\f(CW\*(C`.debug_line\*(C'\fR section is only emitted when the assembly file doesn't +generate one itself. +.IP \fB\-\-gstabs\fR 4 +.IX Item "--gstabs" +Generate stabs debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. +.IP \fB\-\-gstabs+\fR 4 +.IX Item "--gstabs+" +Generate stabs debugging information for each assembler line, with GNU +extensions that probably only gdb can handle, and that could make other +debuggers crash or refuse to read your program. This +may help debugging assembler code. Currently the only GNU extension is +the location of the current working directory at assembling time. +.IP \fB\-\-gdwarf\-2\fR 4 +.IX Item "--gdwarf-2" +Generate DWARF2 debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. Note\-\-\-this +option is only supported by some targets, not all of them. +.IP \fB\-\-gdwarf\-3\fR 4 +.IX Item "--gdwarf-3" +This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it +allows for the possibility of the generation of extra debug information as per +version 3 of the DWARF specification. Note \- enabling this option does not +guarantee the generation of any extra information, the choice to do so is on a +per target basis. +.IP \fB\-\-gdwarf\-4\fR 4 +.IX Item "--gdwarf-4" +This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it +allows for the possibility of the generation of extra debug information as per +version 4 of the DWARF specification. Note \- enabling this option does not +guarantee the generation of any extra information, the choice to do so is on a +per target basis. +.IP \fB\-\-gdwarf\-5\fR 4 +.IX Item "--gdwarf-5" +This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it +allows for the possibility of the generation of extra debug information as per +version 5 of the DWARF specification. Note \- enabling this option does not +guarantee the generation of any extra information, the choice to do so is on a +per target basis. +.IP \fB\-\-gdwarf\-sections\fR 4 +.IX Item "--gdwarf-sections" +Instead of creating a .debug_line section, create a series of +\&.debug_line.\fIfoo\fR sections where \fIfoo\fR is the name of the +corresponding code section. For example a code section called \fI.text.func\fR +will have its dwarf line number information placed into a section called +\&\fI.debug_line.text.func\fR. If the code section is just called \fI.text\fR +then debug line section will still be called just \fI.debug_line\fR without any +suffix. +.IP \fB\-\-gdwarf\-cie\-version=\fR\fIversion\fR 4 +.IX Item "--gdwarf-cie-version=version" +Control which version of DWARF Common Information Entries (CIEs) are produced. +When this flag is not specificed the default is version 1, though some targets +can modify this default. Other possible values for \fIversion\fR are 3 or 4. +.IP \fB\-\-generate\-missing\-build\-notes=yes\fR 4 +.IX Item "--generate-missing-build-notes=yes" +.PD 0 +.IP \fB\-\-generate\-missing\-build\-notes=no\fR 4 +.IX Item "--generate-missing-build-notes=no" +.PD +These options control whether the ELF assembler should generate GNU Build +attribute notes if none are present in the input sources. +The default can be controlled by the \fB\-\-enable\-generate\-build\-notes\fR +configure option. +.IP \fB\-\-gsframe\fR 4 +.IX Item "--gsframe" +.PD 0 +.IP \fB\-\-gsframe\fR 4 +.IX Item "--gsframe" +.PD +Create \fI.sframe\fR section from CFI directives. +.IP "\fB\-\-hash\-size\fR \fIN\fR" 4 +.IX Item "--hash-size N" +Ignored. Supported for command line compatibility with other assemblers. +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Print a summary of the command-line options and exit. +.IP \fB\-\-target\-help\fR 4 +.IX Item "--target-help" +Print a summary of all target specific options and exit. +.IP "\fB\-I\fR \fIdir\fR" 4 +.IX Item "-I dir" +Add directory \fIdir\fR to the search list for \f(CW\*(C`.include\*(C'\fR directives. +.IP \fB\-J\fR 4 +.IX Item "-J" +Don't warn about signed overflow. +.IP \fB\-K\fR 4 +.IX Item "-K" +Issue warnings when difference tables altered for long displacements. +.IP \fB\-L\fR 4 +.IX Item "-L" +.PD 0 +.IP \fB\-\-keep\-locals\fR 4 +.IX Item "--keep-locals" +.PD +Keep (in the symbol table) local symbols. These symbols start with +system-specific local label prefixes, typically \fB.L\fR for ELF systems +or \fBL\fR for traditional a.out systems. +.IP \fB\-\-listing\-lhs\-width=\fR\fInumber\fR 4 +.IX Item "--listing-lhs-width=number" +Set the maximum width, in words, of the output data column for an assembler +listing to \fInumber\fR. +.IP \fB\-\-listing\-lhs\-width2=\fR\fInumber\fR 4 +.IX Item "--listing-lhs-width2=number" +Set the maximum width, in words, of the output data column for continuation +lines in an assembler listing to \fInumber\fR. +.IP \fB\-\-listing\-rhs\-width=\fR\fInumber\fR 4 +.IX Item "--listing-rhs-width=number" +Set the maximum width of an input source line, as displayed in a listing, to +\&\fInumber\fR bytes. +.IP \fB\-\-listing\-cont\-lines=\fR\fInumber\fR 4 +.IX Item "--listing-cont-lines=number" +Set the maximum number of lines printed in a listing for a single line of input +to \fInumber\fR + 1. +.IP \fB\-\-multibyte\-handling=allow\fR 4 +.IX Item "--multibyte-handling=allow" +.PD 0 +.IP \fB\-\-multibyte\-handling=warn\fR 4 +.IX Item "--multibyte-handling=warn" +.IP \fB\-\-multibyte\-handling=warn\-sym\-only\fR 4 +.IX Item "--multibyte-handling=warn-sym-only" +.IP \fB\-\-multibyte\-handling=warn_sym_only\fR 4 +.IX Item "--multibyte-handling=warn_sym_only" +.PD +Controls how the assembler handles multibyte characters in the input. The +default (which can be restored by using the \fBallow\fR argument) is to +allow such characters without complaint. Using the \fBwarn\fR argument will +make the assembler generate a warning message whenever any multibyte character +is encountered. Using the \fBwarn-sym-only\fR argument will only cause a +warning to be generated when a symbol is defined with a name that contains +multibyte characters. (References to undefined symbols will not generate a +warning). +.IP \fB\-\-no\-pad\-sections\fR 4 +.IX Item "--no-pad-sections" +Stop the assembler for padding the ends of output sections to the alignment +of that section. The default is to pad the sections, but this can waste space +which might be needed on targets which have tight memory constraints. +.IP "\fB\-o\fR \fIobjfile\fR" 4 +.IX Item "-o objfile" +Name the object-file output from \fBas\fR \fIobjfile\fR. +.IP \fB\-R\fR 4 +.IX Item "-R" +Fold the data section into the text section. +.IP \fB\-\-reduce\-memory\-overheads\fR 4 +.IX Item "--reduce-memory-overheads" +Ignored. Supported for compatibility with tools that apss the same option to +both the assembler and the linker. +.IP \fB\-\-sectname\-subst\fR 4 +.IX Item "--sectname-subst" +Honor substitution sequences in section names. +.IP \fB\-\-size\-check=error\fR 4 +.IX Item "--size-check=error" +.PD 0 +.IP \fB\-\-size\-check=warning\fR 4 +.IX Item "--size-check=warning" +.PD +Issue an error or warning for invalid ELF .size directive. +.IP \fB\-\-statistics\fR 4 +.IX Item "--statistics" +Print the maximum space (in bytes) and total time (in seconds) used by +assembly. +.IP \fB\-\-strip\-local\-absolute\fR 4 +.IX Item "--strip-local-absolute" +Remove local absolute symbols from the outgoing symbol table. +.IP \fB\-v\fR 4 +.IX Item "-v" +.PD 0 +.IP \fB\-version\fR 4 +.IX Item "-version" +.PD +Print the \fBas\fR version. +.IP \fB\-\-version\fR 4 +.IX Item "--version" +Print the \fBas\fR version and exit. +.IP \fB\-W\fR 4 +.IX Item "-W" +.PD 0 +.IP \fB\-\-no\-warn\fR 4 +.IX Item "--no-warn" +.PD +Suppress warning messages. +.IP \fB\-\-fatal\-warnings\fR 4 +.IX Item "--fatal-warnings" +Treat warnings as errors. +.IP \fB\-\-warn\fR 4 +.IX Item "--warn" +Don't suppress warning messages or treat them as errors. +.IP \fB\-w\fR 4 +.IX Item "-w" +Ignored. +.IP \fB\-x\fR 4 +.IX Item "-x" +Ignored. +.IP \fB\-Z\fR 4 +.IX Item "-Z" +Generate an object file even after errors. +.IP "\fB\-\- |\fR \fIfiles\fR \fB...\fR" 4 +.IX Item "-- | files ..." +Standard input, or source files to assemble. +.PP +The following options are available when as is configured for the +64\-bit mode of the ARM Architecture (AArch64). +.IP \fB\-EB\fR 4 +.IX Item "-EB" +This option specifies that the output generated by the assembler should +be marked as being encoded for a big-endian processor. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +This option specifies that the output generated by the assembler should +be marked as being encoded for a little-endian processor. +.IP \fB\-mabi=\fR\fIabi\fR 4 +.IX Item "-mabi=abi" +Specify which ABI the source code uses. The recognized arguments +are: \f(CW\*(C`ilp32\*(C'\fR and \f(CW\*(C`lp64\*(C'\fR, which decides the generated object +file in ELF32 and ELF64 format respectively. The default is \f(CW\*(C`lp64\*(C'\fR. +.IP \fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR 4 +.IX Item "-mcpu=processor[+extension...]" +This option specifies the target processor. The assembler will issue an error +message if an attempt is made to assemble an instruction which will not execute +on the target processor. The following processor names are recognized: +\&\f(CW\*(C`cortex\-a34\*(C'\fR, +\&\f(CW\*(C`cortex\-a35\*(C'\fR, +\&\f(CW\*(C`cortex\-a53\*(C'\fR, +\&\f(CW\*(C`cortex\-a55\*(C'\fR, +\&\f(CW\*(C`cortex\-a57\*(C'\fR, +\&\f(CW\*(C`cortex\-a65\*(C'\fR, +\&\f(CW\*(C`cortex\-a65ae\*(C'\fR, +\&\f(CW\*(C`cortex\-a72\*(C'\fR, +\&\f(CW\*(C`cortex\-a73\*(C'\fR, +\&\f(CW\*(C`cortex\-a75\*(C'\fR, +\&\f(CW\*(C`cortex\-a76\*(C'\fR, +\&\f(CW\*(C`cortex\-a76ae\*(C'\fR, +\&\f(CW\*(C`cortex\-a77\*(C'\fR, +\&\f(CW\*(C`cortex\-a78\*(C'\fR, +\&\f(CW\*(C`cortex\-a78ae\*(C'\fR, +\&\f(CW\*(C`cortex\-a78c\*(C'\fR, +\&\f(CW\*(C`cortex\-a510\*(C'\fR, +\&\f(CW\*(C`cortex\-a710\*(C'\fR, +\&\f(CW\*(C`ares\*(C'\fR, +\&\f(CW\*(C`exynos\-m1\*(C'\fR, +\&\f(CW\*(C`falkor\*(C'\fR, +\&\f(CW\*(C`neoverse\-n1\*(C'\fR, +\&\f(CW\*(C`neoverse\-n2\*(C'\fR, +\&\f(CW\*(C`neoverse\-e1\*(C'\fR, +\&\f(CW\*(C`neoverse\-v1\*(C'\fR, +\&\f(CW\*(C`qdf24xx\*(C'\fR, +\&\f(CW\*(C`saphira\*(C'\fR, +\&\f(CW\*(C`thunderx\*(C'\fR, +\&\f(CW\*(C`vulcan\*(C'\fR, +\&\f(CW\*(C`xgene1\*(C'\fR +\&\f(CW\*(C`xgene2\*(C'\fR, +\&\f(CW\*(C`cortex\-r82\*(C'\fR, +\&\f(CW\*(C`cortex\-x1\*(C'\fR, +and +\&\f(CW\*(C`cortex\-x2\*(C'\fR. +The special name \f(CW\*(C`all\*(C'\fR may be used to allow the assembler to accept +instructions valid for any supported processor, including all optional +extensions. +.Sp +In addition to the basic instruction set, the assembler can be told to +accept, or restrict, various extension mnemonics that extend the +processor. +.Sp +If some implementations of a particular processor can have an +extension, then then those extensions are automatically enabled. +Consequently, you will not normally have to specify any additional +extensions. +.IP \fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR 4 +.IX Item "-march=architecture[+extension...]" +This option specifies the target architecture. The assembler will +issue an error message if an attempt is made to assemble an +instruction which will not execute on the target architecture. The +following architecture names are recognized: \f(CW\*(C`armv8\-a\*(C'\fR, +\&\f(CW\*(C`armv8.1\-a\*(C'\fR, \f(CW\*(C`armv8.2\-a\*(C'\fR, \f(CW\*(C`armv8.3\-a\*(C'\fR, \f(CW\*(C`armv8.4\-a\*(C'\fR +\&\f(CW\*(C`armv8.5\-a\*(C'\fR, \f(CW\*(C`armv8.6\-a\*(C'\fR, \f(CW\*(C`armv8.7\-a\*(C'\fR, \f(CW\*(C`armv8.8\-a\*(C'\fR, +\&\f(CW\*(C`armv8\-r\*(C'\fR, \f(CW\*(C`armv9\-a\*(C'\fR, \f(CW\*(C`armv9.1\-a\*(C'\fR, \f(CW\*(C`armv9.2\-a\*(C'\fR, +and \f(CW\*(C`armv9.3\-a\*(C'\fR. +.Sp +If both \fB\-mcpu\fR and \fB\-march\fR are specified, the +assembler will use the setting for \fB\-mcpu\fR. If neither are +specified, the assembler will default to \fB\-mcpu=all\fR. +.Sp +The architecture option can be extended with the same instruction set +extension options as the \fB\-mcpu\fR option. Unlike +\&\fB\-mcpu\fR, extensions are not always enabled by default, +.IP \fB\-mverbose\-error\fR 4 +.IX Item "-mverbose-error" +This option enables verbose error messages for AArch64 gas. This option +is enabled by default. +.IP \fB\-mno\-verbose\-error\fR 4 +.IX Item "-mno-verbose-error" +This option disables verbose error messages in AArch64 gas. +.PP +The following options are available when as is configured for an Alpha +processor. +.IP \fB\-m\fR\fIcpu\fR 4 +.IX Item "-mcpu" +This option specifies the target processor. If an attempt is made to +assemble an instruction which will not execute on the target processor, +the assembler may either expand the instruction as a macro or issue an +error message. This option is equivalent to the \f(CW\*(C`.arch\*(C'\fR directive. +.Sp +The following processor names are recognized: +\&\f(CW21064\fR, +\&\f(CW\*(C`21064a\*(C'\fR, +\&\f(CW21066\fR, +\&\f(CW21068\fR, +\&\f(CW21164\fR, +\&\f(CW\*(C`21164a\*(C'\fR, +\&\f(CW\*(C`21164pc\*(C'\fR, +\&\f(CW21264\fR, +\&\f(CW\*(C`21264a\*(C'\fR, +\&\f(CW\*(C`21264b\*(C'\fR, +\&\f(CW\*(C`ev4\*(C'\fR, +\&\f(CW\*(C`ev5\*(C'\fR, +\&\f(CW\*(C`lca45\*(C'\fR, +\&\f(CW\*(C`ev5\*(C'\fR, +\&\f(CW\*(C`ev56\*(C'\fR, +\&\f(CW\*(C`pca56\*(C'\fR, +\&\f(CW\*(C`ev6\*(C'\fR, +\&\f(CW\*(C`ev67\*(C'\fR, +\&\f(CW\*(C`ev68\*(C'\fR. +The special name \f(CW\*(C`all\*(C'\fR may be used to allow the assembler to accept +instructions valid for any Alpha processor. +.Sp +In order to support existing practice in OSF/1 with respect to \f(CW\*(C`.arch\*(C'\fR, +and existing practice within \fBMILO\fR (the Linux ARC bootloader), the +numbered processor names (e.g. 21064) enable the processor-specific PALcode +instructions, while the "electro-vlasic" names (e.g. \f(CW\*(C`ev4\*(C'\fR) do not. +.IP \fB\-mdebug\fR 4 +.IX Item "-mdebug" +.PD 0 +.IP \fB\-no\-mdebug\fR 4 +.IX Item "-no-mdebug" +.PD +Enables or disables the generation of \f(CW\*(C`.mdebug\*(C'\fR encapsulation for +stabs directives and procedure descriptors. The default is to automatically +enable \f(CW\*(C`.mdebug\*(C'\fR when the first stabs directive is seen. +.IP \fB\-relax\fR 4 +.IX Item "-relax" +This option forces all relocations to be put into the object file, instead +of saving space and resolving some relocations at assembly time. Note that +this option does not propagate all symbol arithmetic into the object file, +because not all symbol arithmetic can be represented. However, the option +can still be useful in specific applications. +.IP \fB\-replace\fR 4 +.IX Item "-replace" +.PD 0 +.IP \fB\-noreplace\fR 4 +.IX Item "-noreplace" +.PD +Enables or disables the optimization of procedure calls, both at assemblage +and at link time. These options are only available for VMS targets and +\&\f(CW\*(C`\-replace\*(C'\fR is the default. See section 1.4.1 of the OpenVMS Linker +Utility Manual. +.IP \fB\-g\fR 4 +.IX Item "-g" +This option is used when the compiler generates debug information. When +\&\fBgcc\fR is using \fBmips-tfile\fR to generate debug +information for ECOFF, local labels must be passed through to the object +file. Otherwise this option has no effect. +.IP \fB\-G\fR\fIsize\fR 4 +.IX Item "-Gsize" +A local common symbol larger than \fIsize\fR is placed in \f(CW\*(C`.bss\*(C'\fR, +while smaller symbols are placed in \f(CW\*(C`.sbss\*(C'\fR. +.IP \fB\-F\fR 4 +.IX Item "-F" +.PD 0 +.IP \fB\-32addr\fR 4 +.IX Item "-32addr" +.PD +These options are ignored for backward compatibility. +.PP +The following options are available when as is configured for an ARC +processor. +.IP \fB\-mcpu=\fR\fIcpu\fR 4 +.IX Item "-mcpu=cpu" +This option selects the core processor variant. +.IP "\fB\-EB | \-EL\fR" 4 +.IX Item "-EB | -EL" +Select either big-endian (\-EB) or little-endian (\-EL) output. +.IP \fB\-mcode\-density\fR 4 +.IX Item "-mcode-density" +Enable Code Density extension instructions. +.PP +The following options are available when as is configured for the ARM +processor family. +.IP \fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR 4 +.IX Item "-mcpu=processor[+extension...]" +Specify which ARM processor variant is the target. +.IP \fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR 4 +.IX Item "-march=architecture[+extension...]" +Specify which ARM architecture variant is used by the target. +.IP \fB\-mfpu=\fR\fIfloating-point-format\fR 4 +.IX Item "-mfpu=floating-point-format" +Select which Floating Point architecture is the target. +.IP \fB\-mfloat\-abi=\fR\fIabi\fR 4 +.IX Item "-mfloat-abi=abi" +Select which floating point ABI is in use. +.IP \fB\-mthumb\fR 4 +.IX Item "-mthumb" +Enable Thumb only instruction decoding. +.IP "\fB\-mapcs\-32 | \-mapcs\-26 | \-mapcs\-float | \-mapcs\-reentrant\fR" 4 +.IX Item "-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant" +Select which procedure calling convention is in use. +.IP "\fB\-EB | \-EL\fR" 4 +.IX Item "-EB | -EL" +Select either big-endian (\-EB) or little-endian (\-EL) output. +.IP \fB\-mthumb\-interwork\fR 4 +.IX Item "-mthumb-interwork" +Specify that the code has been generated with interworking between Thumb and +ARM code in mind. +.IP \fB\-mccs\fR 4 +.IX Item "-mccs" +Turns on CodeComposer Studio assembly syntax compatibility mode. +.IP \fB\-k\fR 4 +.IX Item "-k" +Specify that PIC code has been generated. +.PP +The following options are available when as is configured for +the Blackfin processor family. +.IP \fB\-mcpu=\fR\fIprocessor\fR[\fB\-\fR\fIsirevision\fR] 4 +.IX Item "-mcpu=processor[-sirevision]" +This option specifies the target processor. The optional \fIsirevision\fR +is not used in assembler. It's here such that GCC can easily pass down its +\&\f(CW\*(C`\-mcpu=\*(C'\fR option. The assembler will issue an +error message if an attempt is made to assemble an instruction which +will not execute on the target processor. The following processor names are +recognized: +\&\f(CW\*(C`bf504\*(C'\fR, +\&\f(CW\*(C`bf506\*(C'\fR, +\&\f(CW\*(C`bf512\*(C'\fR, +\&\f(CW\*(C`bf514\*(C'\fR, +\&\f(CW\*(C`bf516\*(C'\fR, +\&\f(CW\*(C`bf518\*(C'\fR, +\&\f(CW\*(C`bf522\*(C'\fR, +\&\f(CW\*(C`bf523\*(C'\fR, +\&\f(CW\*(C`bf524\*(C'\fR, +\&\f(CW\*(C`bf525\*(C'\fR, +\&\f(CW\*(C`bf526\*(C'\fR, +\&\f(CW\*(C`bf527\*(C'\fR, +\&\f(CW\*(C`bf531\*(C'\fR, +\&\f(CW\*(C`bf532\*(C'\fR, +\&\f(CW\*(C`bf533\*(C'\fR, +\&\f(CW\*(C`bf534\*(C'\fR, +\&\f(CW\*(C`bf535\*(C'\fR (not implemented yet), +\&\f(CW\*(C`bf536\*(C'\fR, +\&\f(CW\*(C`bf537\*(C'\fR, +\&\f(CW\*(C`bf538\*(C'\fR, +\&\f(CW\*(C`bf539\*(C'\fR, +\&\f(CW\*(C`bf542\*(C'\fR, +\&\f(CW\*(C`bf542m\*(C'\fR, +\&\f(CW\*(C`bf544\*(C'\fR, +\&\f(CW\*(C`bf544m\*(C'\fR, +\&\f(CW\*(C`bf547\*(C'\fR, +\&\f(CW\*(C`bf547m\*(C'\fR, +\&\f(CW\*(C`bf548\*(C'\fR, +\&\f(CW\*(C`bf548m\*(C'\fR, +\&\f(CW\*(C`bf549\*(C'\fR, +\&\f(CW\*(C`bf549m\*(C'\fR, +\&\f(CW\*(C`bf561\*(C'\fR, +and +\&\f(CW\*(C`bf592\*(C'\fR. +.IP \fB\-mfdpic\fR 4 +.IX Item "-mfdpic" +Assemble for the FDPIC ABI. +.IP \fB\-mno\-fdpic\fR 4 +.IX Item "-mno-fdpic" +.PD 0 +.IP \fB\-mnopic\fR 4 +.IX Item "-mnopic" +.PD +Disable \-mfdpic. +.PP +The following options are available when as is configured for +the Linux kernel BPF processor family. +.PP +\&\f(CW@chapter\fR BPF Dependent Features +.SS Options +.IX Subsection "Options" +.IP \fB\-EB\fR 4 +.IX Item "-EB" +This option specifies that the assembler should emit big-endian eBPF. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +This option specifies that the assembler should emit little-endian +eBPF. +.PP +Note that if no endianness option is specified in the command line, +the host endianness is used. +See the info pages for documentation of the CRIS-specific options. +.PP +The following options are available when as is configured for +the C\-SKY processor family. +.IP \fB\-march=\fR\fIarchname\fR 4 +.IX Item "-march=archname" +Assemble for architecture \fIarchname\fR. The \fB\-\-help\fR option +lists valid values for \fIarchname\fR. +.IP \fB\-mcpu=\fR\fIcpuname\fR 4 +.IX Item "-mcpu=cpuname" +Assemble for architecture \fIcpuname\fR. The \fB\-\-help\fR option +lists valid values for \fIcpuname\fR. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +.PD 0 +.IP \fB\-mlittle\-endian\fR 4 +.IX Item "-mlittle-endian" +.PD +Generate little-endian output. +.IP \fB\-EB\fR 4 +.IX Item "-EB" +.PD 0 +.IP \fB\-mbig\-endian\fR 4 +.IX Item "-mbig-endian" +.PD +Generate big-endian output. +.IP \fB\-fpic\fR 4 +.IX Item "-fpic" +.PD 0 +.IP \fB\-pic\fR 4 +.IX Item "-pic" +.PD +Generate position-independent code. +.IP \fB\-mljump\fR 4 +.IX Item "-mljump" +.PD 0 +.IP \fB\-mno\-ljump\fR 4 +.IX Item "-mno-ljump" +.PD +Enable/disable transformation of the short branch instructions +\&\f(CW\*(C`jbf\*(C'\fR, \f(CW\*(C`jbt\*(C'\fR, and \f(CW\*(C`jbr\*(C'\fR to \f(CW\*(C`jmpi\*(C'\fR. +This option is for V2 processors only. +It is ignored on CK801 and CK802 targets, which do not support the \f(CW\*(C`jmpi\*(C'\fR +instruction, and is enabled by default for other processors. +.IP \fB\-mbranch\-stub\fR 4 +.IX Item "-mbranch-stub" +.PD 0 +.IP \fB\-mno\-branch\-stub\fR 4 +.IX Item "-mno-branch-stub" +.PD +Pass through \f(CW\*(C`R_CKCORE_PCREL_IMM26BY2\*(C'\fR relocations for \f(CW\*(C`bsr\*(C'\fR +instructions to the linker. +.Sp +This option is only available for bare-metal C\-SKY V2 ELF targets, +where it is enabled by default. It cannot be used in code that will be +dynamically linked against shared libraries. +.IP \fB\-force2bsr\fR 4 +.IX Item "-force2bsr" +.PD 0 +.IP \fB\-mforce2bsr\fR 4 +.IX Item "-mforce2bsr" +.IP \fB\-no\-force2bsr\fR 4 +.IX Item "-no-force2bsr" +.IP \fB\-mno\-force2bsr\fR 4 +.IX Item "-mno-force2bsr" +.PD +Enable/disable transformation of \f(CW\*(C`jbsr\*(C'\fR instructions to \f(CW\*(C`bsr\*(C'\fR. +This option is always enabled (and \fB\-mno\-force2bsr\fR is ignored) +for CK801/CK802 targets. It is also always enabled when +\&\fB\-mbranch\-stub\fR is in effect. +.IP \fB\-jsri2bsr\fR 4 +.IX Item "-jsri2bsr" +.PD 0 +.IP \fB\-mjsri2bsr\fR 4 +.IX Item "-mjsri2bsr" +.IP \fB\-no\-jsri2bsr\fR 4 +.IX Item "-no-jsri2bsr" +.IP \fB\-mno\-jsri2bsr\fR 4 +.IX Item "-mno-jsri2bsr" +.PD +Enable/disable transformation of \f(CW\*(C`jsri\*(C'\fR instructions to \f(CW\*(C`bsr\*(C'\fR. +This option is enabled by default. +.IP \fB\-mnolrw\fR 4 +.IX Item "-mnolrw" +.PD 0 +.IP \fB\-mno\-lrw\fR 4 +.IX Item "-mno-lrw" +.PD +Enable/disable transformation of \f(CW\*(C`lrw\*(C'\fR instructions into a +\&\f(CW\*(C`movih\*(C'\fR/\f(CW\*(C`ori\*(C'\fR pair. +.IP \fB\-melrw\fR 4 +.IX Item "-melrw" +.PD 0 +.IP \fB\-mno\-elrw\fR 4 +.IX Item "-mno-elrw" +.PD +Enable/disable extended \f(CW\*(C`lrw\*(C'\fR instructions. +This option is enabled by default for CK800\-series processors. +.IP \fB\-mlaf\fR 4 +.IX Item "-mlaf" +.PD 0 +.IP \fB\-mliterals\-after\-func\fR 4 +.IX Item "-mliterals-after-func" +.IP \fB\-mno\-laf\fR 4 +.IX Item "-mno-laf" +.IP \fB\-mno\-literals\-after\-func\fR 4 +.IX Item "-mno-literals-after-func" +.PD +Enable/disable placement of literal pools after each function. +.IP \fB\-mlabr\fR 4 +.IX Item "-mlabr" +.PD 0 +.IP \fB\-mliterals\-after\-br\fR 4 +.IX Item "-mliterals-after-br" +.IP \fB\-mno\-labr\fR 4 +.IX Item "-mno-labr" +.IP \fB\-mnoliterals\-after\-br\fR 4 +.IX Item "-mnoliterals-after-br" +.PD +Enable/disable placement of literal pools after unconditional branches. +This option is enabled by default. +.IP \fB\-mistack\fR 4 +.IX Item "-mistack" +.PD 0 +.IP \fB\-mno\-istack\fR 4 +.IX Item "-mno-istack" +.PD +Enable/disable interrupt stack instructions. This option is enabled by +default on CK801, CK802, and CK802 processors. +.PP +The following options explicitly enable certain optional instructions. +These features are also enabled implicitly by using \f(CW\*(C`\-mcpu=\*(C'\fR to specify +a processor that supports it. +.IP \fB\-mhard\-float\fR 4 +.IX Item "-mhard-float" +Enable hard float instructions. +.IP \fB\-mmp\fR 4 +.IX Item "-mmp" +Enable multiprocessor instructions. +.IP \fB\-mcp\fR 4 +.IX Item "-mcp" +Enable coprocessor instructions. +.IP \fB\-mcache\fR 4 +.IX Item "-mcache" +Enable cache prefetch instruction. +.IP \fB\-msecurity\fR 4 +.IX Item "-msecurity" +Enable C\-SKY security instructions. +.IP \fB\-mtrust\fR 4 +.IX Item "-mtrust" +Enable C\-SKY trust instructions. +.IP \fB\-mdsp\fR 4 +.IX Item "-mdsp" +Enable DSP instructions. +.IP \fB\-medsp\fR 4 +.IX Item "-medsp" +Enable enhanced DSP instructions. +.IP \fB\-mvdsp\fR 4 +.IX Item "-mvdsp" +Enable vector DSP instructions. +.PP +The following options are available when as is configured for +an Epiphany processor. +.IP \fB\-mepiphany\fR 4 +.IX Item "-mepiphany" +Specifies that the both 32 and 16 bit instructions are allowed. This is the +default behavior. +.IP \fB\-mepiphany16\fR 4 +.IX Item "-mepiphany16" +Restricts the permitted instructions to just the 16 bit set. +.PP +The following options are available when as is configured for an H8/300 +processor. +\&\f(CW@chapter\fR H8/300 Dependent Features +.SS Options +.IX Subsection "Options" +The Renesas H8/300 version of \f(CW\*(C`as\*(C'\fR has one +machine-dependent option: +.IP \fB\-h\-tick\-hex\fR 4 +.IX Item "-h-tick-hex" +Support H'00 style hex constants in addition to 0x00 style. +.IP \fB\-mach=\fR\fIname\fR 4 +.IX Item "-mach=name" +Sets the H8300 machine variant. The following machine names +are recognised: +\&\f(CW\*(C`h8300h\*(C'\fR, +\&\f(CW\*(C`h8300hn\*(C'\fR, +\&\f(CW\*(C`h8300s\*(C'\fR, +\&\f(CW\*(C`h8300sn\*(C'\fR, +\&\f(CW\*(C`h8300sx\*(C'\fR and +\&\f(CW\*(C`h8300sxn\*(C'\fR. +.PP +The following options are available when as is configured for +an i386 processor. +.IP "\fB\-\-32 | \-\-x32 | \-\-64\fR" 4 +.IX Item "--32 | --x32 | --64" +Select the word size, either 32 bits or 64 bits. \fB\-\-32\fR +implies Intel i386 architecture, while \fB\-\-x32\fR and \fB\-\-64\fR +imply AMD x86\-64 architecture with 32\-bit or 64\-bit word-size +respectively. +.Sp +These options are only available with the ELF object file format, and +require that the necessary BFD support has been included (on a 32\-bit +platform you have to add \-\-enable\-64\-bit\-bfd to configure enable 64\-bit +usage and use x86\-64 as target platform). +.IP \fB\-n\fR 4 +.IX Item "-n" +By default, x86 GAS replaces multiple nop instructions used for +alignment within code sections with multi-byte nop instructions such +as leal 0(%esi,1),%esi. This switch disables the optimization if a single +byte nop (0x90) is explicitly specified as the fill byte for alignment. +.IP \fB\-\-divide\fR 4 +.IX Item "--divide" +On SVR4\-derived platforms, the character \fB/\fR is treated as a comment +character, which means that it cannot be used in expressions. The +\&\fB\-\-divide\fR option turns \fB/\fR into a normal character. This does +not disable \fB/\fR at the beginning of a line starting a comment, or +affect using \fB#\fR for starting a comment. +.IP \fB\-march=\fR\fICPU\fR\fB[+\fR\fIEXTENSION\fR\fB...]\fR 4 +.IX Item "-march=CPU[+EXTENSION...]" +This option specifies the target processor. The assembler will +issue an error message if an attempt is made to assemble an instruction +which will not execute on the target processor. The following +processor names are recognized: +\&\f(CW\*(C`i8086\*(C'\fR, +\&\f(CW\*(C`i186\*(C'\fR, +\&\f(CW\*(C`i286\*(C'\fR, +\&\f(CW\*(C`i386\*(C'\fR, +\&\f(CW\*(C`i486\*(C'\fR, +\&\f(CW\*(C`i586\*(C'\fR, +\&\f(CW\*(C`i686\*(C'\fR, +\&\f(CW\*(C`pentium\*(C'\fR, +\&\f(CW\*(C`pentiumpro\*(C'\fR, +\&\f(CW\*(C`pentiumii\*(C'\fR, +\&\f(CW\*(C`pentiumiii\*(C'\fR, +\&\f(CW\*(C`pentium4\*(C'\fR, +\&\f(CW\*(C`prescott\*(C'\fR, +\&\f(CW\*(C`nocona\*(C'\fR, +\&\f(CW\*(C`core\*(C'\fR, +\&\f(CW\*(C`core2\*(C'\fR, +\&\f(CW\*(C`corei7\*(C'\fR, +\&\f(CW\*(C`iamcu\*(C'\fR, +\&\f(CW\*(C`k6\*(C'\fR, +\&\f(CW\*(C`k6_2\*(C'\fR, +\&\f(CW\*(C`athlon\*(C'\fR, +\&\f(CW\*(C`opteron\*(C'\fR, +\&\f(CW\*(C`k8\*(C'\fR, +\&\f(CW\*(C`amdfam10\*(C'\fR, +\&\f(CW\*(C`bdver1\*(C'\fR, +\&\f(CW\*(C`bdver2\*(C'\fR, +\&\f(CW\*(C`bdver3\*(C'\fR, +\&\f(CW\*(C`bdver4\*(C'\fR, +\&\f(CW\*(C`znver1\*(C'\fR, +\&\f(CW\*(C`znver2\*(C'\fR, +\&\f(CW\*(C`znver3\*(C'\fR, +\&\f(CW\*(C`znver4\*(C'\fR, +\&\f(CW\*(C`btver1\*(C'\fR, +\&\f(CW\*(C`btver2\*(C'\fR, +\&\f(CW\*(C`generic32\*(C'\fR and +\&\f(CW\*(C`generic64\*(C'\fR. +.Sp +In addition to the basic instruction set, the assembler can be told to +accept various extension mnemonics. For example, +\&\f(CW\*(C`\-march=i686+sse4+vmx\*(C'\fR extends \fIi686\fR with \fIsse4\fR and +\&\fIvmx\fR. The following extensions are currently supported: +\&\f(CW8087\fR, +\&\f(CW287\fR, +\&\f(CW387\fR, +\&\f(CW687\fR, +\&\f(CW\*(C`cmov\*(C'\fR, +\&\f(CW\*(C`fxsr\*(C'\fR, +\&\f(CW\*(C`mmx\*(C'\fR, +\&\f(CW\*(C`sse\*(C'\fR, +\&\f(CW\*(C`sse2\*(C'\fR, +\&\f(CW\*(C`sse3\*(C'\fR, +\&\f(CW\*(C`sse4a\*(C'\fR, +\&\f(CW\*(C`ssse3\*(C'\fR, +\&\f(CW\*(C`sse4.1\*(C'\fR, +\&\f(CW\*(C`sse4.2\*(C'\fR, +\&\f(CW\*(C`sse4\*(C'\fR, +\&\f(CW\*(C`avx\*(C'\fR, +\&\f(CW\*(C`avx2\*(C'\fR, +\&\f(CW\*(C`lahf_sahf\*(C'\fR, +\&\f(CW\*(C`monitor\*(C'\fR, +\&\f(CW\*(C`adx\*(C'\fR, +\&\f(CW\*(C`rdseed\*(C'\fR, +\&\f(CW\*(C`prfchw\*(C'\fR, +\&\f(CW\*(C`smap\*(C'\fR, +\&\f(CW\*(C`mpx\*(C'\fR, +\&\f(CW\*(C`sha\*(C'\fR, +\&\f(CW\*(C`rdpid\*(C'\fR, +\&\f(CW\*(C`ptwrite\*(C'\fR, +\&\f(CW\*(C`cet\*(C'\fR, +\&\f(CW\*(C`gfni\*(C'\fR, +\&\f(CW\*(C`vaes\*(C'\fR, +\&\f(CW\*(C`vpclmulqdq\*(C'\fR, +\&\f(CW\*(C`prefetchwt1\*(C'\fR, +\&\f(CW\*(C`clflushopt\*(C'\fR, +\&\f(CW\*(C`se1\*(C'\fR, +\&\f(CW\*(C`clwb\*(C'\fR, +\&\f(CW\*(C`movdiri\*(C'\fR, +\&\f(CW\*(C`movdir64b\*(C'\fR, +\&\f(CW\*(C`enqcmd\*(C'\fR, +\&\f(CW\*(C`serialize\*(C'\fR, +\&\f(CW\*(C`tsxldtrk\*(C'\fR, +\&\f(CW\*(C`kl\*(C'\fR, +\&\f(CW\*(C`widekl\*(C'\fR, +\&\f(CW\*(C`hreset\*(C'\fR, +\&\f(CW\*(C`avx512f\*(C'\fR, +\&\f(CW\*(C`avx512cd\*(C'\fR, +\&\f(CW\*(C`avx512er\*(C'\fR, +\&\f(CW\*(C`avx512pf\*(C'\fR, +\&\f(CW\*(C`avx512vl\*(C'\fR, +\&\f(CW\*(C`avx512bw\*(C'\fR, +\&\f(CW\*(C`avx512dq\*(C'\fR, +\&\f(CW\*(C`avx512ifma\*(C'\fR, +\&\f(CW\*(C`avx512vbmi\*(C'\fR, +\&\f(CW\*(C`avx512_4fmaps\*(C'\fR, +\&\f(CW\*(C`avx512_4vnniw\*(C'\fR, +\&\f(CW\*(C`avx512_vpopcntdq\*(C'\fR, +\&\f(CW\*(C`avx512_vbmi2\*(C'\fR, +\&\f(CW\*(C`avx512_vnni\*(C'\fR, +\&\f(CW\*(C`avx512_bitalg\*(C'\fR, +\&\f(CW\*(C`avx512_vp2intersect\*(C'\fR, +\&\f(CW\*(C`tdx\*(C'\fR, +\&\f(CW\*(C`avx512_bf16\*(C'\fR, +\&\f(CW\*(C`avx_vnni\*(C'\fR, +\&\f(CW\*(C`avx512_fp16\*(C'\fR, +\&\f(CW\*(C`prefetchi\*(C'\fR, +\&\f(CW\*(C`avx_ifma\*(C'\fR, +\&\f(CW\*(C`avx_vnni_int8\*(C'\fR, +\&\f(CW\*(C`cmpccxadd\*(C'\fR, +\&\f(CW\*(C`wrmsrns\*(C'\fR, +\&\f(CW\*(C`msrlist\*(C'\fR, +\&\f(CW\*(C`avx_ne_convert\*(C'\fR, +\&\f(CW\*(C`rao_int\*(C'\fR, +\&\f(CW\*(C`fred\*(C'\fR, +\&\f(CW\*(C`lkgs\*(C'\fR, +\&\f(CW\*(C`avx10.1\*(C'\fR, +\&\f(CW\*(C`avx10.1/512\*(C'\fR, +\&\f(CW\*(C`avx10.1/256\*(C'\fR, +\&\f(CW\*(C`avx10.1/128\*(C'\fR, +\&\f(CW\*(C`amx_int8\*(C'\fR, +\&\f(CW\*(C`amx_bf16\*(C'\fR, +\&\f(CW\*(C`amx_fp16\*(C'\fR, +\&\f(CW\*(C`amx_complex\*(C'\fR, +\&\f(CW\*(C`amx_tile\*(C'\fR, +\&\f(CW\*(C`vmx\*(C'\fR, +\&\f(CW\*(C`vmfunc\*(C'\fR, +\&\f(CW\*(C`smx\*(C'\fR, +\&\f(CW\*(C`xsave\*(C'\fR, +\&\f(CW\*(C`xsaveopt\*(C'\fR, +\&\f(CW\*(C`xsavec\*(C'\fR, +\&\f(CW\*(C`xsaves\*(C'\fR, +\&\f(CW\*(C`aes\*(C'\fR, +\&\f(CW\*(C`pclmul\*(C'\fR, +\&\f(CW\*(C`fsgsbase\*(C'\fR, +\&\f(CW\*(C`rdrnd\*(C'\fR, +\&\f(CW\*(C`f16c\*(C'\fR, +\&\f(CW\*(C`bmi2\*(C'\fR, +\&\f(CW\*(C`fma\*(C'\fR, +\&\f(CW\*(C`movbe\*(C'\fR, +\&\f(CW\*(C`ept\*(C'\fR, +\&\f(CW\*(C`lzcnt\*(C'\fR, +\&\f(CW\*(C`popcnt\*(C'\fR, +\&\f(CW\*(C`hle\*(C'\fR, +\&\f(CW\*(C`rtm\*(C'\fR, +\&\f(CW\*(C`tsx\*(C'\fR, +\&\f(CW\*(C`invpcid\*(C'\fR, +\&\f(CW\*(C`clflush\*(C'\fR, +\&\f(CW\*(C`mwaitx\*(C'\fR, +\&\f(CW\*(C`clzero\*(C'\fR, +\&\f(CW\*(C`wbnoinvd\*(C'\fR, +\&\f(CW\*(C`pconfig\*(C'\fR, +\&\f(CW\*(C`waitpkg\*(C'\fR, +\&\f(CW\*(C`uintr\*(C'\fR, +\&\f(CW\*(C`cldemote\*(C'\fR, +\&\f(CW\*(C`rdpru\*(C'\fR, +\&\f(CW\*(C`mcommit\*(C'\fR, +\&\f(CW\*(C`sev_es\*(C'\fR, +\&\f(CW\*(C`lwp\*(C'\fR, +\&\f(CW\*(C`fma4\*(C'\fR, +\&\f(CW\*(C`xop\*(C'\fR, +\&\f(CW\*(C`cx16\*(C'\fR, +\&\f(CW\*(C`syscall\*(C'\fR, +\&\f(CW\*(C`rdtscp\*(C'\fR, +\&\f(CW\*(C`3dnow\*(C'\fR, +\&\f(CW\*(C`3dnowa\*(C'\fR, +\&\f(CW\*(C`sse4a\*(C'\fR, +\&\f(CW\*(C`sse5\*(C'\fR, +\&\f(CW\*(C`snp\*(C'\fR, +\&\f(CW\*(C`invlpgb\*(C'\fR, +\&\f(CW\*(C`tlbsync\*(C'\fR, +\&\f(CW\*(C`svme\*(C'\fR and +\&\f(CW\*(C`padlock\*(C'\fR. +Note that these extension mnemonics can be prefixed with \f(CW\*(C`no\*(C'\fR to revoke +the respective (and any dependent) functionality. Note further that the +suffixes permitted on \f(CW\*(C`\-march=avx10.\*(C'\fR enforce a vector length +restriction, i.e. despite these otherwise being "enabling" options, using +these suffixes will disable all insns with wider vector or mask register +operands. +.Sp +When the \f(CW\*(C`.arch\*(C'\fR directive is used with \fB\-march\fR, the +\&\f(CW\*(C`.arch\*(C'\fR directive will take precedent. +.IP \fB\-mtune=\fR\fICPU\fR 4 +.IX Item "-mtune=CPU" +This option specifies a processor to optimize for. When used in +conjunction with the \fB\-march\fR option, only instructions +of the processor specified by the \fB\-march\fR option will be +generated. +.Sp +Valid \fICPU\fR values are identical to the processor list of +\&\fB\-march=\fR\fICPU\fR. +.IP \fB\-msse2avx\fR 4 +.IX Item "-msse2avx" +This option specifies that the assembler should encode SSE instructions +with VEX prefix. +.IP \fB\-muse\-unaligned\-vector\-move\fR 4 +.IX Item "-muse-unaligned-vector-move" +This option specifies that the assembler should encode aligned vector +move as unaligned vector move. +.IP \fB\-msse\-check=\fR\fInone\fR 4 +.IX Item "-msse-check=none" +.PD 0 +.IP \fB\-msse\-check=\fR\fIwarning\fR 4 +.IX Item "-msse-check=warning" +.IP \fB\-msse\-check=\fR\fIerror\fR 4 +.IX Item "-msse-check=error" +.PD +These options control if the assembler should check SSE instructions. +\&\fB\-msse\-check=\fR\fInone\fR will make the assembler not to check SSE +instructions, which is the default. \fB\-msse\-check=\fR\fIwarning\fR +will make the assembler issue a warning for any SSE instruction. +\&\fB\-msse\-check=\fR\fIerror\fR will make the assembler issue an error +for any SSE instruction. +.IP \fB\-mavxscalar=\fR\fI128\fR 4 +.IX Item "-mavxscalar=128" +.PD 0 +.IP \fB\-mavxscalar=\fR\fI256\fR 4 +.IX Item "-mavxscalar=256" +.PD +These options control how the assembler should encode scalar AVX +instructions. \fB\-mavxscalar=\fR\fI128\fR will encode scalar +AVX instructions with 128bit vector length, which is the default. +\&\fB\-mavxscalar=\fR\fI256\fR will encode scalar AVX instructions +with 256bit vector length. +.Sp +WARNING: Don't use this for production code \- due to CPU errata the +resulting code may not work on certain models. +.IP \fB\-mvexwig=\fR\fI0\fR 4 +.IX Item "-mvexwig=0" +.PD 0 +.IP \fB\-mvexwig=\fR\fI1\fR 4 +.IX Item "-mvexwig=1" +.PD +These options control how the assembler should encode VEX.W\-ignored (WIG) +VEX instructions. \fB\-mvexwig=\fR\fI0\fR will encode WIG VEX +instructions with vex.w = 0, which is the default. +\&\fB\-mvexwig=\fR\fI1\fR will encode WIG EVEX instructions with +vex.w = 1. +.Sp +WARNING: Don't use this for production code \- due to CPU errata the +resulting code may not work on certain models. +.IP \fB\-mevexlig=\fR\fI128\fR 4 +.IX Item "-mevexlig=128" +.PD 0 +.IP \fB\-mevexlig=\fR\fI256\fR 4 +.IX Item "-mevexlig=256" +.IP \fB\-mevexlig=\fR\fI512\fR 4 +.IX Item "-mevexlig=512" +.PD +These options control how the assembler should encode length-ignored +(LIG) EVEX instructions. \fB\-mevexlig=\fR\fI128\fR will encode LIG +EVEX instructions with 128bit vector length, which is the default. +\&\fB\-mevexlig=\fR\fI256\fR and \fB\-mevexlig=\fR\fI512\fR will +encode LIG EVEX instructions with 256bit and 512bit vector length, +respectively. +.IP \fB\-mevexwig=\fR\fI0\fR 4 +.IX Item "-mevexwig=0" +.PD 0 +.IP \fB\-mevexwig=\fR\fI1\fR 4 +.IX Item "-mevexwig=1" +.PD +These options control how the assembler should encode w\-ignored (WIG) +EVEX instructions. \fB\-mevexwig=\fR\fI0\fR will encode WIG +EVEX instructions with evex.w = 0, which is the default. +\&\fB\-mevexwig=\fR\fI1\fR will encode WIG EVEX instructions with +evex.w = 1. +.IP \fB\-mmnemonic=\fR\fIatt\fR 4 +.IX Item "-mmnemonic=att" +.PD 0 +.IP \fB\-mmnemonic=\fR\fIintel\fR 4 +.IX Item "-mmnemonic=intel" +.PD +This option specifies instruction mnemonic for matching instructions. +The \f(CW\*(C`.att_mnemonic\*(C'\fR and \f(CW\*(C`.intel_mnemonic\*(C'\fR directives will +take precedent. +.IP \fB\-msyntax=\fR\fIatt\fR 4 +.IX Item "-msyntax=att" +.PD 0 +.IP \fB\-msyntax=\fR\fIintel\fR 4 +.IX Item "-msyntax=intel" +.PD +This option specifies instruction syntax when processing instructions. +The \f(CW\*(C`.att_syntax\*(C'\fR and \f(CW\*(C`.intel_syntax\*(C'\fR directives will +take precedent. +.IP \fB\-mnaked\-reg\fR 4 +.IX Item "-mnaked-reg" +This option specifies that registers don't require a \fB%\fR prefix. +The \f(CW\*(C`.att_syntax\*(C'\fR and \f(CW\*(C`.intel_syntax\*(C'\fR directives will take precedent. +.IP \fB\-madd\-bnd\-prefix\fR 4 +.IX Item "-madd-bnd-prefix" +This option forces the assembler to add BND prefix to all branches, even +if such prefix was not explicitly specified in the source code. +.IP \fB\-mno\-shared\fR 4 +.IX Item "-mno-shared" +On ELF target, the assembler normally optimizes out non-PLT relocations +against defined non-weak global branch targets with default visibility. +The \fB\-mshared\fR option tells the assembler to generate code which +may go into a shared library where all non-weak global branch targets +with default visibility can be preempted. The resulting code is +slightly bigger. This option only affects the handling of branch +instructions. +.IP \fB\-mbig\-obj\fR 4 +.IX Item "-mbig-obj" +On PE/COFF target this option forces the use of big object file +format, which allows more than 32768 sections. +.IP \fB\-momit\-lock\-prefix=\fR\fIno\fR 4 +.IX Item "-momit-lock-prefix=no" +.PD 0 +.IP \fB\-momit\-lock\-prefix=\fR\fIyes\fR 4 +.IX Item "-momit-lock-prefix=yes" +.PD +These options control how the assembler should encode lock prefix. +This option is intended as a workaround for processors, that fail on +lock prefix. This option can only be safely used with single-core, +single-thread computers +\&\fB\-momit\-lock\-prefix=\fR\fIyes\fR will omit all lock prefixes. +\&\fB\-momit\-lock\-prefix=\fR\fIno\fR will encode lock prefix as usual, +which is the default. +.IP \fB\-mfence\-as\-lock\-add=\fR\fIno\fR 4 +.IX Item "-mfence-as-lock-add=no" +.PD 0 +.IP \fB\-mfence\-as\-lock\-add=\fR\fIyes\fR 4 +.IX Item "-mfence-as-lock-add=yes" +.PD +These options control how the assembler should encode lfence, mfence and +sfence. +\&\fB\-mfence\-as\-lock\-add=\fR\fIyes\fR will encode lfence, mfence and +sfence as \fBlock addl \fR\f(CB$0x0\fR\fB, (%rsp)\fR in 64\-bit mode and +\&\fBlock addl \fR\f(CB$0x0\fR\fB, (%esp)\fR in 32\-bit mode. +\&\fB\-mfence\-as\-lock\-add=\fR\fIno\fR will encode lfence, mfence and +sfence as usual, which is the default. +.IP \fB\-mrelax\-relocations=\fR\fIno\fR 4 +.IX Item "-mrelax-relocations=no" +.PD 0 +.IP \fB\-mrelax\-relocations=\fR\fIyes\fR 4 +.IX Item "-mrelax-relocations=yes" +.PD +These options control whether the assembler should generate relax +relocations, R_386_GOT32X, in 32\-bit mode, or R_X86_64_GOTPCRELX and +R_X86_64_REX_GOTPCRELX, in 64\-bit mode. +\&\fB\-mrelax\-relocations=\fR\fIyes\fR will generate relax relocations. +\&\fB\-mrelax\-relocations=\fR\fIno\fR will not generate relax +relocations. The default can be controlled by a configure option +\&\fB\-\-enable\-x86\-relax\-relocations\fR. +.IP \fB\-malign\-branch\-boundary=\fR\fINUM\fR 4 +.IX Item "-malign-branch-boundary=NUM" +This option controls how the assembler should align branches with segment +prefixes or NOP. \fINUM\fR must be a power of 2. It should be 0 or +no less than 16. Branches will be aligned within \fINUM\fR byte +boundary. \fB\-malign\-branch\-boundary=0\fR, which is the default, +doesn't align branches. +.IP \fB\-malign\-branch=\fR\fITYPE\fR\fB[+\fR\fITYPE\fR\fB...]\fR 4 +.IX Item "-malign-branch=TYPE[+TYPE...]" +This option specifies types of branches to align. \fITYPE\fR is +combination of \fBjcc\fR, which aligns conditional jumps, +\&\fBfused\fR, which aligns fused conditional jumps, \fBjmp\fR, +which aligns unconditional jumps, \fBcall\fR which aligns calls, +\&\fBret\fR, which aligns rets, \fBindirect\fR, which aligns indirect +jumps and calls. The default is \fB\-malign\-branch=jcc+fused+jmp\fR. +.IP \fB\-malign\-branch\-prefix\-size=\fR\fINUM\fR 4 +.IX Item "-malign-branch-prefix-size=NUM" +This option specifies the maximum number of prefixes on an instruction +to align branches. \fINUM\fR should be between 0 and 5. The default +\&\fINUM\fR is 5. +.IP \fB\-mbranches\-within\-32B\-boundaries\fR 4 +.IX Item "-mbranches-within-32B-boundaries" +This option aligns conditional jumps, fused conditional jumps and +unconditional jumps within 32 byte boundary with up to 5 segment prefixes +on an instruction. It is equivalent to +\&\fB\-malign\-branch\-boundary=32\fR +\&\fB\-malign\-branch=jcc+fused+jmp\fR +\&\fB\-malign\-branch\-prefix\-size=5\fR. +The default doesn't align branches. +.IP \fB\-mlfence\-after\-load=\fR\fIno\fR 4 +.IX Item "-mlfence-after-load=no" +.PD 0 +.IP \fB\-mlfence\-after\-load=\fR\fIyes\fR 4 +.IX Item "-mlfence-after-load=yes" +.PD +These options control whether the assembler should generate lfence +after load instructions. \fB\-mlfence\-after\-load=\fR\fIyes\fR will +generate lfence. \fB\-mlfence\-after\-load=\fR\fIno\fR will not generate +lfence, which is the default. +.IP \fB\-mlfence\-before\-indirect\-branch=\fR\fInone\fR 4 +.IX Item "-mlfence-before-indirect-branch=none" +.PD 0 +.IP \fB\-mlfence\-before\-indirect\-branch=\fR\fIall\fR 4 +.IX Item "-mlfence-before-indirect-branch=all" +.IP \fB\-mlfence\-before\-indirect\-branch=\fR\fIregister\fR 4 +.IX Item "-mlfence-before-indirect-branch=register" +.IP \fB\-mlfence\-before\-indirect\-branch=\fR\fImemory\fR 4 +.IX Item "-mlfence-before-indirect-branch=memory" +.PD +These options control whether the assembler should generate lfence +before indirect near branch instructions. +\&\fB\-mlfence\-before\-indirect\-branch=\fR\fIall\fR will generate lfence +before indirect near branch via register and issue a warning before +indirect near branch via memory. +It also implicitly sets \fB\-mlfence\-before\-ret=\fR\fIshl\fR when +there's no explicit \fB\-mlfence\-before\-ret=\fR. +\&\fB\-mlfence\-before\-indirect\-branch=\fR\fIregister\fR will generate +lfence before indirect near branch via register. +\&\fB\-mlfence\-before\-indirect\-branch=\fR\fImemory\fR will issue a +warning before indirect near branch via memory. +\&\fB\-mlfence\-before\-indirect\-branch=\fR\fInone\fR will not generate +lfence nor issue warning, which is the default. Note that lfence won't +be generated before indirect near branch via register with +\&\fB\-mlfence\-after\-load=\fR\fIyes\fR since lfence will be generated +after loading branch target register. +.IP \fB\-mlfence\-before\-ret=\fR\fInone\fR 4 +.IX Item "-mlfence-before-ret=none" +.PD 0 +.IP \fB\-mlfence\-before\-ret=\fR\fIshl\fR 4 +.IX Item "-mlfence-before-ret=shl" +.IP \fB\-mlfence\-before\-ret=\fR\fIor\fR 4 +.IX Item "-mlfence-before-ret=or" +.IP \fB\-mlfence\-before\-ret=\fR\fIyes\fR 4 +.IX Item "-mlfence-before-ret=yes" +.IP \fB\-mlfence\-before\-ret=\fR\fInot\fR 4 +.IX Item "-mlfence-before-ret=not" +.PD +These options control whether the assembler should generate lfence +before ret. \fB\-mlfence\-before\-ret=\fR\fIor\fR will generate +generate or instruction with lfence. +\&\fB\-mlfence\-before\-ret=\fR\fIshl/yes\fR will generate shl instruction +with lfence. \fB\-mlfence\-before\-ret=\fR\fInot\fR will generate not +instruction with lfence. \fB\-mlfence\-before\-ret=\fR\fInone\fR will not +generate lfence, which is the default. +.IP \fB\-mx86\-used\-note=\fR\fIno\fR 4 +.IX Item "-mx86-used-note=no" +.PD 0 +.IP \fB\-mx86\-used\-note=\fR\fIyes\fR 4 +.IX Item "-mx86-used-note=yes" +.PD +These options control whether the assembler should generate +GNU_PROPERTY_X86_ISA_1_USED and GNU_PROPERTY_X86_FEATURE_2_USED +GNU property notes. The default can be controlled by the +\&\fB\-\-enable\-x86\-used\-note\fR configure option. +.IP \fB\-mevexrcig=\fR\fIrne\fR 4 +.IX Item "-mevexrcig=rne" +.PD 0 +.IP \fB\-mevexrcig=\fR\fIrd\fR 4 +.IX Item "-mevexrcig=rd" +.IP \fB\-mevexrcig=\fR\fIru\fR 4 +.IX Item "-mevexrcig=ru" +.IP \fB\-mevexrcig=\fR\fIrz\fR 4 +.IX Item "-mevexrcig=rz" +.PD +These options control how the assembler should encode SAE-only +EVEX instructions. \fB\-mevexrcig=\fR\fIrne\fR will encode RC bits +of EVEX instruction with 00, which is the default. +\&\fB\-mevexrcig=\fR\fIrd\fR, \fB\-mevexrcig=\fR\fIru\fR +and \fB\-mevexrcig=\fR\fIrz\fR will encode SAE-only EVEX instructions +with 01, 10 and 11 RC bits, respectively. +.IP \fB\-mamd64\fR 4 +.IX Item "-mamd64" +.PD 0 +.IP \fB\-mintel64\fR 4 +.IX Item "-mintel64" +.PD +This option specifies that the assembler should accept only AMD64 or +Intel64 ISA in 64\-bit mode. The default is to accept common, Intel64 +only and AMD64 ISAs. +.IP "\fB\-O0 | \-O | \-O1 | \-O2 | \-Os\fR" 4 +.IX Item "-O0 | -O | -O1 | -O2 | -Os" +Optimize instruction encoding with smaller instruction size. \fB\-O\fR +and \fB\-O1\fR encode 64\-bit register load instructions with 64\-bit +immediate as 32\-bit register load instructions with 31\-bit or 32\-bits +immediates, encode 64\-bit register clearing instructions with 32\-bit +register clearing instructions, encode 256\-bit/512\-bit VEX/EVEX vector +register clearing instructions with 128\-bit VEX vector register +clearing instructions, encode 128\-bit/256\-bit EVEX vector +register load/store instructions with VEX vector register load/store +instructions, and encode 128\-bit/256\-bit EVEX packed integer logical +instructions with 128\-bit/256\-bit VEX packed integer logical. +.Sp +\&\fB\-O2\fR includes \fB\-O1\fR optimization plus encodes +256\-bit/512\-bit EVEX vector register clearing instructions with 128\-bit +EVEX vector register clearing instructions. In 64\-bit mode VEX encoded +instructions with commutative source operands will also have their +source operands swapped if this allows using the 2\-byte VEX prefix form +instead of the 3\-byte one. Certain forms of AND as well as OR with the +same (register) operand specified twice will also be changed to TEST. +.Sp +\&\fB\-Os\fR includes \fB\-O2\fR optimization plus encodes 16\-bit, 32\-bit +and 64\-bit register tests with immediate as 8\-bit register test with +immediate. \fB\-O0\fR turns off this optimization. +.PP +The following options are available when as is configured for the +Ubicom IP2K series. +.IP \fB\-mip2022ext\fR 4 +.IX Item "-mip2022ext" +Specifies that the extended IP2022 instructions are allowed. +.IP \fB\-mip2022\fR 4 +.IX Item "-mip2022" +Restores the default behaviour, which restricts the permitted instructions to +just the basic IP2022 ones. +.PP +The following options are available when as is configured for the +Renesas M32C and M16C processors. +.IP \fB\-m32c\fR 4 +.IX Item "-m32c" +Assemble M32C instructions. +.IP \fB\-m16c\fR 4 +.IX Item "-m16c" +Assemble M16C instructions (the default). +.IP \fB\-relax\fR 4 +.IX Item "-relax" +Enable support for link-time relaxations. +.IP \fB\-h\-tick\-hex\fR 4 +.IX Item "-h-tick-hex" +Support H'00 style hex constants in addition to 0x00 style. +.PP +The following options are available when as is configured for the +Renesas M32R (formerly Mitsubishi M32R) series. +.IP \fB\-\-m32rx\fR 4 +.IX Item "--m32rx" +Specify which processor in the M32R family is the target. The default +is normally the M32R, but this option changes it to the M32RX. +.IP "\fB\-\-warn\-explicit\-parallel\-conflicts or \-\-Wp\fR" 4 +.IX Item "--warn-explicit-parallel-conflicts or --Wp" +Produce warning messages when questionable parallel constructs are +encountered. +.IP "\fB\-\-no\-warn\-explicit\-parallel\-conflicts or \-\-Wnp\fR" 4 +.IX Item "--no-warn-explicit-parallel-conflicts or --Wnp" +Do not produce warning messages when questionable parallel constructs are +encountered. +.PP +The following options are available when as is configured for the +Motorola 68000 series. +.IP \fB\-l\fR 4 +.IX Item "-l" +Shorten references to undefined symbols, to one word instead of two. +.IP "\fB\-m68000 | \-m68008 | \-m68010 | \-m68020 | \-m68030\fR" 4 +.IX Item "-m68000 | -m68008 | -m68010 | -m68020 | -m68030" +.PD 0 +.IP "\fB| \-m68040 | \-m68060 | \-m68302 | \-m68331 | \-m68332\fR" 4 +.IX Item "| -m68040 | -m68060 | -m68302 | -m68331 | -m68332" +.IP "\fB| \-m68333 | \-m68340 | \-mcpu32 | \-m5200\fR" 4 +.IX Item "| -m68333 | -m68340 | -mcpu32 | -m5200" +.PD +Specify what processor in the 68000 family is the target. The default +is normally the 68020, but this can be changed at configuration time. +.IP "\fB\-m68881 | \-m68882 | \-mno\-68881 | \-mno\-68882\fR" 4 +.IX Item "-m68881 | -m68882 | -mno-68881 | -mno-68882" +The target machine does (or does not) have a floating-point coprocessor. +The default is to assume a coprocessor for 68020, 68030, and cpu32. Although +the basic 68000 is not compatible with the 68881, a combination of the +two can be specified, since it's possible to do emulation of the +coprocessor instructions with the main processor. +.IP "\fB\-m68851 | \-mno\-68851\fR" 4 +.IX Item "-m68851 | -mno-68851" +The target machine does (or does not) have a memory-management +unit coprocessor. The default is to assume an MMU for 68020 and up. +.PP +The following options are available when as is configured for an +Altera Nios II processor. +.IP \fB\-relax\-section\fR 4 +.IX Item "-relax-section" +Replace identified out-of-range branches with PC-relative \f(CW\*(C`jmp\*(C'\fR +sequences when possible. The generated code sequences are suitable +for use in position-independent code, but there is a practical limit +on the extended branch range because of the length of the sequences. +This option is the default. +.IP \fB\-relax\-all\fR 4 +.IX Item "-relax-all" +Replace branch instructions not determinable to be in range +and all call instructions with \f(CW\*(C`jmp\*(C'\fR and \f(CW\*(C`callr\*(C'\fR sequences +(respectively). This option generates absolute relocations against the +target symbols and is not appropriate for position-independent code. +.IP \fB\-no\-relax\fR 4 +.IX Item "-no-relax" +Do not replace any branches or calls. +.IP \fB\-EB\fR 4 +.IX Item "-EB" +Generate big-endian output. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +Generate little-endian output. This is the default. +.IP \fB\-march=\fR\fIarchitecture\fR 4 +.IX Item "-march=architecture" +This option specifies the target architecture. The assembler issues +an error message if an attempt is made to assemble an instruction which +will not execute on the target architecture. The following architecture +names are recognized: +\&\f(CW\*(C`r1\*(C'\fR, +\&\f(CW\*(C`r2\*(C'\fR. +The default is \f(CW\*(C`r1\*(C'\fR. +.PP +The following options are available when as is configured for a +PRU processor. +.IP \fB\-mlink\-relax\fR 4 +.IX Item "-mlink-relax" +Assume that LD would optimize LDI32 instructions by checking the upper +16 bits of the \fIexpression\fR. If they are all zeros, then LD would +shorten the LDI32 instruction to a single LDI. In such case \f(CW\*(C`as\*(C'\fR +will output DIFF relocations for diff expressions. +.IP \fB\-mno\-link\-relax\fR 4 +.IX Item "-mno-link-relax" +Assume that LD would not optimize LDI32 instructions. As a consequence, +DIFF relocations will not be emitted. +.IP \fB\-mno\-warn\-regname\-label\fR 4 +.IX Item "-mno-warn-regname-label" +Do not warn if a label name matches a register name. Usually assembler +programmers will want this warning to be emitted. C compilers may want +to turn this off. +.PP +The following options are available when as is configured for +a MIPS processor. +.IP "\fB\-G\fR \fInum\fR" 4 +.IX Item "-G num" +This option sets the largest size of an object that can be referenced +implicitly with the \f(CW\*(C`gp\*(C'\fR register. It is only accepted for targets that +use ECOFF format, such as a DECstation running Ultrix. The default value is 8. +.IP \fB\-EB\fR 4 +.IX Item "-EB" +Generate "big endian" format output. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +Generate "little endian" format output. +.IP \fB\-mips1\fR 4 +.IX Item "-mips1" +.PD 0 +.IP \fB\-mips2\fR 4 +.IX Item "-mips2" +.IP \fB\-mips3\fR 4 +.IX Item "-mips3" +.IP \fB\-mips4\fR 4 +.IX Item "-mips4" +.IP \fB\-mips5\fR 4 +.IX Item "-mips5" +.IP \fB\-mips32\fR 4 +.IX Item "-mips32" +.IP \fB\-mips32r2\fR 4 +.IX Item "-mips32r2" +.IP \fB\-mips32r3\fR 4 +.IX Item "-mips32r3" +.IP \fB\-mips32r5\fR 4 +.IX Item "-mips32r5" +.IP \fB\-mips32r6\fR 4 +.IX Item "-mips32r6" +.IP \fB\-mips64\fR 4 +.IX Item "-mips64" +.IP \fB\-mips64r2\fR 4 +.IX Item "-mips64r2" +.IP \fB\-mips64r3\fR 4 +.IX Item "-mips64r3" +.IP \fB\-mips64r5\fR 4 +.IX Item "-mips64r5" +.IP \fB\-mips64r6\fR 4 +.IX Item "-mips64r6" +.PD +Generate code for a particular MIPS Instruction Set Architecture level. +\&\fB\-mips1\fR is an alias for \fB\-march=r3000\fR, \fB\-mips2\fR is an +alias for \fB\-march=r6000\fR, \fB\-mips3\fR is an alias for +\&\fB\-march=r4000\fR and \fB\-mips4\fR is an alias for \fB\-march=r8000\fR. +\&\fB\-mips5\fR, \fB\-mips32\fR, \fB\-mips32r2\fR, \fB\-mips32r3\fR, +\&\fB\-mips32r5\fR, \fB\-mips32r6\fR, \fB\-mips64\fR, \fB\-mips64r2\fR, +\&\fB\-mips64r3\fR, \fB\-mips64r5\fR, and \fB\-mips64r6\fR correspond to generic +MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, MIPS32 Release 5, MIPS32 +Release 6, MIPS64, MIPS64 Release 2, MIPS64 Release 3, MIPS64 Release 5, and +MIPS64 Release 6 ISA processors, respectively. +.IP \fB\-march=\fR\fIcpu\fR 4 +.IX Item "-march=cpu" +Generate code for a particular MIPS CPU. +.IP \fB\-mtune=\fR\fIcpu\fR 4 +.IX Item "-mtune=cpu" +Schedule and tune for a particular MIPS CPU. +.IP \fB\-mfix7000\fR 4 +.IX Item "-mfix7000" +.PD 0 +.IP \fB\-mno\-fix7000\fR 4 +.IX Item "-mno-fix7000" +.PD +Cause nops to be inserted if the read of the destination register +of an mfhi or mflo instruction occurs in the following two instructions. +.IP \fB\-mfix\-rm7000\fR 4 +.IX Item "-mfix-rm7000" +.PD 0 +.IP \fB\-mno\-fix\-rm7000\fR 4 +.IX Item "-mno-fix-rm7000" +.PD +Cause nops to be inserted if a dmult or dmultu instruction is +followed by a load instruction. +.IP \fB\-mfix\-r5900\fR 4 +.IX Item "-mfix-r5900" +.PD 0 +.IP \fB\-mno\-fix\-r5900\fR 4 +.IX Item "-mno-fix-r5900" +.PD +Do not attempt to schedule the preceding instruction into the delay slot +of a branch instruction placed at the end of a short loop of six +instructions or fewer and always schedule a \f(CW\*(C`nop\*(C'\fR instruction there +instead. The short loop bug under certain conditions causes loops to +execute only once or twice, due to a hardware bug in the R5900 chip. +.IP \fB\-mdebug\fR 4 +.IX Item "-mdebug" +.PD 0 +.IP \fB\-no\-mdebug\fR 4 +.IX Item "-no-mdebug" +.PD +Cause stabs-style debugging output to go into an ECOFF-style .mdebug +section instead of the standard ELF .stabs sections. +.IP \fB\-mpdr\fR 4 +.IX Item "-mpdr" +.PD 0 +.IP \fB\-mno\-pdr\fR 4 +.IX Item "-mno-pdr" +.PD +Control generation of \f(CW\*(C`.pdr\*(C'\fR sections. +.IP \fB\-mgp32\fR 4 +.IX Item "-mgp32" +.PD 0 +.IP \fB\-mfp32\fR 4 +.IX Item "-mfp32" +.PD +The register sizes are normally inferred from the ISA and ABI, but these +flags force a certain group of registers to be treated as 32 bits wide at +all times. \fB\-mgp32\fR controls the size of general-purpose registers +and \fB\-mfp32\fR controls the size of floating-point registers. +.IP \fB\-mgp64\fR 4 +.IX Item "-mgp64" +.PD 0 +.IP \fB\-mfp64\fR 4 +.IX Item "-mfp64" +.PD +The register sizes are normally inferred from the ISA and ABI, but these +flags force a certain group of registers to be treated as 64 bits wide at +all times. \fB\-mgp64\fR controls the size of general-purpose registers +and \fB\-mfp64\fR controls the size of floating-point registers. +.IP \fB\-mfpxx\fR 4 +.IX Item "-mfpxx" +The register sizes are normally inferred from the ISA and ABI, but using +this flag in combination with \fB\-mabi=32\fR enables an ABI variant +which will operate correctly with floating-point registers which are +32 or 64 bits wide. +.IP \fB\-modd\-spreg\fR 4 +.IX Item "-modd-spreg" +.PD 0 +.IP \fB\-mno\-odd\-spreg\fR 4 +.IX Item "-mno-odd-spreg" +.PD +Enable use of floating-point operations on odd-numbered single-precision +registers when supported by the ISA. \fB\-mfpxx\fR implies +\&\fB\-mno\-odd\-spreg\fR, otherwise the default is \fB\-modd\-spreg\fR. +.IP \fB\-mips16\fR 4 +.IX Item "-mips16" +.PD 0 +.IP \fB\-no\-mips16\fR 4 +.IX Item "-no-mips16" +.PD +Generate code for the MIPS 16 processor. This is equivalent to putting +\&\f(CW\*(C`.module mips16\*(C'\fR at the start of the assembly file. \fB\-no\-mips16\fR +turns off this option. +.IP \fB\-mmips16e2\fR 4 +.IX Item "-mmips16e2" +.PD 0 +.IP \fB\-mno\-mips16e2\fR 4 +.IX Item "-mno-mips16e2" +.PD +Enable the use of MIPS16e2 instructions in MIPS16 mode. This is equivalent +to putting \f(CW\*(C`.module mips16e2\*(C'\fR at the start of the assembly file. +\&\fB\-mno\-mips16e2\fR turns off this option. +.IP \fB\-mmicromips\fR 4 +.IX Item "-mmicromips" +.PD 0 +.IP \fB\-mno\-micromips\fR 4 +.IX Item "-mno-micromips" +.PD +Generate code for the microMIPS processor. This is equivalent to putting +\&\f(CW\*(C`.module micromips\*(C'\fR at the start of the assembly file. +\&\fB\-mno\-micromips\fR turns off this option. This is equivalent to putting +\&\f(CW\*(C`.module nomicromips\*(C'\fR at the start of the assembly file. +.IP \fB\-msmartmips\fR 4 +.IX Item "-msmartmips" +.PD 0 +.IP \fB\-mno\-smartmips\fR 4 +.IX Item "-mno-smartmips" +.PD +Enables the SmartMIPS extension to the MIPS32 instruction set. This is +equivalent to putting \f(CW\*(C`.module smartmips\*(C'\fR at the start of the assembly +file. \fB\-mno\-smartmips\fR turns off this option. +.IP \fB\-mips3d\fR 4 +.IX Item "-mips3d" +.PD 0 +.IP \fB\-no\-mips3d\fR 4 +.IX Item "-no-mips3d" +.PD +Generate code for the MIPS\-3D Application Specific Extension. +This tells the assembler to accept MIPS\-3D instructions. +\&\fB\-no\-mips3d\fR turns off this option. +.IP \fB\-mdmx\fR 4 +.IX Item "-mdmx" +.PD 0 +.IP \fB\-no\-mdmx\fR 4 +.IX Item "-no-mdmx" +.PD +Generate code for the MDMX Application Specific Extension. +This tells the assembler to accept MDMX instructions. +\&\fB\-no\-mdmx\fR turns off this option. +.IP \fB\-mdsp\fR 4 +.IX Item "-mdsp" +.PD 0 +.IP \fB\-mno\-dsp\fR 4 +.IX Item "-mno-dsp" +.PD +Generate code for the DSP Release 1 Application Specific Extension. +This tells the assembler to accept DSP Release 1 instructions. +\&\fB\-mno\-dsp\fR turns off this option. +.IP \fB\-mdspr2\fR 4 +.IX Item "-mdspr2" +.PD 0 +.IP \fB\-mno\-dspr2\fR 4 +.IX Item "-mno-dspr2" +.PD +Generate code for the DSP Release 2 Application Specific Extension. +This option implies \fB\-mdsp\fR. +This tells the assembler to accept DSP Release 2 instructions. +\&\fB\-mno\-dspr2\fR turns off this option. +.IP \fB\-mdspr3\fR 4 +.IX Item "-mdspr3" +.PD 0 +.IP \fB\-mno\-dspr3\fR 4 +.IX Item "-mno-dspr3" +.PD +Generate code for the DSP Release 3 Application Specific Extension. +This option implies \fB\-mdsp\fR and \fB\-mdspr2\fR. +This tells the assembler to accept DSP Release 3 instructions. +\&\fB\-mno\-dspr3\fR turns off this option. +.IP \fB\-mmsa\fR 4 +.IX Item "-mmsa" +.PD 0 +.IP \fB\-mno\-msa\fR 4 +.IX Item "-mno-msa" +.PD +Generate code for the MIPS SIMD Architecture Extension. +This tells the assembler to accept MSA instructions. +\&\fB\-mno\-msa\fR turns off this option. +.IP \fB\-mxpa\fR 4 +.IX Item "-mxpa" +.PD 0 +.IP \fB\-mno\-xpa\fR 4 +.IX Item "-mno-xpa" +.PD +Generate code for the MIPS eXtended Physical Address (XPA) Extension. +This tells the assembler to accept XPA instructions. +\&\fB\-mno\-xpa\fR turns off this option. +.IP \fB\-mmt\fR 4 +.IX Item "-mmt" +.PD 0 +.IP \fB\-mno\-mt\fR 4 +.IX Item "-mno-mt" +.PD +Generate code for the MT Application Specific Extension. +This tells the assembler to accept MT instructions. +\&\fB\-mno\-mt\fR turns off this option. +.IP \fB\-mmcu\fR 4 +.IX Item "-mmcu" +.PD 0 +.IP \fB\-mno\-mcu\fR 4 +.IX Item "-mno-mcu" +.PD +Generate code for the MCU Application Specific Extension. +This tells the assembler to accept MCU instructions. +\&\fB\-mno\-mcu\fR turns off this option. +.IP \fB\-mcrc\fR 4 +.IX Item "-mcrc" +.PD 0 +.IP \fB\-mno\-crc\fR 4 +.IX Item "-mno-crc" +.PD +Generate code for the MIPS cyclic redundancy check (CRC) Application +Specific Extension. This tells the assembler to accept CRC instructions. +\&\fB\-mno\-crc\fR turns off this option. +.IP \fB\-mginv\fR 4 +.IX Item "-mginv" +.PD 0 +.IP \fB\-mno\-ginv\fR 4 +.IX Item "-mno-ginv" +.PD +Generate code for the Global INValidate (GINV) Application Specific +Extension. This tells the assembler to accept GINV instructions. +\&\fB\-mno\-ginv\fR turns off this option. +.IP \fB\-mloongson\-mmi\fR 4 +.IX Item "-mloongson-mmi" +.PD 0 +.IP \fB\-mno\-loongson\-mmi\fR 4 +.IX Item "-mno-loongson-mmi" +.PD +Generate code for the Loongson MultiMedia extensions Instructions (MMI) +Application Specific Extension. This tells the assembler to accept MMI +instructions. +\&\fB\-mno\-loongson\-mmi\fR turns off this option. +.IP \fB\-mloongson\-cam\fR 4 +.IX Item "-mloongson-cam" +.PD 0 +.IP \fB\-mno\-loongson\-cam\fR 4 +.IX Item "-mno-loongson-cam" +.PD +Generate code for the Loongson Content Address Memory (CAM) instructions. +This tells the assembler to accept Loongson CAM instructions. +\&\fB\-mno\-loongson\-cam\fR turns off this option. +.IP \fB\-mloongson\-ext\fR 4 +.IX Item "-mloongson-ext" +.PD 0 +.IP \fB\-mno\-loongson\-ext\fR 4 +.IX Item "-mno-loongson-ext" +.PD +Generate code for the Loongson EXTensions (EXT) instructions. +This tells the assembler to accept Loongson EXT instructions. +\&\fB\-mno\-loongson\-ext\fR turns off this option. +.IP \fB\-mloongson\-ext2\fR 4 +.IX Item "-mloongson-ext2" +.PD 0 +.IP \fB\-mno\-loongson\-ext2\fR 4 +.IX Item "-mno-loongson-ext2" +.PD +Generate code for the Loongson EXTensions R2 (EXT2) instructions. +This option implies \fB\-mloongson\-ext\fR. +This tells the assembler to accept Loongson EXT2 instructions. +\&\fB\-mno\-loongson\-ext2\fR turns off this option. +.IP \fB\-minsn32\fR 4 +.IX Item "-minsn32" +.PD 0 +.IP \fB\-mno\-insn32\fR 4 +.IX Item "-mno-insn32" +.PD +Only use 32\-bit instruction encodings when generating code for the +microMIPS processor. This option inhibits the use of any 16\-bit +instructions. This is equivalent to putting \f(CW\*(C`.set insn32\*(C'\fR at +the start of the assembly file. \fB\-mno\-insn32\fR turns off this +option. This is equivalent to putting \f(CW\*(C`.set noinsn32\*(C'\fR at the +start of the assembly file. By default \fB\-mno\-insn32\fR is +selected, allowing all instructions to be used. +.IP \fB\-\-construct\-floats\fR 4 +.IX Item "--construct-floats" +.PD 0 +.IP \fB\-\-no\-construct\-floats\fR 4 +.IX Item "--no-construct-floats" +.PD +The \fB\-\-no\-construct\-floats\fR option disables the construction of +double width floating point constants by loading the two halves of the +value into the two single width floating point registers that make up +the double width register. By default \fB\-\-construct\-floats\fR is +selected, allowing construction of these floating point constants. +.IP \fB\-\-relax\-branch\fR 4 +.IX Item "--relax-branch" +.PD 0 +.IP \fB\-\-no\-relax\-branch\fR 4 +.IX Item "--no-relax-branch" +.PD +The \fB\-\-relax\-branch\fR option enables the relaxation of out-of-range +branches. By default \fB\-\-no\-relax\-branch\fR is selected, causing any +out-of-range branches to produce an error. +.IP \fB\-mignore\-branch\-isa\fR 4 +.IX Item "-mignore-branch-isa" +.PD 0 +.IP \fB\-mno\-ignore\-branch\-isa\fR 4 +.IX Item "-mno-ignore-branch-isa" +.PD +Ignore branch checks for invalid transitions between ISA modes. The +semantics of branches does not provide for an ISA mode switch, so in +most cases the ISA mode a branch has been encoded for has to be the +same as the ISA mode of the branch's target label. Therefore GAS has +checks implemented that verify in branch assembly that the two ISA +modes match. \fB\-mignore\-branch\-isa\fR disables these checks. By +default \fB\-mno\-ignore\-branch\-isa\fR is selected, causing any invalid +branch requiring a transition between ISA modes to produce an error. +.IP \fB\-mnan=\fR\fIencoding\fR 4 +.IX Item "-mnan=encoding" +Select between the IEEE 754\-2008 (\fB\-mnan=2008\fR) or the legacy +(\fB\-mnan=legacy\fR) NaN encoding format. The latter is the default. +.IP \fB\-\-emulation=\fR\fIname\fR 4 +.IX Item "--emulation=name" +This option was formerly used to switch between ELF and ECOFF output +on targets like IRIX 5 that supported both. MIPS ECOFF support was +removed in GAS 2.24, so the option now serves little purpose. +It is retained for backwards compatibility. +.Sp +The available configuration names are: \fBmipself\fR, \fBmipslelf\fR and +\&\fBmipsbelf\fR. Choosing \fBmipself\fR now has no effect, since the output +is always ELF. \fBmipslelf\fR and \fBmipsbelf\fR select little\- and +big-endian output respectively, but \fB\-EL\fR and \fB\-EB\fR are now the +preferred options instead. +.IP \fB\-nocpp\fR 4 +.IX Item "-nocpp" +\&\fBas\fR ignores this option. It is accepted for compatibility with +the native tools. +.IP \fB\-\-trap\fR 4 +.IX Item "--trap" +.PD 0 +.IP \fB\-\-no\-trap\fR 4 +.IX Item "--no-trap" +.IP \fB\-\-break\fR 4 +.IX Item "--break" +.IP \fB\-\-no\-break\fR 4 +.IX Item "--no-break" +.PD +Control how to deal with multiplication overflow and division by zero. +\&\fB\-\-trap\fR or \fB\-\-no\-break\fR (which are synonyms) take a trap exception +(and only work for Instruction Set Architecture level 2 and higher); +\&\fB\-\-break\fR or \fB\-\-no\-trap\fR (also synonyms, and the default) take a +break exception. +.IP \fB\-n\fR 4 +.IX Item "-n" +When this option is used, \fBas\fR will issue a warning every +time it generates a nop instruction from a macro. +.PP +The following options are available when as is configured for a +LoongArch processor. +.IP \fB\-fpic\fR 4 +.IX Item "-fpic" +.PD 0 +.IP \fB\-fPIC\fR 4 +.IX Item "-fPIC" +.PD +Generate position-independent code +.IP \fB\-fno\-pic\fR 4 +.IX Item "-fno-pic" +Don't generate position-independent code (default) +.PP +The following options are available when as is configured for a +Meta processor. +.ie n .IP """\-mcpu=metac11""" 4 +.el .IP \f(CW\-mcpu=metac11\fR 4 +.IX Item "-mcpu=metac11" +Generate code for Meta 1.1. +.ie n .IP """\-mcpu=metac12""" 4 +.el .IP \f(CW\-mcpu=metac12\fR 4 +.IX Item "-mcpu=metac12" +Generate code for Meta 1.2. +.ie n .IP """\-mcpu=metac21""" 4 +.el .IP \f(CW\-mcpu=metac21\fR 4 +.IX Item "-mcpu=metac21" +Generate code for Meta 2.1. +.ie n .IP """\-mfpu=metac21""" 4 +.el .IP \f(CW\-mfpu=metac21\fR 4 +.IX Item "-mfpu=metac21" +Allow code to use FPU hardware of Meta 2.1. +.PP +See the info pages for documentation of the MMIX-specific options. +.PP +The following options are available when as is configured for a +NDS32 processor. +.ie n .IP """\-O1""" 4 +.el .IP \f(CW\-O1\fR 4 +.IX Item "-O1" +Optimize for performance. +.ie n .IP """\-Os""" 4 +.el .IP \f(CW\-Os\fR 4 +.IX Item "-Os" +Optimize for space. +.ie n .IP """\-EL""" 4 +.el .IP \f(CW\-EL\fR 4 +.IX Item "-EL" +Produce little endian data output. +.ie n .IP """\-EB""" 4 +.el .IP \f(CW\-EB\fR 4 +.IX Item "-EB" +Produce little endian data output. +.ie n .IP """\-mpic""" 4 +.el .IP \f(CW\-mpic\fR 4 +.IX Item "-mpic" +Generate PIC. +.ie n .IP """\-mno\-fp\-as\-gp\-relax""" 4 +.el .IP \f(CW\-mno\-fp\-as\-gp\-relax\fR 4 +.IX Item "-mno-fp-as-gp-relax" +Suppress fp-as-gp relaxation for this file. +.ie n .IP """\-mb2bb\-relax""" 4 +.el .IP \f(CW\-mb2bb\-relax\fR 4 +.IX Item "-mb2bb-relax" +Back-to-back branch optimization. +.ie n .IP """\-mno\-all\-relax""" 4 +.el .IP \f(CW\-mno\-all\-relax\fR 4 +.IX Item "-mno-all-relax" +Suppress all relaxation for this file. +.ie n .IP """\-march=""" 4 +.el .IP "\f(CW\-march=\fR" 4 +.IX Item "-march=" +Assemble for architecture which could be v3, v3j, v3m, v3f, +v3s, v2, v2j, v2f, v2s. +.ie n .IP """\-mbaseline=""" 4 +.el .IP \f(CW\-mbaseline=\fR 4 +.IX Item "-mbaseline=" +Assemble for baseline which could be v2, v3, v3m. +.ie n .IP """\-mfpu\-freg=\fIFREG\fR""" 4 +.el .IP \f(CW\-mfpu\-freg=\fR\f(CIFREG\fR\f(CW\fR 4 +.IX Item "-mfpu-freg=FREG" +Specify a FPU configuration. +.RS 4 +.ie n .IP """0 8 SP / 4 DP registers""" 4 +.el .IP "\f(CW0 8 SP / 4 DP registers\fR" 4 +.IX Item "0 8 SP / 4 DP registers" +.PD 0 +.ie n .IP """1 16 SP / 8 DP registers""" 4 +.el .IP "\f(CW1 16 SP / 8 DP registers\fR" 4 +.IX Item "1 16 SP / 8 DP registers" +.ie n .IP """2 32 SP / 16 DP registers""" 4 +.el .IP "\f(CW2 32 SP / 16 DP registers\fR" 4 +.IX Item "2 32 SP / 16 DP registers" +.ie n .IP """3 32 SP / 32 DP registers""" 4 +.el .IP "\f(CW3 32 SP / 32 DP registers\fR" 4 +.IX Item "3 32 SP / 32 DP registers" +.RE +.RS 4 +.RE +.ie n .IP """\-mabi=\fIabi\fR""" 4 +.el .IP \f(CW\-mabi=\fR\f(CIabi\fR\f(CW\fR 4 +.IX Item "-mabi=abi" +.PD +Specify a abi version could be v1, v2, v2fp, v2fpp. +.ie n .IP """\-m[no\-]mac""" 4 +.el .IP \f(CW\-m[no\-]mac\fR 4 +.IX Item "-m[no-]mac" +Enable/Disable Multiply instructions support. +.ie n .IP """\-m[no\-]div""" 4 +.el .IP \f(CW\-m[no\-]div\fR 4 +.IX Item "-m[no-]div" +Enable/Disable Divide instructions support. +.ie n .IP """\-m[no\-]16bit\-ext""" 4 +.el .IP \f(CW\-m[no\-]16bit\-ext\fR 4 +.IX Item "-m[no-]16bit-ext" +Enable/Disable 16\-bit extension +.ie n .IP """\-m[no\-]dx\-regs""" 4 +.el .IP \f(CW\-m[no\-]dx\-regs\fR 4 +.IX Item "-m[no-]dx-regs" +Enable/Disable d0/d1 registers +.ie n .IP """\-m[no\-]perf\-ext""" 4 +.el .IP \f(CW\-m[no\-]perf\-ext\fR 4 +.IX Item "-m[no-]perf-ext" +Enable/Disable Performance extension +.ie n .IP """\-m[no\-]perf2\-ext""" 4 +.el .IP \f(CW\-m[no\-]perf2\-ext\fR 4 +.IX Item "-m[no-]perf2-ext" +Enable/Disable Performance extension 2 +.ie n .IP """\-m[no\-]string\-ext""" 4 +.el .IP \f(CW\-m[no\-]string\-ext\fR 4 +.IX Item "-m[no-]string-ext" +Enable/Disable String extension +.ie n .IP """\-m[no\-]reduced\-regs""" 4 +.el .IP \f(CW\-m[no\-]reduced\-regs\fR 4 +.IX Item "-m[no-]reduced-regs" +Enable/Disable Reduced Register configuration (GPR16) option +.ie n .IP """\-m[no\-]audio\-isa\-ext""" 4 +.el .IP \f(CW\-m[no\-]audio\-isa\-ext\fR 4 +.IX Item "-m[no-]audio-isa-ext" +Enable/Disable AUDIO ISA extension +.ie n .IP """\-m[no\-]fpu\-sp\-ext""" 4 +.el .IP \f(CW\-m[no\-]fpu\-sp\-ext\fR 4 +.IX Item "-m[no-]fpu-sp-ext" +Enable/Disable FPU SP extension +.ie n .IP """\-m[no\-]fpu\-dp\-ext""" 4 +.el .IP \f(CW\-m[no\-]fpu\-dp\-ext\fR 4 +.IX Item "-m[no-]fpu-dp-ext" +Enable/Disable FPU DP extension +.ie n .IP """\-m[no\-]fpu\-fma""" 4 +.el .IP \f(CW\-m[no\-]fpu\-fma\fR 4 +.IX Item "-m[no-]fpu-fma" +Enable/Disable FPU fused-multiply-add instructions +.ie n .IP """\-mall\-ext""" 4 +.el .IP \f(CW\-mall\-ext\fR 4 +.IX Item "-mall-ext" +Turn on all extensions and instructions support +.PP +The following options are available when as is configured for a +PowerPC processor. +.IP \fB\-a32\fR 4 +.IX Item "-a32" +Generate ELF32 or XCOFF32. +.IP \fB\-a64\fR 4 +.IX Item "-a64" +Generate ELF64 or XCOFF64. +.IP "\fB\-K PIC\fR" 4 +.IX Item "-K PIC" +Set EF_PPC_RELOCATABLE_LIB in ELF flags. +.IP "\fB\-mpwrx | \-mpwr2\fR" 4 +.IX Item "-mpwrx | -mpwr2" +Generate code for POWER/2 (RIOS2). +.IP \fB\-mpwr\fR 4 +.IX Item "-mpwr" +Generate code for POWER (RIOS1) +.IP \fB\-m601\fR 4 +.IX Item "-m601" +Generate code for PowerPC 601. +.IP "\fB\-mppc, \-mppc32, \-m603, \-m604\fR" 4 +.IX Item "-mppc, -mppc32, -m603, -m604" +Generate code for PowerPC 603/604. +.IP "\fB\-m403, \-m405\fR" 4 +.IX Item "-m403, -m405" +Generate code for PowerPC 403/405. +.IP \fB\-m440\fR 4 +.IX Item "-m440" +Generate code for PowerPC 440. BookE and some 405 instructions. +.IP \fB\-m464\fR 4 +.IX Item "-m464" +Generate code for PowerPC 464. +.IP \fB\-m476\fR 4 +.IX Item "-m476" +Generate code for PowerPC 476. +.IP "\fB\-m7400, \-m7410, \-m7450, \-m7455\fR" 4 +.IX Item "-m7400, -m7410, -m7450, -m7455" +Generate code for PowerPC 7400/7410/7450/7455. +.IP "\fB\-m750cl, \-mgekko, \-mbroadway\fR" 4 +.IX Item "-m750cl, -mgekko, -mbroadway" +Generate code for PowerPC 750CL/Gekko/Broadway. +.IP "\fB\-m821, \-m850, \-m860\fR" 4 +.IX Item "-m821, -m850, -m860" +Generate code for PowerPC 821/850/860. +.IP "\fB\-mppc64, \-m620\fR" 4 +.IX Item "-mppc64, -m620" +Generate code for PowerPC 620/625/630. +.IP "\fB\-me200z2, \-me200z4\fR" 4 +.IX Item "-me200z2, -me200z4" +Generate code for e200 variants, e200z2 with LSP, e200z4 with SPE. +.IP \fB\-me300\fR 4 +.IX Item "-me300" +Generate code for PowerPC e300 family. +.IP "\fB\-me500, \-me500x2\fR" 4 +.IX Item "-me500, -me500x2" +Generate code for Motorola e500 core complex. +.IP \fB\-me500mc\fR 4 +.IX Item "-me500mc" +Generate code for Freescale e500mc core complex. +.IP \fB\-me500mc64\fR 4 +.IX Item "-me500mc64" +Generate code for Freescale e500mc64 core complex. +.IP \fB\-me5500\fR 4 +.IX Item "-me5500" +Generate code for Freescale e5500 core complex. +.IP \fB\-me6500\fR 4 +.IX Item "-me6500" +Generate code for Freescale e6500 core complex. +.IP \fB\-mlsp\fR 4 +.IX Item "-mlsp" +Enable LSP instructions. (Disables SPE and SPE2.) +.IP \fB\-mspe\fR 4 +.IX Item "-mspe" +Generate code for Motorola SPE instructions. (Disables LSP.) +.IP \fB\-mspe2\fR 4 +.IX Item "-mspe2" +Generate code for Freescale SPE2 instructions. (Disables LSP.) +.IP \fB\-mtitan\fR 4 +.IX Item "-mtitan" +Generate code for AppliedMicro Titan core complex. +.IP \fB\-mppc64bridge\fR 4 +.IX Item "-mppc64bridge" +Generate code for PowerPC 64, including bridge insns. +.IP \fB\-mbooke\fR 4 +.IX Item "-mbooke" +Generate code for 32\-bit BookE. +.IP \fB\-ma2\fR 4 +.IX Item "-ma2" +Generate code for A2 architecture. +.IP \fB\-maltivec\fR 4 +.IX Item "-maltivec" +Generate code for processors with AltiVec instructions. +.IP \fB\-mvle\fR 4 +.IX Item "-mvle" +Generate code for Freescale PowerPC VLE instructions. +.IP \fB\-mvsx\fR 4 +.IX Item "-mvsx" +Generate code for processors with Vector-Scalar (VSX) instructions. +.IP \fB\-mhtm\fR 4 +.IX Item "-mhtm" +Generate code for processors with Hardware Transactional Memory instructions. +.IP "\fB\-mpower4, \-mpwr4\fR" 4 +.IX Item "-mpower4, -mpwr4" +Generate code for Power4 architecture. +.IP "\fB\-mpower5, \-mpwr5, \-mpwr5x\fR" 4 +.IX Item "-mpower5, -mpwr5, -mpwr5x" +Generate code for Power5 architecture. +.IP "\fB\-mpower6, \-mpwr6\fR" 4 +.IX Item "-mpower6, -mpwr6" +Generate code for Power6 architecture. +.IP "\fB\-mpower7, \-mpwr7\fR" 4 +.IX Item "-mpower7, -mpwr7" +Generate code for Power7 architecture. +.IP "\fB\-mpower8, \-mpwr8\fR" 4 +.IX Item "-mpower8, -mpwr8" +Generate code for Power8 architecture. +.IP "\fB\-mpower9, \-mpwr9\fR" 4 +.IX Item "-mpower9, -mpwr9" +Generate code for Power9 architecture. +.IP "\fB\-mpower10, \-mpwr10\fR" 4 +.IX Item "-mpower10, -mpwr10" +Generate code for Power10 architecture. +.IP "\fB\-mpower11, \-mpwr11\fR" 4 +.IX Item "-mpower11, -mpwr11" +Generate code for Power11 architecture. +.IP \fB\-mfuture\fR 4 +.IX Item "-mfuture" +Generate code for 'future' architecture. +.IP \fB\-mcell\fR 4 +.IX Item "-mcell" +.PD 0 +.IP \fB\-mcell\fR 4 +.IX Item "-mcell" +.PD +Generate code for Cell Broadband Engine architecture. +.IP \fB\-mcom\fR 4 +.IX Item "-mcom" +Generate code Power/PowerPC common instructions. +.IP \fB\-many\fR 4 +.IX Item "-many" +Generate code for any architecture (PWR/PWRX/PPC). +.IP \fB\-mregnames\fR 4 +.IX Item "-mregnames" +Allow symbolic names for registers. +.IP \fB\-mno\-regnames\fR 4 +.IX Item "-mno-regnames" +Do not allow symbolic names for registers. +.IP \fB\-mrelocatable\fR 4 +.IX Item "-mrelocatable" +Support for GCC's \-mrelocatable option. +.IP \fB\-mrelocatable\-lib\fR 4 +.IX Item "-mrelocatable-lib" +Support for GCC's \-mrelocatable\-lib option. +.IP \fB\-memb\fR 4 +.IX Item "-memb" +Set PPC_EMB bit in ELF flags. +.IP "\fB\-mlittle, \-mlittle\-endian, \-le\fR" 4 +.IX Item "-mlittle, -mlittle-endian, -le" +Generate code for a little endian machine. +.IP "\fB\-mbig, \-mbig\-endian, \-be\fR" 4 +.IX Item "-mbig, -mbig-endian, -be" +Generate code for a big endian machine. +.IP \fB\-msolaris\fR 4 +.IX Item "-msolaris" +Generate code for Solaris. +.IP \fB\-mno\-solaris\fR 4 +.IX Item "-mno-solaris" +Do not generate code for Solaris. +.IP \fB\-nops=\fR\fIcount\fR 4 +.IX Item "-nops=count" +If an alignment directive inserts more than \fIcount\fR nops, put a +branch at the beginning to skip execution of the nops. +.PP +The following options are available when as is configured for a +RISC-V processor. +.IP \fB\-fpic\fR 4 +.IX Item "-fpic" +.PD 0 +.IP \fB\-fPIC\fR 4 +.IX Item "-fPIC" +.PD +Generate position-independent code +.IP \fB\-fno\-pic\fR 4 +.IX Item "-fno-pic" +Don't generate position-independent code (default) +.IP \fB\-march=ISA\fR 4 +.IX Item "-march=ISA" +Select the base isa, as specified by ISA. For example \-march=rv32ima. +If this option and the architecture attributes aren't set, then assembler +will check the default configure setting \-\-with\-arch=ISA. +.IP \fB\-misa\-spec=ISAspec\fR 4 +.IX Item "-misa-spec=ISAspec" +Select the default isa spec version. If the version of ISA isn't set +by \-march, then assembler helps to set the version according to +the default chosen spec. If this option isn't set, then assembler will +check the default configure setting \-\-with\-isa\-spec=ISAspec. +.IP \fB\-mpriv\-spec=PRIVspec\fR 4 +.IX Item "-mpriv-spec=PRIVspec" +Select the privileged spec version. We can decide whether the CSR is valid or +not according to the chosen spec. If this option and the privilege attributes +aren't set, then assembler will check the default configure setting +\&\-\-with\-priv\-spec=PRIVspec. +.IP \fB\-mabi=ABI\fR 4 +.IX Item "-mabi=ABI" +Selects the ABI, which is either "ilp32" or "lp64", optionally followed +by "f", "d", or "q" to indicate single-precision, double-precision, or +quad-precision floating-point calling convention, or none to indicate +the soft-float calling convention. Also, "ilp32" can optionally be followed +by "e" to indicate the RVE ABI, which is always soft-float. +.IP \fB\-mrelax\fR 4 +.IX Item "-mrelax" +Take advantage of linker relaxations to reduce the number of instructions +required to materialize symbol addresses. (default) +.IP \fB\-mno\-relax\fR 4 +.IX Item "-mno-relax" +Don't do linker relaxations. +.IP \fB\-march\-attr\fR 4 +.IX Item "-march-attr" +Generate the default contents for the riscv elf attribute section if the +\&.attribute directives are not set. This section is used to record the +information that a linker or runtime loader needs to check compatibility. +This information includes ISA string, stack alignment requirement, unaligned +memory accesses, and the major, minor and revision version of privileged +specification. +.IP \fB\-mno\-arch\-attr\fR 4 +.IX Item "-mno-arch-attr" +Don't generate the default riscv elf attribute section if the .attribute +directives are not set. +.IP \fB\-mcsr\-check\fR 4 +.IX Item "-mcsr-check" +Enable the CSR checking for the ISA-dependent CRS and the read-only CSR. +The ISA-dependent CSR are only valid when the specific ISA is set. The +read-only CSR can not be written by the CSR instructions. +.IP \fB\-mno\-csr\-check\fR 4 +.IX Item "-mno-csr-check" +Don't do CSR checking. +.IP \fB\-mlittle\-endian\fR 4 +.IX Item "-mlittle-endian" +Generate code for a little endian machine. +.IP \fB\-mbig\-endian\fR 4 +.IX Item "-mbig-endian" +Generate code for a big endian machine. +.PP +See the info pages for documentation of the RX-specific options. +.PP +The following options are available when as is configured for the s390 +processor family. +.IP \fB\-m31\fR 4 +.IX Item "-m31" +.PD 0 +.IP \fB\-m64\fR 4 +.IX Item "-m64" +.PD +Select the word size, either 31/32 bits or 64 bits. +.IP \fB\-mesa\fR 4 +.IX Item "-mesa" +.PD 0 +.IP \fB\-mzarch\fR 4 +.IX Item "-mzarch" +.PD +Select the architecture mode, either the Enterprise System +Architecture (esa) or the z/Architecture mode (zarch). +.IP \fB\-march=\fR\fIprocessor\fR 4 +.IX Item "-march=processor" +Specify which s390 processor variant is the target, \fBg5\fR (or +\&\fBarch3\fR), \fBg6\fR, \fBz900\fR (or \fBarch5\fR), \fBz990\fR (or +\&\fBarch6\fR), \fBz9\-109\fR, \fBz9\-ec\fR (or \fBarch7\fR), \fBz10\fR (or +\&\fBarch8\fR), \fBz196\fR (or \fBarch9\fR), \fBzEC12\fR (or \fBarch10\fR), +\&\fBz13\fR (or \fBarch11\fR), \fBz14\fR (or \fBarch12\fR), \fBz15\fR +(or \fBarch13\fR), or \fBz16\fR (or \fBarch14\fR). +.IP \fB\-mregnames\fR 4 +.IX Item "-mregnames" +.PD 0 +.IP \fB\-mno\-regnames\fR 4 +.IX Item "-mno-regnames" +.PD +Allow or disallow symbolic names for registers. +.IP \fB\-mwarn\-areg\-zero\fR 4 +.IX Item "-mwarn-areg-zero" +Warn whenever the operand for a base or index register has been specified +but evaluates to zero. +.PP +The following options are available when as is configured for a +TMS320C6000 processor. +.IP \fB\-march=\fR\fIarch\fR 4 +.IX Item "-march=arch" +Enable (only) instructions from architecture \fIarch\fR. By default, +all instructions are permitted. +.Sp +The following values of \fIarch\fR are accepted: \f(CW\*(C`c62x\*(C'\fR, +\&\f(CW\*(C`c64x\*(C'\fR, \f(CW\*(C`c64x+\*(C'\fR, \f(CW\*(C`c67x\*(C'\fR, \f(CW\*(C`c67x+\*(C'\fR, \f(CW\*(C`c674x\*(C'\fR. +.IP \fB\-mdsbt\fR 4 +.IX Item "-mdsbt" +.PD 0 +.IP \fB\-mno\-dsbt\fR 4 +.IX Item "-mno-dsbt" +.PD +The \fB\-mdsbt\fR option causes the assembler to generate the +\&\f(CW\*(C`Tag_ABI_DSBT\*(C'\fR attribute with a value of 1, indicating that the +code is using DSBT addressing. The \fB\-mno\-dsbt\fR option, the +default, causes the tag to have a value of 0, indicating that the code +does not use DSBT addressing. The linker will emit a warning if +objects of different type (DSBT and non-DSBT) are linked together. +.IP \fB\-mpid=no\fR 4 +.IX Item "-mpid=no" +.PD 0 +.IP \fB\-mpid=near\fR 4 +.IX Item "-mpid=near" +.IP \fB\-mpid=far\fR 4 +.IX Item "-mpid=far" +.PD +The \fB\-mpid=\fR option causes the assembler to generate the +\&\f(CW\*(C`Tag_ABI_PID\*(C'\fR attribute with a value indicating the form of data +addressing used by the code. \fB\-mpid=no\fR, the default, +indicates position-dependent data addressing, \fB\-mpid=near\fR +indicates position-independent addressing with GOT accesses using near +DP addressing, and \fB\-mpid=far\fR indicates position-independent +addressing with GOT accesses using far DP addressing. The linker will +emit a warning if objects built with different settings of this option +are linked together. +.IP \fB\-mpic\fR 4 +.IX Item "-mpic" +.PD 0 +.IP \fB\-mno\-pic\fR 4 +.IX Item "-mno-pic" +.PD +The \fB\-mpic\fR option causes the assembler to generate the +\&\f(CW\*(C`Tag_ABI_PIC\*(C'\fR attribute with a value of 1, indicating that the +code is using position-independent code addressing, The +\&\f(CW\*(C`\-mno\-pic\*(C'\fR option, the default, causes the tag to have a value of +0, indicating position-dependent code addressing. The linker will +emit a warning if objects of different type (position-dependent and +position-independent) are linked together. +.IP \fB\-mbig\-endian\fR 4 +.IX Item "-mbig-endian" +.PD 0 +.IP \fB\-mlittle\-endian\fR 4 +.IX Item "-mlittle-endian" +.PD +Generate code for the specified endianness. The default is +little-endian. +.PP +The following options are available when as is configured for a TILE-Gx +processor. +.IP "\fB\-m32 | \-m64\fR" 4 +.IX Item "-m32 | -m64" +Select the word size, either 32 bits or 64 bits. +.IP "\fB\-EB | \-EL\fR" 4 +.IX Item "-EB | -EL" +Select the endianness, either big-endian (\-EB) or little-endian (\-EL). +.PP +The following option is available when as is configured for a Visium +processor. +.IP \fB\-mtune=\fR\fIarch\fR 4 +.IX Item "-mtune=arch" +This option specifies the target architecture. If an attempt is made to +assemble an instruction that will not execute on the target architecture, +the assembler will issue an error message. +.Sp +The following names are recognized: +\&\f(CW\*(C`mcm24\*(C'\fR +\&\f(CW\*(C`mcm\*(C'\fR +\&\f(CW\*(C`gr5\*(C'\fR +\&\f(CW\*(C`gr6\*(C'\fR +.PP +The following options are available when as is configured for an +Xtensa processor. +.IP "\fB\-\-text\-section\-literals | \-\-no\-text\-section\-literals\fR" 4 +.IX Item "--text-section-literals | --no-text-section-literals" +Control the treatment of literal pools. The default is +\&\fB\-\-no\-text\-section\-literals\fR, which places literals in +separate sections in the output file. This allows the literal pool to be +placed in a data RAM/ROM. With \fB\-\-text\-section\-literals\fR, the +literals are interspersed in the text section in order to keep them as +close as possible to their references. This may be necessary for large +assembly files, where the literals would otherwise be out of range of the +\&\f(CW\*(C`L32R\*(C'\fR instructions in the text section. Literals are grouped into +pools following \f(CW\*(C`.literal_position\*(C'\fR directives or preceding +\&\f(CW\*(C`ENTRY\*(C'\fR instructions. These options only affect literals referenced +via PC-relative \f(CW\*(C`L32R\*(C'\fR instructions; literals for absolute mode +\&\f(CW\*(C`L32R\*(C'\fR instructions are handled separately. +.IP "\fB\-\-auto\-litpools | \-\-no\-auto\-litpools\fR" 4 +.IX Item "--auto-litpools | --no-auto-litpools" +Control the treatment of literal pools. The default is +\&\fB\-\-no\-auto\-litpools\fR, which in the absence of +\&\fB\-\-text\-section\-literals\fR places literals in separate sections +in the output file. This allows the literal pool to be placed in a data +RAM/ROM. With \fB\-\-auto\-litpools\fR, the literals are interspersed +in the text section in order to keep them as close as possible to their +references, explicit \f(CW\*(C`.literal_position\*(C'\fR directives are not +required. This may be necessary for very large functions, where single +literal pool at the beginning of the function may not be reachable by +\&\f(CW\*(C`L32R\*(C'\fR instructions at the end. These options only affect +literals referenced via PC-relative \f(CW\*(C`L32R\*(C'\fR instructions; literals +for absolute mode \f(CW\*(C`L32R\*(C'\fR instructions are handled separately. +When used together with \fB\-\-text\-section\-literals\fR, +\&\fB\-\-auto\-litpools\fR takes precedence. +.IP "\fB\-\-absolute\-literals | \-\-no\-absolute\-literals\fR" 4 +.IX Item "--absolute-literals | --no-absolute-literals" +Indicate to the assembler whether \f(CW\*(C`L32R\*(C'\fR instructions use absolute +or PC-relative addressing. If the processor includes the absolute +addressing option, the default is to use absolute \f(CW\*(C`L32R\*(C'\fR +relocations. Otherwise, only the PC-relative \f(CW\*(C`L32R\*(C'\fR relocations +can be used. +.IP "\fB\-\-target\-align | \-\-no\-target\-align\fR" 4 +.IX Item "--target-align | --no-target-align" +Enable or disable automatic alignment to reduce branch penalties at some +expense in code size. This optimization is enabled by default. Note +that the assembler will always align instructions like \f(CW\*(C`LOOP\*(C'\fR that +have fixed alignment requirements. +.IP "\fB\-\-longcalls | \-\-no\-longcalls\fR" 4 +.IX Item "--longcalls | --no-longcalls" +Enable or disable transformation of call instructions to allow calls +across a greater range of addresses. This option should be used when call +targets can potentially be out of range. It may degrade both code size +and performance, but the linker can generally optimize away the +unnecessary overhead when a call ends up within range. The default is +\&\fB\-\-no\-longcalls\fR. +.IP "\fB\-\-transform | \-\-no\-transform\fR" 4 +.IX Item "--transform | --no-transform" +Enable or disable all assembler transformations of Xtensa instructions, +including both relaxation and optimization. The default is +\&\fB\-\-transform\fR; \fB\-\-no\-transform\fR should only be used in the +rare cases when the instructions must be exactly as specified in the +assembly source. Using \fB\-\-no\-transform\fR causes out of range +instruction operands to be errors. +.IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR" 4 +.IX Item "--rename-section oldname=newname" +Rename the \fIoldname\fR section to \fInewname\fR. This option can be used +multiple times to rename multiple sections. +.IP "\fB\-\-trampolines | \-\-no\-trampolines\fR" 4 +.IX Item "--trampolines | --no-trampolines" +Enable or disable transformation of jump instructions to allow jumps +across a greater range of addresses. This option should be used when jump targets can +potentially be out of range. In the absence of such jumps this option +does not affect code size or performance. The default is +\&\fB\-\-trampolines\fR. +.IP "\fB\-\-abi\-windowed | \-\-abi\-call0\fR" 4 +.IX Item "--abi-windowed | --abi-call0" +Choose ABI tag written to the \f(CW\*(C`.xtensa.info\*(C'\fR section. ABI tag +indicates ABI of the assembly code. A warning is issued by the linker +on an attempt to link object files with inconsistent ABI tags. +Default ABI is chosen by the Xtensa core configuration. +.PP +The following options are available when as is configured for an +Z80 processor. +.PP +\&\f(CW@chapter\fR Z80 Dependent Features +.SS "Command-line Options" +.IX Subsection "Command-line Options" +.IP \fB\-march=\fR\fICPU\fR\fB[\-\fR\fIEXT\fR\fB...][+\fR\fIEXT\fR\fB...]\fR 4 +.IX Item "-march=CPU[-EXT...][+EXT...]" +This option specifies the target processor. The assembler will issue +an error message if an attempt is made to assemble an instruction which +will not execute on the target processor. The following processor names +are recognized: +\&\f(CW\*(C`z80\*(C'\fR, +\&\f(CW\*(C`z180\*(C'\fR, +\&\f(CW\*(C`ez80\*(C'\fR, +\&\f(CW\*(C`gbz80\*(C'\fR, +\&\f(CW\*(C`z80n\*(C'\fR, +\&\f(CW\*(C`r800\*(C'\fR. +In addition to the basic instruction set, the assembler can be told to +accept some extention mnemonics. For example, +\&\f(CW\*(C`\-march=z180+sli+infc\*(C'\fR extends \fIz180\fR with \fISLI\fR instructions and +\&\fIIN F,(C)\fR. The following extentions are currently supported: +\&\f(CW\*(C`full\*(C'\fR (all known instructions), +\&\f(CW\*(C`adl\*(C'\fR (ADL CPU mode by default, eZ80 only), +\&\f(CW\*(C`sli\*(C'\fR (instruction known as \fISLI\fR, \fISLL\fR or \fISL1\fR), +\&\f(CW\*(C`xyhl\*(C'\fR (instructions with halves of index registers: \fIIXL\fR, \fIIXH\fR, +\&\fIIYL\fR, \fIIYH\fR), +\&\f(CW\*(C`xdcb\*(C'\fR (instructions like \fIRotOp (II+d),R\fR and \fIBitOp n,(II+d),R\fR), +\&\f(CW\*(C`infc\*(C'\fR (instruction \fIIN F,(C)\fR or \fIIN (C)\fR), +\&\f(CW\*(C`outc0\*(C'\fR (instruction \fIOUT (C),0\fR). +Note that rather than extending a basic instruction set, the extention +mnemonics starting with \f(CW\*(C`\-\*(C'\fR revoke the respective functionality: +\&\f(CW\*(C`\-march=z80\-full+xyhl\*(C'\fR first removes all default extentions and adds +support for index registers halves only. +.Sp +If this option is not specified then \f(CW\*(C`\-march=z80+xyhl+infc\*(C'\fR is assumed. +.IP \fB\-local\-prefix=\fR\fIprefix\fR 4 +.IX Item "-local-prefix=prefix" +Mark all labels with specified prefix as local. But such label can be +marked global explicitly in the code. This option do not change default +local label prefix \f(CW\*(C`.L\*(C'\fR, it is just adds new one. +.IP \fB\-colonless\fR 4 +.IX Item "-colonless" +Accept colonless labels. All symbols at line begin are treated as labels. +.IP \fB\-sdcc\fR 4 +.IX Item "-sdcc" +Accept assembler code produced by SDCC. +.IP \fB\-fp\-s=\fR\fIFORMAT\fR 4 +.IX Item "-fp-s=FORMAT" +Single precision floating point numbers format. Default: ieee754 (32 bit). +.IP \fB\-fp\-d=\fR\fIFORMAT\fR 4 +.IX Item "-fp-d=FORMAT" +Double precision floating point numbers format. Default: ieee754 (64 bit). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBgcc\fR\|(1), \fBld\fR\|(1), and the Info entries for \fIbinutils\fR and \fIld\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/asciitopgm.1 b/upstream/fedora-40/man1/asciitopgm.1 new file mode 100644 index 00000000..ff6adc8b --- /dev/null +++ b/upstream/fedora-40/man1/asciitopgm.1 @@ -0,0 +1,102 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Asciitopgm User Manual" 0 "20 January 2011" "netpbm documentation" + +.SH NAME +asciitopgm - convert ASCII graphics into a PGM + +.UN synopsis +.SH SYNOPSIS + +\fBasciitopgm\fP +[\fB-d\fP \fIdivisor\fP] \fIheight\fP \fIwidth\fP [\fIasciifile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBasciitopgm\fP reads ASCII data as input and produces a PGM image +with pixel values which are an approximation of the +"brightness" of the ASCII characters, assuming +black-on-white printing. In other words, a capital M is very dark, a +period is very light, and a space is white. +.PP +Obviously, \fBasciitopgm\fP assumes a certain font in assigning +a brightness value to a character. +.PP +\fBasciitopgm\fP considers ASCII control characters to be all white. For +a lower case character, It assigns a special brightnesses which has nothing to +do with what it looks like printed. +\fBasciitopgm\fP takes the ASCII character code from the lower 7 bits +of each input byte. But it warns you if the most significant bit of +any input byte is not zero. +.PP +The output image is \fIheight\fP pixels high by \fIwidth\fP pixels wide, +truncating and padding with white on the right and bottom as necessary. +.PP +The \fIdivisor\fP value is an integer (decimal) by which the +blackness of an input character is divided. You can use this to +adjust the brightness of the output: for example, if the image is too +bright, increase the divisor. +.PP +In a sort of reminiscence of Fortran line printer carriage control, +where a line starts with \fB+\fP (plus), \fBasciitopgm\fP combines it +with the previous row of output instead of generating a new row. This +allows a larger range of gray values. (In Fortran carriage control, the +first character of every line sent to the printer tells how much to advance +the paper, with \fB+\fP meaning not at all, so that the rest of the +characters on the line overstrike the ones already on the paper. What +\fBasciitopgm\fP does is rather different in that \fBasciitopgm\fP does not +reserve the first character of every line that way. If the first character is +anything but \fB+\fP, \fBasciitopgm\fP considers it just to be first +character of the image. +.PP +If you're looking for something that creates an image of text, +with that text specified in ASCII, that is something quite different. +Use \fBpbmtext\fP for that. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBasciitopgm\fP recognizes the following +command line option: + + +.TP +\fB-d\fP \fIdivisor\fP +Specify the value by which the blackness of an input character is +divided. This is an integer value. Default value is 1. Larger +values produce darker output images. + + + +.UN seealso +.SH SEE ALSO +.BR "pbmtoascii" (1)\c +\&, +.BR "pbmtext" (1)\c +\&, +.BR "pgm" (1)\c +\& + +.UN author +.SH AUTHOR + +Wilson H. Bent. Jr. (\fIwhb@usc.edu\fP) +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/asciitopgm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/at.1 b/upstream/fedora-40/man1/at.1 new file mode 100644 index 00000000..bae9ba7b --- /dev/null +++ b/upstream/fedora-40/man1/at.1 @@ -0,0 +1,334 @@ +.TH AT 1 2009-11-14 +.SH NAME +at, batch, atq, atrm \- queue, examine, or delete jobs for later execution +.SH SYNOPSIS +.B at +.RB [ \-V ] +.RB [ \-q +.IR queue ] +.RB [ \-f +.IR file ] +.RB [ \-u +.IR username ] +.RB [ \-mMlv ] +.IR timespec " ...\&" +.br +.B at +.RB [ \-V ] +.RB [ \-q +.IR queue ] +.RB [ \-f +.IR file ] +.RB [ \-u +.IR username ] +.RB [ \-mMkv ] +.RB [ \-t +.IR time ] +.br +.B "at \-c" +.I job +[...\&] +.br +.B at +.RB [ \-V ] +.RB \-l +.RB [ -o +.IR timeformat ] +.I [job +.IR ... ] +.br +.B atq +.RB [ \-V ] +.RB [ \-q +.IR queue ] +.RB [ -o +.IR timeformat ] +.I [job +.IR ... ] +.br +.B at +.RB [ \-rd ] +.I job +[...\&] +.br +.B atrm +.RB [ \-V ] +.I job +[...\&] +.br +.B batch +.br +.B "at \-b" +.SH DESCRIPTION +.B at +and +.B batch +read commands from standard input or a specified file which are to +be executed at a later time, using +.BR /bin/sh . +.TP 8 +.B at +executes commands at a specified time. +.TP 8 +.B atq +lists the user's pending jobs, unless the user is the superuser; in that +case, everybody's jobs are listed. The format of the output lines (one +for each job) is: Job number, date, hour, queue, and username. +.TP 8 +.B atrm +deletes jobs, identified by their job number. +.TP 8 +.B batch +executes commands when system load levels permit; in other words, when the load average +drops below 0.8, or the value specified in the invocation of +.BR atd . +.PP +.B At +allows fairly complex time +specifications, extending the POSIX.2 standard. It accepts times +of the form +.B HH:MM +to run a job at a specific time of day. +(If that time is already past, the next day is assumed.) +You may also specify +.B midnight, +.B noon, +or +.B teatime +(4pm) +and you can have a time-of-day suffixed with +.B AM +or +.B PM +for running in the morning or the evening. +You can also say what day the job will be run, +by giving a date in the form +.B month-name +.B day +with an optional +.B year, +or giving a date of the form +.IR MMDD [ CC ] YY , +.IR MM / DD /[ CC ] YY , +.IR DD . MM .[ CC ] YY +or +.RI [ CC ] YY - MM - DD . +The specification of a date +.I must +follow the specification of the time of day. +You can also give times like +.B now +.B + +.I count +.I time-units, +where the time-units can be +.B minutes, +.B hours, +.B days, +or +.B weeks +and you can tell +.B at +to run the job today by suffixing the time with +.B today +and to run the job tomorrow by suffixing the time with +.B tomorrow. +.PP +For example, to run a job at 4pm three days from now, you would do +.B at 4pm + 3 days, +to run a job at 10:00am on July 31, you would do +.B at 10am Jul 31 +and to run a job at 1am tomorrow, you would do +.B at 1am tomorrow. +.PP +If you specify a job to absolutely run at a specific time and date in +the past, the job will run as soon as possible. For example, if it is +8pm and you do a +.B at 6pm today, +it will run more likely at 8:05pm. +.PP +The definition of the time specification can be found in +.IR /usr/share/doc/at/timespec . +.PP +For both +.BR at " and " batch , +commands are read from standard input or the file specified +with the +.B \-f +option and executed. +The working directory, the environment (except for the variables +.BR BASH_VERSINFO , +.BR DISPLAY , +.BR EUID , +.BR GROUPS , +.BR SHELLOPTS , +.BR TERM , +.BR UID , +and +.BR _ ) +and the umask are retained from the time of invocation. + +As +.B at +is currently implemented as a setuid program, other environment variables (e.g., +.BR LD_LIBRARY_PATH " or " LD_PRELOAD ) +are also not exported. This may change in the future. As a workaround, +set these variables explicitly in your job. + +An +.BR "at " \- +or +.BR "batch "\- +command invoked from a +.BR su (1) +shell will retain the current userid. +The user will be mailed standard error and standard output from his +commands, if any. +Mail will be sent using the command +.BR /usr/sbin/sendmail . +If +.B at +is executed from a +.BR su (1) +shell, the owner of the login shell will receive the mail. +.PP +The superuser may use these commands in any case. +For other users, permission to use at is determined by the files +.I /etc/at.allow +and +.IR /etc/at.deny . +See +.BR at.allow (5) +for details. +.SH OPTIONS +.TP 8 +.B \-V +prints the version number to standard error and exit successfully. +.TP 8 +.BI \-q " queue" +uses the specified queue. +A queue designation consists of a single letter; valid queue designations +range from +.B a +to +.B z +and +.B A +to +.BR Z . +The +.B a +queue is the default for +.B at +and the +.B b +queue for +.BR batch . +Queues with higher letters run with increased niceness. The special +queue "=" is reserved for jobs which are currently running. + +If a job is submitted to a queue designated with an uppercase letter, the +job is treated as if it were submitted to batch at the time of the job. +Once the time is reached, the batch processing rules with respect to load +average apply. +If +.B atq +is given a specific queue, it will only show jobs pending in that queue. +.TP 8 +.B \-m +Send mail to the user when the job has completed even if there was no +output. +.TP 8 +.B \-M +Never send mail to the user. +.TP 8 +.BI \-u " username" +Sends mail to +.I username +rather than the current user. +.TP 8 +.BI \-f " file" +Reads the job from +.I file +rather than standard input. +.TP 8 +.BI \-t " time" +run the job at +.IR time , +given in the format [[CC]YY]MMDDhhmm[.ss] +.TP 8 +.B \-l +Is an alias for +.B atq. +.TP +.B \-r +Is an alias for +.B atrm. +.TP +.B \-d +Is an alias for +.B atrm. +.TP +.B \-b +is an alias for +.BR batch . +.TP +.B \-v +Shows the time the job will be executed before reading the job. +.P +Times displayed will be in the format "Thu Feb 20 14:50:00 1997". +.TP +.B +\-c +cats the jobs listed on the command line to standard output. +.TP 8 +.BI \-o " fmt" +strftime-like time format used for the job list +.SH FILES +.I /var/spool/at +.br +.I /var/spool/at/spool +.br +.I /proc/loadavg +.br +.I /var/run/utmp +.br +.I /etc/at.allow +.br +.I /etc/at.deny +.SH SEE ALSO +.BR at.allow (5), +.BR at.deny (5), +.BR atd (8), +.BR cron (1), +.BR nice (1), +.BR sh (1), +.BR umask (2). +.SH BUGS +The correct operation of +.B batch +for Linux depends on the presence of a +.IR proc - +type directory mounted on +.IR /proc . +.PP +If the file +.I /var/run/utmp +is not available or corrupted, or if the user is not logged on at the +time +.B at +is invoked, the mail is sent to the userid found +in the environment variable +.BR LOGNAME . +If that is undefined or empty, the current userid is assumed. +.PP +.B At +and +.B batch +as presently implemented are not suitable when users are competing for +resources. +If this is the case for your site, you might want to consider another +batch system, such as +.BR nqs . +.SH AUTHOR +At was mostly written by Thomas Koenig. diff --git a/upstream/fedora-40/man1/atktopbm.1 b/upstream/fedora-40/man1/atktopbm.1 new file mode 100644 index 00000000..eaa79655 --- /dev/null +++ b/upstream/fedora-40/man1/atktopbm.1 @@ -0,0 +1,61 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Atktopbm User Manual" 0 "26 September 1991" "netpbm documentation" + +.SH NAME +atktopbm - convert Andrew Toolkit raster object to PBM + +.UN synopsis +.SH SYNOPSIS + +\fBatktopbm\fP [\fIatkfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBatktopbm\fP reads an Andrew Toolkit raster object as input. +and produces a PBM image as output. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBatktopbm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO + + +.IP \(bu + +.BR "pbmtoatk" (1)\c +\& +.IP \(bu + +.BR "pbm" (1)\c +\& + + + +.UN author +.SH AUTHOR + +Copyright (C) 1991 by Bill Janssen. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/atktopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/autoconf.1 b/upstream/fedora-40/man1/autoconf.1 new file mode 100644 index 00000000..dcf6762f --- /dev/null +++ b/upstream/fedora-40/man1/autoconf.1 @@ -0,0 +1,128 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTOCONF "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autoconf \- Generate configuration scripts +.SH SYNOPSIS +.B autoconf +[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR] +.SH DESCRIPTION +Generate a configuration script from a TEMPLATE\-FILE if given, or +\&'configure.ac' if present, or else 'configure.in'. Output is sent +to the standard output if TEMPLATE\-FILE is given, else into +\&'configure'. +.SS "Operation modes:" +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.TP +\fB\-f\fR, \fB\-\-force\fR +consider all files obsolete +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE (stdout is the default) +.TP +\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR +report the warnings falling in CATEGORY +.SS "Warning categories include:" +.TP +cross +cross compilation issues +.TP +gnu +GNU coding standards (default in gnu and gnits modes) +.TP +obsolete +obsolete features or constructions (default) +.TP +override +user redefinitions of Automake rules or variables +.TP +portability +portability issues (default in gnu and gnits modes) +.TP +portability\-recursive +nested Make variables (default with \fB\-Wportability\fR) +.TP +extra\-portability +extra portability issues related to obscure tools +.TP +syntax +dubious syntactic constructs (default) +.TP +unsupported +unsupported or incomplete features (default) +.TP +all +all the warnings +.TP +no\-CATEGORY +turn off warnings in CATEGORY +.TP +none +turn off all the warnings +.PP +The environment variables 'M4' and 'WARNINGS' are honored. +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.SS "Tracing:" +.TP +\fB\-t\fR, \fB\-\-trace\fR=\fI\,MACRO[\/\fR:FORMAT] +report the list of calls to MACRO +.TP +\fB\-i\fR, \fB\-\-initialization\fR +also trace Autoconf's initialization process +.PP +In tracing mode, no configuration script is created. FORMAT defaults +to '$f:$l:$n:$%'; see 'autom4te \fB\-\-help\fR' for information about FORMAT. +.SH AUTHOR +Written by David J. MacKenzie and Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autoconf +is maintained as a Texinfo manual. If the +.B info +and +.B autoconf +programs are properly installed at your site, the command +.IP +.B info autoconf +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autoheader.1 b/upstream/fedora-40/man1/autoheader.1 new file mode 100644 index 00000000..d90418b0 --- /dev/null +++ b/upstream/fedora-40/man1/autoheader.1 @@ -0,0 +1,114 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTOHEADER "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autoheader \- Create a template header for configure +.SH SYNOPSIS +.B autoheader +[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR] +.SH DESCRIPTION +Create a template file of C '#define' statements for 'configure' to +use. To this end, scan TEMPLATE\-FILE, or 'configure.ac' if present, +or else 'configure.in'. +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.TP +\fB\-f\fR, \fB\-\-force\fR +consider all files obsolete +.TP +\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR +report the warnings falling in CATEGORY +.SS "Warning categories include:" +.TP +cross +cross compilation issues +.TP +gnu +GNU coding standards (default in gnu and gnits modes) +.TP +obsolete +obsolete features or constructions (default) +.TP +override +user redefinitions of Automake rules or variables +.TP +portability +portability issues (default in gnu and gnits modes) +.TP +portability\-recursive +nested Make variables (default with \fB\-Wportability\fR) +.TP +extra\-portability +extra portability issues related to obscure tools +.TP +syntax +dubious syntactic constructs (default) +.TP +unsupported +unsupported or incomplete features (default) +.TP +all +all the warnings +.TP +no\-CATEGORY +turn off warnings in CATEGORY +.TP +none +turn off all the warnings +.TP +error +treat warnings as errors +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.SH AUTHOR +Written by Roland McGrath and Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autoheader +is maintained as a Texinfo manual. If the +.B info +and +.B autoheader +programs are properly installed at your site, the command +.IP +.B info autoheader +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autom4te.1 b/upstream/fedora-40/man1/autom4te.1 new file mode 100644 index 00000000..c7902d2e --- /dev/null +++ b/upstream/fedora-40/man1/autom4te.1 @@ -0,0 +1,198 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTOM4TE "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autom4te \- Generate files and scripts thanks to M4 +.SH SYNOPSIS +.B autom4te +[\fI\,OPTION\/\fR]... [\fI\,FILES\/\fR] +.SH DESCRIPTION +Run GNU M4 on the FILES, avoiding useless runs. Output the traces if tracing, +the frozen file if freezing, otherwise the expansion of the FILES. +.PP +If some of the FILES are named 'FILE.m4f' they are considered to be M4 +frozen files of all the previous files (which are therefore not loaded). +If 'FILE.m4f' is not found, then 'FILE.m4' will be used, together with +all the previous files. +.PP +Some files may be optional, i.e., will only be processed if found in the +include path, but then must end in '.m4?'; the question mark is not part +of the actual file name. +.SS "Operation modes:" +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE (defaults to '\-', stdout) +.TP +\fB\-f\fR, \fB\-\-force\fR +don't rely on cached values +.TP +\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR +report the warnings falling in CATEGORY +.TP +\fB\-l\fR, \fB\-\-language\fR=\fI\,LANG\/\fR +specify the set of M4 macros to use +.TP +\fB\-C\fR, \fB\-\-cache\fR=\fI\,DIRECTORY\/\fR +preserve results for future runs in DIRECTORY +.TP +\fB\-\-no\-cache\fR +disable the cache +.TP +\fB\-m\fR, \fB\-\-mode\fR=\fI\,OCTAL\/\fR +change the non trace output file mode (0666) +.TP +\fB\-M\fR, \fB\-\-melt\fR +don't use M4 frozen files +.SS "Languages include:" +.TP +\&'Autoconf' +create Autoconf configure scripts +.TP +\&'Autotest' +create Autotest test suites +.TP +\&'M4sh' +create M4sh shell scripts +.TP +\&'M4sugar' +create M4sugar output +.SS "Warning categories include:" +.TP +cross +cross compilation issues +.TP +gnu +GNU coding standards (default in gnu and gnits modes) +.TP +obsolete +obsolete features or constructions (default) +.TP +override +user redefinitions of Automake rules or variables +.TP +portability +portability issues (default in gnu and gnits modes) +.TP +portability\-recursive +nested Make variables (default with \fB\-Wportability\fR) +.TP +extra\-portability +extra portability issues related to obscure tools +.TP +syntax +dubious syntactic constructs (default) +.TP +unsupported +unsupported or incomplete features (default) +.TP +all +all the warnings +.TP +no\-CATEGORY +turn off warnings in CATEGORY +.TP +none +turn off all the warnings +.TP +error +treat warnings as errors +.PP +The environment variables 'M4' and 'WARNINGS' are honored. +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.SS "Tracing:" +.TP +\fB\-t\fR, \fB\-\-trace\fR=\fI\,MACRO[\/\fR:FORMAT] +report the MACRO invocations +.TP +\fB\-p\fR, \fB\-\-preselect\fR=\fI\,MACRO\/\fR +prepare to trace MACRO in a future run +.SS "Freezing:" +.TP +\fB\-F\fR, \fB\-\-freeze\fR +produce an M4 frozen state file for FILES +.SS "FORMAT defaults to '$f:$l:$n:$%', and can use the following escapes:" +.TP +$$ +literal $ +.TP +$f +file where macro was called +.TP +$l +line where macro was called +.TP +$d +nesting depth of macro call +.TP +$n +name of the macro +.TP +$NUM +argument NUM, unquoted and with newlines +.TP +$SEP@ +all arguments, with newlines, quoted, and separated by SEP +.TP +$SEP* +all arguments, with newlines, unquoted, and separated by SEP +.TP +$SEP% +all arguments, without newlines, unquoted, and separated by SEP +.PP +SEP can be empty for the default (comma for @ and *, colon for %), +a single character for that character, or {STRING} to use a string. +.SH AUTHOR +Written by Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autom4te +is maintained as a Texinfo manual. If the +.B info +and +.B autom4te +programs are properly installed at your site, the command +.IP +.B info autom4te +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autopoint.1 b/upstream/fedora-40/man1/autopoint.1 new file mode 100644 index 00000000..47d30007 --- /dev/null +++ b/upstream/fedora-40/man1/autopoint.1 @@ -0,0 +1,47 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. +.TH AUTOPOINT "1" "June 2023" "GNU gettext-tools 0.22" "User Commands" +.SH NAME +autopoint \- copies standard gettext infrastructure +.SH SYNOPSIS +.B autopoint +[\fI\,OPTION\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Copies standard gettext infrastructure files into a source package. +.SH OPTIONS +.TP +\fB\-\-help\fR +print this help and exit +.TP +\fB\-\-version\fR +print version information and exit +.TP +\fB\-f\fR, \fB\-\-force\fR +force overwriting of files that already exist +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +print modifications but don't perform them +.SH AUTHOR +Written by Bruno Haible +.SH "REPORTING BUGS" +Report bugs in the bug tracker at +or by email to . +.SH COPYRIGHT +Copyright \(co 2002\-2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B autopoint +is maintained as a Texinfo manual. If the +.B info +and +.B autopoint +programs are properly installed at your site, the command +.IP +.B info autopoint +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autoreconf.1 b/upstream/fedora-40/man1/autoreconf.1 new file mode 100644 index 00000000..a0970b10 --- /dev/null +++ b/upstream/fedora-40/man1/autoreconf.1 @@ -0,0 +1,140 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTORECONF "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autoreconf \- Update generated configuration files +.SH SYNOPSIS +.B autoreconf +[\fI\,OPTION\/\fR]... [\fI\,DIRECTORY\/\fR]... +.SH DESCRIPTION +Run 'autoconf' and, when needed, 'aclocal', 'autoheader', 'automake', +\&'autopoint' (formerly 'gettextize'), 'libtoolize', 'intltoolize', and +\&'gtkdocize' to regenerate the GNU Build System files in specified +DIRECTORIES and their subdirectories (defaulting to '.'). +.PP +By default, it only remakes those files that are older than their +sources. If you install new versions of the GNU Build System, +you can make 'autoreconf' remake all of the files by giving it the +\&'\-\-force' option. +.SS "Operation modes:" +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.TP +\fB\-f\fR, \fB\-\-force\fR +consider all generated and standard files obsolete +.TP +\fB\-i\fR, \fB\-\-install\fR +copy missing standard auxiliary files +.TP +\fB\-\-no\-recursive\fR +don't rebuild sub\-packages +.TP +\fB\-s\fR, \fB\-\-symlink\fR +with \fB\-i\fR, install symbolic links instead of copies +.TP +\fB\-m\fR, \fB\-\-make\fR +when applicable, re\-run ./configure && make +.TP +\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR +report the warnings falling in CATEGORY [syntax] +.SS "Warning categories include:" +.TP +cross +cross compilation issues +.TP +gnu +GNU coding standards (default in gnu and gnits modes) +.TP +obsolete +obsolete features or constructions (default) +.TP +override +user redefinitions of Automake rules or variables +.TP +portability +portability issues (default in gnu and gnits modes) +.TP +portability\-recursive +nested Make variables (default with \fB\-Wportability\fR) +.TP +extra\-portability +extra portability issues related to obscure tools +.TP +syntax +dubious syntactic constructs (default) +.TP +unsupported +unsupported or incomplete features (default) +.TP +all +all the warnings +.TP +no\-CATEGORY +turn off warnings in CATEGORY +.TP +none +turn off all the warnings +.TP +error +treat warnings as errors +.PP +The environment variable 'WARNINGS' is honored. Some subtools might +support other warning types, using 'all' is encouraged. +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.PP +The environment variables AUTOCONF, ACLOCAL, AUTOHEADER, AUTOM4TE, +AUTOMAKE, AUTOPOINT, GTKDOCIZE, INTLTOOLIZE, LIBTOOLIZE, M4, and MAKE +are honored. +.SH AUTHOR +Written by David J. MacKenzie and Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autoreconf +is maintained as a Texinfo manual. If the +.B info +and +.B autoreconf +programs are properly installed at your site, the command +.IP +.B info autoreconf +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autoscan.1 b/upstream/fedora-40/man1/autoscan.1 new file mode 100644 index 00000000..cae64007 --- /dev/null +++ b/upstream/fedora-40/man1/autoscan.1 @@ -0,0 +1,70 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTOSCAN "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autoscan \- Generate a preliminary configure.ac +.SH SYNOPSIS +.B autoscan +[\fI\,OPTION\/\fR]... [\fI\,SRCDIR\/\fR] +.SH DESCRIPTION +Examine source files in the directory tree rooted at SRCDIR, or the +current directory if none is given. Search the source files for +common portability problems, check for incompleteness of +\&'configure.ac', and create a file 'configure.scan' which is a +preliminary 'configure.ac' for that package. +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.SH AUTHOR +Written by David J. MacKenzie and Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autoscan +is maintained as a Texinfo manual. If the +.B info +and +.B autoscan +programs are properly installed at your site, the command +.IP +.B info autoscan +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/autoupdate.1 b/upstream/fedora-40/man1/autoupdate.1 new file mode 100644 index 00000000..0b18ca58 --- /dev/null +++ b/upstream/fedora-40/man1/autoupdate.1 @@ -0,0 +1,72 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH AUTOUPDATE "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +autoupdate \- Update a configure.ac to a newer Autoconf +.SH SYNOPSIS +.B autoupdate +[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR]... +.SH DESCRIPTION +Update each TEMPLATE\-FILE if given, or 'configure.ac' if present, +or else 'configure.in', to the syntax of the current version of +Autoconf. The original files are backed up. +.SS "Operation modes:" +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.TP +\fB\-v\fR, \fB\-\-verbose\fR +verbosely report processing +.TP +\fB\-d\fR, \fB\-\-debug\fR +don't remove temporary files +.TP +\fB\-f\fR, \fB\-\-force\fR +consider all files obsolete +.SS "Library directories:" +.TP +\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR +prepend directory DIR to search path +.TP +\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR +append directory DIR to search path +.SH AUTHOR +Written by David J. MacKenzie and Akim Demaille. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B autoupdate +is maintained as a Texinfo manual. If the +.B info +and +.B autoupdate +programs are properly installed at your site, the command +.IP +.B info autoupdate +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/avstopam.1 b/upstream/fedora-40/man1/avstopam.1 new file mode 100644 index 00000000..38604e4b --- /dev/null +++ b/upstream/fedora-40/man1/avstopam.1 @@ -0,0 +1,63 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Avstopam User Manual" 0 "07 February 2010" "netpbm documentation" +.PP + +.PP + +.SH NAME +.PP +avstopam - convert an AVS X image to a Netpbm image + +.UN synopsis +.SH SYNOPSIS +.PP +\fBavstopam\fP +[\fIavsfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBavstopam\fP reads a Stardent AVS X image as input and produces a Netpbm +image as output. +.PP +\fIavsfile\fP is the input file, which defaults to Standard Input. +Output is always on Standard Output. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBavstopam\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN author +.SH AUTHOR +.PP +Copyright\ \(co 2010 Scott Pakin, +\fIscott+pbm@pakin.org\fP + +.UN seealso +.SH SEE ALSO +.PP +.BR "pamtoavs" (1)\c +\&, +.BR "pam" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/avstopam.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/b2sum.1 b/upstream/fedora-40/man1/b2sum.1 new file mode 100644 index 00000000..3f0366c5 --- /dev/null +++ b/upstream/fedora-40/man1/b2sum.1 @@ -0,0 +1,84 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH B2SUM "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +b2sum \- compute and check BLAKE2 message digest +.SH SYNOPSIS +.B b2sum +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print or check BLAKE2b (512\-bit) checksums. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-b\fR, \fB\-\-binary\fR +read in binary mode +.TP +\fB\-c\fR, \fB\-\-check\fR +read checksums from the FILEs and check them +.TP +\fB\-l\fR, \fB\-\-length\fR=\fI\,BITS\/\fR +digest length in bits; must not exceed the max for +the blake2 algorithm and must be a multiple of 8 +.TP +\fB\-\-tag\fR +create a BSD\-style checksum +.TP +\fB\-t\fR, \fB\-\-text\fR +read in text mode (default) +.TP +\fB\-z\fR, \fB\-\-zero\fR +end each output line with NUL, not newline, +and disable file name escaping +.SS "The following five options are useful only when verifying checksums:" +.TP +\fB\-\-ignore\-missing\fR +don't fail or report status for missing files +.TP +\fB\-\-quiet\fR +don't print OK for each successfully verified file +.TP +\fB\-\-status\fR +don't output anything, status code shows success +.TP +\fB\-\-strict\fR +exit non\-zero for improperly formatted checksum lines +.TP +\fB\-w\fR, \fB\-\-warn\fR +warn about improperly formatted checksum lines +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +The sums are computed as described in RFC 7693. +When checking, the input should be a former output of this program. +The default mode is to print a line with: checksum, a space, +a character indicating input mode ('*' for binary, ' ' for text +or where binary is insignificant), and name for each FILE. +.PP +Note: There is no difference between binary mode and text mode on GNU systems. +.SH AUTHOR +Written by Padraig Brady and Samuel Neves. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBcksum\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) b2sum invocation\(aq diff --git a/upstream/fedora-40/man1/banner.1 b/upstream/fedora-40/man1/banner.1 new file mode 100644 index 00000000..7235053a --- /dev/null +++ b/upstream/fedora-40/man1/banner.1 @@ -0,0 +1,101 @@ +.\" vim: set ft=nroff .\" +.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +.\" # +.\" # C E D A R +.\" # S O L U T I O N S "Software done right." +.\" # S O F T W A R E +.\" # +.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +.\" # +.\" # Author : Kenneth J. Pronovici +.\" # Project : banner +.\" # Purpose : Manpage for the banner program +.\" # +.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +.TH banner "1" "Oct 2020" "Banner" "Kenneth J. Pronovici" +.SH NAME +banner \- prints a short string to the console in very large letters +.SH SYNOPSIS +.B banner +\fIstring\fR +.SH DESCRIPTION +.PP +This is a classic-style banner program similar to the one found in Solaris or +AIX in the late 1990s. It prints a short string to the console in very large +letters. +.PP +Banners that do not fit in the terminal will be truncated. If $COLUMNS is +exported in the environment, it is taken to be the width of the terminal. If +$COLUMNS is not exported, and TIOCGWINSZ is available on the platform, then its +idea of the terminal size is used. Otherwise, a terminal width of 80 +characters is assumed. +.PP +Usage is straightforward. For instance, a single word is printed like this: +.PP + > banner ken + + # # ####### # # + # # # ## # + # # # # # # + ### ##### # # # + # # # # # # + # # # # ## + # # ####### # # +.PP +Multiple arguments are printed on separate lines: +.PP + > banner one two + + ####### # # ####### + # # ## # # + # # # # # # + # # # # # ##### + # # # # # # + # # # ## # + ####### # # ####### + + + ####### # # ####### + # # # # # # + # # # # # # + # # # # # # + # # # # # # + # # # # # # + # ## ## ####### +.PP +To get a single long line containing whitespace, you must quote the string: +.PP + > banner "one two" + + ####### # # ####### ####### # # ####### + # # ## # # # # # # # # + # # # # # # # # # # # # + # # # # # ##### # # # # # # + # # # # # # # # # # # # + # # # ## # # # # # # # + ####### # # ####### # ## ## ####### + +.SH COMPATIBILITY +.PP +From time to time, people assert that this program is buggy because it +doesn't do something that some other banner implementation does. The +behavior of the program is based on what I saw on Solaris and AIX systems +at the time I wrote it in the late 1990s. I make no claims that the +behavior is identical to that of any other contemporary system, especially +any non-free system that I may or may not have access to. +.PP +If you don't like the behavior, you can either submit a patch, or you can +use an alternative program such as figlet. I am always happy to accept +patches, and I promise to integrate patches promptly if provided. So far, +no one who's complained has bothered to provide any patches, so the +behavior remains the same. +.SH BUGS +Report bugs to . +.SH AUTHOR +Written by Kenneth J. Pronovici . +.SH COPYRIGHT +Copyright (c) 2000\-2004.2007,2013,2014 Kenneth J. Pronovici. +.br +This is free software; see the source for copying conditions. There is +NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. diff --git a/upstream/fedora-40/man1/base32.1 b/upstream/fedora-40/man1/base32.1 new file mode 100644 index 00000000..3635b4c3 --- /dev/null +++ b/upstream/fedora-40/man1/base32.1 @@ -0,0 +1,55 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH BASE32 "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +base32 \- base32 encode/decode data and print to standard output +.SH SYNOPSIS +.B base32 +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Base32 encode or decode FILE, or standard input, to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-d\fR, \fB\-\-decode\fR +decode data +.TP +\fB\-i\fR, \fB\-\-ignore\-garbage\fR +when decoding, ignore non\-alphabet characters +.TP +\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR +wrap encoded lines after COLS character (default 76). +Use 0 to disable line wrapping +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +The data are encoded as described for the base32 alphabet in RFC 4648. +When decoding, the input may contain newlines in addition to the bytes of +the formal base32 alphabet. Use \fB\-\-ignore\-garbage\fR to attempt to recover +from any other non\-alphabet bytes in the encoded stream. +.SH AUTHOR +Written by Simon Josefsson. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBbasenc\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) base32 invocation\(aq diff --git a/upstream/fedora-40/man1/base64.1 b/upstream/fedora-40/man1/base64.1 new file mode 100644 index 00000000..c3f68531 --- /dev/null +++ b/upstream/fedora-40/man1/base64.1 @@ -0,0 +1,55 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH BASE64 "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +base64 \- base64 encode/decode data and print to standard output +.SH SYNOPSIS +.B base64 +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Base64 encode or decode FILE, or standard input, to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-d\fR, \fB\-\-decode\fR +decode data +.TP +\fB\-i\fR, \fB\-\-ignore\-garbage\fR +when decoding, ignore non\-alphabet characters +.TP +\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR +wrap encoded lines after COLS character (default 76). +Use 0 to disable line wrapping +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +The data are encoded as described for the base64 alphabet in RFC 4648. +When decoding, the input may contain newlines in addition to the bytes of +the formal base64 alphabet. Use \fB\-\-ignore\-garbage\fR to attempt to recover +from any other non\-alphabet bytes in the encoded stream. +.SH AUTHOR +Written by Simon Josefsson. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBbasenc\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) base64 invocation\(aq diff --git a/upstream/fedora-40/man1/basename.1 b/upstream/fedora-40/man1/basename.1 new file mode 100644 index 00000000..81f3f61f --- /dev/null +++ b/upstream/fedora-40/man1/basename.1 @@ -0,0 +1,64 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH BASENAME "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +basename \- strip directory and suffix from filenames +.SH SYNOPSIS +.B basename +\fI\,NAME \/\fR[\fI\,SUFFIX\/\fR] +.br +.B basename +\fI\,OPTION\/\fR... \fI\,NAME\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print NAME with any leading directory components removed. +If specified, also remove a trailing SUFFIX. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-a\fR, \fB\-\-multiple\fR +support multiple arguments and treat each as a NAME +.TP +\fB\-s\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR +remove a trailing SUFFIX; implies \fB\-a\fR +.TP +\fB\-z\fR, \fB\-\-zero\fR +end each output line with NUL, not newline +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH EXAMPLES +.TP +basename /usr/bin/sort +\-> "sort" +.TP +basename include/stdio.h .h +\-> "stdio" +.TP +basename \-s .h include/stdio.h +\-> "stdio" +.TP +basename \-a any/str1 any/str2 +\-> "str1" followed by "str2" +.SH AUTHOR +Written by David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBdirname\fP(1), \fBreadlink\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) basename invocation\(aq diff --git a/upstream/fedora-40/man1/basenc.1 b/upstream/fedora-40/man1/basenc.1 new file mode 100644 index 00000000..1634d39e --- /dev/null +++ b/upstream/fedora-40/man1/basenc.1 @@ -0,0 +1,106 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH BASENC "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +basenc \- Encode/decode data and print to standard output +.SH SYNOPSIS +.B basenc +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +basenc encode or decode FILE, or standard input, to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-\-base64\fR +same as 'base64' program (RFC4648 section 4) +.TP +\fB\-\-base64url\fR +file\- and url\-safe base64 (RFC4648 section 5) +.TP +\fB\-\-base32\fR +same as 'base32' program (RFC4648 section 6) +.TP +\fB\-\-base32hex\fR +extended hex alphabet base32 (RFC4648 section 7) +.TP +\fB\-\-base16\fR +hex encoding (RFC4648 section 8) +.TP +\fB\-\-base2msbf\fR +bit string with most significant bit (msb) first +.TP +\fB\-\-base2lsbf\fR +bit string with least significant bit (lsb) first +.TP +\fB\-d\fR, \fB\-\-decode\fR +decode data +.TP +\fB\-i\fR, \fB\-\-ignore\-garbage\fR +when decoding, ignore non\-alphabet characters +.TP +\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR +wrap encoded lines after COLS character (default 76). +Use 0 to disable line wrapping +.TP +\fB\-\-z85\fR +ascii85\-like encoding (ZeroMQ spec:32/Z85); +when encoding, input length must be a multiple of 4; +when decoding, input length must be a multiple of 5 +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +When decoding, the input may contain newlines in addition to the bytes of +the formal alphabet. Use \fB\-\-ignore\-garbage\fR to attempt to recover +from any other non\-alphabet bytes in the encoded stream. +.SH "ENCODING EXAMPLES" +.PP +.nf +.RS +$ printf '\\376\\117\\202' | basenc \-\-base64 +/k+C + +$ printf '\\376\\117\\202' | basenc \-\-base64url +_k-C + +$ printf '\\376\\117\\202' | basenc \-\-base32 +7ZHYE=== + +$ printf '\\376\\117\\202' | basenc \-\-base32hex +VP7O4=== + +$ printf '\\376\\117\\202' | basenc \-\-base16 +FE4F82 + +$ printf '\\376\\117\\202' | basenc \-\-base2lsbf +011111111111001001000001 + +$ printf '\\376\\117\\202' | basenc \-\-base2msbf +111111100100111110000010 + +$ printf '\\376\\117\\202\\000' | basenc \-\-z85 +@.FaC +.RE +.fi +.SH AUTHOR +Written by Simon Josefsson and Assaf Gordon. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) basenc invocation\(aq diff --git a/upstream/fedora-40/man1/bash.1 b/upstream/fedora-40/man1/bash.1 new file mode 100644 index 00000000..734a2ccc --- /dev/null +++ b/upstream/fedora-40/man1/bash.1 @@ -0,0 +1,11779 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Case Western Reserve University +.\" chet.ramey@case.edu +.\" +.\" Last Change: Mon Sep 19 11:13:21 EDT 2022 +.\" +.\" bash_builtins, strip all but Built-Ins section +.if \n(zZ=1 .ig zZ +.if \n(zY=1 .ig zY +.TH BASH 1 "2022 September 19" "GNU Bash 5.2" +.\" +.\" There's some problem with having a `@' +.\" in a tagged paragraph with the BSD man macros. +.\" It has to do with `@' appearing in the }1 macro. +.\" This is a problem on 4.3 BSD and Ultrix, but Sun +.\" appears to have fixed it. +.\" If you're seeing the characters +.\" `@u-3p' appearing before the lines reading +.\" `possible-hostname-completions +.\" and `complete-hostname' down in READLINE, +.\" then uncomment this redefinition. +.\" +.\" .de }1 +.\" .ds ]X \&\\*(]B\\ +.\" .nr )E 0 +.\" .if !"\\$1"" .nr )I \\$1n +.\" .}f +.\" .ll \\n(LLu +.\" .in \\n()Ru+\\n(INu+\\n()Iu +.\" .ti \\n(INu +.\" .ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X +.\" .br\} +.\" .el \\*(]X\h|\\n()Iu+\\n()Ru\c +.\" .}f +.\" .. +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.SH NAME +bash \- GNU Bourne-Again SHell +.SH SYNOPSIS +.B bash +[options] +[command_string | file] +.SH COPYRIGHT +.if n Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc. +.if t Bash is Copyright \(co 1989-2022 by the Free Software Foundation, Inc. +.SH DESCRIPTION +.B Bash +is an \fBsh\fR-compatible command language interpreter that +executes commands read from the standard input or from a file. +.B Bash +also incorporates useful features from the \fIKorn\fP and \fIC\fP +shells (\fBksh\fP and \fBcsh\fP). +.PP +.B Bash +is intended to be a conformant implementation of the +Shell and Utilities portion of the IEEE POSIX specification +(IEEE Standard 1003.1). +.B Bash +can be configured to be POSIX-conformant by default. +.SH OPTIONS +All of the single-character shell options documented in the +description of the \fBset\fR builtin command, including \fB\-o\fP, +can be used as options when the shell is invoked. +In addition, \fBbash\fR +interprets the following options when it is invoked: +.PP +.PD 0 +.TP 10 +.B \-c +If the +.B \-c +option is present, then commands are read from the first non-option argument +.IR command_string . +If there are arguments after the +.IR command_string , +the first argument is assigned to +.B $0 +and any remaining arguments are assigned to the positional parameters. +The assignment to +.B $0 +sets the name of the shell, which is used in warning and error messages. +.TP +.B \-i +If the +.B \-i +option is present, the shell is +.IR interactive . +.TP +.B \-l +Make +.B bash +act as if it had been invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-r +If the +.B \-r +option is present, the shell becomes +.I restricted +(see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-s +If the +.B \-s +option is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell or when reading input +through a pipe. +.TP +.B \-D +A list of all double-quoted strings preceded by \fB$\fP +is printed on the standard output. +These are the strings that +are subject to language translation when the current locale +is not \fBC\fP or \fBPOSIX\fP. +This implies the \fB\-n\fP option; no commands will be executed. +.TP +.B [\-+]O [\fIshopt_option\fP] +\fIshopt_option\fP is one of the shell options accepted by the +\fBshopt\fP builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option; +\fB+O\fP unsets it. +If \fIshopt_option\fP is not supplied, the names and values of the shell +options accepted by \fBshopt\fP are printed on the standard output. +If the invocation option is \fB+O\fP, the output is displayed in a format +that may be reused as input. +.TP +.B \-\- +A +.B \-\- +signals the end of options and disables further option processing. +Any arguments after the +.B \-\- +are treated as filenames and arguments. An argument of +.B \- +is equivalent to \fB\-\-\fP. +.PD +.PP +.B Bash +also interprets a number of multi-character options. +These options must appear on the command line before the +single-character options to be recognized. +.PP +.PD 0 +.TP +.B \-\-debugger +Arrange for the debugger profile to be executed before the shell +starts. +Turns on extended debugging mode (see the description of the +.B extdebug +option to the +.B shopt +builtin below). +.TP +.B \-\-dump\-po\-strings +Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP +\fBpo\fP (portable object) file format. +.TP +.B \-\-dump\-strings +Equivalent to \fB\-D\fP. +.TP +.B \-\-help +Display a usage message on standard output and exit successfully. +.TP +\fB\-\-init\-file\fP \fIfile\fP +.PD 0 +.TP +\fB\-\-rcfile\fP \fIfile\fP +.PD +Execute commands from +.I file +instead of the standard personal initialization file +.I ~/.bashrc +if the shell is interactive (see +.SM +.B INVOCATION +below). +.TP +.B \-\-login +Equivalent to \fB\-l\fP. +.TP +.B \-\-noediting +Do not use the GNU +.B readline +library to read command lines when the shell is interactive. +.TP +.B \-\-noprofile +Do not read either the system-wide startup file +.FN /etc/profile +or any of the personal initialization files +.IR ~/.bash_profile , +.IR ~/.bash_login , +or +.IR ~/.profile . +By default, +.B bash +reads these files when it is invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-\-norc +Do not read and execute the personal initialization file +.I ~/.bashrc +if the shell is interactive. +This option is on by default if the shell is invoked as +.BR sh . +.TP +.B \-\-posix +Change the behavior of \fBbash\fP where the default operation differs +from the POSIX standard to match the standard (\fIposix mode\fP). +See +.SM +.B "SEE ALSO" +below for a reference to a document that details how posix mode affects +bash's behavior. +.TP +.B \-\-restricted +The shell becomes restricted (see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-\-rpm-requires +Produce the list of files that are required for the +shell script to run. This implies '-n' and is subject +to the same limitations as compile time error checking checking; +Command substitutions, Conditional expressions and +.BR eval +builtin are not parsed so some dependencies may be missed. +.TP +.B \-\-verbose +Equivalent to \fB\-v\fP. +.TP +.B \-\-version +Show version information for this instance of +.B bash +on the standard output and exit successfully. +.PD +.SH ARGUMENTS +If arguments remain after option processing, and neither the +.B \-c +nor the +.B \-s +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands. +If +.B bash +is invoked in this fashion, +.B $0 +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +.B Bash +reads and executes commands from this file, then exits. +\fBBash\fP's exit status is the exit status of the last command +executed in the script. +If no commands are executed, the exit status is 0. +An attempt is first made to open the file in the current directory, and, +if no file is found, then the shell searches the directories in +.SM +.B PATH +for the script. +.SH INVOCATION +A \fIlogin shell\fP is one whose first character of argument zero is a +.BR \- , +or one started with the +.B \-\-login +option. +.PP +An \fIinteractive\fP shell is one started without non-option arguments +(unless \fB\-s\fP is specified) +and without the +.B \-c +option, +whose standard input and error are +both connected to terminals (as determined by +.IR isatty (3)), +or one started with the +.B \-i +option. +.SM +.B PS1 +is set and +.B $\- +includes +.B i +if +.B bash +is interactive, +allowing a shell script or a startup file to test this state. +.PP +The following paragraphs describe how +.B bash +executes its startup files. +If any of the files exist but cannot be read, +.B bash +reports an error. +Tildes are expanded in filenames as described below under +.B "Tilde Expansion" +in the +.SM +.B EXPANSION +section. +.PP +When +.B bash +is invoked as an interactive login shell, or as a non-interactive shell +with the \fB\-\-login\fP option, it first reads and +executes commands from the file \fI/etc/profile\fP, if that +file exists. +After reading that file, it looks for \fI~/.bash_profile\fP, +\fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads +and executes commands from the first one that exists and is readable. +The +.B \-\-noprofile +option may be used when the shell is started to inhibit this behavior. +.PP +When an interactive login shell exits, +or a non-interactive login shell executes the \fBexit\fP builtin command, +.B bash +reads and executes commands from the files \fI~/.bash_logout\fP +and \fI/etc/bash.bash_logout\fP, if the files exists. +.PP +When an interactive shell that is not a login shell is started, +.B bash +reads and executes commands from \fI~/.bashrc\fP, if that file exists. +This may be inhibited by using the +.B \-\-norc +option. +The \fB\-\-rcfile\fP \fIfile\fP option will force +.B bash +to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP. +.PP +When +.B bash +is started non-interactively, to run a shell script, for example, it +looks for the variable +.SM +.B BASH_ENV +in the environment, expands its value if it appears there, and uses the +expanded value as the name of a file to read and execute. +.B Bash +behaves as if the following command were executed: +.sp .5 +.RS +.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP +.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi +.RE +.sp .5 +but the value of the +.SM +.B PATH +variable is not used to search for the filename. +.PP +If +.B bash +is invoked with the name +.BR sh , +it tries to mimic the startup behavior of historical versions of +.B sh +as closely as possible, +while conforming to the POSIX standard as well. +When invoked as an interactive login shell, or a non-interactive +shell with the \fB\-\-login\fP option, it first attempts to +read and execute commands from +.I /etc/profile +and +.IR ~/.profile , +in that order. +The +.B \-\-noprofile +option may be used to inhibit this behavior. +When invoked as an interactive shell with the name +.BR sh , +.B bash +looks for the variable +.SM +.BR ENV , +expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. +Since a shell invoked as +.B sh +does not attempt to read and execute commands from any other startup +files, the +.B \-\-rcfile +option has no effect. +A non-interactive shell invoked with the name +.B sh +does not attempt to read any other startup files. +When invoked as +.BR sh , +.B bash +enters +.I posix +mode after the startup files are read. +.PP +When +.B bash +is started in +.I posix +mode, as with the +.B \-\-posix +command line option, it follows the POSIX standard for startup files. +In this mode, interactive shells expand the +.SM +.B ENV +variable and commands are read and executed from the file +whose name is the expanded value. +No other startup files are read. +.PP +.B Bash +attempts to determine when it is being run with its standard input +connected to a network connection, as when executed by +the historical remote shell daemon, usually \fIrshd\fP, +or the secure shell daemon \fIsshd\fP. +If +.B bash +determines it is being run non-interactively in this fashion, +it reads and executes commands from \fI~/.bashrc\fP, +if that file exists and is readable. +It will not do this if invoked as \fBsh\fP. +The +.B \-\-norc +option may be used to inhibit this behavior, and the +.B \-\-rcfile +option may be used to force another file to be read, but neither +\fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options +or allow them to be specified. +.PP +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, no startup +files are read, shell functions are not inherited from the environment, the +.SM +.BR SHELLOPTS , +.SM +.BR BASHOPTS , +.SM +.BR CDPATH , +and +.SM +.B GLOBIGNORE +variables, if they appear in the environment, are ignored, +and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at invocation, the startup behavior is +the same, but the effective user id is not reset. +.SH DEFINITIONS +The following definitions are used throughout the rest of this +document. +.PD 0 +.TP +.B blank +A space or tab. +.TP +.B word +A sequence of characters considered as a single unit by the shell. +Also known as a +.BR token . +.TP +.B name +A +.I word +consisting only of alphanumeric characters and underscores, and +beginning with an alphabetic character or an underscore. Also +referred to as an +.BR identifier . +.TP +.B metacharacter +A character that, when unquoted, separates words. One of the following: +.br +.RS +.PP +.if t \fB| & ; ( ) < > space tab newline\fP +.if n \fB| & ; ( ) < > space tab newline\fP +.RE +.TP +.B control operator +A \fItoken\fP that performs a control function. It is one of the following +symbols: +.RS +.PP +.if t \fB|| & && ; ;; ;& ;;& ( ) | |& \fP +.if n \fB|| & && ; ;; ;& ;;& ( ) | |& \fP +.RE +.PD +.SH "RESERVED WORDS" +\fIReserved words\fP are words that have a special meaning to the shell. +The following words are recognized as reserved when unquoted and either +the first word of a command (see +.SM +.B SHELL GRAMMAR +below), the third word of a +.B case +or +.B select +command +(only \fBin\fP is valid), or the third word of a +.B for +command (only \fBin\fP and \fBdo\fP are valid): +.if t .RS +.PP +.B +.if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] +.if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] +.if t .RE +.SH "SHELL GRAMMAR" +This section describes the syntax of the various forms of shell commands. +.SS Simple Commands +A \fIsimple command\fP is a sequence of optional variable assignments +followed by \fBblank\fP-separated words and redirections, and +terminated by a \fIcontrol operator\fP. The first word +specifies the command to be executed, and is passed as argument zero. +The remaining words are passed as arguments to the invoked command. +.PP +The return value of a \fIsimple command\fP is its exit status, or +128+\fIn\^\fP if the command is terminated by signal +.IR n . +.SS Pipelines +A \fIpipeline\fP is a sequence of one or more commands separated by +one of the control operators +.B | +or \fB|&\fP. +The format for a pipeline is: +.RS +.PP +[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ] +.RE +.PP +The standard output of +.I command1 +is connected via a pipe to the standard input of +.IR command2 . +This connection is performed before any redirections specified by the +.IR command1 (see +.SM +.B REDIRECTION +below). +If \fB|&\fP is used, \fIcommand1\fP's standard error, in addition to its +standard output, is connected to +\fIcommand2\fP's standard input through the pipe; +it is shorthand for \fB2>&1 |\fP. +This implicit redirection of the standard error to the standard output is +performed after any redirections specified by \fIcommand1\fP. +.PP +The return status of a pipeline is the exit status of the last +command, unless the \fBpipefail\fP option is enabled. +If \fBpipefail\fP is enabled, the pipeline's return status is the +value of the last (rightmost) command to exit with a non-zero status, +or zero if all commands exit successfully. +If the reserved word +.B ! +precedes a pipeline, the exit status of that pipeline is the logical +negation of the exit status as described above. +The shell waits for all commands in the pipeline to +terminate before returning a value. +.PP +If the +.B time +reserved word precedes a pipeline, the elapsed as well as user and +system time consumed by its execution are reported when the pipeline +terminates. +The \fB\-p\fP option changes the output format to that specified by POSIX. +When the shell is in \fIposix mode\fP, it does not recognize +\fBtime\fP as a reserved word if the next token begins with a `-'. +The +.SM +.B TIMEFORMAT +variable may be set to a format string that specifies how the timing +information should be displayed; see the description of +.SM +.B TIMEFORMAT +under +.B "Shell Variables" +below. +.PP +When the shell is in \fIposix mode\fP, \fBtime\fP +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The +.SM +.B TIMEFORMAT +variable may be used to specify the format of +the time information. +.PP +Each command in a multi-command pipeline, +where pipes are created, +is executed in a \fIsubshell\fP, which is a +separate process. +See +.SM +\fBCOMMAND EXECUTION ENVIRONMENT\fP +for a description of subshells and a subshell environment. +If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin +(see the description of \fBshopt\fP below), +the last element of a pipeline may be run by the shell process +when job control is not active. +.SS Lists +A \fIlist\fP is a sequence of one or more pipelines separated by one +of the operators +.BR ; , +.BR & , +.BR && , +or +.BR || , +and optionally terminated by one of +.BR ; , +.BR & , +or +.BR . +.PP +Of these list operators, +.B && +and +.B || +have equal precedence, followed by +.B ; +and +.BR & , +which have equal precedence. +.PP +A sequence of one or more newlines may appear in a \fIlist\fP instead +of a semicolon to delimit commands. +.PP +If a command is terminated by the control operator +.BR & , +the shell executes the command in the \fIbackground\fP +in a subshell. +The shell does not wait for the command to +finish, and the return status is 0. +These are referred to as \fIasynchronous\fP commands. +Commands separated by a +.B ; +are executed sequentially; the shell waits for each +command to terminate in turn. The return status is the +exit status of the last command executed. +.PP +AND and OR lists are sequences of one or more pipelines separated by the +\fB&&\fP and \fB||\fP control operators, respectively. +AND and OR lists are executed with left associativity. +An AND list has the form +.RS +.PP +\fIcommand1\fP \fB&&\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command1 +returns an exit status of zero (success). +.PP +An OR list has the form +.RS +.PP +\fIcommand1\fP \fB||\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command1 +returns a non-zero exit status. +The return status of +AND and OR lists is the exit status of the last command +executed in the list. +.SS Compound Commands +A \fIcompound command\fP is one of the following. +In most cases a \fIlist\fP in a command's description may be separated from +the rest of the command by one or more newlines, and may be followed by a +newline in place of a semicolon. +.TP +(\fIlist\fP) +\fIlist\fP is executed in a subshell (see +.SM +\fBCOMMAND EXECUTION ENVIRONMENT\fP +below for a description of a subshell environment). +Variable assignments and builtin +commands that affect the shell's environment do not remain in effect +after the command completes. The return status is the exit status of +\fIlist\fP. +.TP +{ \fIlist\fP; } +\fIlist\fP is simply executed in the current shell environment. +\fIlist\fP must be terminated with a newline or semicolon. +This is known as a \fIgroup command\fP. +The return status is the exit status of +\fIlist\fP. +Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and +\fB}\fP are \fIreserved words\fP and must occur where a reserved +word is permitted to be recognized. Since they do not cause a word +break, they must be separated from \fIlist\fP by whitespace or another +shell metacharacter. +.TP +((\fIexpression\fP)) +The \fIexpression\fP is evaluated according to the rules described +below under +.SM +.BR "ARITHMETIC EVALUATION" . +If the value of the expression is non-zero, the return status is 0; +otherwise the return status is 1. +The \fIexpression\fP +undergoes the same expansions +as if it were within double quotes, +but double quote characters in \fIexpression\fP are not treated specially +and are removed. +.TP +\fB[[\fP \fIexpression\fP \fB]]\fP +Return a status of 0 or 1 depending on the evaluation of +the conditional expression \fIexpression\fP. +Expressions are composed of the primaries described below under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting +and pathname expansion. +The shell performs tilde expansion, parameter and +variable expansion, arithmetic expansion, command substitution, process +substitution, and quote removal on those words +(the expansions that would occur if the words were enclosed in double quotes). +Conditional operators such as \fB\-f\fP must be unquoted to be recognized +as primaries. +.if t .sp 0.5 +.if n .sp 1 +When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort +lexicographically using the current locale. +.if t .sp 0.5 +.if n .sp 1 +When the \fB==\fP and \fB!=\fP operators are used, the string to the +right of the operator is considered a pattern and matched according +to the rules described below under \fBPattern Matching\fP, +as if the \fBextglob\fP shell option were enabled. +The \fB=\fP operator is equivalent to \fB==\fP. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +The return value is 0 if the string matches (\fB==\fP) or does not match +(\fB!=\fP) the pattern, and 1 otherwise. +Any part of the pattern may be quoted to force the quoted portion +to be matched as a string. +.if t .sp 0.5 +.if n .sp 1 +An additional binary operator, \fB=~\fP, is available, with the same +precedence as \fB==\fP and \fB!=\fP. +When it is used, the string to the right of the operator is considered +a POSIX extended regular expression and matched accordingly +(using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces +usually described in \fIregex\fP(3)). +The return value is 0 if the string matches +the pattern, and 1 otherwise. +If the regular expression is syntactically incorrect, the conditional +expression's return value is 2. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +If any part of the pattern is quoted, the quoted portion is matched literally. +This means every character in the quoted portion matches itself, +instead of having any special pattern matching meaning. +If the pattern is stored in a shell variable, quoting the variable +expansion forces the entire pattern to be matched literally. +Treat bracket expressions in regular expressions carefully, +since normal quoting and pattern characters lose their meanings +between brackets. +.if t .sp 0.5 +.if n .sp 1 +The pattern will match if it matches any part of the string. +Anchor the pattern using the \fB^\fP and \fB$\fP regular expression +operators to force it to match the entire string. +The array variable +.SM +.B BASH_REMATCH +records which parts of the string matched the pattern. +The element of +.SM +.B BASH_REMATCH +with index 0 contains the portion of +the string matching the entire regular expression. +Substrings matched by parenthesized subexpressions within the regular +expression are saved in the remaining +.SM +.B BASH_REMATCH +indices. The element of +.SM +.B BASH_REMATCH +with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +Bash sets +.SM +.B BASH_REMATCH +in the global scope; declaring it as a local variable will lead to +unexpected results. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence: +.if t .sp 0.5 +.if n .sp 1 +.RS +.PD 0 +.TP +.B ( \fIexpression\fP ) +Returns the value of \fIexpression\fP. +This may be used to override the normal precedence of operators. +.TP +.B ! \fIexpression\fP +True if +.I expression +is false. +.TP +\fIexpression1\fP \fB&&\fP \fIexpression2\fP +True if both +.I expression1 +and +.I expression2 +are true. +.TP +\fIexpression1\fP \fB||\fP \fIexpression2\fP +True if either +.I expression1 +or +.I expression2 +is true. +.PD +.LP +The \fB&&\fP and \fB||\fP +operators do not evaluate \fIexpression2\fP if the value of +\fIexpression1\fP is sufficient to determine the return value of +the entire conditional expression. +.RE +.TP +\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items. +The variable \fIname\fP is set to each element of this list +in turn, and \fIlist\fP is executed each time. +If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes +\fIlist\fP once for each positional parameter that is set (see +.SM +.B PARAMETERS +below). +The return status is the exit status of the last command that executes. +If the expansion of the items following \fBin\fP results in an empty +list, no commands are executed, and the return status is 0. +.TP +\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP +First, the arithmetic expression \fIexpr1\fP is evaluated according +to the rules described below under +.SM +.BR "ARITHMETIC EVALUATION" . +The arithmetic expression \fIexpr2\fP is then evaluated repeatedly +until it evaluates to zero. +Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is +executed and the arithmetic expression \fIexpr3\fP is evaluated. +If any expression is omitted, it behaves as if it evaluates to 1. +The return value is the exit status of the last command in \fIlist\fP +that is executed, or false if any of the expressions is invalid. +.TP +\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items, and the set of expanded words is printed on the standard +error, each preceded by a number. If the \fBin\fP +\fIword\fP is omitted, the positional parameters are printed (see +.SM +.B PARAMETERS +below). +.B select +then displays the +.SM +.B PS3 +prompt and reads a line from the standard input. +If the line consists of a number corresponding to one of +the displayed words, then the value of +.I name +is set to that word. +If the line is empty, the words and prompt are displayed again. +If EOF is read, the \fBselect\fP command completes and returns 1. +Any other value read causes +.I name +to be set to null. The line read is saved in the variable +.SM +.BR REPLY . +The +.I list +is executed after each selection until a +.B break +command is executed. +The exit status of +.B select +is the exit status of the last command executed in +.IR list , +or zero if no commands were executed. +.TP +\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ +... ) \fIlist\fP ;; ] ... \fBesac\fP +A \fBcase\fP command first expands \fIword\fP, and tries to match +it against each \fIpattern\fP in turn, using the matching rules +described under +.B Pattern Matching +below. +The \fIword\fP is expanded using tilde +expansion, parameter and variable expansion, arithmetic expansion, +command substitution, process substitution and quote removal. +Each \fIpattern\fP examined is expanded using tilde +expansion, parameter and variable expansion, arithmetic expansion, +command substitution, process substitution, and quote removal. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +When a match is found, the corresponding \fIlist\fP is executed. +If the \fB;;\fP operator is used, no subsequent matches are attempted after +the first pattern match. +Using \fB;&\fP in place of \fB;;\fP causes execution to continue with +the \fIlist\fP associated with the next set of patterns. +Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next +pattern list in the statement, if any, and execute any associated \fIlist\fP +on a successful match, +continuing the case statement execution as if the pattern list had not matched. +The exit status is zero if no +pattern matches. Otherwise, it is the exit status of the +last command executed in \fIlist\fP. +.TP +\fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \ +[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \ +[ \fBelse\fP \fIlist\fP; ] \fBfi\fP +The +.B if +.I list +is executed. If its exit status is zero, the +\fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP +\fIlist\fP is executed in turn, and if its exit status is zero, +the corresponding \fBthen\fP \fIlist\fP is executed and the +command completes. Otherwise, the \fBelse\fP \fIlist\fP is +executed, if present. The exit status is the exit status of the +last command executed, or zero if no condition tested true. +.TP +\fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP +.PD 0 +.TP +\fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP +.PD +The \fBwhile\fP command continuously executes the list +\fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns +an exit status of zero. The \fBuntil\fP command is identical +to the \fBwhile\fP command, except that the test is negated: +.I list-2 +is executed as long as the last command in +.I list-1 +returns a non-zero exit status. +The exit status of the \fBwhile\fP and \fBuntil\fP commands +is the exit status +of the last command executed in \fIlist-2\fP, or zero if +none was executed. +.SS Coprocesses +A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved +word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the \fB&\fP control operator, with a two-way pipe +established between the executing shell and the coprocess. +.PP +The syntax for a coprocess is: +.RS +.PP +\fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP] +.RE +.PP +This creates a coprocess named \fINAME\fP. +\fIcommand\fP may be either a simple command or a compound +command (see above). +\fINAME\fP is a shell variable name. +If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP. +.PP +The recommended form to use for a coprocess is +.RS +.PP +\fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; } +.RE +.PP +This form is recommended because simple commands result in the coprocess +always being named \fBCOPROC\fP, and it is simpler to use and more complete +than the other compound commands. +.PP +If \fIcommand\fP is a compound command, \fINAME\fP is optional. The +word following \fBcoproc\fP determines whether that word is interpreted +as a variable name: it is interpreted as \fINAME\fP if it is not a +reserved word that introduces a compound command. +If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this +is to avoid confusion between \fINAME\fP and the first word of the simple +command. +.PP +When the coprocess is executed, the shell creates an array variable (see +.B Arrays +below) named \fINAME\fP in the context of the executing shell. +The standard output of +.I command +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to \fINAME\fP[0]. +The standard input of +.I command +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to \fINAME\fP[1]. +This pipe is established before any redirections specified by the +command (see +.SM +.B REDIRECTION +below). +The file descriptors can be utilized as arguments to shell commands +and redirections using standard word expansions. +Other than those created to execute command and process substitutions, +the file descriptors are not available in subshells. +.PP +The process ID of the shell spawned to execute the coprocess is +available as the value of the variable \fINAME\fP_PID. +The \fBwait\fP +builtin command may be used to wait for the coprocess to terminate. +.PP +Since the coprocess is created as an asynchronous command, +the \fBcoproc\fP command always returns success. +The return status of a coprocess is the exit status of \fIcommand\fP. +.SS Shell Function Definitions +A shell function is an object that is called like a simple command and +executes a compound command with a new set of positional parameters. +Shell functions are declared as follows: +.TP +\fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP] +.PD 0 +.TP +\fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP] +.PD +This defines a function named \fIfname\fP. +The reserved word \fBfunction\fP is optional. +If the \fBfunction\fP reserved word is supplied, the parentheses are optional. +The \fIbody\fP of the function is the compound command +.I compound\-command +(see \fBCompound Commands\fP above). +That command is usually a \fIlist\fP of commands between { and }, but +may be any command listed under \fBCompound Commands\fP above. +If the \fBfunction\fP reserved word is used, but the +parentheses are not supplied, the braces are recommended. +\fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the +name of a simple command. +When in \fIposix mode\fP, \fIfname\fP must be a valid shell \fIname\fP +and may not be the name of one of the +POSIX \fIspecial builtins\fP. +In default mode, a function name can be any unquoted shell word that does +not contain \fB$\fP. +Any redirections (see +.SM +.B REDIRECTION +below) specified when a function is defined are performed +when the function is executed. +The exit status of a function definition is zero unless a syntax error +occurs or a readonly function with the same name already exists. +When executed, the exit status of a function is the exit status of the +last command executed in the body. (See +.SM +.B FUNCTIONS +below.) +.SH COMMENTS +In a non-interactive shell, or an interactive shell in which the +.B interactive_comments +option to the +.B shopt +builtin is enabled (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), a word beginning with +.B # +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the +.B interactive_comments +option enabled does not allow comments. The +.B interactive_comments +option is on by default in interactive shells. +.SH QUOTING +\fIQuoting\fP is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +parameter expansion. +.PP +Each of the \fImetacharacters\fP listed above under +.SM +.B DEFINITIONS +has special meaning to the shell and must be quoted if it is to +represent itself. +.PP +When the command history expansion facilities are being used +(see +.SM +.B HISTORY EXPANSION +below), the +\fIhistory expansion\fP character, usually \fB!\fP, must be quoted +to prevent history expansion. +.PP +There are three quoting mechanisms: the +.IR "escape character" , +single quotes, and double quotes. +.PP +A non-quoted backslash (\fB\e\fP) is the +.IR "escape character" . +It preserves the literal value of the next character that follows, +with the exception of . If a \fB\e\fP pair +appears, and the backslash is not itself quoted, the \fB\e\fP +is treated as a line continuation (that is, it is removed from the +input stream and effectively ignored). +.PP +Enclosing characters in single quotes preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. +.PP +Enclosing characters in double quotes preserves the literal value +of all characters within the quotes, with the exception of +.BR $ , +.BR \` , +.BR \e , +and, when history expansion is enabled, +.BR ! . +When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning +within double quotes, even when history expansion is enabled. +The characters +.B $ +and +.B \` +retain their special meaning within double quotes. The backslash +retains its special meaning only when followed by one of the following +characters: +.BR $ , +.BR \` , +\^\fB"\fP\^, +.BR \e , +or +.BR . +A double quote may be quoted within double quotes by preceding it with +a backslash. +If enabled, history expansion will be performed unless an +.B ! +appearing in double quotes is escaped using a backslash. +The backslash preceding the +.B ! +is not removed. +.PP +The special parameters +.B * +and +.B @ +have special meaning when in double +quotes (see +.SM +.B PARAMETERS +below). +.PP +Character sequences of the form \fB$\fP\(aq\fIstring\fP\(aq are treated +as a special variant of single quotes. +The sequence expands to \fIstring\fP, with backslash-escaped characters +in \fIstring\fP replaced as specified by the ANSI C standard. +Backslash escape sequences, if present, are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ee +.TP +.B \eE +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e\(aq +single quote +.TP +.B \e\(dq +double quote +.TP +.B \e? +question mark +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.TP +.B \ec\fIx\fP +a control-\fIx\fP character +.PD +.RE +.LP +The expanded result is single-quoted, as if the dollar sign had +not been present. +.PP +A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq) +will cause the string to be translated according to the current locale. +The \fIgettext\fP infrastructure performs the lookup and +translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP, +and \fBTEXTDOMAIN\fP shell variables. +If the current locale is \fBC\fP or \fBPOSIX\fP, +if there are no translations available, +or if the string is not translated, +the dollar sign is ignored. +This is a form of double quoting, so the string remains double-quoted +by default, whether or not it is translated and replaced. +If the \fBnoexpand_translation\fP option is enabled +using the \fBshopt\fP builtin, +translated strings are single-quoted instead of double-quoted. +See the description of +.B shopt +below under +.SM +.BR SHELL BUILTIN COMMANDS . +.SH PARAMETERS +A +.I parameter +is an entity that stores values. +It can be a +.IR name , +a number, or one of the special characters listed below under +.BR "Special Parameters" . +A +.I variable +is a parameter denoted by a +.IR name . +A variable has a \fIvalue\fP and zero or more \fIattributes\fP. +Attributes are assigned using the +.B declare +builtin command (see +.B declare +below in +.SM +.BR "SHELL BUILTIN COMMANDS" ). +.PP +A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the +.B unset +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.PP +A +.I variable +may be assigned to by a statement of the form +.RS +.PP +\fIname\fP=[\fIvalue\fP] +.RE +.PP +If +.I value +is not given, the variable is assigned the null string. All +.I values +undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote +removal (see +.SM +.B EXPANSION +below). If the variable has its +.B integer +attribute set, then +.I value +is evaluated as an arithmetic expression even if the $((...)) expansion is +not used (see +.B "Arithmetic Expansion" +below). +Word splitting and pathname expansion are not performed. +Assignment statements may also appear as arguments to the +.BR alias , +.BR declare , +.BR typeset , +.BR export , +.BR readonly , +and +.B local +builtin commands (\fIdeclaration\fP commands). +When in \fIposix mode\fP, these builtins may appear in a command after +one or more instances of the \fBcommand\fP builtin and retain these +assignment statement properties. +.PP +In the context where an assignment statement is assigning a value +to a shell variable or array index, the += operator can be used to +append to or add to the variable's previous value. +This includes arguments to builtin commands such as \fBdeclare\fP that +accept assignment statements (\fIdeclaration\fP commands). +When += is applied to a variable for which the \fBinteger\fP attribute has been +set, \fIvalue\fP is evaluated as an arithmetic expression and added to the +variable's current value, which is also evaluated. +When += is applied to an array variable using compound assignment (see +.B Arrays +below), the +variable's value is not unset (as it is when using =), and new values are +appended to the array beginning at one greater than the array's maximum index +(for indexed arrays) or added as additional key\-value pairs in an +associative array. +When applied to a string-valued variable, \fIvalue\fP is expanded and +appended to the variable's value. +.PP +A variable can be assigned the \fInameref\fP attribute using the +\fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands +(see the descriptions of \fBdeclare\fP and \fBlocal\fP below) +to create a \fInameref\fP, or a reference to another variable. +This allows variables to be manipulated indirectly. +Whenever the nameref variable is referenced, assigned to, unset, or has +its attributes modified (other than using or changing the \fInameref\fP +attribute itself), the +operation is actually performed on the variable specified by the nameref +variable's value. +A nameref is commonly used within shell functions to refer to a variable +whose name is passed as an argument to the function. +For instance, if a variable name is passed to a shell function as its first +argument, running +.sp .5 +.RS +.if t \f(CWdeclare -n ref=$1\fP +.if n declare -n ref=$1 +.RE +.sp .5 +inside the function creates a nameref variable \fBref\fP whose value is +the variable name passed as the first argument. +References and assignments to \fBref\fP, and changes to its attributes, +are treated as references, assignments, and attribute modifications +to the variable whose name was passed as \fB$1\fP. +If the control variable in a \fBfor\fP loop has the nameref attribute, +the list of words can be a list of shell variables, and a name reference +will be established for each word in the list, in turn, when the loop is +executed. +Array variables cannot be given the \fBnameref\fP attribute. +However, nameref variables can reference array variables and subscripted +array variables. +Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin. +Otherwise, if \fBunset\fP is executed with the name of a nameref variable +as an argument, the variable referenced by the nameref variable will be unset. +.SS Positional Parameters +A +.I positional parameter +is a parameter denoted by one or more +digits, other than the single digit 0. Positional parameters are +assigned from the shell's arguments when it is invoked, +and may be reassigned using the +.B set +builtin command. Positional parameters may not be assigned to +with assignment statements. The positional parameters are +temporarily replaced when a shell function is executed (see +.SM +.B FUNCTIONS +below). +.PP +When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces (see +.SM +.B EXPANSION +below). +.SS Special Parameters +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. +.PD 0 +.TP +.B * +Expands to the positional parameters, starting from one. +When the expansion is not within double quotes, each positional parameter +expands to a separate word. +In contexts where it is performed, those words +are subject to further word splitting and pathname expansion. +When the expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character of the +.SM +.B IFS +special variable. That is, "\fB$*\fP" is equivalent +to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where +.I c +is the first character of the value of the +.SM +.B IFS +variable. If +.SM +.B IFS +is unset, the parameters are separated by spaces. +If +.SM +.B IFS +is null, the parameters are joined without intervening separators. +.TP +.B @ +Expands to the positional parameters, starting from one. +In contexts where word splitting is performed, this expands each +positional parameter to a separate word; if not within double +quotes, these words are subject to word splitting. +In contexts where word splitting is not performed, +this expands to a single word +with each positional parameter separated by a space. +When the +expansion occurs within double quotes, each parameter expands to a +separate word. That is, "\fB$@\fP" is equivalent to +"\fB$1\fP" "\fB$2\fP" ... +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +When there are no positional parameters, "\fB$@\fP" and +.B $@ +expand to nothing (i.e., they are removed). +.TP +.B # +Expands to the number of positional parameters in decimal. +.TP +.B ? +Expands to the exit status of the most recently executed foreground +pipeline. +.TP +.B \- +Expands to the current option flags as specified upon invocation, +by the +.B set +builtin command, or those set by the shell itself +(such as the +.B \-i +option). +.TP +.B $ +Expands to the process ID of the shell. In a subshell, it +expands to the process ID of the current shell, not the +subshell. +.TP +.B ! +Expands to the process ID of the job most recently placed into the +background, whether executed as an asynchronous command or using +the \fBbg\fP builtin (see +.SM +.B "JOB CONTROL" +below). +.TP +.B 0 +Expands to the name of the shell or shell script. This is set at +shell initialization. If +.B bash +is invoked with a file of commands, +.B $0 +is set to the name of that file. If +.B bash +is started with the +.B \-c +option, then +.B $0 +is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the filename used to invoke +.BR bash , +as given by argument zero. +.PD +.SS Shell Variables +The following variables are set by the shell: +.PP +.PD 0 +.TP +.B _ +At shell startup, set to the pathname used to invoke the +shell or shell script being executed as passed in the environment +or argument list. +Subsequently, expands to the last argument to the previous simple +command executed in the foreground, after expansion. +Also set to the full pathname used to invoke each command executed +and placed in the environment exported to that command. +When checking mail, this parameter holds the name of the mail file +currently being checked. +.TP +.B BASH +Expands to the full filename used to invoke this instance of +.BR bash . +.TP +.B BASHOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the +.B \-s +option to the +.B shopt +builtin command (see +.SM +.B "SHELL BUILTIN COMMANDS" +below). The options appearing in +.SM +.B BASHOPTS +are those reported as +.I on +by \fBshopt\fP. +If this variable is in the environment when +.B bash +starts up, each shell option in the list will be enabled before +reading any startup files. +This variable is read-only. +.TP +.B BASHPID +Expands to the process ID of the current \fBbash\fP process. +This differs from \fB$$\fP under certain circumstances, such as subshells +that do not require \fBbash\fP to be re-initialized. +Assignments to +.SM +.B BASHPID +have no effect. +If +.B BASHPID +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_ALIASES +An associative array variable whose members correspond to the internal +list of aliases as maintained by the \fBalias\fP builtin. +Elements added to this array appear in the alias list; however, +unsetting array elements currently does not cause aliases to be removed +from the alias list. +If +.B BASH_ALIASES +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_ARGC +An array variable whose values are the number of parameters in each +frame of the current \fBbash\fP execution call stack. +The number of +parameters to the current subroutine (shell function or script executed +with \fB.\fP or \fBsource\fP) is at the top of the stack. +When a subroutine is executed, the number of parameters passed is pushed onto +.SM +.BR BASH_ARGC . +The shell sets +.SM +.B BASH_ARGC +only when in extended debugging mode (see the description of the +.B extdebug +option to the +.B shopt +builtin below). +Setting \fBextdebug\fP after the shell has started to execute a script, +or referencing this variable when \fBextdebug\fP is not set, +may result in inconsistent values. +.TP +.B BASH_ARGV +An array variable containing all of the parameters in the current \fBbash\fP +execution call stack. The final parameter of the last subroutine call +is at the top of the stack; the first parameter of the initial call is +at the bottom. When a subroutine is executed, the parameters supplied +are pushed onto +.SM +.BR BASH_ARGV . +The shell sets +.SM +.B BASH_ARGV +only when in extended debugging mode +(see the description of the +.B extdebug +option to the +.B shopt +builtin below). +Setting \fBextdebug\fP after the shell has started to execute a script, +or referencing this variable when \fBextdebug\fP is not set, +may result in inconsistent values. +.TP +.B BASH_ARGV0 +When referenced, this variable expands to the name of the shell or shell +script (identical to +.BR $0 ; +see the description of special parameter 0 above). +Assignment to +.B BASH_ARGV0 +causes the value assigned to also be assigned to \fB$0\fP. +If +.B BASH_ARGV0 +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_CMDS +An associative array variable whose members correspond to the internal +hash table of commands as maintained by the \fBhash\fP builtin. +Elements added to this array appear in the hash table; however, +unsetting array elements currently does not cause command names to be removed +from the hash table. +If +.B BASH_CMDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_COMMAND +The command currently being executed or about to be executed, unless the +shell is executing a command as the result of a trap, +in which case it is the command executing at the time of the trap. +If +.B BASH_COMMAND +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_EXECUTION_STRING +The command argument to the \fB\-c\fP invocation option. +.TP +.B BASH_LINENO +An array variable whose members are the line numbers in source files +where each corresponding member of +.SM +.B FUNCNAME +was invoked. +\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source +file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where +\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called +(or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another +shell function). +Use +.SM +.B LINENO +to obtain the current line number. +.TP +.B BASH_LOADABLES_PATH +A colon-separated list of directories in which the shell looks for +dynamically loadable builtins specified by the +.B enable +command. +.TP +.B BASH_REMATCH +An array variable whose members are assigned by the \fB=~\fP binary +operator to the \fB[[\fP conditional command. +The element with index 0 is the portion of the string +matching the entire regular expression. +The element with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +.TP +.B BASH_SOURCE +An array variable whose members are the source filenames +where the corresponding shell function names in the +.SM +.B FUNCNAME +array variable are defined. +The shell function +\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file +\fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from +\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP. +.TP +.B BASH_SUBSHELL +Incremented by one within each subshell or subshell environment when +the shell begins executing in that environment. +The initial value is 0. +If +.B BASH_SUBSHELL +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_VERSINFO +A readonly array variable whose members hold version information for +this instance of +.BR bash . +The values assigned to the array members are as follows: +.sp .5 +.RS +.TP 24 +.B BASH_VERSINFO[\fR0\fP] +The major version number (the \fIrelease\fP). +.TP +.B BASH_VERSINFO[\fR1\fP] +The minor version number (the \fIversion\fP). +.TP +.B BASH_VERSINFO[\fR2\fP] +The patch level. +.TP +.B BASH_VERSINFO[\fR3\fP] +The build version. +.TP +.B BASH_VERSINFO[\fR4\fP] +The release status (e.g., \fIbeta1\fP). +.TP +.B BASH_VERSINFO[\fR5\fP] +The value of +.SM +.BR MACHTYPE . +.RE +.TP +.B BASH_VERSION +Expands to a string describing the version of this instance of +.BR bash . +.TP +.B COMP_CWORD +An index into \fB${COMP_WORDS}\fP of the word containing the current +cursor position. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_KEY +The key (or final key of a key sequence) used to invoke the current +completion function. +.TP +.B COMP_LINE +The current command line. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_POINT +The index of the current cursor position relative to the beginning of +the current command. +If the current cursor position is at the end of the current command, +the value of this variable is equal to \fB${#COMP_LINE}\fP. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_TYPE +Set to an integer value corresponding to the type of completion attempted +that caused a completion function to be called: +\fITAB\fP, for normal completion, +\fI?\fP, for listing completions after successive tabs, +\fI!\fP, for listing alternatives on partial word completion, +\fI@\fP, to list completions if the word is not unmodified, +or +\fI%\fP, for menu completion. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_WORDBREAKS +The set of characters that the \fBreadline\fP library treats as word +separators when performing word completion. +If +.SM +.B COMP_WORDBREAKS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B COMP_WORDS +An array variable (see \fBArrays\fP below) consisting of the individual +words in the current command line. +The line is split into words as \fBreadline\fP would split it, using +.SM +.B COMP_WORDBREAKS +as described above. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COPROC +An array variable (see \fBArrays\fP below) created to hold the file descriptors +for output from and input to an unnamed coprocess (see \fBCoprocesses\fP +above). +.TP +.B DIRSTACK +An array variable (see +.B Arrays +below) containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +.B dirs +builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the +.B pushd +and +.B popd +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If +.SM +.B DIRSTACK +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EPOCHREALTIME +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value +with micro-second granularity. +Assignments to +.SM +.B EPOCHREALTIME +are ignored. +If +.SM +.B EPOCHREALTIME +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EPOCHSECONDS +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see \fItime\fP\fR(3)\fP). +Assignments to +.SM +.B EPOCHSECONDS +are ignored. +If +.SM +.B EPOCHSECONDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EUID +Expands to the effective user ID of the current user, initialized at +shell startup. This variable is readonly. +.TP +.B FUNCNAME +An array variable containing the names of all shell functions +currently in the execution call stack. +The element with index 0 is the name of any currently-executing +shell function. +The bottom-most element (the one with the highest index) is +.if t \f(CW"main"\fP. +.if n "main". +This variable exists only when a shell function is executing. +Assignments to +.SM +.B FUNCNAME +have no effect. +If +.SM +.B FUNCNAME +is unset, it loses its special properties, even if it is +subsequently reset. +.if t .sp 0.5 +.if n .sp 1 +This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP. +Each element of \fBFUNCNAME\fP has corresponding elements in +\fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack. +For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file +\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number +\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP. +The \fBcaller\fP builtin displays the current call stack using this +information. +.TP +.B GROUPS +An array variable containing the list of groups of which the current +user is a member. +Assignments to +.SM +.B GROUPS +have no effect. +If +.SM +.B GROUPS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B HISTCMD +The history number, or index in the history list, of the current +command. +Assignments to +.SM +.B HISTCMD +are ignored. +If +.SM +.B HISTCMD +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B HOSTNAME +Automatically set to the name of the current host. +.TP +.B HOSTTYPE +Automatically set to a string that uniquely +describes the type of machine on which +.B bash +is executing. +The default is system-dependent. +.TP +.B LINENO +Each time this parameter is referenced, the shell substitutes +a decimal number representing the current sequential line number +(starting with 1) within a script or function. When not in a +script or function, the value substituted is not guaranteed to +be meaningful. +If +.SM +.B LINENO +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B MACHTYPE +Automatically set to a string that fully describes the system +type on which +.B bash +is executing, in the standard GNU \fIcpu-company-system\fP format. +The default is system-dependent. +.TP +.B MAPFILE +An array variable (see \fBArrays\fP below) created to hold the text +read by the \fBmapfile\fP builtin when no variable name is supplied. +.TP +.B OLDPWD +The previous working directory as set by the +.B cd +command. +.TP +.B OPTARG +The value of the last option argument processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B OPTIND +The index of the next argument to be processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B OSTYPE +Automatically set to a string that +describes the operating system on which +.B bash +is executing. +The default is system-dependent. +.TP +.B PIPESTATUS +An array variable (see +.B Arrays +below) containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). +.TP +.B PPID +The process ID of the shell's parent. This variable is readonly. +.TP +.B PWD +The current working directory as set by the +.B cd +command. +.TP +.B RANDOM +Each time this parameter is referenced, it expands to a random integer +between 0 and 32767. +Assigning +a value to +.SM +.BR RANDOM +initializes (seeds) the sequence of random numbers. +If +.SM +.B RANDOM +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B READLINE_ARGUMENT +Any numeric argument given to a readline command that was defined using +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below) +when it was invoked. +.TP +.B READLINE_LINE +The contents of the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +.TP +.B READLINE_MARK +The position of the mark (saved insertion point) in the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +The characters between the insertion point and the mark are often +called the \fIregion\fP. +.TP +.B READLINE_POINT +The position of the insertion point in the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +.TP +.B REPLY +Set to the line of input read by the +.B read +builtin command when no arguments are supplied. +.TP +.B SECONDS +Each time this parameter is +referenced, it expands to the number of seconds since shell invocation. +If a value is assigned to +.SM +.BR SECONDS , +the value returned upon subsequent +references is +the number of seconds since the assignment plus the value assigned. +The number of seconds at shell invocation and the current time are always +determined by querying the system clock. +If +.SM +.B SECONDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B SHELLOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the +.B \-o +option to the +.B set +builtin command (see +.SM +.B "SHELL BUILTIN COMMANDS" +below). The options appearing in +.SM +.B SHELLOPTS +are those reported as +.I on +by \fBset \-o\fP. +If this variable is in the environment when +.B bash +starts up, each shell option in the list will be enabled before +reading any startup files. +This variable is read-only. +.TP +.B SHLVL +Incremented by one each time an instance of +.B bash +is started. +.TP +.B SRANDOM +This variable expands to a 32-bit pseudo-random number each time it is +referenced. The random number generator is not linear on systems that +support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number +has no relationship to the numbers preceding it. +The random number generator cannot be seeded, so assignments to this +variable have no effect. +If +.SM +.B SRANDOM +is unset, it loses its special properties, +even if it is subsequently reset. +.TP +.B UID +Expands to the user ID of the current user, initialized at shell startup. +This variable is readonly. +.PD +.PP +The following variables are used by the shell. In some cases, +.B bash +assigns a default value to a variable; these cases are noted +below. +.PP +.PD 0 +.TP +.B BASH_COMPAT +The value is used to set the shell's compatibility level. +See +.SM +.B "SHELL COMPATIBILITY MODE" +below for a description of the various compatibility +levels and their effects. +The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) +corresponding to the desired compatibility level. +If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility +level is set to the default for the current version. +If \fBBASH_COMPAT\fP is set to a value that is not one of the valid +compatibility levels, the shell prints an error message and sets the +compatibility level to the default for the current version. +The valid values correspond to the compatibility levels +described below under +.SM +.BR "SHELL COMPATIBILITY MODE" . +For example, 4.2 and 42 are valid values that correspond +to the \fBcompat42\fP \fBshopt\fP option +and set the compatibility level to 42. +The current version is also a valid value. +.TP +.B BASH_ENV +If this parameter is set when \fBbash\fP is executing a shell script, +its value is interpreted as a filename containing commands to +initialize the shell, as in +.IR ~/.bashrc . +The value of +.SM +.B BASH_ENV +is subjected to parameter expansion, command substitution, and arithmetic +expansion before being interpreted as a filename. +.SM +.B PATH +is not used to search for the resultant filename. +.TP +.B BASH_XTRACEFD +If set to an integer corresponding to a valid file descriptor, \fBbash\fP +will write the trace output generated when +.if t \f(CWset -x\fP +.if n \fIset -x\fP +is enabled to that file descriptor. +The file descriptor is closed when +.SM +.B BASH_XTRACEFD +is unset or assigned a new value. +Unsetting +.SM +.B BASH_XTRACEFD +or assigning it the empty string causes the +trace output to be sent to the standard error. +Note that setting +.SM +.B BASH_XTRACEFD +to 2 (the standard error file +descriptor) and then unsetting it will result in the standard error +being closed. +.TP +.B CDPATH +The search path for the +.B cd +command. +This is a colon-separated list of directories in which the shell looks +for destination directories specified by the +.B cd +command. +A sample value is +.if t \f(CW".:~:/usr"\fP. +.if n ".:~:/usr". +.TP +.B CHILD_MAX +Set the number of exited child status values for the shell to remember. +Bash will not allow this value to be decreased below a POSIX-mandated +minimum, and there is a maximum value (currently 8192) that this may +not exceed. +The minimum value is system-dependent. +.TP +.B COLUMNS +Used by the \fBselect\fP compound command to determine the terminal width +when printing selection lists. +Automatically set if the +.B checkwinsize +option is enabled or in an interactive shell upon receipt of a +.SM +.BR SIGWINCH . +.TP +.B COMPREPLY +An array variable from which \fBbash\fP reads the possible completions +generated by a shell function invoked by the programmable completion +facility (see \fBProgrammable Completion\fP below). +Each array element contains one possible completion. +.TP +.B EMACS +If \fBbash\fP finds this variable in the environment when the shell starts +with value +.if t \f(CWt\fP, +.if n "t", +it assumes that the shell is running in an Emacs shell buffer and disables +line editing. +.TP +.B ENV +Expanded and executed similarly to +.SM +.B BASH_ENV +(see \fBINVOCATION\fP above) +when an interactive shell is invoked in \fIposix mode\fP. +.TP +.B EXECIGNORE +A colon-separated list of shell patterns (see \fBPattern Matching\fP) +defining the list of filenames to be ignored by command search using +\fBPATH\fP. +Files whose full pathnames match one of these patterns are not considered +executable files for the purposes of completion and command execution +via \fBPATH\fP lookup. +This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP +commands. +Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP. +Use this variable to ignore shared library files that have the executable +bit set, but are not executable files. +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.TP +.B FCEDIT +The default editor for the +.B fc +builtin command. +.TP +.B FIGNORE +A colon-separated list of suffixes to ignore when performing +filename completion (see +.SM +.B READLINE +below). +A filename whose suffix matches one of the entries in +.SM +.B FIGNORE +is excluded from the list of matched filenames. +A sample value is +.if t \f(CW".o:~"\fP. +.if n ".o:~". +.TP +.B FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. +.TP +.B GLOBIGNORE +A colon-separated list of patterns defining the set of file names to +be ignored by pathname expansion. +If a file name matched by a pathname expansion pattern also matches one +of the patterns in +.SM +.BR GLOBIGNORE , +it is removed from the list of matches. +.TP +.B HISTCONTROL +A colon-separated list of values controlling how commands are saved on +the history list. +If the list of values includes +.IR ignorespace , +lines which begin with a +.B space +character are not saved in the history list. +A value of +.I ignoredups +causes lines matching the previous history entry to not be saved. +A value of +.I ignoreboth +is shorthand for \fIignorespace\fP and \fIignoredups\fP. +A value of +.I erasedups +causes all previous lines matching the current line to be removed from +the history list before that line is saved. +Any value not in the above list is ignored. +If +.SM +.B HISTCONTROL +is unset, or does not include a valid value, +all lines read by the shell parser are saved on the history list, +subject to the value of +.SM +.BR HISTIGNORE . +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.SM +.BR HISTCONTROL . +.TP +.B HISTFILE +The name of the file in which command history is saved (see +.SM +.B HISTORY +below). The default value is \fI~/.bash_history\fP. If unset, the +command history is not saved when a shell exits. +.TP +.B HISTFILESIZE +The maximum number of lines contained in the history file. When this +variable is assigned a value, the history file is truncated, if +necessary, +to contain no more than that number of lines by removing the oldest entries. +The history file is also truncated to this size after +writing it when a shell exits. +If the value is 0, the history file is truncated to zero size. +Non-numeric values and numeric values less than zero inhibit truncation. +The shell sets the default value to the value of \fBHISTSIZE\fP +after reading any startup files. +.TP +.B HISTIGNORE +A colon-separated list of patterns used to decide which command lines +should be saved on the history list. Each pattern is anchored at the +beginning of the line and must match the complete line (no implicit +`\fB*\fP' is appended). Each pattern is tested against the line +after the checks specified by +.SM +.B HISTCONTROL +are applied. +In addition to the normal shell pattern matching characters, `\fB&\fP' +matches the previous history line. `\fB&\fP' may be escaped using a +backslash; the backslash is removed before attempting a match. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.SM +.BR HISTIGNORE . +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.TP +.B HISTSIZE +The number of commands to remember in the command history (see +.SM +.B HISTORY +below). +If the value is 0, commands are not saved in the history list. +Numeric values less than zero result in every command being saved +on the history list (there is no limit). +The shell sets the default value to 500 after reading any startup files. +.TP +.B HISTTIMEFORMAT +If this variable is set and not null, its value is used as a format string +for \fIstrftime\fP(3) to print the time stamp associated with each history +entry displayed by the \fBhistory\fP builtin. +If this variable is set, time stamps are written to the history file so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. +.TP +.B HOME +The home directory of the current user; the default argument for the +\fBcd\fP builtin command. +The value of this variable is also used when performing tilde expansion. +.TP +.B HOSTFILE +Contains the name of a file in the same format as +.FN /etc/hosts +that should be read when the shell needs to complete a +hostname. +The list of possible hostname completions may be changed while the +shell is running; +the next time hostname completion is attempted after the +value is changed, +.B bash +adds the contents of the new file to the existing list. +If +.SM +.B HOSTFILE +is set, but has no value, or does not name a readable file, +\fBbash\fP attempts to read +.FN /etc/hosts +to obtain the list of possible hostname completions. +When +.SM +.B HOSTFILE +is unset, the hostname list is cleared. +.TP +.B IFS +The +.I Internal Field Separator +that is used +for word splitting after expansion and to +split lines into words with the +.B read +builtin command. The default value is +``''. +.TP +.B IGNOREEOF +Controls the +action of an interactive shell on receipt of an +.SM +.B EOF +character as the sole input. If set, the value is the number of +consecutive +.SM +.B EOF +characters which must be +typed as the first characters on an input line before +.B bash +exits. If the variable exists but does not have a numeric value, or +has no value, the default value is 10. If it does not exist, +.SM +.B EOF +signifies the end of input to the shell. +.TP +.B INPUTRC +The filename for the +.B readline +startup file, overriding the default of +.FN ~/.inputrc +(see +.SM +.B READLINE +below). +.TP +.B INSIDE_EMACS +If this variable appears in the environment when the shell starts, +\fBbash\fP assumes that it is running inside an Emacs shell buffer +and may disable line editing, depending on the value of \fBTERM\fP. +.TP +.B LANG +Used to determine the locale category for any category not specifically +selected with a variable starting with \fBLC_\fP. +.TP +.B LC_ALL +This variable overrides the value of +.SM +.B LANG +and any other +\fBLC_\fP variable specifying a locale category. +.TP +.B LC_COLLATE +This variable determines the collation order used when sorting the +results of pathname expansion, and determines the behavior of range +expressions, equivalence classes, and collating sequences within +pathname expansion and pattern matching. +.TP +.B LC_CTYPE +This variable determines the interpretation of characters and the +behavior of character classes within pathname expansion and pattern +matching. +.TP +.B LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a \fB$\fP. +.TP +.B LC_NUMERIC +This variable determines the locale category used for number formatting. +.TP +.B LC_TIME +This variable determines the locale category used for data and time +formatting. +.TP +.B LINES +Used by the \fBselect\fP compound command to determine the column length +for printing selection lists. +Automatically set if the +.B checkwinsize +option is enabled or in an interactive shell upon receipt of a +.SM +.BR SIGWINCH . +.TP +.B MAIL +If this parameter is set to a file or directory name and the +.SM +.B MAILPATH +variable is not set, +.B bash +informs the user of the arrival of mail in the specified file or +Maildir-format directory. +.TP +.B MAILCHECK +Specifies how +often (in seconds) +.B bash +checks for mail. The default is 60 seconds. When it is time to check +for mail, the shell does so before displaying the primary prompt. +If this variable is unset, or set to a value that is not a number +greater than or equal to zero, the shell disables mail checking. +.TP +.B MAILPATH +A colon-separated list of filenames to be checked for mail. +The message to be printed when mail arrives in a particular file +may be specified by separating the filename from the message with a `?'. +When used in the text of the message, \fB$_\fP expands to the name of +the current mailfile. +Example: +.RS +.PP +\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq +.PP +.B Bash +can be configured to supply +a default value for this variable (there is no value by default), +but the location of the user +mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP). +.RE +.TP +.B OPTERR +If set to the value 1, +.B bash +displays error messages generated by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SM +.B OPTERR +is initialized to 1 each time the shell is invoked or a shell +script is executed. +.TP +.B PATH +The search path for commands. It +is a colon-separated list of directories in which +the shell looks for commands (see +.SM +.B COMMAND EXECUTION +below). +A zero-length (null) directory name in the value of +.SM +.B PATH +indicates the current directory. +A null directory name may appear as two adjacent colons, or as an initial +or trailing colon. +The default path is system-dependent, +and is set by the administrator who installs +.BR bash . +A common value is +.na +.if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP. +.if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''. +.ad +.TP +.B POSIXLY_CORRECT +If this variable is in the environment when \fBbash\fP starts, the shell +enters \fIposix mode\fP before reading the startup files, as if the +.B \-\-posix +invocation option had been supplied. If it is set while the shell is +running, \fBbash\fP enables \fIposix mode\fP, as if the command +.if t \f(CWset -o posix\fP +.if n \fIset -o posix\fP +had been executed. +When the shell enters \fIposix mode\fP, it sets this variable if it was +not already set. +.TP +.B PROMPT_COMMAND +If this variable is set, and is an array, +the value of each set element is executed as a command +prior to issuing each primary prompt. +If this is set but not an array variable, +its value is used as a command to execute instead. +.TP +.B PROMPT_DIRTRIM +If set to a number greater than zero, the value is used as the number of +trailing directory components to retain when expanding the \fB\ew\fP and +\fB\eW\fP prompt string escapes (see +.SM +.B PROMPTING +below). Characters removed are replaced with an ellipsis. +.TP +.B PS0 +The value of this parameter is expanded (see +.SM +.B PROMPTING +below) and displayed by interactive shells after reading a command +and before the command is executed. +.TP +.B PS1 +The value of this parameter is expanded (see +.SM +.B PROMPTING +below) and used as the primary prompt string. The default value is +``\fB\es\-\ev\e$ \fP''. +.TP +.B PS2 +The value of this parameter is expanded as with +.SM +.B PS1 +and used as the secondary prompt string. The default is +``\fB> \fP''. +.TP +.B PS3 +The value of this parameter is used as the prompt for the +.B select +command (see +.SM +.B SHELL GRAMMAR +above). +.TP +.B PS4 +The value of this parameter is expanded as with +.SM +.B PS1 +and the value is printed before each command +.B bash +displays during an execution trace. The first character of +the expanded value of +.SM +.B PS4 +is replicated multiple times, as necessary, to indicate multiple +levels of indirection. The default is ``\fB+ \fP''. +.TP +.B SHELL +This variable expands to the full pathname to the shell. +If it is not set when the shell starts, +.B bash +assigns to it the full pathname of the current user's login shell. +.TP +.B TIMEFORMAT +The value of this parameter is used as a format string specifying +how the timing information for pipelines prefixed with the +.B time +reserved word should be displayed. +The \fB%\fP character introduces an escape sequence that is +expanded to a time value or other information. +The escape sequences and their meanings are as follows; the +braces denote optional portions. +.sp .5 +.RS +.PD 0 +.TP 10 +.B %% +A literal \fB%\fP. +.TP +.B %[\fIp\fP][l]R +The elapsed time in seconds. +.TP +.B %[\fIp\fP][l]U +The number of CPU seconds spent in user mode. +.TP +.B %[\fIp\fP][l]S +The number of CPU seconds spent in system mode. +.TP +.B %P +The CPU percentage, computed as (%U + %S) / %R. +.PD +.RE +.IP +The optional \fIp\fP is a digit specifying the \fIprecision\fP, +the number of fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; +values of \fIp\fP greater than 3 are changed to 3. +If \fIp\fP is not specified, the value 3 is used. +.IP +The optional \fBl\fP specifies a longer format, including +minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs. +The value of \fIp\fP determines whether or not the fraction is +included. +.IP +If this variable is not set, \fBbash\fP acts as if it had the +value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP. +If the value is null, no timing information is displayed. +A trailing newline is added when the format string is displayed. +.PD 0 +.TP +.B TMOUT +If set to a value greater than zero, +.SM +.B TMOUT +is treated as the +default timeout for the \fBread\fP builtin. +The \fBselect\fP command terminates if input does not arrive +after +.SM +.B TMOUT +seconds when input is coming from a terminal. +In an interactive shell, the value is interpreted as the +number of seconds to wait for a line of input after issuing the +primary prompt. +.B Bash +terminates after waiting for that number of seconds if a complete +line of input does not arrive. +.TP +.B TMPDIR +If set, \fBbash\fP uses its value as the name of a directory in which +\fBbash\fP creates temporary files for the shell's use. +.TP +.B auto_resume +This variable controls how the shell interacts with the user and +job control. If this variable is set, single word simple +commands without redirections are treated as candidates for resumption +of an existing stopped job. There is no ambiguity allowed; if there is +more than one job beginning with the string typed, the job most recently +accessed is selected. The +.I name +of a stopped job, in this context, is the command line used to +start it. +If set to the value +.IR exact , +the string supplied must match the name of a stopped job exactly; +if set to +.IR substring , +the string supplied needs to match a substring of the name of a +stopped job. The +.I substring +value provides functionality analogous to the +.B %? +job identifier (see +.SM +.B JOB CONTROL +below). If set to any other value, the supplied string must +be a prefix of a stopped job's name; this provides functionality +analogous to the \fB%\fP\fIstring\fP job identifier. +.TP +.B histchars +The two or three characters which control history expansion +and tokenization (see +.SM +.B HISTORY EXPANSION +below). The first character is the \fIhistory expansion\fP character, +the character which signals the start of a history +expansion, normally `\fB!\fP'. +The second character is the \fIquick substitution\fP +character, which is used as shorthand for re-running the previous +command entered, substituting one string for another in the command. +The default is `\fB^\fP'. +The optional third character is the character +which indicates that the remainder of the line is a comment when found +as the first character of a word, normally `\fB#\fP'. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. +.PD +.SS Arrays +.B Bash +provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; the +.B declare +builtin will explicitly declare an array. +There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. +Indexed arrays are referenced using integers (including arithmetic +expressions) and are zero-based; associative arrays are referenced +using arbitrary strings. +Unless otherwise noted, indexed array indices must be non-negative integers. +.PP +An indexed array is created automatically if any variable is assigned to +using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The +.I subscript +is treated as an arithmetic expression that must evaluate to a number. +To explicitly declare an indexed array, use +.B declare \-a \fIname\fP +(see +.SM +.B SHELL BUILTIN COMMANDS +below). +.B declare \-a \fIname\fP[\fIsubscript\fP] +is also accepted; the \fIsubscript\fP is ignored. +.PP +Associative arrays are created using +.BR "declare \-A \fIname\fP" . +.PP +Attributes may be +specified for an array variable using the +.B declare +and +.B readonly +builtins. Each attribute applies to all members of an array. +.PP +Arrays are assigned to using compound assignments of the form +\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each +\fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP. +Indexed array assignments do not require anything but \fIstring\fP. +Each \fIvalue\fP in the list is expanded using all the shell expansions +described below under +.SM +.BR EXPANSION . +When assigning to indexed arrays, if the optional brackets and subscript +are supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. +.PP +When assigning to an associative array, the words in a compound assignment +may be either assignment statements, for which the subscript is required, +or a list of words that is interpreted as a sequence of alternating keys +and values: +\fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP. +These are treated identically to +\fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP. +The first word in the list determines how the remaining words +are interpreted; all assignments in a list must be of the same type. +When using key/value pairs, the keys may not be missing or empty; +a final missing value is treated like the empty string. +.PP +This syntax is also accepted by the +.B declare +builtin. Individual array elements may be assigned to using the +\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above. +When assigning to an indexed array, if +.I name +is subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +\fIname\fP, so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.PP +The += operator will append to an array variable when assigning +using the compound assignment syntax; see +.SM +.B PARAMETERS +above. +.PP +Any element of an array may be referenced using +${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid +conflicts with pathname expansion. If +\fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to +all members of \fIname\fP. These subscripts differ only when the +word appears within double quotes. If the word is double-quoted, +${\fIname\fP[*]} expands to a single +word with the value of each array member separated by the first +character of the +.SM +.B IFS +special variable, and ${\fIname\fP[@]} expands each element of +\fIname\fP to a separate word. When there are no array members, +${\fIname\fP[@]} expands to nothing. +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +This is analogous to the expansion +of the special parameters \fB*\fP and \fB@\fP (see +.B Special Parameters +above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of +${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or +\fB@\fP, the expansion is the number of elements in the array. +If the +.I subscript +used to reference an element of an indexed array +evaluates to a number less than zero, it is +interpreted as relative to one greater than the maximum index of the array, +so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.PP +Referencing an array variable without a subscript is equivalent to +referencing the array with a subscript of 0. +Any reference to a variable using a valid subscript is legal, and +.B bash +will create an array if necessary. +.PP +An array variable is considered set if a subscript has been assigned a +value. The null string is a valid value. +.PP +It is possible to obtain the keys (indices) of an array as well as the values. +${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]} +expand to the indices assigned in array variable \fIname\fP. +The treatment when in double quotes is similar to the expansion of the +special parameters \fI@\fP and \fI*\fP within double quotes. +.PP +The +.B unset +builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP] +destroys the array element at index \fIsubscript\fP, +for both indexed and associative arrays. +Negative subscripts to indexed arrays are interpreted as described above. +Unsetting the last element of an array variable does not unset the variable. +\fBunset\fP \fIname\fP, where \fIname\fP is an array, +removes the entire array. +\fBunset\fP \fIname\fP[\fIsubscript\fP], where +\fIsubscript\fP is \fB*\fP or \fB@\fP, behaves differently depending on +whether \fIname\fP is an indexed or associative array. +If \fIname\fP is an associative array, this unsets the element with +subscript \fB*\fP or \fB@\fP. +If \fIname\fP is an indexed array, unset removes all of the elements but +does not remove the array itself. +.PP +When using a variable name with a subscript as an argument to a command, +such as with \fBunset\fP, without using the word expansion syntax +described above, the argument is subject to pathname expansion. +If pathname expansion is not desired, the argument should be quoted. +.PP +The +.BR declare , +.BR local , +and +.B readonly +builtins each accept a +.B \-a +option to specify an indexed array and a +.B \-A +option to specify an associative array. +If both options are supplied, +.B \-A +takes precedence. +The +.B read +builtin accepts a +.B \-a +option to assign a list of words read from the standard input +to an array. The +.B set +and +.B declare +builtins display array values in a way that allows them to be +reused as assignments. +.SH EXPANSION +Expansion is performed on the command line after it has been split into +words. There are seven kinds of expansion performed: +.IR "brace expansion" , +.IR "tilde expansion" , +.IR "parameter and variable expansion" , +.IR "command substitution" , +.IR "arithmetic expansion" , +.IR "word splitting" , +and +.IR "pathname expansion" . +.PP +The order of expansions is: +brace expansion; +tilde expansion, parameter and variable expansion, arithmetic expansion, +and command substitution (done in a left-to-right fashion); +word splitting; +and pathname expansion. +.PP +On systems that can support it, there is an additional expansion +available: \fIprocess substitution\fP. +This is performed at the +same time as tilde, parameter, variable, and arithmetic expansion and +command substitution. +.PP +After these expansions are performed, quote characters present in the +original word are removed unless they have been quoted themselves +(\fIquote removal\fP). +.PP +Only brace expansion, word splitting, and pathname expansion +can increase the number of words of the expansion; other expansions +expand a single word to a single word. +The only exceptions to this are the expansions of +"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP", +and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP +as explained above (see +.SM +.BR PARAMETERS ). +.SS Brace Expansion +.I "Brace expansion" +is a mechanism by which arbitrary strings +may be generated. This mechanism is similar to +\fIpathname expansion\fP, but the filenames generated +need not exist. Patterns to be brace expanded take +the form of an optional +.IR preamble , +followed by either a series of comma-separated strings or +a sequence expression between a pair of braces, followed by +an optional +.IR postscript . +The preamble is prefixed to each string contained +within the braces, and the postscript is then appended +to each resulting string, expanding left to right. +.PP +Brace expansions may be nested. The results of each expanded +string are not sorted; left to right order is preserved. +For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. +.PP +A sequence expression takes the form +\fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP, +where \fIx\fP and \fIy\fP are either integers or single letters, +and \fIincr\fP, an optional increment, is an integer. +When integers are supplied, the expression expands to each number between +\fIx\fP and \fIy\fP, inclusive. +Supplied integers may be prefixed with \fI0\fP to force each term to have the +same width. +When either \fIx\fP or \fPy\fP begins with a zero, the shell +attempts to force all generated terms to contain the same number of digits, +zero-padding where necessary. +When letters are supplied, the expression expands to each character +lexicographically between \fIx\fP and \fIy\fP, inclusive, +using the default C locale. +Note that both \fIx\fP and \fIy\fP must be of the same type +(integer or letter). +When the increment is supplied, it is used as the difference between +each term. The default increment is 1 or \-1 as appropriate. +.PP +Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. +.B Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. +.PP +A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma or a valid +sequence expression. +Any incorrectly formed brace expansion is left unchanged. +A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its +being considered part of a brace expression. +To avoid conflicts with parameter expansion, the string \fB${\fP +is not considered eligible for brace expansion, and inhibits brace +expansion until the closing \fB}\fP. +.PP +This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +.RS +.PP +mkdir /usr/local/src/bash/{old,new,dist,bugs} +.RE +or +.RS +chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +.RE +.PP +Brace expansion introduces a slight incompatibility with +historical versions of +.BR sh . +.B sh +does not treat opening or closing braces specially when they +appear as part of a word, and preserves them in the output. +.B Bash +removes braces from words as a consequence of brace +expansion. For example, a word entered to +.B sh +as \fIfile{1,2}\fP +appears identically in the output. The same word is +output as +.I file1 file2 +after expansion by +.BR bash . +If strict compatibility with +.B sh +is desired, start +.B bash +with the +.B +B +option or disable brace expansion with the +.B +B +option to the +.B set +command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS Tilde Expansion +If a word begins with an unquoted tilde character (`\fB~\fP'), all of +the characters preceding the first unquoted slash (or all characters, +if there is no unquoted slash) are considered a \fItilde-prefix\fP. +If none of the characters in the tilde-prefix are quoted, the +characters in the tilde-prefix following the tilde are treated as a +possible \fIlogin name\fP. +If this login name is the null string, the tilde is replaced with the +value of the shell parameter +.SM +.BR HOME . +If +.SM +.B HOME +is unset, the home directory of the user executing the shell is +substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. +.PP +If the tilde-prefix is a `~+', the value of the shell variable +.SM +.B PWD +replaces the tilde-prefix. +If the tilde-prefix is a `~\-', the value of the shell variable +.SM +.BR OLDPWD , +if it is set, is substituted. +If the characters following the tilde in the tilde-prefix consist +of a number \fIN\fP, optionally prefixed +by a `+' or a `\-', the tilde-prefix is replaced with the corresponding +element from the directory stack, as it would be displayed by the +.B dirs +builtin invoked with the tilde-prefix as an argument. +If the characters following the tilde in the tilde-prefix consist of a +number without a leading `+' or `\-', `+' is assumed. +.PP +If the login name is invalid, or the tilde expansion fails, the word +is unchanged. +.PP +Each variable assignment is checked for unquoted tilde-prefixes immediately +following a +.B : +or the first +.BR = . +In these cases, tilde expansion is also performed. +Consequently, one may use filenames with tildes in assignments to +.SM +.BR PATH , +.SM +.BR MAILPATH , +and +.SM +.BR CDPATH , +and the shell assigns the expanded value. +.PP +Bash also performs tilde expansion on words satisfying the conditions of +variable assignments (as described above under +.SM +.BR PARAMETERS ) +when they appear as arguments to simple commands. +Bash does not do this, except for the \fIdeclaration\fP commands listed +above, when in \fIposix mode\fP. +.SS Parameter Expansion +The `\fB$\fP' character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. +.PP +When braces are used, the matching ending brace is the first `\fB}\fP' +not escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. +.PP +.PD 0 +.TP +${\fIparameter\fP} +The value of \fIparameter\fP is substituted. The braces are required +when +.I parameter +is a positional parameter with more than one digit, +or when +.I parameter +is followed by a character which is not to be +interpreted as part of its name. +The \fIparameter\fP is a shell parameter as described above +\fBPARAMETERS\fP) or an array reference (\fBArrays\fP). +.PD +.PP +If the first character of \fIparameter\fP is an exclamation point (\fB!\fP), +and \fIparameter\fP is not a \fInameref\fP, +it introduces a level of indirection. +\fBBash\fP uses the value formed by expanding the rest of +\fIparameter\fP as the new \fIparameter\fP; this is then +expanded and that value is used in the rest of the expansion, rather +than the expansion of the original \fIparameter\fP. +This is known as \fIindirect expansion\fP. +The value is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +If \fIparameter\fP is a nameref, this expands to the name of the +parameter referenced by \fIparameter\fP instead of performing the +complete indirect expansion. +The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and +${\fB!\fP\fIname\fP[\fI@\fP]} described below. +The exclamation point must immediately follow the left brace in order to +introduce indirection. +.PP +In each of the cases below, \fIword\fP is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +.PP +When not performing substring expansion, using the forms documented below +(e.g., \fB:-\fP), +\fBbash\fP tests for a parameter that is unset or null. Omitting the colon +results in a test only for a parameter that is unset. +.PP +.PD 0 +.TP +${\fIparameter\fP\fB:\-\fP\fIword\fP} +\fBUse Default Values\fP. If +.I parameter +is unset or null, the expansion of +.I word +is substituted. Otherwise, the value of +.I parameter +is substituted. +.TP +${\fIparameter\fP\fB:=\fP\fIword\fP} +\fBAssign Default Values\fP. +If +.I parameter +is unset or null, the expansion of +.I word +is assigned to +.IR parameter . +The value of +.I parameter +is then substituted. Positional parameters and special parameters may +not be assigned to in this way. +.TP +${\fIparameter\fP\fB:?\fP\fIword\fP} +\fBDisplay Error if Null or Unset\fP. +If +.I parameter +is null or unset, the expansion of \fIword\fP (or a message to that effect +if +.I word +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of \fIparameter\fP is +substituted. +.TP +${\fIparameter\fP\fB:+\fP\fIword\fP} +\fBUse Alternate Value\fP. +If +.I parameter +is null or unset, nothing is substituted, otherwise the expansion of +.I word +is substituted. +.TP +${\fIparameter\fP\fB:\fP\fIoffset\fP} +.PD 0 +.TP +${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP} +.PD +\fBSubstring Expansion\fP. +Expands to up to \fIlength\fP characters of the value of \fIparameter\fP +starting at the character specified by \fIoffset\fP. +If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by +\fB@\fP or \fB*\fP, or an associative array name, the results differ as +described below. +If \fIlength\fP is omitted, expands to the substring of the value of +\fIparameter\fP starting at the character specified by \fIoffset\fP +and extending to the end of the value. +\fIlength\fP and \fIoffset\fP are arithmetic expressions (see +.SM +.B +ARITHMETIC EVALUATION +below). +.sp 1 +If \fIoffset\fP evaluates to a number less than zero, the value +is used as an offset in characters +from the end of the value of \fIparameter\fP. +If \fIlength\fP evaluates to a number less than zero, +it is interpreted as an offset in characters +from the end of the value of \fIparameter\fP rather than +a number of characters, and the expansion is the characters between +\fIoffset\fP and that result. +Note that a negative offset must be separated from the colon by at least +one space to avoid being confused with the \fB:-\fP expansion. +.sp 1 +If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP +positional parameters beginning at \fIoffset\fP. +A negative \fIoffset\fP is taken relative to one greater than the greatest +positional parameter, so an offset of \-1 evaluates to the last positional +parameter. +It is an expansion error if \fIlength\fP evaluates to a number less than +zero. +.sp 1 +If \fIparameter\fP is an indexed array name subscripted by @ or *, +the result is the \fIlength\fP +members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}. +A negative \fIoffset\fP is taken relative to one greater than the maximum +index of the specified array. +It is an expansion error if \fIlength\fP evaluates to a number less than +zero. +.sp 1 +Substring expansion applied to an associative array produces undefined +results. +.sp 1 +Substring indexing is zero-based unless the positional parameters +are used, in which case the indexing starts at 1 by default. +If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is +prefixed to the list. +.TP +${\fB!\fP\fIprefix\fP\fB*\fP} +.PD 0 +.TP +${\fB!\fP\fIprefix\fP\fB@\fP} +.PD +\fBNames matching prefix\fP. +Expands to the names of variables whose names begin with \fIprefix\fP, +separated by the first character of the +.SM +.B IFS +special variable. +When \fI@\fP is used and the expansion appears within double quotes, each +variable name expands to a separate word. +.TP +${\fB!\fP\fIname\fP[\fI@\fP]} +.PD 0 +.TP +${\fB!\fP\fIname\fP[\fI*\fP]} +.PD +\fBList of array keys\fP. +If \fIname\fP is an array variable, expands to the list of array indices +(keys) assigned in \fIname\fP. +If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null +otherwise. +When \fI@\fP is used and the expansion appears within double quotes, each +key expands to a separate word. +.TP +${\fB#\fP\fIparameter\fP} +\fBParameter length\fP. +The length in characters of the value of \fIparameter\fP is substituted. +If +.I parameter +is +.B * +or +.BR @ , +the value substituted is the number of positional parameters. +If +.I parameter +is an array name subscripted by +.B * +or +.BR @ , +the value substituted is the number of elements in the array. +If +.I parameter +is an indexed array name subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +\fIparameter\fP, so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.TP +${\fIparameter\fP\fB#\fP\fIword\fP} +.PD 0 +.TP +${\fIparameter\fP\fB##\fP\fIword\fP} +.PD +\fBRemove matching prefix pattern\fP. +The +.I word +is expanded to produce a pattern just as in pathname +expansion, and matched against the expanded value of +.I parameter +using the rules described under +.B Pattern Matching +below. +If the pattern matches the beginning of +the value of +.IR parameter , +then the result of the expansion is the expanded value of +.I parameter +with the shortest matching pattern (the ``\fB#\fP'' case) or the +longest matching pattern (the ``\fB##\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB%\fP\fIword\fP} +.PD 0 +.TP +${\fIparameter\fP\fB%%\fP\fIword\fP} +.PD +\fBRemove matching suffix pattern\fP. +The \fIword\fP is expanded to produce a pattern just as in +pathname expansion, and matched against the expanded value of +.I parameter +using the rules described under +.B Pattern Matching +below. +If the pattern matches a trailing portion of the expanded value of +.IR parameter , +then the result of the expansion is the expanded value of +.I parameter +with the shortest matching pattern (the ``\fB%\fP'' case) or the +longest matching pattern (the ``\fB%%\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD 0 +.TP +${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.TP +${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.TP +${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD +\fBPattern substitution\fP. +The \fIpattern\fP is expanded to produce a pattern just as in +pathname expansion. +\fIParameter\fP is expanded and the longest match of \fIpattern\fP +against its value is replaced with \fIstring\fP. +\fIstring\fP undergoes tilde expansion, parameter and variable expansion, +arithmetic expansion, command and process substitution, and quote removal. +The match is performed using the rules described under +.B Pattern Matching +below. +In the first form above, only the first match is replaced. +If there are two slashes separating \fIparameter\fP and \fIpattern\fP +(the second form above), all matches of \fIpattern\fP are +replaced with \fIstring\fP. +If \fIpattern\fP is preceded by \fB#\fP (the third form above), +it must match at the beginning of the expanded value of \fIparameter\fP. +If \fIpattern\fP is preceded by \fB%\fP (the fourth form above), +it must match at the end of the expanded value of \fIparameter\fP. +If the expansion of \fIstring\fP is null, +matches of \fIpattern\fP are deleted. +If \fIstring\fP is null, +matches of \fIpattern\fP are deleted +and the \fB/\fP following \fIpattern\fP may be omitted. +.sp 1 +If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP, +any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the +matching portion of \fIpattern\fP. +.sp 1 +Quoting any part of \fIstring\fP inhibits replacement in the +expansion of the quoted portion, including replacement strings stored +in shell variables. +Backslash will escape \fB&\fP in \fIstring\fP; the backslash is removed +in order to permit a literal \fB&\fP in the replacement string. +Backslash can also be used to escape a backslash; \fB\e\e\fP results in +a literal backslash in the replacement. +Users should take care if \fIstring\fP is double-quoted to avoid +unwanted interactions between the backslash and double-quoting, since +backslash has special meaning within double quotes. +Pattern substitution performs the check for unquoted \fB&\fP after +expanding \fIstring\fP; +shell programmers should quote any occurrences of \fB&\fP +they want to be taken literally in the replacement +and ensure any instances of \fB&\fP they want to be replaced are unquoted. +.sp 1 +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +If +.I parameter +is +.B @ +or +.BR * , +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB^\fP\fIpattern\fP} +.PD 0 +.TP +${\fIparameter\fP\fB^^\fP\fIpattern\fP} +.TP +${\fIparameter\fP\fB,\fP\fIpattern\fP} +.TP +${\fIparameter\fP\fB,,\fP\fIpattern\fP} +.PD +\fBCase modification\fP. +This expansion modifies the case of alphabetic characters in \fIparameter\fP. +The \fIpattern\fP is expanded to produce a pattern just as in +pathname expansion. +Each character in the expanded value of \fIparameter\fP is tested against +\fIpattern\fP, and, if it matches the pattern, its case is converted. +The pattern should not attempt to match more than one character. +The \fB^\fP operator converts lowercase letters matching \fIpattern\fP +to uppercase; the \fB,\fP operator converts matching uppercase letters +to lowercase. +The \fB^^\fP and \fB,,\fP expansions convert each matched character in the +expanded value; the \fB^\fP and \fB,\fP expansions match and convert only +the first character in the expanded value. +If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches +every character. +If +.I parameter +is +.B @ +or +.BR * , +the case modification operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the case modification operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB@\fP\fIoperator\fP} +\fBParameter transformation\fP. +The expansion is either a transformation of the value of \fIparameter\fP +or information about \fIparameter\fP itself, depending on the value of +\fIoperator\fP. Each \fIoperator\fP is a single letter: +.sp 1 +.RS +.PD 0 +.TP +.B U +The expansion is a string that is the value of \fIparameter\fP with lowercase +alphabetic characters converted to uppercase. +.TP +.B u +The expansion is a string that is the value of \fIparameter\fP with the first +character converted to uppercase, if it is alphabetic. +.TP +.B L +The expansion is a string that is the value of \fIparameter\fP with uppercase +alphabetic characters converted to lowercase. +.TP +.B Q +The expansion is a string that is the value of \fIparameter\fP quoted in a +format that can be reused as input. +.TP +.B E +The expansion is a string that is the value of \fIparameter\fP with backslash +escape sequences expanded as with the \fB$\(aq...\(aq\fP quoting mechanism. +.TP +.B P +The expansion is a string that is the result of expanding the value of +\fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below). +.TP +.B A +The expansion is a string in the form of +an assignment statement or \fBdeclare\fP command that, if +evaluated, will recreate \fIparameter\fP with its attributes and value. +.TP +.B K +Produces a possibly-quoted version of the value of \fIparameter\fP, +except that it prints the values of +indexed and associative arrays as a sequence of quoted key-value pairs +(see \fBArrays\fP above). +.TP +.B a +The expansion is a string consisting of flag values representing +\fIparameter\fP's attributes. +.TP +.B k +Like the K transformation, but expands the keys and values of +indexed and associative arrays to separate words after word splitting. +.PD +.PP +If +.I parameter +is +.B @ +or +.BR * , +the operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.sp 1 +The result of the expansion is subject to word splitting and pathname +expansion as described below. +.RE +.SS Command Substitution +\fICommand substitution\fP allows the output of a command to replace +the command name. There are two forms: +.RS +.PP +\fB$(\fP\fIcommand\fP\|\fB)\fP +.RE +or +.RS +\fB\`\fP\fIcommand\fP\fB\`\fP +.RE +.PP +.B Bash +performs the expansion by executing \fIcommand\fP in a subshell environment +and replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. +Embedded newlines are not deleted, but they may be removed during +word splitting. +The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by +the equivalent but faster \fB$(< \fIfile\fP)\fR. +.PP +When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +.BR $ , +.BR \` , +or +.BR \e . +The first backquote not preceded by a backslash terminates the +command substitution. +When using the $(\^\fIcommand\fP\|) form, all characters between the +parentheses make up the command; none are treated specially. +.PP +Command substitutions may be nested. To nest when using the backquoted form, +escape the inner backquotes with backslashes. +.PP +If the substitution appears within double quotes, word splitting and +pathname expansion are not performed on the results. +.SS Arithmetic Expansion +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: +.RS +.PP +\fB$((\fP\fIexpression\fP\fB))\fP +.RE +.PP +The +.I expression +undergoes the same expansions +as if it were within double quotes, +but double quote characters in \fIexpression\fP are not treated specially +and are removed. +All tokens in the expression undergo parameter and variable expansion, +command substitution, and quote removal. +The result is treated as the arithmetic expression to be evaluated. +Arithmetic expansions may be nested. +.PP +The evaluation is performed according to the rules listed below under +.SM +.BR "ARITHMETIC EVALUATION" . +If +.I expression +is invalid, +.B bash +prints a message indicating failure and no substitution occurs. +.SS Process Substitution +\fIProcess substitution\fP allows a process's input or output to be +referred to using a filename. +It takes the form of +\fB<(\fP\fIlist\^\fP\fB)\fP +or +\fB>(\fP\fIlist\^\fP\fB)\fP. +The process \fIlist\fP is run asynchronously, and its input or output +appears as a filename. +This filename is +passed as an argument to the current command as the result of the +expansion. +If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to +the file will provide input for \fIlist\fP. If the +\fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an +argument should be read to obtain the output of \fIlist\fP. +Process substitution is supported on systems that support named +pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. +.PP +When available, process substitution is performed +simultaneously with parameter and variable expansion, +command substitution, +and arithmetic expansion. +.SS Word Splitting +The shell scans the results of +parameter expansion, +command substitution, +and +arithmetic expansion +that did not occur within double quotes for +.IR "word splitting" . +.PP +The shell treats each character of +.SM +.B IFS +as a delimiter, and splits the results of the other +expansions into words using these characters as field terminators. +If +.SM +.B IFS +is unset, or its +value is exactly +.BR , +the default, then +sequences of +.BR , +.BR , +and +.B +at the beginning and end of the results of the previous +expansions are ignored, and +any sequence of +.SM +.B IFS +characters not at the beginning or end serves to delimit words. +If +.SM +.B IFS +has a value other than the default, then sequences of +the whitespace characters +.BR space , +.BR tab , +and +.B newline +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of +.SM +.B IFS +(an +.SM +.B IFS +whitespace character). +Any character in +.SM +.B IFS +that is not +.SM +.B IFS +whitespace, along with any adjacent +.SM +.B IFS +whitespace characters, delimits a field. +A sequence of +.SM +.B IFS +whitespace characters is also treated as a delimiter. +If the value of +.SM +.B IFS +is null, no word splitting occurs. +.PP +Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained +and passed to commands as empty strings. +Unquoted implicit null arguments, resulting from the expansion of +parameters that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained +and passed to a command as an empty string. +When a quoted null argument appears as part of a word whose expansion is +non-null, the null argument is removed. +That is, the word +\f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and +null argument removal. +.PP +Note that if no expansion occurs, no splitting +is performed. +.SS Pathname Expansion +After word splitting, +unless the +.B \-f +option has been set, +.B bash +scans each word for the characters +.BR * , +.BR ? , +and +.BR [ . +If one of these characters appears, and is not quoted, then the word is +regarded as a +.IR pattern , +and replaced with an alphabetically sorted list of +filenames matching the pattern +(see +.SM +.B "Pattern Matching" +below). +If no matching filenames are found, +and the shell option +.B nullglob +is not enabled, the word is left unchanged. +If the +.B nullglob +option is set, and no matches are found, +the word is removed. +If the +.B failglob +shell option is set, and no matches are found, an error message +is printed and the command is not executed. +If the shell option +.B nocaseglob +is enabled, the match is performed without regard to the case +of alphabetic characters. +When a pattern is used for pathname expansion, +the character +.B ``.'' +at the start of a name or immediately following a slash +must be matched explicitly, unless the shell option +.B dotglob +is set. +In order to match the filenames +.B ``.'' +and +.BR ``..'' , +the pattern must begin with ``.'' (for example, ``.?''), +even if +.B dotglob +is set. +If the +.B globskipdots +shell option is enabled, the filenames +.B ``.'' +and +.BR ``..'' +are never matched, even if the pattern begins with a +.BR ``.'' . +When not matching pathnames, the +.B ``.'' +character is not treated specially. +When matching a pathname, the slash character must always be +matched explicitly by a slash in the pattern, but in other matching +contexts it can be matched by a special pattern character as described +below under +.SM +.BR "Pattern Matching" . +See the description of +.B shopt +below under +.SM +.B SHELL BUILTIN COMMANDS +for a description of the +.BR nocaseglob , +.BR nullglob , +.BR globskipdots , +.BR failglob , +and +.B dotglob +shell options. +.PP +The +.SM +.B GLOBIGNORE +shell variable may be used to restrict the set of file names matching a +.IR pattern . +If +.SM +.B GLOBIGNORE +is set, each matching file name that also matches one of the patterns in +.SM +.B GLOBIGNORE +is removed from the list of matches. +If the \fBnocaseglob\fP option is set, the matching against the patterns in +.SM +.B GLOBIGNORE +is performed without regard to case. +The filenames +.B ``.'' +and +.B ``..'' +are always ignored when +.SM +.B GLOBIGNORE +is set and not null. However, setting +.SM +.B GLOBIGNORE +to a non-null value has the effect of enabling the +.B dotglob +shell option, so all other filenames beginning with a +.B ``.'' +will match. +To get the old behavior of ignoring filenames beginning with a +.BR ``.'' , +make +.B ``.*'' +one of the patterns in +.SM +.BR GLOBIGNORE . +The +.B dotglob +option is disabled when +.SM +.B GLOBIGNORE +is unset. +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.PP +\fBPattern Matching\fP +.PP +Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. The NUL character may not +occur in a pattern. A backslash escapes the following character; the +escaping backslash is discarded when matching. +The special pattern characters must be quoted if +they are to be matched literally. +.PP +The special pattern characters have the following meanings: +.PP +.PD 0 +.RS +.TP +.B * +Matches any string, including the null string. +When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in +a pathname expansion context, two adjacent \fB*\fPs used as a single +pattern will match all files and zero or more directories and +subdirectories. +If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories +and subdirectories. +.TP +.B ? +Matches any single character. +.TP +.B [...] +Matches any one of the enclosed characters. A pair of characters +separated by a hyphen denotes a +\fIrange expression\fP; +any character that falls between those two characters, inclusive, +using the current locale's collating sequence and character set, +is matched. If the first character following the +.B [ +is a +.B ! +or a +.B ^ +then any character not enclosed is matched. +The sorting order of characters in range expressions, +and the characters included in the range, +are determined by +the current locale and the values of the +.SM +.B LC_COLLATE +or +.SM +.B LC_ALL +shell variables, if set. +To obtain the traditional interpretation of range expressions, where +.B [a\-d] +is equivalent to +.BR [abcd] , +set value of the +.B LC_ALL +shell variable to +.BR C , +or enable the +.B globasciiranges +shell option. +A +.B \- +may be matched by including it as the first or last character +in the set. +A +.B ] +may be matched by including it as the first character +in the set. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +\fIcharacter classes\fP can be specified using the syntax +\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the +following classes defined in the POSIX standard: +.PP +.RS +.B +.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.br +A character class matches any character belonging to that class. +The \fBword\fP character class matches letters, digits, and the character _. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +an \fIequivalence class\fP can be specified using the syntax +\fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the +same collation weight (as defined by the current locale) as +the character \fIc\fP. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol +\fIsymbol\fP. +.RE +.RE +.PD +.PP +If the \fBextglob\fP shell option is enabled using the \fBshopt\fP +builtin, the shell recognizes several extended pattern matching operators. +In the following description, a \fIpattern-list\fP is a list of one +or more patterns separated by a \fB|\fP. +Composite patterns may be formed using one or more of the following +sub-patterns: +.sp 1 +.PD 0 +.RS +.TP +\fB?(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or one occurrence of the given patterns +.TP +\fB*(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or more occurrences of the given patterns +.TP +\fB+(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one or more occurrences of the given patterns +.TP +\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one of the given patterns +.TP +\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches anything except one of the given patterns +.RE +.PD +.PP +The\fBextglob\fP option changes the behavior of the parser, since the +parentheses are normally treated as operators with syntactic meaning. +To ensure that extended matching patterns are parsed correctly, make sure +that \fBextglob\fP is enabled before parsing constructs containing the +patterns, including shell functions and command substitutions. +.PP +When matching filenames, the \fBdotglob\fP shell option determines +the set of filenames that are tested: +when \fBdotglob\fP is enabled, the set of filenames includes all files +beginning with ``.'', but ``.'' and ``..'' must be matched by a +pattern or sub-pattern that begins with a dot; +when it is disabled, the set does not +include any filenames beginning with ``.'' unless the pattern +or sub-pattern begins with a ``.''. +As above, ``.'' only has a special meaning when matching filenames. +.PP +Complicated extended pattern matching against long strings is slow, +especially when the patterns contain alternations and the strings +contain multiple matches. +Using separate matches against shorter strings, or using arrays of +strings instead of a single long string, may be faster. +.SS Quote Removal +After the preceding expansions, all unquoted occurrences of the +characters +.BR \e , +.BR \(aq , +and \^\f3"\fP\^ that did not result from one of the above +expansions are removed. +.SH REDIRECTION +Before a command is executed, its input and output +may be +.I redirected +using a special notation interpreted by the shell. +\fIRedirection\fP allows commands' file handles to be +duplicated, opened, closed, +made to refer to different files, +and can change the files the command reads from and writes to. +Redirection may also be used to modify file handles in the +current shell execution environment. +The following redirection +operators may precede or appear anywhere within a +.I simple command +or may follow a +.IR command . +Redirections are processed in the order they appear, from +left to right. +.PP +Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form {\fIvarname\fP}. +In this case, for each redirection operator except +>&- and <&-, the shell will allocate a file descriptor greater +than or equal to 10 and assign it to \fIvarname\fP. +If >&- or <&- is preceded +by {\fIvarname\fP}, the value of \fIvarname\fP defines the file +descriptor to close. +If {\fIvarname\fP} is supplied, the redirection persists beyond +the scope of the command, allowing the shell programmer to manage +the file descriptor's lifetime manually. +The \fBvarredir_close\fP shell option manages this behavior. +.PP +In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +.BR < , +the redirection refers to the standard input (file descriptor +0). If the first character of the redirection operator is +.BR > , +the redirection refers to the standard output (file descriptor +1). +.PP +The word following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, quote removal, +pathname expansion, and word splitting. +If it expands to more than one word, +.B bash +reports an error. +.PP +Note that the order of redirections is significant. For example, +the command +.RS +.PP +ls \fB>\fP dirlist 2\fB>&\fP1 +.RE +.PP +directs both standard output and standard error to the file +.IR dirlist , +while the command +.RS +.PP +ls 2\fB>&\fP1 \fB>\fP dirlist +.RE +.PP +directs only the standard output to file +.IR dirlist , +because the standard error was duplicated from the standard output +before the standard output was redirected to +.IR dirlist . +.PP +\fBBash\fP handles several filenames specially when they are used in +redirections, as described in the following table. +If the operating system on which \fBbash\fP is running provides these +special files, bash will use them; otherwise it will emulate them +internally with the behavior described below. +.RS +.PP +.PD 0 +.TP +.B /dev/fd/\fIfd\fP +If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated. +.TP +.B /dev/stdin +File descriptor 0 is duplicated. +.TP +.B /dev/stdout +File descriptor 1 is duplicated. +.TP +.B /dev/stderr +File descriptor 2 is duplicated. +.TP +.B /dev/tcp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +the corresponding TCP socket. +.TP +.B /dev/udp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +the corresponding UDP socket. +.PD +.RE +.PP +A failure to open or create a file causes the redirection to fail. +.PP +Redirections using file descriptors greater than 9 should be used with +care, as they may conflict with file descriptors the shell uses +internally. +.SS Redirecting Input +Redirection of input causes the file whose name results from +the expansion of +.I word +to be opened for reading on file descriptor +.IR n , +or the standard input (file descriptor 0) if +.I n +is not specified. +.PP +The general format for redirecting input is: +.RS +.PP +[\fIn\fP]\fB<\fP\fIword\fP +.RE +.SS Redirecting Output +Redirection of output causes the file whose name results from +the expansion of +.I word +to be opened for writing on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. +.PP +The general format for redirecting output is: +.RS +.PP +[\fIn\fP]\fB>\fP\fIword\fP +.RE +.PP +If the redirection operator is +.BR > , +and the +.B noclobber +option to the +.B set +builtin has been enabled, the redirection will fail if the file +whose name results from the expansion of \fIword\fP exists and is +a regular file. +If the redirection operator is +.BR >| , +or the redirection operator is +.B > +and the +.B noclobber +option to the +.B set +builtin command is not enabled, the redirection is attempted even +if the file named by \fIword\fP exists. +.SS Appending Redirected Output +Redirection of output in this fashion +causes the file whose name results from +the expansion of +.I word +to be opened for appending on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created. +.PP +The general format for appending output is: +.RS +.PP +[\fIn\fP]\fB>>\fP\fIword\fP +.RE +.SS Redirecting Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of +.IR word . +.PP +There are two formats for redirecting standard output and +standard error: +.RS +.PP +\fB&>\fP\fIword\fP +.RE +and +.RS +\fB>&\fP\fIword\fP +.RE +.PP +Of the two forms, the first is preferred. +This is semantically equivalent to +.RS +.PP +\fB>\fP\fIword\fP 2\fB>&\fP1 +.RE +.PP +When using the second form, \fIword\fP may not expand to a number or +\fB\-\fP. If it does, other redirection operators apply +(see \fBDuplicating File Descriptors\fP below) for compatibility +reasons. +.SS Appending Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be appended to the file whose name is the +expansion of +.IR word . +.PP +The format for appending standard output and standard error is: +.RS +.PP +\fB&>>\fP\fIword\fP +.RE +.PP +This is semantically equivalent to +.RS +.PP +\fB>>\fP\fIword\fP 2\fB>&\fP1 +.RE +.PP +(see \fBDuplicating File Descriptors\fP below). +.SS Here Documents +This type of redirection instructs the shell to read input from the +current source until a line containing only +.I delimiter +(with no trailing blanks) +is seen. All of +the lines read up to that point are then used as the standard +input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command. +.PP +The format of here-documents is: +.RS +.PP +.nf +[\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP + \fIhere-document\fP +\fIdelimiter\fP +.fi +.RE +.PP +No parameter and variable expansion, command substitution, +arithmetic expansion, or pathname expansion is performed on +.IR word . +If any part of +.I word +is quoted, the +.I delimiter +is the result of quote removal on +.IR word , +and the lines in the here-document are not expanded. +If \fIword\fP is unquoted, +all lines of the here-document are subjected to +parameter expansion, command substitution, and arithmetic expansion, +the character sequence +.B \e +is ignored, and +.B \e +must be used to quote the characters +.BR \e , +.BR $ , +and +.BR \` . +.PP +If the redirection operator is +.BR <<\- , +then all leading tab characters are stripped from input lines and the +line containing +.IR delimiter . +This allows +here-documents within shell scripts to be indented in a +natural fashion. +.SS "Here Strings" +A variant of here documents, the format is: +.RS +.PP +.nf +[\fIn\fP]\fB<<<\fP\fIword\fP +.fi +.RE +.PP +The \fIword\fP undergoes +tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal. +Pathname expansion and word splitting are not performed. +The result is supplied as a single string, with a newline appended, +to the command on its +standard input (or file descriptor \fIn\fP if \fIn\fP is specified). +.SS "Duplicating File Descriptors" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIword\fP +.RE +.PP +is used to duplicate input file descriptors. +If +.I word +expands to one or more digits, the file descriptor denoted by +.I n +is made to be a copy of that file descriptor. +If the digits in +.I word +do not specify a file descriptor open for input, a redirection error occurs. +If +.I word +evaluates to +.BR \- , +file descriptor +.I n +is closed. If +.I n +is not specified, the standard input (file descriptor 0) is used. +.PP +The operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIword\fP +.RE +.PP +is used similarly to duplicate output file descriptors. If +.I n +is not specified, the standard output (file descriptor 1) is used. +If the digits in +.I word +do not specify a file descriptor open for output, a redirection error occurs. +If +.I word +evaluates to +.BR \- , +file descriptor +.I n +is closed. +As a special case, if \fIn\fP is omitted, and \fIword\fP does not +expand to one or more digits or \fB\-\fP, the standard output and standard +error are redirected as described previously. +.SS "Moving File Descriptors" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard input (file descriptor 0) if \fIn\fP is not specified. +\fIdigit\fP is closed after being duplicated to \fIn\fP. +.PP +Similarly, the redirection operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard output (file descriptor 1) if \fIn\fP is not specified. +.SS "Opening File Descriptors for Reading and Writing" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<>\fP\fIword\fP +.RE +.PP +causes the file whose name is the expansion of +.I word +to be opened for both reading and writing on file descriptor +.IR n , +or on file descriptor 0 if +.I n +is not specified. If the file does not exist, it is created. +.SH ALIASES +\fIAliases\fP allow a string to be substituted for a word when it is used +as the first word of a simple command. +The shell maintains a list of aliases that may be set and unset with the +.B alias +and +.B unalias +builtin commands (see +.SM +.B SHELL BUILTIN COMMANDS +below). +The first word of each simple command, if unquoted, +is checked to see if it has an +alias. If so, that word is replaced by the text of the alias. +The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and +any of the shell \fImetacharacters\fP or quoting characters +listed above may not appear in an alias name. +The replacement text may contain any valid shell input, +including shell metacharacters. +The first word of the replacement text is tested +for aliases, but a word that is identical to an alias being expanded +is not expanded a second time. +This means that one may alias +.B ls +to +.BR "ls \-F" , +for instance, and +.B bash +does not try to recursively expand the replacement text. +If the last character of the alias value is a +.IR blank , +then the next command +word following the alias is also checked for alias expansion. +.PP +Aliases are created and listed with the +.B alias +command, and removed with the +.B unalias +command. +.PP +There is no mechanism for using arguments in the replacement text. +If arguments are needed, use a shell function (see +.SM +.B FUNCTIONS +below). +.PP +Aliases are not expanded when the shell is not interactive, unless +the +.B expand_aliases +shell option is set using +.B shopt +(see the description of +.B shopt +under +.SM +\fBSHELL BUILTIN COMMANDS\fP +below). +.PP +The rules concerning the definition and use of aliases are +somewhat confusing. +.B Bash +always reads at least one complete line of input, +and all lines that make up a compound command, +before executing any of the commands on that line or the compound command. +Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when a function definition is read, +not when the function is executed, because a function definition +is itself a command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use +.B alias +in compound commands. +.PP +For almost every purpose, aliases are superseded by +shell functions. +.SH FUNCTIONS +A shell function, defined as described above under +.SM +.BR "SHELL GRAMMAR" , +stores a series of commands for later execution. +When the name of a shell function is used as a simple command name, +the list of commands associated with that function name is executed. +Functions are executed in the context of the +current shell; no new process is created to interpret +them (contrast this with the execution of a shell script). +When a function is executed, the arguments to the +function become the positional parameters +during its execution. +The special parameter +.B # +is updated to reflect the change. Special parameter \fB0\fP +is unchanged. +The first element of the +.SM +.B FUNCNAME +variable is set to the name of the function while the function +is executing. +.PP +All other aspects of the shell execution +environment are identical between a function and its caller +with these exceptions: the +.SM +.B DEBUG +and +.B RETURN +traps (see the description of the +.B trap +builtin under +.SM +.B SHELL BUILTIN COMMANDS +below) are not inherited unless the function has been given the +\fBtrace\fP attribute (see the description of the +.SM +.B declare +builtin below) or the +\fB\-o functrace\fP shell option has been enabled with +the \fBset\fP builtin +(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps), +and the +.SM +.B ERR +trap is not inherited unless the \fB\-o errtrace\fP shell option has +been enabled. +.PP +Variables local to the function may be declared with the +.B local +builtin command (\fIlocal variables\fP). +Ordinarily, variables and their values +are shared between the function and its caller. +If a variable is declared \fBlocal\fP, the variable's visible scope +is restricted to that function and its children (including the functions +it calls). +.PP +In the following description, the \fIcurrent scope\fP is a currently- +executing function. +Previous scopes consist of that function's caller and so on, +back to the "global" scope, where the shell is not executing +any shell function. +Consequently, a local variable at the current scope is a variable +declared using the \fBlocal\fP or \fBdeclare\fP builtins in the +function that is currently executing. +.PP +Local variables "shadow" variables with the same name declared at +previous scopes. +For instance, a local variable declared in a function +hides a global variable of the same name: references and assignments +refer to the local variable, leaving the global variable unmodified. +When the function returns, the global variable is once again visible. +.PP +The shell uses \fIdynamic scoping\fP to control a variable's visibility +within functions. +With dynamic scoping, visible variables and their values +are a result of the sequence of function calls that caused execution +to reach the current function. +The value of a variable that a function sees depends +on its value within its caller, if any, whether that caller is +the "global" scope or another shell function. +This is also the value that a local variable +declaration "shadows", and the value that is restored when the function +returns. +.PP +For example, if a variable \fIvar\fP is declared as local in function +\fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP, +references to \fIvar\fP made from within \fIfunc2\fP will resolve to the +local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable +named \fIvar\fP. +.PP +The \fBunset\fP builtin also acts using the same dynamic scope: if a +variable is local to the current scope, \fBunset\fP will unset it; +otherwise the unset will refer to the variable found in any calling scope +as described above. +If a variable at the current local scope is unset, it will remain so +(appearing as unset) +until it is reset in that scope or until the function returns. +Once the function returns, any instance of the variable at a previous +scope will become visible. +If the unset acts on a variable at a previous scope, any instance of a +variable with that name that had been shadowed will become visible +(see below how the \fBlocalvar_unset\fP shell option changes this behavior). +.PP +The \fBFUNCNEST\fP variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. +.PP +If the builtin command +.B return +is executed in a function, the function completes and +execution resumes with the next command after the function +call. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes. +When a function completes, the values of the +positional parameters and the special parameter +.B # +are restored to the values they had prior to the function's +execution. +.PP +Function names and definitions may be listed with the +.B \-f +option to the +.B declare +or +.B typeset +builtin commands. The +.B \-F +option to +.B declare +or +.B typeset +will list the function names only +(and optionally the source file and line number, if the \fBextdebug\fP +shell option is enabled). +Functions may be exported so that child shell processes +(those created when executing a separate shell invocation) +automatically have them defined with the +.B \-f +option to the +.B export +builtin. +A function definition may be deleted using the \fB\-f\fP option to +the +.B unset +builtin. +.PP +Functions may be recursive. +The \fBFUNCNEST\fP variable may be used to limit the depth of the +function call stack and restrict the number of function invocations. +By default, no limit is imposed on the number of recursive calls. +.SH "ARITHMETIC EVALUATION" +The shell allows arithmetic expressions to be evaluated, under +certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin +commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP). +Evaluation is done in fixed-width integers with no check for overflow, +though division by 0 is trapped and flagged as an error. +The operators and their precedence, associativity, and values +are the same as in the C language. +The following list of operators is grouped into levels of +equal-precedence operators. +The levels are listed in order of decreasing precedence. +.PP +.PD 0 +.TP +.B \fIid\fP++ \fIid\fP\-\- +variable post-increment and post-decrement +.TP +.B \- + +unary minus and plus +.TP +.B ++\fIid\fP \-\-\fIid\fP +variable pre-increment and pre-decrement +.TP +.B ! ~ +logical and bitwise negation +.TP +.B ** +exponentiation +.TP +.B * / % +multiplication, division, remainder +.TP +.B + \- +addition, subtraction +.TP +.B << >> +left and right bitwise shifts +.TP +.B <= >= < > +comparison +.TP +.B == != +equality and inequality +.TP +.B & +bitwise AND +.TP +.B ^ +bitwise exclusive OR +.TP +.B | +bitwise OR +.TP +.B && +logical AND +.TP +.B || +logical OR +.TP +.B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP +conditional operator +.TP +.B = *= /= %= += \-= <<= >>= &= ^= |= +assignment +.TP +.B \fIexpr1\fP , \fIexpr2\fP +comma +.PD +.PP +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +Within an expression, shell variables may also be referenced by name +without using the parameter expansion syntax. +A shell variable that is null or unset evaluates to 0 when referenced +by name without using the parameter expansion syntax. +The value of a variable is evaluated as an arithmetic expression +when it is referenced, or when a variable which has been given the +\fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value. +A null value evaluates to 0. +A shell variable need not have its \fIinteger\fP attribute +turned on to be used in an expression. +.PP +Integer constants follow the C language definition, without suffixes or +character constants. +Constants with a leading 0 are interpreted as octal numbers. +A leading 0x or 0X denotes hexadecimal. +Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP +is a decimal number between 2 and 64 representing the arithmetic +base, and \fIn\fP is a number in that base. +If \fIbase#\fP is omitted, then base 10 is used. +When specifying \fIn\fP, +if a non-digit is required, +the digits greater than 9 are represented by the lowercase letters, +the uppercase letters, @, and _, in that order. +If \fIbase\fP is less than or equal to 36, lowercase and uppercase +letters may be used interchangeably to represent numbers between 10 +and 35. +.PP +Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. +.SH "CONDITIONAL EXPRESSIONS" +Conditional expressions are used by the \fB[[\fP compound command and +the \fBtest\fP and \fB[\fP builtin commands to test file attributes +and perform string and arithmetic comparisons. +The \fBtest\fP and \fB[\fP commands determine their behavior based on +the number of arguments; see the descriptions of those commands for any +other command-specific actions. +.PP +Expressions are formed from the following unary or binary primaries. +\fBBash\fP handles several filenames specially when they are used in +expressions. +If the operating system on which \fBbash\fP is running provides these +special files, bash will use them; otherwise it will emulate them +internally with this behavior: +If any \fIfile\fP argument to one of the primaries is of the form +\fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked. +If the \fIfile\fP argument to one of the primaries is one of +\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file +descriptor 0, 1, or 2, respectively, is checked. +.PP +Unless otherwise specified, primaries that operate on files follow symbolic +links and operate on the target of the link, rather than the link itself. +.if t .sp 0.5 +.if n .sp 1 +When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort +lexicographically using the current locale. +The \fBtest\fP command sorts using ASCII ordering. +.sp 1 +.PD 0 +.TP +.B \-a \fIfile\fP +True if \fIfile\fP exists. +.TP +.B \-b \fIfile\fP +True if \fIfile\fP exists and is a block special file. +.TP +.B \-c \fIfile\fP +True if \fIfile\fP exists and is a character special file. +.TP +.B \-d \fIfile\fP +True if \fIfile\fP exists and is a directory. +.TP +.B \-e \fIfile\fP +True if \fIfile\fP exists. +.TP +.B \-f \fIfile\fP +True if \fIfile\fP exists and is a regular file. +.TP +.B \-g \fIfile\fP +True if \fIfile\fP exists and is set-group-id. +.TP +.B \-h \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-k \fIfile\fP +True if \fIfile\fP exists and its ``sticky'' bit is set. +.TP +.B \-p \fIfile\fP +True if \fIfile\fP exists and is a named pipe (FIFO). +.TP +.B \-r \fIfile\fP +True if \fIfile\fP exists and is readable. +.TP +.B \-s \fIfile\fP +True if \fIfile\fP exists and has a size greater than zero. +.TP +.B \-t \fIfd\fP +True if file descriptor +.I fd +is open and refers to a terminal. +.TP +.B \-u \fIfile\fP +True if \fIfile\fP exists and its set-user-id bit is set. +.TP +.B \-w \fIfile\fP +True if \fIfile\fP exists and is writable. +.TP +.B \-x \fIfile\fP +True if \fIfile\fP exists and is executable. +.TP +.B \-G \fIfile\fP +True if \fIfile\fP exists and is owned by the effective group id. +.TP +.B \-L \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-N \fIfile\fP +True if \fIfile\fP exists and has been modified since it was last read. +.TP +.B \-O \fIfile\fP +True if \fIfile\fP exists and is owned by the effective user id. +.TP +.B \-S \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP +\fIfile1\fP \fB\-ef\fP \fIfile2\fP +True if \fIfile1\fP and \fIfile2\fP refer to the same device and +inode numbers. +.TP +\fIfile1\fP \-\fBnt\fP \fIfile2\fP +True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP, +or if \fIfile1\fP exists and \fPfile2\fP does not. +.TP +\fIfile1\fP \-\fBot\fP \fIfile2\fP +True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists +and \fIfile1\fP does not. +.TP +.B \-o \fIoptname\fP +True if the shell option +.I optname +is enabled. +See the list of options under the description of the +.B \-o +option to the +.B set +builtin below. +.TP +.B \-v \fIvarname\fP +True if the shell variable +.I varname +is set (has been assigned a value). +.TP +.B \-R \fIvarname\fP +True if the shell variable +.I varname +is set and is a name reference. +.TP +.B \-z \fIstring\fP +True if the length of \fIstring\fP is zero. +.TP +\fIstring\fP +.PD 0 +.TP +.B \-n \fIstring\fP +.PD +True if the length of +.I string +is non-zero. +.TP +\fIstring1\fP \fB==\fP \fIstring2\fP +.PD 0 +.TP +\fIstring1\fP \fB=\fP \fIstring2\fP +.PD +True if the strings are equal. \fB=\fP should be used +with the \fBtest\fP command for POSIX conformance. +When used with the \fB[[\fP command, this performs pattern matching as +described above (\fBCompound Commands\fP). +.TP +\fIstring1\fP \fB!=\fP \fIstring2\fP +True if the strings are not equal. +.TP +\fIstring1\fP \fB<\fP \fIstring2\fP +True if \fIstring1\fP sorts before \fIstring2\fP lexicographically. +.TP +\fIstring1\fP \fB>\fP \fIstring2\fP +True if \fIstring1\fP sorts after \fIstring2\fP lexicographically. +.TP +.I \fIarg1\fP \fBOP\fP \fIarg2\fP +.SM +.B OP +is one of +.BR \-eq , +.BR \-ne , +.BR \-lt , +.BR \-le , +.BR \-gt , +or +.BR \-ge . +These arithmetic binary operators return true if \fIarg1\fP +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to \fIarg2\fP, respectively. +.I Arg1 +and +.I arg2 +may be positive or negative integers. +When used with the \fB[[\fP command, +.I Arg1 +and +.I Arg2 +are evaluated as arithmetic expressions (see +.SM +.B "ARITHMETIC EVALUATION" +above). +.PD +.SH "SIMPLE COMMAND EXPANSION" +When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right, in +the following order. +.IP 1. +The words that the parser has marked as variable assignments (those +preceding the command name) and redirections are saved for later +processing. +.IP 2. +The words that are not variable assignments or redirections are +expanded. If any words remain after expansion, the first word +is taken to be the name of the command and the remaining words are +the arguments. +.IP 3. +Redirections are performed as described above under +.SM +.BR REDIRECTION . +.IP 4. +The text after the \fB=\fP in each variable assignment undergoes tilde +expansion, parameter expansion, command substitution, arithmetic expansion, +and quote removal before being assigned to the variable. +.PP +If no command name results, the variable assignments affect the current +shell environment. +In the case of such a command (one that consists only of assignment +statements and redirections), assignment statements are performed before +redirections. +Otherwise, the variables are added to the environment +of the executed command and do not affect the current shell environment. +If any of the assignments attempts to assign a value to a readonly variable, +an error occurs, and the command exits with a non-zero status. +.PP +If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. +.PP +If there is a command name left after expansion, execution proceeds as +described below. Otherwise, the command exits. If one of the expansions +contained a command substitution, the exit status of the command is +the exit status of the last command substitution performed. If there +were no command substitutions, the command exits with a status of zero. +.SH "COMMAND EXECUTION" +After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. +.PP +If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described above in +.SM +.BR FUNCTIONS . +If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. +.PP +If the name is neither a shell function nor a builtin, +and contains no slashes, +.B bash +searches each element of the +.SM +.B PATH +for a directory containing an executable file by that name. +.B Bash +uses a hash table to remember the full pathnames of executable +files (see +.B hash +under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +A full search of the directories in +.SM +.B PATH +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell searches for a defined shell +function named \fBcommand_not_found_handle\fP. +If that function exists, it is invoked in a separate execution environment +with the original command and +the original command's arguments as its arguments, and the function's +exit status becomes the exit status of that subshell. +If that function is not defined, the shell prints an error +message and returns an exit status of 127. +.PP +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program in a +separate execution environment. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments given, if any. +.PP +If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be +a \fIshell script\fP, a file +containing shell commands, and the shell creates a +new instance of itself +to execute it. +This subshell reinitializes itself, so +that the effect is as if a new shell had been invoked +to handle the script, with the exception that the locations of +commands remembered by the parent (see +.B hash +below under +.SM +\fBSHELL BUILTIN COMMANDS\fP) +are retained by the child. +.PP +If the program is a file beginning with +.BR #! , +the remainder of the first line specifies an interpreter +for the program. The shell executes the +specified interpreter on operating systems that do not +handle this executable format themselves. The arguments to the +interpreter consist of a single optional argument following the +interpreter name on the first line of the program, followed +by the name of the program, followed by the command +arguments, if any. +.SH COMMAND EXECUTION ENVIRONMENT +The shell has an \fIexecution environment\fP, which consists of the +following: +.IP \(bu +open files inherited by the shell at invocation, as modified by +redirections supplied to the \fBexec\fP builtin +.IP \(bu +the current working directory as set by \fBcd\fP, \fBpushd\fP, or +\fBpopd\fP, or inherited by the shell at invocation +.IP \(bu +the file creation mode mask as set by \fBumask\fP or inherited from +the shell's parent +.IP \(bu +current traps set by \fBtrap\fP +.IP \(bu +shell parameters that are set by variable assignment or with \fBset\fP +or inherited from the shell's parent in the environment +.IP \(bu +shell functions defined during execution or inherited from the shell's +parent in the environment +.IP \(bu +options enabled at invocation (either by default or with command-line +arguments) or by \fBset\fP +.IP \(bu +options enabled by \fBshopt\fP +.IP \(bu +shell aliases defined with \fBalias\fP +.IP \(bu +various process IDs, including those of background jobs, the value +of \fB$$\fP, and the value of +.SM +.B PPID +.PP +When a simple command other than a builtin or shell function +is to be executed, it +is invoked in a separate execution environment that consists of +the following. +Unless otherwise noted, the values are inherited from the shell. +.if n .sp 1 +.IP \(bu +the shell's open files, plus any modifications and additions specified +by redirections to the command +.IP \(bu +the current working directory +.IP \(bu +the file creation mode mask +.IP \(bu +shell variables and functions marked for export, along with variables +exported for the command, passed in the environment +.IP \(bu +traps caught by the shell are reset to the values inherited from the +shell's parent, and traps ignored by the shell are ignored +.PP +A command invoked in this separate environment cannot affect the +shell's execution environment. +.PP +A \fIsubshell\fP is a copy of the shell process. +.PP +Command substitution, commands grouped with parentheses, +and asynchronous commands are invoked in a +subshell environment that is a duplicate of the shell environment, +except that traps caught by the shell are reset to the values +that the shell inherited from its parent at invocation. Builtin +commands that are invoked as part of a pipeline are also executed in a +subshell environment. Changes made to the subshell environment +cannot affect the shell's execution environment. +.PP +Subshells spawned to execute command substitutions inherit the value of +the \fB\-e\fP option from the parent shell. When not in \fIposix mode\fP, +\fBbash\fP clears the \fB\-e\fP option in such subshells. +.PP +If a command is followed by a \fB&\fP and job control is not active, the +default standard input for the command is the empty file \fI/dev/null\fP. +Otherwise, the invoked command inherits the file descriptors of the calling +shell as modified by redirections. +.SH ENVIRONMENT +When a program is invoked it is given an array of strings +called the +.IR environment . +This is a list of +\fIname\fP\-\fIvalue\fP pairs, of the form +.IR "name\fR=\fPvalue" . +.PP +The shell provides several ways to manipulate the environment. +On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for +.I export +to child processes. Executed commands inherit the environment. +The +.B export +and +.B declare \-x +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell's +initial environment, whose values may be modified in the shell, +less any pairs removed by the +.B unset +command, plus any additions via the +.B export +and +.B declare \-x +commands. +.PP +The environment for any +.I simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described above in +.SM +.BR PARAMETERS . +These assignment statements affect only the environment seen +by that command. +.PP +If the +.B \-k +option is set (see the +.B set +builtin command below), then +.I all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. +.PP +When +.B bash +invokes an external command, the variable +.B _ +is set to the full filename of the command and passed to that +command in its environment. +.SH "EXIT STATUS" +The exit status of an executed command is the value returned by the +\fIwaitpid\fP system call or equivalent function. Exit statuses +fall between 0 and 255, though, as explained below, the shell may +use values above 125 specially. Exit statuses from shell builtins and +compound commands are also limited to this range. Under certain +circumstances, the shell will use special values to indicate specific +failure modes. +.PP +For the shell's purposes, a command which exits with a +zero exit status has succeeded. An exit status of zero +indicates success. A non-zero exit status indicates failure. +When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses +the value of 128+\fIN\fP as the exit status. +.PP +If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. +.PP +If a command fails because of an error during expansion or redirection, +the exit status is greater than zero. +.PP +Shell builtin commands return a status of 0 (\fItrue\fP) if +successful, and non-zero (\fIfalse\fP) if an error occurs +while they execute. +All builtins return an exit status of 2 to indicate incorrect usage, +generally invalid options or missing arguments. +.PP +The exit status of the last command is available in the special +parameter $?. +.PP +\fBBash\fP itself returns the exit status of the last command +executed, unless a syntax error occurs, in which case it exits +with a non-zero value. See also the \fBexit\fP builtin +command below. +.SH SIGNALS +When \fBbash\fP is interactive, in the absence of any traps, it ignores +.SM +.B SIGTERM +(so that \fBkill 0\fP does not kill an interactive shell), +and +.SM +.B SIGINT +is caught and handled (so that the \fBwait\fP builtin is interruptible). +In all cases, \fBbash\fP ignores +.SM +.BR SIGQUIT . +If job control is in effect, +.B bash +ignores +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +Non-builtin commands run by \fBbash\fP have signal handlers +set to the values inherited by the shell from its parent. +When job control is not in effect, asynchronous commands +ignore +.SM +.B SIGINT +and +.SM +.B SIGQUIT +in addition to these inherited handlers. +Commands run as a result of command substitution ignore the +keyboard-generated job control signals +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +The shell exits by default upon receipt of a +.SM +.BR SIGHUP . +Before exiting, an interactive shell resends the +.SM +.B SIGHUP +to all jobs, running or stopped. +Stopped jobs are sent +.SM +.B SIGCONT +to ensure that they receive the +.SM +.BR SIGHUP . +To prevent the shell from +sending the signal to a particular job, it should be removed from the +jobs table with the +.B disown +builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below) or marked +to not receive +.SM +.B SIGHUP +using +.BR "disown \-h" . +.PP +If the +.B huponexit +shell option has been set with +.BR shopt , +.B bash +sends a +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.PP +If \fBbash\fP is waiting for a command to complete and receives a signal +for which a trap has been set, the trap will not be executed until +the command completes. +When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP +builtin, the reception of a signal for which a trap has been set will +cause the \fBwait\fP builtin to return immediately with an exit status +greater than 128, immediately after which the trap is executed. +.PP +When job control is not enabled, and \fBbash\fP is waiting for a foreground +command to complete, the shell receives keyboard-generated signals +such as +.SM +.B SIGINT +(usually generated by \fB^C\fP) that users commonly intend to send +to that command. +This happens because the shell and the command are in the +same process group as the terminal, and \fB^C\fP sends +.SM +.B SIGINT +to all processes in that process group. +.PP +When \fBbash\fP is running without job control enabled and receives +.SM +.B SIGINT +while waiting for a foreground command, it waits until that foreground +command terminates and then decides what to do about the +.SM +.BR SIGINT : +.IP 1. +If the command terminates due to the +.SM +.BR SIGINT , +\fBbash\fP concludes +that the user meant to end the entire script, and acts on the +.SM +.B SIGINT +(e.g., by running a +.SM +.B SIGINT +trap or exiting itself); +.IP 2. +If the command does not terminate due to +.SM +.BR SIGINT , +the program handled the +.SM +.B SIGINT +itself and did not treat it as a fatal signal. +In that case, \fBbash\fP does not treat +.SM +.B SIGINT +as a fatal signal, either, instead assuming that the +.SM +.B SIGINT +was used as part of the program's normal operation +(e.g., emacs uses it to abort editing +commands) or deliberately discarded. +However, \fBbash\fP will run any +trap set on +.SM +.BR SIGINT , +as it does with any other trapped signal it +receives while it is waiting for the foreground command to +complete, for compatibility. +.SH "JOB CONTROL" +.I Job control +refers to the ability to selectively stop (\fIsuspend\fP) +the execution of processes and continue (\fIresume\fP) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the operating system kernel's terminal driver and +.BR bash . +.PP +The shell associates a +.I job +with each pipeline. It keeps a table of currently executing +jobs, which may be listed with the +.B jobs +command. When +.B bash +starts a job asynchronously (in the +.IR background ), +it prints a line that looks like: +.RS +.PP +[1] 25647 +.RE +.PP +indicating that this job is job number 1 and that the process ID +of the last process in the pipeline associated with this job is 25647. +All of the processes in a single pipeline are members of the same job. +.B Bash +uses the +.I job +abstraction as the basis for job control. +.PP +To facilitate the implementation of the user interface to job +control, the operating system maintains the notion of a \fIcurrent terminal +process group ID\fP. Members of this process group (processes whose +process group ID is equal to the current terminal process group ID) +receive keyboard-generated signals such as +.SM +.BR SIGINT . +These processes are said to be in the +.IR foreground . +.I Background +processes are those whose process group ID differs from the terminal's; +such processes are immune to keyboard-generated signals. +Only foreground processes are allowed to read from or, if the +user so specifies with \f(CWstty tostop\fP, write to the +terminal. +Background processes which attempt to read from (write to when +\f(CWstty tostop\fP is in effect) the +terminal are sent a +.SM +.B SIGTTIN (SIGTTOU) +signal by the kernel's terminal driver, +which, unless caught, suspends the process. +.PP +If the operating system on which +.B bash +is running supports +job control, +.B bash +contains facilities to use it. +Typing the +.I suspend +character (typically +.BR ^Z , +Control-Z) while a process is running +causes that process to be stopped and returns control to +.BR bash . +Typing the +.I "delayed suspend" +character (typically +.BR ^Y , +Control-Y) causes the process to be stopped when it +attempts to read input from the terminal, and control to +be returned to +.BR bash . +The user may then manipulate the state of this job, using the +.B bg +command to continue it in the background, the +.B fg +command to continue it in the foreground, or +the +.B kill +command to kill it. A \fB^Z\fP takes effect immediately, +and has the additional side effect of causing pending output +and typeahead to be discarded. +.PP +There are a number of ways to refer to a job in the shell. +The character +.B % +introduces a job specification (\fIjobspec\fP). Job number +.I n +may be referred to as +.BR %n . +A job may also be referred to using a prefix of the name used to +start it, or using a substring that appears in its command line. +For example, +.B %ce +refers to a stopped +job whose command name begins with +.BR ce . +If a prefix matches more than one job, +.B bash +reports an error. Using +.BR %?ce , +on the other hand, refers to any job containing the string +.B ce +in its command line. If the substring matches more than one job, +.B bash +reports an error. The symbols +.B %% +and +.B %+ +refer to the shell's notion of the +.IR "current job" , +which is the last job stopped while it was in +the foreground or started in the background. +The +.I "previous job" +may be referenced using +.BR %\- . +If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used +to refer to that job. +In output pertaining to jobs (e.g., the output of the +.B jobs +command), the current job is always flagged with a +.BR + , +and the previous job with a +.BR \- . +A single % (with no accompanying job specification) also refers to the +current job. +.PP +Simply naming a job can be used to bring it into the +foreground: +.B %1 +is a synonym for +\fB``fg %1''\fP, +bringing job 1 from the background into the foreground. +Similarly, +.B ``%1 &'' +resumes job 1 in the background, equivalent to +\fB``bg %1''\fP. +.PP +The shell learns immediately whenever a job changes state. +Normally, +.B bash +waits until it is about to print a prompt before reporting +changes in a job's status so as to not interrupt +any other output. If the +.B \-b +option to the +.B set +builtin command +is enabled, +.B bash +reports such changes immediately. +Any trap on +.SM +.B SIGCHLD +is executed for each child that exits. +.PP +If an attempt to exit +.B bash +is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has +been enabled using the \fBshopt\fP builtin, running), the shell prints a +warning message, and, if the \fBcheckjobs\fP option is enabled, lists the +jobs and their statuses. +The +.B jobs +command may then be used to inspect their status. +If a second attempt to exit is made without an intervening command, +the shell does not print another warning, and any stopped +jobs are terminated. +.PP +When the shell is waiting for a job or process using the \fBwait\fP +builtin, and job control is enabled, \fBwait\fP will return when the +job changes state. The \fB\-f\fP option causes \fBwait\fP to wait +until the job or process terminates before returning. +.SH PROMPTING +When executing interactively, +.B bash +displays the primary prompt +.SM +.B PS1 +when it is ready to read a command, and the secondary prompt +.SM +.B PS2 +when it needs more input to complete a command. +.B Bash +displays +.SM +.B PS0 +after it reads a command but before executing it. +.B Bash +displays +.SM +.B PS4 +as described above +before tracing each command when the \fB\-x\fP option is enabled. +.B Bash +allows these prompt strings to be customized by inserting a number of +backslash-escaped special characters that are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +an ASCII bell character (07) +.TP +.B \ed +the date in "Weekday Month Date" format (e.g., "Tue May 26") +.TP +.B \eD{\fIformat\fP} +the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted +into the prompt string; an empty \fIformat\fP results in a locale-specific +time representation. The braces are required +.TP +.B \ee +an ASCII escape character (033) +.TP +.B \eh +the hostname up to the first `.' +.TP +.B \eH +the hostname +.TP +.B \ej +the number of jobs currently managed by the shell +.TP +.B \el +the basename of the shell's terminal device name +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \es +the name of the shell, the basename of +.B $0 +(the portion following the final slash) +.TP +.B \et +the current time in 24-hour HH:MM:SS format +.TP +.B \eT +the current time in 12-hour HH:MM:SS format +.TP +.B \e@ +the current time in 12-hour am/pm format +.TP +.B \eA +the current time in 24-hour HH:MM format +.TP +.B \eu +the username of the current user +.TP +.B \ev +the version of \fBbash\fP (e.g., 2.00) +.TP +.B \eV +the release of \fBbash\fP, version + patch level (e.g., 2.00.0) +.TP +.B \ew +the value of the \fBPWD\fP shell variable (\fB$PWD\fP), +with +.SM +.B $HOME +abbreviated with a tilde +(uses the value of the +.SM +.B PROMPT_DIRTRIM +variable) +.TP +.B \eW +the basename of \fB$PWD\fP, +with +.SM +.B $HOME +abbreviated with a tilde +.TP +.B \e! +the history number of this command +.TP +.B \e# +the command number of this command +.TP +.B \e$ +if the effective UID is 0, a +.BR # , +otherwise a +.B $ +.TP +.B \e\fInnn\fP +the character corresponding to the octal number \fInnn\fP +.TP +.B \e\e +a backslash +.TP +.B \e[ +begin a sequence of non-printing characters, which could be used to +embed a terminal control sequence into the prompt +.TP +.B \e] +end a sequence of non-printing characters +.PD +.RE +.PP +The command number and the history number are usually different: +the history number of a command is its position in the history +list, which may include commands restored from the history file +(see +.SM +.B HISTORY +below), while the command number is the position in the sequence +of commands executed during the current shell session. +After the string is decoded, it is expanded via +parameter expansion, command substitution, arithmetic +expansion, and quote removal, subject to the value of the +.B promptvars +shell option (see the description of the +.B shopt +command under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +This can have unwanted side effects if escaped portions of the string +appear within command substitution or contain characters special to +word expansion. +.SH READLINE +This is the library that handles reading input when using an interactive +shell, unless the +.B \-\-noediting +option is given at shell invocation. +Line editing is also used when using the \fB\-e\fP option to the +\fBread\fP builtin. +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the +.B \-o emacs +or +.B \-o vi +options to the +.B set +builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +To turn off line editing after the shell is running, use the +.B +o emacs +or +.B +o vi +options to the +.B set +builtin. +.SS "Readline Notation" +In this section, the Emacs-style notation is used to denote +keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n +means Control\-N. Similarly, +.I meta +keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards +without a +.I meta +key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key +then the +.I x +key. This makes ESC the \fImeta prefix\fP. +The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, +or press the Escape key +then hold the Control key while pressing the +.I x +key.) +.PP +Readline commands may be given numeric +.IR arguments , +which normally act as a repeat count. +Sometimes, however, it is the sign of the argument that is significant. +Passing a negative argument to a command that acts in the forward +direction (e.g., \fBkill\-line\fP) causes that command to act in a +backward direction. +Commands whose behavior with arguments deviates from this are noted +below. +.PP +When a command is described as \fIkilling\fP text, the text +deleted is saved for possible future retrieval +(\fIyanking\fP). The killed text is saved in a +\fIkill ring\fP. Consecutive kills cause the text to be +accumulated into one unit, which can be yanked all at once. +Commands which do not kill text separate the chunks of text +on the kill ring. +.SS "Readline Initialization" +Readline is customized by putting commands in an initialization +file (the \fIinputrc\fP file). +The name of this file is taken from the value of the +.SM +.B INPUTRC +variable. If that variable is unset, the default is +.IR ~/.inputrc . +If that file does not exist or cannot be read, the ultimate default is +.IR /etc/inputrc . +When a program which uses the readline library starts up, the +initialization file is read, and the key bindings and variables +are set. +There are only a few basic constructs allowed in the +readline initialization file. +Blank lines are ignored. +Lines beginning with a \fB#\fP are comments. +Lines beginning with a \fB$\fP indicate conditional constructs. +Other lines denote key bindings and variable settings. +.PP +The default key-bindings may be changed with an +.I inputrc +file. +Other programs that use this library may add their own commands +and bindings. +.PP +For example, placing +.RS +.PP +M\-Control\-u: universal\-argument +.RE +or +.RS +C\-Meta\-u: universal\-argument +.RE +into the +.I inputrc +would make M\-C\-u execute the readline command +.IR universal\-argument . +.PP +The following symbolic character names are recognized: +.IR RUBOUT , +.IR DEL , +.IR ESC , +.IR LFD , +.IR NEWLINE , +.IR RET , +.IR RETURN , +.IR SPC , +.IR SPACE , +and +.IR TAB . +.PP +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a \fImacro\fP). +.SS "Readline Key Bindings" +The syntax for controlling key bindings in the +.I inputrc +file is simple. All that is required is the name of the +command or the text of a macro and a key sequence to which +it should be bound. The name may be specified in one of two ways: +as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP +prefixes, or as a key sequence. +.PP +When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP, +.I keyname +is the name of a key spelled out in English. For example: +.sp +.RS +Control-u: universal\-argument +.br +Meta-Rubout: backward-kill-word +.br +Control-o: "> output" +.RE +.LP +In the above example, +.I C\-u +is bound to the function +.BR universal\-argument , +.I M\-DEL +is bound to the function +.BR backward\-kill\-word , +and +.I C\-o +is bound to run the macro +expressed on the right hand side (that is, to insert the text +.if t \f(CW> output\fP +.if n ``> output'' +into the line). +.PP +In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP, +.B keyseq +differs from +.B keyname +above in that strings denoting +an entire key sequence may be specified by placing the sequence +within double quotes. Some GNU Emacs style key escapes can be +used, as in the following example, but the symbolic character names +are not recognized. +.sp +.RS +"\eC\-u": universal\-argument +.br +"\eC\-x\eC\-r": re\-read\-init\-file +.br +"\ee[11~": "Function Key 1" +.RE +.PP +In this example, +.I C\-u +is again bound to the function +.BR universal\-argument . +.I "C\-x C\-r" +is bound to the function +.BR re\-read\-init\-file , +and +.I "ESC [ 1 1 ~" +is bound to insert the text +.if t \f(CWFunction Key 1\fP. +.if n ``Function Key 1''. +.PP +The full set of GNU Emacs style escape sequences is +.RS +.PD 0 +.TP +.B \eC\- +control prefix +.TP +.B \eM\- +meta prefix +.TP +.B \ee +an escape character +.TP +.B \e\e +backslash +.TP +.B \e" +literal " +.TP +.B \e\(aq +literal \(aq +.RE +.PD +.PP +In addition to the GNU Emacs style escape sequences, a second +set of backslash escapes is available: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ed +delete +.TP +.B \ef +form feed +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.RE +.PD +.PP +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including " and \(aq. +.PP +.B Bash +allows the current readline key bindings to be displayed or modified +with the +.B bind +builtin command. The editing mode may be switched during interactive +use by using the +.B \-o +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS "Readline Variables" +Readline has variables that can be used to further customize its +behavior. A variable may be set in the +.I inputrc +file with a statement of the form +.RS +.PP +\fBset\fP \fIvariable\-name\fP \fIvalue\fP +.RE +or using the \fBbind\fP builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.PP +Except where noted, readline variables can take the values +.B On +or +.B Off +(without regard to case). +Unrecognized variable names are ignored. +When a variable value is read, empty or null values, "on" (case-insensitive), +and "1" are equivalent to \fBOn\fP. All other values are equivalent to +\fBOff\fP. +The variables and their default values are: +.PP +.PD 0 +.TP +.B active\-region\-start\-color +A string variable that controls the text color and background when displaying +the text in the active region (see the description of +\fBenable\-active\-region\fP below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[01;33m"\fP. +.TP +.B active\-region\-end\-color +A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[0m"\fP. +.TP +.B bell\-style (audible) +Controls what happens when readline wants to ring the terminal bell. +If set to \fBnone\fP, readline never rings the bell. If set to +\fBvisible\fP, readline uses a visible bell if one is available. +If set to \fBaudible\fP, readline attempts to ring the terminal's bell. +.TP +.B bind\-tty\-special\-chars (On) +If set to \fBOn\fP, readline attempts to bind the control characters +treated specially by the kernel's terminal driver to their readline +equivalents. +.TP +.B blink\-matching\-paren (Off) +If set to \fBOn\fP, readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. +.TP +.B colored\-completion\-prefix (Off) +If set to \fBOn\fP, when listing completions, readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +If there is a color definition in \fB$LS_COLORS\fP for the custom suffix +"readline-colored-completion-prefix", readline uses this color for +the common prefix instead of its default. +.TP +.B colored\-stats (Off) +If set to \fBOn\fP, readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +.TP +.B comment\-begin (``#'') +The string that is inserted when the readline +.B insert\-comment +command is executed. +This command is bound to +.B M\-# +in emacs mode and to +.B # +in vi command mode. +.TP +.B completion\-display\-width (\-1) +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is \-1. +.TP +.B completion\-ignore\-case (Off) +If set to \fBOn\fP, readline performs filename matching and completion +in a case\-insensitive fashion. +.TP +.B completion\-map\-case (Off) +If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline +treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when +performing case\-insensitive filename matching and completion. +.TP +.B completion\-prefix\-display\-length (0) +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. +.TP +.B completion\-query\-items (100) +This determines when the user is queried about viewing +the number of possible completions +generated by the \fBpossible\-completions\fP command. +It may be set to any integer value greater than or equal to zero. +If the number of possible completions is greater than +or equal to the value of this variable, +readline will ask whether or not the user wishes to view them; +otherwise they are simply listed on the terminal. +A zero value means readline should never ask; negative values are +treated as zero. +.TP +.B convert\-meta (On) +If set to \fBOn\fP, readline will convert characters with the +eighth bit set to an ASCII key sequence +by stripping the eighth bit and prefixing an +escape character (in effect, using escape as the \fImeta prefix\fP). +The default is \fIOn\fP, but readline will set it to \fIOff\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B disable\-completion (Off) +If set to \fBOn\fP, readline will inhibit word completion. Completion +characters will be inserted into the line as if they had been +mapped to \fBself-insert\fP. +.TP +.B echo\-control\-characters (On) +When set to \fBOn\fP, on operating systems that indicate they support it, +readline echoes a character corresponding to a signal generated from the +keyboard. +.TP +.B editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to \fIEmacs\fP or \fIvi\fP. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.TP +.B emacs\-mode\-string (@) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B enable\-active\-region (On) +The \fIpoint\fP is the current cursor position, and \fImark\fP refers +to a saved cursor position. +The text between the point and mark is referred to as the \fIregion\fP. +When this variable is set to \fIOn\fP, readline allows certain commands +to designate the region as \fIactive\fP. +When the region is active, readline highlights the text in the region using +the value of the \fBactive\-region\-start\-color\fP, which defaults to the +string that enables +the terminal's standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +.TP +.B enable\-bracketed\-paste (On) +When set to \fBOn\fP, readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This prevents readline from executing any editing commands bound to key +sequences appearing in the pasted text. +.TP +.B enable\-keypad (Off) +When set to \fBOn\fP, readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. +.TP +.B enable\-meta\-key (On) +When set to \fBOn\fP, readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +.TP +.B expand\-tilde (Off) +If set to \fBOn\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B history\-preserve\-point (Off) +If set to \fBOn\fP, the history code attempts to place point at the +same location on each history line retrieved with \fBprevious-history\fP +or \fBnext-history\fP. +.TP +.B history\-size (unset) +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is set to the value of the +\fBHISTSIZE\fP shell variable. +If an attempt is made to set \fIhistory\-size\fP to a non-numeric value, +the maximum number of history entries will be set to 500. +.TP +.B horizontal\-scroll\-mode (Off) +When set to \fBOn\fP, makes readline use a single line for display, +scrolling the input horizontally on a single screen line when it +becomes longer than the screen width rather than wrapping to a new line. +This setting is automatically enabled for terminals of height 1. +.TP +.B input\-meta (Off) +If set to \fBOn\fP, readline will enable eight-bit input (that is, +it will not strip the eighth bit from the characters it reads), +regardless of what the terminal claims it can support. The name +.B meta\-flag +is a synonym for this variable. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B isearch\-terminators (``C\-[C\-J'') +The string of characters that should terminate an incremental +search without subsequently executing the character as a command. +If this variable has not been given a value, the characters +\fIESC\fP and \fIC\-J\fP will terminate an incremental search. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of valid keymap names is +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. The default value is +.IR emacs ; +the value of +.B editing\-mode +also affects the default keymap. +.TP +.B keyseq\-timeout (500) +Specifies the duration \fIreadline\fP will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, \fIreadline\fP will use the shorter +but complete key sequence. +The value is specified in milliseconds, so a value of 1000 means that +\fIreadline\fP will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, \fIreadline\fP will wait until another key is pressed to +decide which key sequence to complete. +.TP +.B mark\-directories (On) +If set to \fBOn\fP, completed directory names have a slash +appended. +.TP +.B mark\-modified\-lines (Off) +If set to \fBOn\fP, history lines that have been modified are displayed +with a preceding asterisk (\fB*\fP). +.TP +.B mark\-symlinked\-directories (Off) +If set to \fBOn\fP, completed names which are symbolic links to directories +have a slash appended (subject to the value of +\fBmark\-directories\fP). +.TP +.B match\-hidden\-files (On) +This variable, when set to \fBOn\fP, causes readline to match files whose +names begin with a `.' (hidden files) when performing filename +completion. +If set to \fBOff\fP, the leading `.' must be +supplied by the user in the filename to be completed. +.TP +.B menu\-complete\-display\-prefix (Off) +If set to \fBOn\fP, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. +.TP +.B output\-meta (Off) +If set to \fBOn\fP, readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B page\-completions (On) +If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager +to display a screenful of possible completions at a time. +.TP +.B print\-completions\-horizontally (Off) +If set to \fBOn\fP, readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +.TP +.B revert\-all\-at\-newline (Off) +If set to \fBOn\fP, readline will undo all changes to history lines +before returning when \fBaccept\-line\fP is executed. By default, +history lines may be modified and retain individual undo lists across +calls to \fBreadline\fP. +.TP +.B show\-all\-if\-ambiguous (Off) +This alters the default behavior of the completion functions. If +set to +.BR On , +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +.TP +.B show\-all\-if\-unmodified (Off) +This alters the default behavior of the completion functions in +a fashion similar to \fBshow\-all\-if\-ambiguous\fP. +If set to +.BR On , +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +.TP +.B show\-mode\-in\-prompt (Off) +If set to \fBOn\fP, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP). +.TP +.B skip\-completed\-text (Off) +If set to \fBOn\fP, this alters the default completion behavior when +inserting a single match into the line. It's only active when +performing completion in the middle of a word. If enabled, readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +.TP +.B vi\-cmd\-mode\-string ((cmd)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B vi\-ins\-mode\-string ((ins)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B visible\-stats (Off) +If set to \fBOn\fP, a character denoting a file's type as reported +by \fIstat\fP(2) is appended to the filename when listing possible +completions. +.PD +.SS "Readline Conditional Constructs" +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. +.IP \fB$if\fP +The +.B $if +construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +readline. The text of the test, after any comparison operator, + extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. +.RS +.IP \fBmode\fP +The \fBmode=\fP form of the \fB$if\fP directive is used to test +whether readline is in emacs or vi mode. +This may be used in conjunction +with the \fBset keymap\fP command, for instance, to set bindings in +the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if +readline is starting out in emacs mode. +.IP \fBterm\fP +The \fBterm=\fP form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +.B = +is tested against both the full name of the terminal and the portion +of the terminal name before the first \fB\-\fP. This allows +.I sun +to match both +.I sun +and +.IR sun\-cmd , +for instance. +.IP \fBversion\fP +The \fBversion\fP test may be used to perform comparisons against +specific readline versions. +The \fBversion\fP expands to the current readline version. +The set of comparison operators includes +.BR = , +(and +.BR == ), +.BR != , +.BR <= , +.BR >= , +.BR < , +and +.BR > . +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., \fB7.1\fP). If the minor version is omitted, it +is assumed to be \fB0\fP. +The operator may be separated from the string \fBversion\fP +and from the version number argument by whitespace. +.IP \fBapplication\fP +The \fBapplication\fP construct is used to include +application-specific settings. Each program using the readline +library sets the \fIapplication name\fP, and an initialization +file can test for a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in \fBbash\fP: +.sp 1 +.RS +.nf +\fB$if\fP Bash +# Quote the current or previous word +"\eC\-xq": "\eeb\e"\eef\e"" +\fB$endif\fP +.fi +.RE +.IP \fIvariable\fP +The \fIvariable\fP construct provides simple equality tests for readline +variables and values. +The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values \fIon\fP and \fIoff\fP. +.RE +.IP \fB$endif\fP +This command, as seen in the previous example, terminates an +\fB$if\fP command. +.IP \fB$else\fP +Commands in this branch of the \fB$if\fP directive are executed if +the test fails. +.IP \fB$include\fP +This directive takes a single filename as an argument and reads commands +and bindings from that file. For example, the following directive +would read \fI/etc/inputrc\fP: +.sp 1 +.RS +.nf +\fB$include\fP \^ \fI/etc/inputrc\fP +.fi +.RE +.SS Searching +Readline provides commands for searching through the command history +(see +.SM +.B HISTORY +below) for lines containing a specified string. +There are two search modes: +.I incremental +and +.IR non-incremental . +.PP +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +The characters present in the value of the \fBisearch-terminators\fP +variable are used to terminate an incremental search. +If that variable has not been assigned a value the Escape and +Control-J characters will terminate an incremental search. +Control-G will abort an incremental search and restore the original +line. +When the search is terminated, the history entry containing the +search string becomes the current line. +.PP +To find other matching entries in the history list, type Control-S or +Control-R as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a readline command will terminate +the search and execute that command. +For instance, a \fInewline\fP will terminate the search and accept +the line, thereby executing the command from the history list. +.PP +Readline remembers the last incremental search string. If two +Control-Rs are typed without any intervening characters defining a +new search string, any remembered search string is used. +.PP +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. +.SS "Readline Command Names" +The following is a list of the names of the commands and the default +key sequences to which they are bound. +Command names without an accompanying key sequence are unbound by default. +In the following descriptions, \fIpoint\fP refers to the current cursor +position, and \fImark\fP refers to a cursor position saved by the +\fBset\-mark\fP command. +The text between the point and mark is referred to as the \fIregion\fP. +.SS Commands for Moving +.PD 0 +.TP +.B beginning\-of\-line (C\-a) +Move to the start of the current line. +.TP +.B end\-of\-line (C\-e) +Move to the end of the line. +.TP +.B forward\-char (C\-f) +Move forward a character. +.TP +.B backward\-char (C\-b) +Move back a character. +.TP +.B forward\-word (M\-f) +Move forward to the end of the next word. Words are composed of +alphanumeric characters (letters and digits). +.TP +.B backward\-word (M\-b) +Move back to the start of the current or previous word. +Words are composed of alphanumeric characters (letters and digits). +.TP +.B shell\-forward\-word +Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. +.TP +.B shell\-backward\-word +Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +.TP +.B previous\-screen\-line +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. +.TP +.B next\-screen\-line +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if the length +of the current readline line is not greater than the length of the prompt +plus the screen width. +.TP +.B clear\-display (M\-C\-l) +Clear the screen and, if possible, the terminal's scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. +.TP +.B clear\-screen (C\-l) +Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. +With an argument, refresh the current line without clearing the +screen. +.TP +.B redraw\-current\-line +Refresh the current line. +.PD +.SS Commands for Manipulating the History +.PD 0 +.TP +.B accept\-line (Newline, Return) +Accept the line regardless of where the cursor is. If this line is +non-empty, add it to the history list according to the state of the +.SM +.B HISTCONTROL +variable. If the line is a modified history +line, then restore the history line to its original state. +.TP +.B previous\-history (C\-p) +Fetch the previous command from the history list, moving back in +the list. +.TP +.B next\-history (C\-n) +Fetch the next command from the history list, moving forward in the +list. +.TP +.B beginning\-of\-history (M\-<) +Move to the first line in the history. +.TP +.B end\-of\-history (M\->) +Move to the end of the input history, i.e., the line currently being +entered. +.TP +.B operate\-and\-get\-next (C\-o) +Accept the current line for execution and fetch the next line +relative to the current line from the history for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. +.TP +.B +fetch\-history +With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. +.TP +.B reverse\-search\-history (C\-r) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. +.TP +.B forward\-search\-history (C\-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +.TP +.B non\-incremental\-reverse\-search\-history (M\-p) +Search backward through the history starting at the current line +using a non-incremental search for a string supplied by the user. +.TP +.B non\-incremental\-forward\-search\-history (M\-n) +Search forward through the history using a non-incremental search for +a string supplied by the user. +.TP +.B history\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B history\-substring\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B history\-substring\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B yank\-nth\-arg (M\-C\-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument +.IR n , +insert the \fIn\fPth word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the \fIn\fPth word from the end of the previous command. +Once the argument \fIn\fP is computed, the argument is extracted +as if the "!\fIn\fP" history expansion had been specified. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). +With a numeric argument, behave exactly like \fByank\-nth\-arg\fP. +Successive calls to \fByank\-last\-arg\fP move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last word, +as if the "!$" history expansion had been specified. +.TP +.B shell\-expand\-line (M\-C\-e) +Expand the line as the shell does. This +performs alias and history expansion as well as all of the shell +word expansions. See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B history\-expand\-line (M\-^) +Perform history expansion on the current line. +See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B magic\-space +Perform history expansion on the current line and insert a space. +See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B alias\-expand\-line +Perform alias expansion on the current line. +See +.SM +.B ALIASES +above for a description of alias expansion. +.TP +.B history\-and\-alias\-expand\-line +Perform history and alias expansion on the current line. +.TP +.B insert\-last\-argument (M\-.\^, M\-_\^) +A synonym for \fByank\-last\-arg\fP. +.TP +.B edit\-and\-execute\-command (C\-x C\-e) +Invoke an editor on the current command line, and execute the result as shell +commands. +\fBBash\fP attempts to invoke +.SM +.BR $VISUAL , +.SM +.BR $EDITOR , +and \fIemacs\fP as the editor, in that order. +.PD +.SS Commands for Changing Text +.PD 0 +.TP +.B \fIend\-of\-file\fP (usually C\-d) +The character indicating end-of-file as set, for example, by +.if t \f(CWstty\fP. +.if n ``stty''. +If this character is read when there are no characters +on the line, and point is at the beginning of the line, readline +interprets it as the end of input and returns +.SM +.BR EOF . +.TP +.B delete\-char (C\-d) +Delete the character at point. +If this function is bound to the +same character as the tty \fBEOF\fP character, as \fBC\-d\fP +commonly is, see above for the effects. +.TP +.B backward\-delete\-char (Rubout) +Delete the character behind the cursor. When given a numeric argument, +save the deleted text on the kill ring. +.TP +.B forward\-backward\-delete\-char +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character typed to the line verbatim. This is +how to insert characters like \fBC\-q\fP, for example. +.TP +.B tab\-insert (C\-v TAB) +Insert a tab character. +.TP +.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) +Insert the character typed. +.TP +.B transpose\-chars (C\-t) +Drag the character before point forward over the character at point, +moving point forward as well. +If point is at the end of the line, then this transposes +the two characters before point. +Negative arguments have no effect. +.TP +.B transpose\-words (M\-t) +Drag the word before point past the word after point, +moving point over that word as well. +If point is at the end of the line, this transposes +the last two words on the line. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move point. +.TP +.B overwrite\-mode +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +\fBemacs\fP mode; \fBvi\fP mode does overwrite differently. +Each call to \fIreadline()\fP starts in insert mode. +In overwrite mode, characters bound to \fBself\-insert\fP replace +the text at point rather than pushing the text to the right. +Characters bound to \fBbackward\-delete\-char\fP replace the character +before point with a space. By default, this command is unbound. +.PD +.SS Killing and Yanking +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from point to the end of the line. +.TP +.B backward\-kill\-line (C\-x Rubout) +Kill backward to the beginning of the line. +.TP +.B unix\-line\-discard (C\-u) +Kill backward from point to the beginning of the line. +The killed text is saved on the kill-ring. +.\" There is no real difference between this and backward-kill-line +.TP +.B kill\-whole\-line +Kill all characters on the current line, no matter where point is. +.TP +.B kill\-word (M\-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as those used by \fBforward\-word\fP. +.TP +.B backward\-kill\-word (M\-Rubout) +Kill the word behind point. +Word boundaries are the same as those used by \fBbackward\-word\fP. +.TP +.B shell\-kill\-word +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as those used by \fBshell\-forward\-word\fP. +.TP +.B shell\-backward\-kill\-word +Kill the word behind point. +Word boundaries are the same as those used by \fBshell\-backward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. +.TP +.B unix\-filename\-rubout +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text in the current region. +.TP +.B copy\-region\-as\-kill +Copy the text in the region to the kill buffer. +.TP +.B copy\-backward\-word +Copy the word before point to the kill buffer. +The word boundaries are the same as \fBbackward\-word\fP. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +The word boundaries are the same as \fBforward\-word\fP. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at point. +.TP +.B yank\-pop (M\-y) +Rotate the kill ring, and yank the new top. Only works following +.B yank +or +.BR yank\-pop . +.PD +.SS Numeric Arguments +.PD 0 +.TP +.B digit\-argument (M\-0, M\-1, ..., M\-\-) +Add this digit to the argument already accumulating, or start a new +argument. M\-\- starts a negative argument. +.TP +.B universal\-argument +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing +.B universal\-argument +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit nor minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +.PD +.SS Completing +.PD 0 +.TP +.B complete (TAB) +Attempt to perform completion on the text before point. +.B Bash +attempts completion treating the text as a variable (if the +text begins with \fB$\fP), username (if the text begins with +\fB~\fP), hostname (if the text begins with \fB@\fP), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +.TP +.B possible\-completions (M\-?) +List the possible completions of the text before point. +.TP +.B insert\-completions (M\-*) +Insert all completions of the text before point +that would have been generated by +\fBpossible\-completions\fP. +.TP +.B menu\-complete +Similar to \fBcomplete\fP, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of \fBmenu\-complete\fP steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of \fBbell\-style\fP) +and the original text is restored. +An argument of \fIn\fP moves \fIn\fP positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to \fBTAB\fP, but is unbound +by default. +.TP +.B menu\-complete\-backward +Identical to \fBmenu\-complete\fP, but moves backward through the list +of possible completions, as if \fBmenu\-complete\fP had been given a +negative argument. This command is unbound by default. +.TP +.B delete\-char\-or\-list +Deletes the character under the cursor if not at the beginning or +end of the line (like \fBdelete\-char\fP). +If at the end of the line, behaves identically to +\fBpossible\-completions\fP. +This command is unbound by default. +.TP +.B complete\-filename (M\-/) +Attempt filename completion on the text before point. +.TP +.B possible\-filename\-completions (C\-x /) +List the possible completions of the text before point, +treating it as a filename. +.TP +.B complete\-username (M\-~) +Attempt completion on the text before point, treating +it as a username. +.TP +.B possible\-username\-completions (C\-x ~) +List the possible completions of the text before point, +treating it as a username. +.TP +.B complete\-variable (M\-$) +Attempt completion on the text before point, treating +it as a shell variable. +.TP +.B possible\-variable\-completions (C\-x $) +List the possible completions of the text before point, +treating it as a shell variable. +.TP +.B complete\-hostname (M\-@) +Attempt completion on the text before point, treating +it as a hostname. +.TP +.B possible\-hostname\-completions (C\-x @) +List the possible completions of the text before point, +treating it as a hostname. +.TP +.B complete\-command (M\-!) +Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, shell builtins, and finally executable filenames, +in that order. +.TP +.B possible\-command\-completions (C\-x !) +List the possible completions of the text before point, +treating it as a command name. +.TP +.B dynamic\-complete\-history (M\-TAB) +Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +.TP +.B dabbrev\-expand +Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +.TP +.B complete\-into\-braces (M\-{) +Perform filename completion and insert the list of possible completions +enclosed within braces so the list is available to the shell (see +.B Brace Expansion +above). +.PD +.SS Keyboard Macros +.PD 0 +.TP +.B start\-kbd\-macro (C\-x (\^) +Begin saving the characters typed into the current keyboard macro. +.TP +.B end\-kbd\-macro (C\-x )\^) +Stop saving the characters typed into the current keyboard macro +and store the definition. +.TP +.B call\-last\-kbd\-macro (C\-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +.TP +.B print\-last\-kbd\-macro () +Print the last keyboard macro defined in a format suitable for the +\fIinputrc\fP file. +.PD +.SS Miscellaneous +.PD 0 +.TP +.B re\-read\-init\-file (C\-x C\-r) +Read in the contents of the \fIinputrc\fP file, and incorporate +any bindings or variable assignments found there. +.TP +.B abort (C\-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +.BR bell\-style ). +.TP +.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is uppercase, run the command +that is bound to the corresponding metafied lowercase character. +The behavior is undefined if \fIx\fP is already lowercase. +.TP +.B prefix\-meta (ESC) +Metafy the next character typed. +.SM +.B ESC +.B f +is equivalent to +.BR Meta\-f . +.TP +.B undo (C\-_, C\-x C\-u) +Incremental undo, separately remembered for each line. +.TP +.B revert\-line (M\-r) +Undo all changes made to this line. This is like executing the +.B undo +command enough times to return the line to its initial state. +.TP +.B tilde\-expand (M\-&) +Perform tilde expansion on the current word. +.TP +.B set\-mark (C\-@, M\-) +Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. +.TP +.B exchange\-point\-and\-mark (C\-x C\-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +.TP +.B character\-search (C\-]) +A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. +.TP +.B character\-search\-backward (M\-C\-]) +A character is read and point is moved to the previous occurrence of that +character. A negative argument searches for subsequent occurrences. +.TP +.B skip\-csi\-sequence +Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC\-[. +.TP +.B insert\-comment (M\-#) +Without a numeric argument, the value of the readline +.B comment\-begin +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of \fBcomment\-begin\fP, the value is inserted, otherwise +the characters in \fBcomment\-begin\fP are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +The default value of +\fBcomment\-begin\fP causes this command to make the current line +a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +.TP +.B spell\-correct\-word (C\-x s) +Perform spelling correction on the current word, treating it as a directory +or filename, in the same way as the \fBcdspell\fP shell option. +Word boundaries are the same as those used by \fBshell\-forward\-word\fP. +.TP +.B glob\-complete\-word (M\-g) +The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching filenames for possible completions. +.TP +.B glob\-expand\-word (C\-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching filenames is inserted, replacing the word. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.TP +.B glob\-list\-expansions (C\-x g) +The list of expansions that would have been generated by +.B glob\-expand\-word +is displayed, and the line is redrawn. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.TP +.B dump\-functions +Print all of the functions and their key bindings to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-variables +Print all of the settable readline variables and their values to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-macros +Print all of the readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B display\-shell\-version (C\-x C\-v) +Display version information about the current instance of +.BR bash . +.PD +.SS Programmable Completion +When word completion is attempted for an argument to a command for +which a completion specification (a \fIcompspec\fP) has been defined +using the \fBcomplete\fP builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), the programmable completion facilities are invoked. +.PP +First, the command name is identified. +If the command word is the empty string (completion attempted at the +beginning of an empty line), any compspec defined with +the \fB\-E\fP option to \fBcomplete\fP is used. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +If those searches do not result in a compspec, any compspec defined with +the \fB\-D\fP option to \fBcomplete\fP is used as the default. +If there is no default compspec, \fBbash\fP attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion. +.PP +Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default \fBbash\fP completion as +described above under \fBCompleting\fP is performed. +.PP +First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the +.B \-f +or +.B \-d +option is used for filename or directory name completion, the shell +variable +.SM +.B FIGNORE +is used to filter the matches. +.PP +Any completions specified by a pathname expansion pattern to the +\fB\-G\fP option are generated next. +The words generated by the pattern need not match the word +being completed. +The +.SM +.B GLOBIGNORE +shell variable is not used to filter the matches, but the +.SM +.B FIGNORE +variable is used. +.PP +Next, the string specified as the argument to the \fB\-W\fP option +is considered. +The string is first split using the characters in the +.SM +.B IFS +special variable as delimiters. +Shell quoting is honored. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above under +.SM +.BR EXPANSION . +The results are split using the rules described above under +\fBWord Splitting\fP. +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. +.PP +After these matches have been generated, any shell function or command +specified with the \fB\-F\fP and \fB\-C\fP options is invoked. +When the command or function is invoked, the +.SM +.BR COMP_LINE , +.SM +.BR COMP_POINT , +.SM +.BR COMP_KEY , +and +.SM +.B COMP_TYPE +variables are assigned values as described above under +\fBShell Variables\fP. +If a shell function is being invoked, the +.SM +.B COMP_WORDS +and +.SM +.B COMP_CWORD +variables are also set. +When the function or command is invoked, +the first argument (\fB$1\fP) is the name of the command whose arguments are +being completed, +the second argument (\fB$2\fP) is the word being completed, +and the third argument (\fB$3\fP) is the word preceding the word being +completed on the current command line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. +.PP +Any function specified with \fB\-F\fP is invoked first. +The function may use any of the shell facilities, including the +\fBcompgen\fP builtin described below, to generate the matches. +It must put the possible completions in the +.SM +.B COMPREPLY +array variable, one per array element. +.PP +Next, any command specified with the \fB\-C\fP option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to the +standard output. +Backslash may be used to escape a newline, if necessary. +.PP +After all of the possible completions are generated, any filter +specified with the \fB\-X\fP option is applied to the list. +The filter is a pattern as used for pathname expansion; a \fB&\fP +in the pattern is replaced with the text of the word being completed. +A literal \fB&\fP may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading \fB!\fP negates the pattern; in this case any completion +not matching the pattern will be removed. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +.PP +Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP +options are added to each member of the completion list, and the result is +returned to the readline completion code as the list of possible +completions. +.PP +If the previously-applied actions do not generate any matches, and the +\fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted. +.PP +If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. +.PP +By default, if a compspec is found, whatever it generates is returned +to the completion code as the full set of possible completions. +The default \fBbash\fP completions are not attempted, and the readline +default of filename completion is disabled. +If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when +the compspec was defined, the \fBbash\fP default completions are attempted +if the compspec generates no matches. +If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the +compspec was defined, readline's default completion will be performed +if the compspec (and, if attempted, the default \fBbash\fP completions) +generate no matches. +.PP +When a compspec indicates that directory name completion is desired, +the programmable completion functions force readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the \fBmark\-directories\fP readline variable, regardless +of the setting of the \fBmark-symlinked\-directories\fP readline variable. +.PP +There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with \fBcomplete \-D\fP. +It's possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes +the compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is executed), +programmable completion restarts from the beginning, with an +attempt to find a new compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather than +being loaded all at once. +.PP +For instance, assuming that there is a library of compspecs, each kept in a +file corresponding to the name of the command, the following default +completion function would load completions dynamically: +.PP +\f(CW_completion_loader() +.br +{ +.br + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 +.br +} +.br +complete -D -F _completion_loader -o bashdefault -o default +.br +\fP +.SH HISTORY +When the +.B \-o history +option to the +.B set +builtin is enabled, the shell provides access to the +\fIcommand history\fP, +the list of commands previously typed. +The value of the +.SM +.B HISTSIZE +variable is used as the +number of commands to save in a history list. +The text of the last +.SM +.B HISTSIZE +commands (default 500) is saved. The shell +stores each command in the history list prior to parameter and +variable expansion (see +.SM +.B EXPANSION +above) but after history expansion is performed, subject to the +values of the shell variables +.SM +.B HISTIGNORE +and +.SM +.BR HISTCONTROL . +.PP +On startup, the history is initialized from the file named by +the variable +.SM +.B HISTFILE +(default \fI~/.bash_history\fP). +The file named by the value of +.SM +.B HISTFILE +is truncated, if necessary, to contain no more than +the number of lines specified by the value of +.SM +.BR HISTFILESIZE . +If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value, +or a numeric value less than zero, the history file is not truncated. +When the history file is read, +lines beginning with the history comment character followed immediately +by a digit are interpreted as timestamps for the following history line. +These timestamps are optionally displayed depending on the value of the +.SM +.B HISTTIMEFORMAT +variable. +When a shell with history enabled exits, the last +.SM +.B $HISTSIZE +lines are copied from the history list to +.SM +.BR $HISTFILE . +If the +.B histappend +shell option is enabled +(see the description of +.B shopt +under +.SM +.B "SHELL BUILTIN COMMANDS" +below), the lines are appended to the history file, +otherwise the history file is overwritten. +If +.SM +.B HISTFILE +is unset, or if the history file is unwritable, the history is +not saved. +If the +.SM +.B HISTTIMEFORMAT +variable is set, time stamps are written to the history file, marked +with the history comment character, so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. +After saving the history, the history file is truncated +to contain no more than +.SM +.B HISTFILESIZE +lines. If +.SM +.B HISTFILESIZE +is unset, or set to null, a non-numeric value, +or a numeric value less than zero, the history file is not truncated. +.PP +The builtin command +.B fc +(see +.SM +.B SHELL BUILTIN COMMANDS +below) may be used to list or edit and re-execute a portion of +the history list. +The +.B history +builtin may be used to display or modify the history list and +manipulate the history file. +When using command-line editing, search commands +are available in each editing mode that provide access to the +history list. +.PP +The shell allows control over which commands are saved on the history +list. The +.SM +.B HISTCONTROL +and +.SM +.B HISTIGNORE +variables may be set to cause the shell to save only a subset of the +commands entered. +The +.B cmdhist +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The +.B lithist +shell option causes the shell to save the command with embedded newlines +instead of semicolons. See the description of the +.B shopt +builtin below under +.SM +.B "SHELL BUILTIN COMMANDS" +for information on setting and unsetting shell options. +.SH "HISTORY EXPANSION" +The shell supports a history expansion feature that +is similar to the history expansion in +.BR csh . +This section describes what syntax features are available. This +feature is enabled by default for interactive shells, and can be +disabled using the +.B +H +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). Non-interactive shells do not perform history expansion +by default. +.PP +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +.PP +History expansion is performed immediately after a complete line +is read, before the shell breaks it into words, and is performed +on each line individually without taking quoting on previous lines into +account. +It takes place in two parts. +The first is to determine which line from the history list +to use during substitution. +The second is to select portions of that line for inclusion into +the current one. +The line selected from the history is the \fIevent\fP, +and the portions of that line that are acted upon are \fIwords\fP. +Various \fImodifiers\fP are available to manipulate the selected words. +The line is broken into words in the same fashion as when reading input, +so that several \fImetacharacter\fP-separated words surrounded by +quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is \^\fB!\fP\^ by default. +Only backslash (\^\fB\e\fP\^) and single quotes can quote +the history expansion character, but the history expansion character is +also treated as quoted if it immediately precedes the closing double quote +in a double-quoted string. +.PP +Several characters inhibit history expansion if found immediately +following the history expansion character, even if it is unquoted: +space, tab, newline, carriage return, and \fB=\fP. +If the \fBextglob\fP shell option is enabled, \fB(\fP will also +inhibit expansion. +.PP +Several shell options settable with the +.B shopt +builtin may be used to tailor the behavior of history expansion. +If the +.B histverify +shell option is enabled (see the description of the +.B shopt +builtin below), and +.B readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the +.B readline +editing buffer for further modification. +If +.B readline +is being used, and the +.B histreedit +shell option is enabled, a failed history substitution will be reloaded +into the +.B readline +editing buffer for correction. +The +.B \-p +option to the +.B history +builtin command may be used to see what a history expansion will +do before using it. +The +.B \-s +option to the +.B history +builtin may be used to add commands to the end of the history list +without actually executing them, so that they are available for +subsequent recall. +.PP +The shell allows control of the various characters used by the +history expansion mechanism (see the description of +.B histchars +above under +.BR "Shell Variables" ). +The shell uses +the history comment character to mark history timestamps when +writing the history file. +.SS Event Designators +An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +.PP +.PD 0 +.TP +.B ! +Start a history substitution, except when followed by a +.BR blank , +newline, carriage return, = +or ( (when the \fBextglob\fP shell option is enabled using +the \fBshopt\fP builtin). +.TP +.B !\fIn\fR +Refer to command line +.IR n . +.TP +.B !\-\fIn\fR +Refer to the current command minus +.IR n . +.TP +.B !! +Refer to the previous command. This is a synonym for `!\-1'. +.TP +.B !\fIstring\fR +Refer to the most recent command preceding the current position in the +history list starting with +.IR string . +.TP +.B !?\fIstring\fR\fB[?]\fR +Refer to the most recent command preceding the current position in the +history list containing +.IR string . +The trailing \fB?\fP may be omitted if +.I string +is followed immediately by a newline. +If \fIstring\fP is missing, the string from the most recent search is used; +it is an error if there is no previous search string. +.TP +.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u +Quick substitution. Repeat the previous command, replacing +.I string1 +with +.IR string2 . +Equivalent to +``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' +(see \fBModifiers\fP below). +.TP +.B !# +The entire command line typed so far. +.PD +.SS Word Designators +Word designators are used to select desired words from the event. +A +.B : +separates the event specification from the word designator. +It may be omitted if the word designator begins with a +.BR ^ , +.BR $ , +.BR * , +.BR \- , +or +.BR % . +Words are numbered from the beginning of the line, +with the first word being denoted by 0 (zero). +Words are inserted into the current line separated by single spaces. +.PP +.PD 0 +.TP +.B 0 (zero) +The zeroth word. For the shell, this is the command +word. +.TP +.I n +The \fIn\fRth word. +.TP +.B ^ +The first argument. That is, word 1. +.TP +.B $ +The last word. This is usually the last argument, but will expand to the +zeroth word if there is only one word in the line. +.TP +.B % +The first word matched by the most recent `?\fIstring\fR?' search, +if the search string begins with a character that is part of a word. +.TP +.I x\fB\-\fPy +A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. +.TP +.B * +All of the words but the zeroth. This is a synonym +for `\fI1\-$\fP'. It is not an error to use +.B * +if there is just one +word in the event; the empty string is returned in that case. +.TP +.B x* +Abbreviates \fIx\-$\fP. +.TP +.B x\- +Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. +If \fBx\fP is missing, it defaults to 0. +.PD +.PP +If a word designator is supplied without an event specification, the +previous command is used as the event. +.SS Modifiers +After the optional word designator, there may appear a sequence of +one or more of the following modifiers, each preceded by a `:'. +These modify, or edit, the word or words selected from the history event. +.PP +.PD 0 +.TP +.B h +Remove a trailing filename component, leaving only the head. +.TP +.B t +Remove all leading filename components, leaving the tail. +.TP +.B r +Remove a trailing suffix of the form \fI.xxx\fP, leaving the +basename. +.TP +.B e +Remove all but the trailing suffix. +.TP +.B p +Print the new command but do not execute it. +.TP +.B q +Quote the substituted words, escaping further substitutions. +.TP +.B x +Quote the substituted words as with +.BR q , +but break into words at +.B blanks +and newlines. +The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one +supplied is used. +.TP +.B s/\fIold\fP/\fInew\fP/ +Substitute +.I new +for the first occurrence of +.I old +in the event line. +Any character may be used as the delimiter in place of /. +The final delimiter is optional if it is the last character of the +event line. +The delimiter may be quoted in +.I old +and +.I new +with a single backslash. If & appears in +.IR new , +it is replaced by +.IR old . +A single backslash will quote the &. +If +.I old +is null, it is set to the last +.I old +substituted, or, if no previous history substitutions took place, +the last +.I string +in a +.B !?\fIstring\fR\fB[?]\fR +search. +If +.I new +is null, each matching +.I old +is deleted. +.TP +.B & +Repeat the previous substitution. +.TP +.B g +Cause changes to be applied over the entire event line. This is +used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') +or `\fB:&\fP'. If used with +`\fB:s\fP', any delimiter can be used +in place of /, and the final delimiter is optional +if it is the last character of the event line. +An \fBa\fP may be used as a synonym for \fBg\fP. +.TP +.B G +Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word +in the event line. +.PD +.SH "SHELL BUILTIN COMMANDS" +.\" start of bash_builtins +.zZ +.PP +Unless otherwise noted, each builtin command documented in this +section as accepting options preceded by +.B \- +accepts +.B \-\- +to signify the end of the options. +The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins +do not accept options and do not treat \fB\-\-\fP specially. +The \fBexit\fP, \fBlogout\fP, \fBreturn\fP, +\fBbreak\fP, \fBcontinue\fP, \fBlet\fP, +and \fBshift\fP builtins accept and process arguments beginning with +\fB\-\fP without requiring \fB\-\-\fP. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with \fB\-\fP as invalid options and +require \fB\-\-\fP to prevent this interpretation. +.sp .5 +.PD 0 +.TP +\fB:\fP [\fIarguments\fP] +.PD +No effect; the command does nothing beyond expanding +.I arguments +and performing any specified +redirections. +The return status is zero. +.TP +\fB .\| \fP \fIfilename\fP [\fIarguments\fP] +.PD 0 +.TP +\fBsource\fP \fIfilename\fP [\fIarguments\fP] +.PD +Read and execute commands from +.I filename +in the current +shell environment and return the exit status of the last command +executed from +.IR filename . +If +.I filename +does not contain a slash, filenames in +.SM +.B PATH +are used to find the directory containing +.IR filename , +but \fIfilename\fP does not need to be executable. +The file searched for in +.SM +.B PATH +need not be executable. +When \fBbash\fP is not in \fIposix mode\fP, it searches +the current directory if no file is found in +.SM +.BR PATH . +If the +.B sourcepath +option to the +.B shopt +builtin command is turned off, the +.SM +.B PATH +is not searched. +If any \fIarguments\fP are supplied, they become the positional +parameters when \fIfilename\fP is executed. Otherwise the positional +parameters are unchanged. +If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on +\fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and +restored around the call to \fB.\fP, and \fB.\fP unsets the +\fBDEBUG\fP trap while it executes. +If \fB\-T\fP is not set, and the sourced file changes +the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes. +The return status is the status of the last command exited within +the script (0 if no commands are executed), and false if +.I filename +is not found or cannot be read. +.TP +\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBAlias\fP with no arguments or with the +.B \-p +option prints the list of aliases in the form +\fBalias\fP \fIname\fP=\fIvalue\fP on standard output. +When arguments are supplied, an alias is defined for +each \fIname\fP whose \fIvalue\fP is given. +A trailing space in \fIvalue\fP causes the next word to be +checked for alias substitution when the alias is expanded. +For each \fIname\fP in the argument list for which no \fIvalue\fP +is supplied, the name and value of the alias is printed. +\fBAlias\fP returns true unless a \fIname\fP is given for which +no alias has been defined. +.TP +\fBbg\fP [\fIjobspec\fP ...] +Resume each suspended job \fIjobspec\fP in the background, as if it +had been started with +.BR & . +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +.B bg +.I jobspec +returns 0 unless run when job control is disabled or, when run with +job control enabled, any specified \fIjobspec\fP was not found +or was started without job control. +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP] +.PD 0 +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP] +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP +.TP +\fBbind\fP \fIreadline-command-line\fP +.PD +Display current +.B readline +key and function bindings, bind a key sequence to a +.B readline +function or macro, or set a +.B readline +variable. +Each non-option argument is a command as it would appear in a +.B readline +initialization file such as +.IR .inputrc , +but each binding or command must be passed as a separate argument; +e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-m \fIkeymap\fP +Use +.I keymap +as the keymap to be affected by the subsequent bindings. +Acceptable +.I keymap +names are +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-move, vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also +a synonym); \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. +.TP +.B \-l +List the names of all \fBreadline\fP functions. +.TP +.B \-p +Display \fBreadline\fP function names and bindings in such a way +that they can be re-read. +.TP +.B \-P +List current \fBreadline\fP function names and bindings. +.TP +.B \-s +Display \fBreadline\fP key sequences bound to macros and the strings +they output in such a way that they can be re-read. +.TP +.B \-S +Display \fBreadline\fP key sequences bound to macros and the strings +they output. +.TP +.B \-v +Display \fBreadline\fP variable names and values in such a way that they +can be re-read. +.TP +.B \-V +List current \fBreadline\fP variable names and values. +.TP +.B \-f \fIfilename\fP +Read key bindings from \fIfilename\fP. +.TP +.B \-q \fIfunction\fP +Query about which keys invoke the named \fIfunction\fP. +.TP +.B \-u \fIfunction\fP +Unbind all keys bound to the named \fIfunction\fP. +.TP +.B \-r \fIkeyseq\fP +Remove any current binding for \fIkeyseq\fP. +.TP +.B \-x \fIkeyseq\fP:\fIshell\-command\fP +Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is +entered. +When \fIshell\-command\fP is executed, the shell sets the +.SM +.B READLINE_LINE +variable to the contents of the \fBreadline\fP line buffer and the +.SM +.B READLINE_POINT +and +.SM +.B READLINE_MARK +variables to the current location of the insertion point and the saved +insertion point (the mark), respectively. +The shell assigns any numeric argument the user supplied to the +.SM +.B READLINE_ARGUMENT +variable. +If there was no argument, that variable is not set. +If the executed command changes the value of any of +.SM +.BR READLINE_LINE , +.SM +.BR READLINE_POINT , +or +.SM +.BR READLINE_MARK , +those new values will be reflected in the editing state. +.TP +.B \-X +List all key sequences bound to shell commands and the associated commands +in a format that can be reused as input. +.PD +.PP +The return value is 0 unless an unrecognized option is given or an +error occurred. +.RE +.TP +\fBbreak\fP [\fIn\fP] +Exit from within a +.BR for , +.BR while , +.BR until , +or +.B select +loop. If \fIn\fP is specified, break \fIn\fP levels. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, all enclosing loops +are exited. +The return value is 0 unless \fIn\fP is not greater than or equal to 1. +.TP +\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] +Execute the specified shell builtin, passing it +.IR arguments , +and return its exit status. +This is useful when defining a +function whose name is the same as a shell builtin, +retaining the functionality of the builtin within the function. +The \fBcd\fP builtin is commonly redefined this way. +The return status is false if +.I shell\-builtin +is not a shell builtin command. +.TP +\fBcaller\fP [\fIexpr\fP] +Returns the context of any active subroutine call (a shell function or +a script executed with the \fB.\fP or \fBsource\fP builtins). +Without \fIexpr\fP, \fBcaller\fP displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. +The return value is 0 unless the shell is not executing a subroutine +call or \fIexpr\fP does not correspond to a valid position in the +call stack. +.TP +\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP] +Change the current directory to \fIdir\fP. +if \fIdir\fP is not supplied, the value of the +.SM +.B HOME +shell variable is the default. +The variable +.SM +.B CDPATH +defines the search path for the directory containing +.IR dir : +each directory name in +.SM +.B CDPATH +is searched for \fIdir\fP. +Alternative directory names in +.SM +.B CDPATH +are separated by a colon (:). A null directory name in +.SM +.B CDPATH +is the same as the current directory, i.e., ``\fB.\fP''. If +.I dir +begins with a slash (/), +then +.SM +.B CDPATH +is not used. The +.B \-P +option causes \fBcd\fP to use the physical directory structure +by resolving symbolic links while traversing \fIdir\fP and +before processing instances of \fI..\fP in \fIdir\fP (see also the +.B \-P +option to the +.B set +builtin command); the +.B \-L +option forces symbolic links to be followed by resolving the link +after processing instances of \fI..\fP in \fIdir\fP. +If \fI..\fP appears in \fIdir\fP, it is processed by removing the +immediately previous pathname component from \fIdir\fP, back to a slash +or the beginning of \fIdir\fP. +If the +.B \-e +option is supplied with +.BR \-P , +and the current working directory cannot be successfully determined +after a successful directory change, \fBcd\fP will return an unsuccessful +status. +On systems that support it, the \fB\-@\fP option presents the extended +attributes associated with a file as a directory. +An argument of +.B \- +is converted to +.SM +.B $OLDPWD +before the directory change is attempted. +If a non-empty directory name from +.SM +.B CDPATH +is used, or if +\fB\-\fP is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. +If the directory change is successful, \fBcd\fP sets the value of the +\fBPWD\fP environment variable to the new directory name, and sets the +\fBOLDPWD\fP environment variable to the value of the current working +directory before the change. +The return value is true if the directory was successfully changed; +false otherwise. +.TP +\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] +Run +.I command +with +.I args +suppressing the normal shell function lookup. +Only builtin commands or commands found in the +.SM +.B PATH +are executed. If the +.B \-p +option is given, the search for +.I command +is performed using a default value for +.SM +.B PATH +that is guaranteed to find all of the standard utilities. +If either the +.B \-V +or +.B \-v +option is supplied, a description of +.I command +is printed. The +.B \-v +option causes a single word indicating the command or filename +used to invoke +.I command +to be displayed; the +.B \-V +option produces a more verbose description. +If the +.B \-V +or +.B \-v +option is supplied, the exit status is 0 if +.I command +was found, and 1 if not. If neither option is supplied and +an error occurred or +.I command +cannot be found, the exit status is 127. Otherwise, the exit status of the +.B command +builtin is the exit status of +.IR command . +.TP +\fBcompgen\fP [\fIoption\fP] [\fIword\fP] +Generate possible completion matches for \fIword\fP according to +the \fIoption\fPs, which may be any option accepted by the +.B complete +builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write +the matches to the standard output. +When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. +.sp 1 +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If \fIword\fP is specified, only those completions matching \fIword\fP +will be displayed. +.sp 1 +The return value is true unless an invalid option is supplied, or no +matches were generated. +.TP +\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] +.br +[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP] +.PD 0 +.TP +\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...] +.PD +Specify how arguments to each \fIname\fP should be completed. +If the \fB\-p\fP option is supplied, or if no options are supplied, +existing completion specifications are printed in a way that allows +them to be reused as input. +The \fB\-r\fP option removes a completion specification for +each \fIname\fP, or, if no \fIname\fPs are supplied, all +completion specifications. +The \fB\-D\fP option indicates that other supplied options and actions should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The \fB\-E\fP option indicates that other supplied options and actions should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after +a command delimiter such as \fB;\fP or \fB|\fP, which is usually command +name completion. +If multiple options are supplied, the \fB\-D\fP option takes precedence +over \fB\-E\fP, and both take precedence over \fB\-I\fP. +If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other +\fIname\fP arguments are ignored; these completions only apply to the case +specified by the option. +.sp 1 +The process of applying these completion specifications when word completion +is attempted is described +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above under \fBProgrammable Completion\fP. +.sp 1 +Other options, if specified, have the following meanings. +The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options +(and, if necessary, the \fB\-P\fP and \fB\-S\fP options) +should be quoted to protect them from expansion before the +.B complete +builtin is invoked. +.RS +.PD 0 +.TP 8 +\fB\-o\fP \fIcomp-option\fP +The \fIcomp-option\fP controls several aspects of the compspec's behavior +beyond the simple generation of completions. +\fIcomp-option\fP may be one of: +.RS +.TP 8 +.B bashdefault +Perform the rest of the default \fBbash\fP completions if the compspec +generates no matches. +.TP 8 +.B default +Use readline's default filename completion if the compspec generates +no matches. +.TP 8 +.B dirnames +Perform directory name completion if the compspec generates no matches. +.TP 8 +.B filenames +Tell readline that the compspec generates filenames, so it can perform any +filename\-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +Intended to be used with shell functions. +.TP 8 +.B noquote +Tell readline not to quote the completed words if they are filenames +(quoting filenames is the default). +.TP 8 +.B nosort +Tell readline not to sort the list of possible completions alphabetically. +.TP 8 +.B nospace +Tell readline not to append a space (the default) to words completed at +the end of the line. +.TP 8 +.B plusdirs +After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. +.RE +.TP 8 +\fB\-A\fP \fIaction\fP +The \fIaction\fP may be one of the following to generate a list of possible +completions: +.RS +.TP 8 +.B alias +Alias names. May also be specified as \fB\-a\fP. +.TP 8 +.B arrayvar +Array variable names. +.TP 8 +.B binding +\fBReadline\fP key binding names. +.TP 8 +.B builtin +Names of shell builtin commands. May also be specified as \fB\-b\fP. +.TP 8 +.B command +Command names. May also be specified as \fB\-c\fP. +.TP 8 +.B directory +Directory names. May also be specified as \fB\-d\fP. +.TP 8 +.B disabled +Names of disabled shell builtins. +.TP 8 +.B enabled +Names of enabled shell builtins. +.TP 8 +.B export +Names of exported shell variables. May also be specified as \fB\-e\fP. +.TP 8 +.B file +File names. May also be specified as \fB\-f\fP. +.TP 8 +.B function +Names of shell functions. +.TP 8 +.B group +Group names. May also be specified as \fB\-g\fP. +.TP 8 +.B helptopic +Help topics as accepted by the \fBhelp\fP builtin. +.TP 8 +.B hostname +Hostnames, as taken from the file specified by the +.SM +.B HOSTFILE +shell variable. +.TP 8 +.B job +Job names, if job control is active. May also be specified as \fB\-j\fP. +.TP 8 +.B keyword +Shell reserved words. May also be specified as \fB\-k\fP. +.TP 8 +.B running +Names of running jobs, if job control is active. +.TP 8 +.B service +Service names. May also be specified as \fB\-s\fP. +.TP 8 +.B setopt +Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. +.TP 8 +.B shopt +Shell option names as accepted by the \fBshopt\fP builtin. +.TP 8 +.B signal +Signal names. +.TP 8 +.B stopped +Names of stopped jobs, if job control is active. +.TP 8 +.B user +User names. May also be specified as \fB\-u\fP. +.TP 8 +.B variable +Names of all shell variables. May also be specified as \fB\-v\fP. +.RE +.TP 8 +\fB\-C\fP \fIcommand\fP +\fIcommand\fP is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the \fB\-F\fP option. +.TP 8 +\fB\-F\fP \fIfunction\fP +The shell function \fIfunction\fP is executed in the current shell +environment. +When the function is executed, +the first argument (\fB$1\fP) is the name of the command whose arguments are +being completed, +the second argument (\fB$2\fP) is the word being completed, +and the third argument (\fB$3\fP) is the word preceding the word being +completed on the current command line. +When it finishes, the possible completions are retrieved from the value +of the +.SM +.B COMPREPLY +array variable. +.TP 8 +\fB\-G\fP \fIglobpat\fP +The pathname expansion pattern \fIglobpat\fP is expanded to generate +the possible completions. +.TP 8 +\fB\-P\fP \fIprefix\fP +\fIprefix\fP is added at the beginning of each possible completion +after all other options have been applied. +.TP 8 +\fB\-S\fP \fIsuffix\fP +\fIsuffix\fP is appended to each possible completion +after all other options have been applied. +.TP 8 +\fB\-W\fP \fIwordlist\fP +The \fIwordlist\fP is split using the characters in the +.SM +.B IFS +special variable as delimiters, and each resultant word is expanded. +Shell quoting is honored within \fIwordlist\fP, +in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of +.SM +.BR IFS . +The possible completions are the members of the resultant list which +match the word being completed. +.TP 8 +\fB\-X\fP \fIfilterpat\fP +\fIfilterpat\fP is a pattern as used for pathname expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +\fIfilterpat\fP is removed from the list. +A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this +case, any completion not matching \fIfilterpat\fP is removed. +.PD +.PP +The return value is true unless an invalid option is supplied, an option +other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP +argument, an attempt is made to remove a completion specification for +a \fIname\fP for which no specification exists, or +an error occurs adding a completion specification. +.RE +.TP +\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP] +Modify completion options for each \fIname\fP according to the +\fIoption\fPs, or for the +currently-executing completion if no \fIname\fPs are supplied. +If no \fIoption\fPs are given, display the completion options for each +\fIname\fP or the current completion. +The possible values of \fIoption\fP are those valid for the \fBcomplete\fP +builtin described above. +The \fB\-D\fP option indicates that other supplied options should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The \fB\-E\fP option indicates that other supplied options should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, +or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually +command name completion. +.sp 1 +The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a \fIname\fP for which no completion +specification exists, or an output error occurs. +.TP +\fBcontinue\fP [\fIn\fP] +Resume the next iteration of the enclosing +.BR for , +.BR while , +.BR until , +or +.B select +loop. +If +.I n +is specified, resume at the \fIn\fPth enclosing loop. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, the last enclosing loop +(the ``top-level'' loop) is resumed. +The return value is 0 unless \fIn\fP is not greater than or equal to 1. +.TP +\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD 0 +.TP +\fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD +Declare variables and/or give them attributes. +If no \fIname\fPs are given then display the values of variables. +The +.B \-p +option will display the attributes and values of each +.IR name . +When +.B \-p +is used with \fIname\fP arguments, additional options, +other than \fB\-f\fP and \fB\-F\fP, are ignored. +When +.B \-p +is supplied without \fIname\fP arguments, it will display the attributes +and values of all variables having the attributes specified by the +additional options. +If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display +the attributes and values of all shell variables. The \fB\-f\fP option +will restrict the display to shell functions. +The +.B \-F +option inhibits the display of function definitions; only the +function name and attributes are printed. +If the \fBextdebug\fP shell option is enabled using \fBshopt\fP, +the source file name and line number where each \fIname\fP +is defined are displayed as well. The +.B \-F +option implies +.BR \-f . +The +.B \-g +option forces variables to be created or modified at the global scope, +even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. +The +.B \-I +option causes local variables to inherit the attributes +(except the \fInameref\fP attribute) +and value of any existing variable with the same +\fIname\fP at a surrounding scope. +If there is no existing variable, the local variable is initially unset. +The following options can +be used to restrict output to variables with the specified attribute or +to give variables attributes: +.RS +.PD 0 +.TP +.B \-a +Each \fIname\fP is an indexed array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-A +Each \fIname\fP is an associative array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-f +Use function names only. +.TP +.B \-i +The variable is treated as an integer; arithmetic evaluation (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is performed when the variable is assigned a value. +.TP +.B \-l +When the variable is assigned a value, all upper-case characters are +converted to lower-case. +The upper-case attribute is disabled. +.TP +.B \-n +Give each \fIname\fP the \fInameref\fP attribute, making +it a name reference to another variable. +That other variable is defined by the value of \fIname\fP. +All references, assignments, and attribute modifications +to \fIname\fP, except those using or changing the +\fB\-n\fP attribute itself, are performed on the variable referenced by +\fIname\fP's value. +The nameref attribute cannot be applied to array variables. +.TP +.B \-r +Make \fIname\fPs readonly. These names cannot then be assigned values +by subsequent assignment statements or unset. +.TP +.B \-t +Give each \fIname\fP the \fItrace\fP attribute. +Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from +the calling shell. +The trace attribute has no special meaning for variables. +.TP +.B \-u +When the variable is assigned a value, all lower-case characters are +converted to upper-case. +The lower-case attribute is disabled. +.TP +.B \-x +Mark \fIname\fPs for export to subsequent commands via the environment. +.PD +.PP +Using `+' instead of `\-' +turns off the attribute instead, +with the exceptions that \fB+a\fP and \fB+A\fP +may not be used to destroy array variables and \fB+r\fP will not +remove the readonly attribute. +When used in a function, +.B declare +and +.B typeset +make each +\fIname\fP local, as with the +.B local +command, +unless the \fB\-g\fP option is supplied. +If a variable name is followed by =\fIvalue\fP, the value of +the variable is set to \fIvalue\fP. +When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to +create array variables, additional attributes do not take effect until +subsequent assignments. +The return value is 0 unless an invalid option is encountered, +an attempt is made to define a function using +.if n ``\-f foo=bar'', +.if t \f(CW\-f foo=bar\fP, +an attempt is made to assign a value to a readonly variable, +an attempt is made to assign a value to an array variable without +using the compound assignment syntax (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +one of the \fInames\fP is not a valid shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with \fB\-f\fP. +.RE +.TP +.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] +Without options, displays the list of currently remembered directories. +The default display is on a single line with directory names separated +by spaces. +Directories are added to the list with the +.B pushd +command; the +.B popd +command removes entries from the list. +The current directory is always the first directory in the stack. +.RS +.PD 0 +.TP +.B \-c +Clears the directory stack by deleting all of the entries. +.TP +.B \-l +Produces a listing using full pathnames; +the default listing format uses a tilde to denote the home directory. +.TP +.B \-p +Print the directory stack with one entry per line. +.TP +.B \-v +Print the directory stack with one entry per line, +prefixing each entry with its index in the stack. +.TP +\fB+\fP\fIn\fP +Displays the \fIn\fPth entry counting from the left of the list +shown by +.B dirs +when invoked without options, starting with zero. +.TP +\fB\-\fP\fIn\fP +Displays the \fIn\fPth entry counting from the right of the list +shown by +.B dirs +when invoked without options, starting with zero. +.PD +.PP +The return value is 0 unless an +invalid option is supplied or \fIn\fP indexes beyond the end +of the directory stack. +.RE +.TP +\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ] +Without options, remove each +.I jobspec +from the table of active jobs. +If +.I jobspec +is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option +is supplied, the \fIcurrent job\fP is used. +If the \fB\-h\fP option is given, each +.I jobspec +is not removed from the table, but is marked so that +.SM +.B SIGHUP +is not sent to the job if the shell receives a +.SM +.BR SIGHUP . +If no +.I jobspec +is supplied, the +.B \-a +option means to remove or mark all jobs; the +.B \-r +option without a +.I jobspec +argument restricts operation to running jobs. +The return value is 0 unless a +.I jobspec +does not specify a valid job. +.TP +\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] +Output the \fIarg\fPs, separated by spaces, followed by a newline. +The return status is 0 unless a write error occurs. +If \fB\-n\fP is specified, the trailing newline is +suppressed. If the \fB\-e\fP option is given, interpretation of +the following backslash-escaped characters is enabled. The +.B \-E +option disables the interpretation of these escape characters, +even on systems where they are interpreted by default. +The \fBxpg_echo\fP shell option may be used to +dynamically determine whether or not \fBecho\fP expands these +escape characters by default. +.B echo +does not interpret \fB\-\-\fP to mean the end of options. +.B echo +interprets the following escape sequences: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ec +suppress further output +.TP +.B \ee +.TP +.B \eE +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e0\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(zero to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.PD +.RE +.TP +\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] +Enable and disable builtin shell commands. +Disabling a builtin allows a disk command which has the same name +as a shell builtin to be executed without specifying a full pathname, +even though the shell normally searches for builtins before disk commands. +If \fB\-n\fP is used, each \fIname\fP +is disabled; otherwise, +\fInames\fP are enabled. For example, to use the +.B test +binary found via the +.SM +.B PATH +instead of the shell builtin version, run +.if t \f(CWenable -n test\fP. +.if n ``enable -n test''. +The +.B \-f +option means to load the new builtin command +.I name +from shared object +.IR filename , +on systems that support dynamic loading. +Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a +colon-separated list of directories in which to search for \fIfilename\fP. +The default is system-dependent. +The +.B \-d +option will delete a builtin previously loaded with +.BR \-f . +If no \fIname\fP arguments are given, or if the +.B \-p +option is supplied, a list of shell builtins is printed. +With no other option arguments, the list consists of all enabled +shell builtins. +If \fB\-n\fP is supplied, only disabled builtins are printed. +If \fB\-a\fP is supplied, the list printed includes all builtins, with an +indication of whether or not each is enabled. +If \fB\-s\fP is supplied, the output is restricted to the POSIX +\fIspecial\fP builtins. +If no options are supplied and a \fIname\fP is not a shell builtin, +\fBenable\fP will attempt to load \fIname\fP from a shared object named +\fIname\fP, as if the command were +.if t \f(CWenable \-f\fP \fIname name\fP . +.if n ``enable -f \fIname name\fP . +The return value is 0 unless a +.I name +is not a shell builtin or there is an error loading a new builtin +from a shared object. +.TP +\fBeval\fP [\fIarg\fP ...] +The \fIarg\fPs are read and concatenated together into a single +command. This command is then read and executed by the shell, and +its exit status is returned as the value of +.BR eval . +If there are no +.IR args , +or only null arguments, +.B eval +returns 0. +.TP +\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]] +If +.I command +is specified, it replaces the shell. +No new process is created. The +.I arguments +become the arguments to \fIcommand\fP. +If the +.B \-l +option is supplied, +the shell places a dash at the beginning of the zeroth argument passed to +.IR command . +This is what +.IR login (1) +does. The +.B \-c +option causes +.I command +to be executed with an empty environment. If +.B \-a +is supplied, the shell passes +.I name +as the zeroth argument to the executed command. +If +.I command +cannot be executed for some reason, a non-interactive shell exits, +unless the +.B execfail +shell option +is enabled. In that case, it returns failure. +An interactive shell returns failure if the file cannot be executed. +A subshell exits unconditionally if \fBexec\fP fails. +If +.I command +is not specified, any redirections take effect in the current shell, +and the return status is 0. If there is a redirection error, the +return status is 1. +.TP +\fBexit\fP [\fIn\fP] +Cause the shell to exit +with a status of \fIn\fP. If +.I n +is omitted, the exit status +is that of the last command executed. +A trap on +.SM +.B EXIT +is executed before the shell terminates. +.TP +\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... +.PD 0 +.TP +.B export \-p +.PD +The supplied +.I names +are marked for automatic export to the environment of +subsequently executed commands. If the +.B \-f +option is given, the +.I names +refer to functions. +If no +.I names +are given, or if the +.B \-p +option is supplied, a list +of names of all exported variables is printed. +The +.B \-n +option causes the export property to be removed from each +\fIname\fP. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +.B export +returns an exit status of 0 unless an invalid option is +encountered, +one of the \fInames\fP is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP] +.PD 0 +.TP +\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] +.PD +The first form selects a range of commands from +.I first +to +.I last +from the history list and displays or edits and re-executes them. +.I First +and +.I last +may be specified as a string (to locate the last command beginning +with that string) or as a number (an index into the history list, +where a negative number is used as an offset from the current +command number). +When listing, a \fIfirst\fP or \fIlast\fP of +0 is equivalent to \-1 and \-0 is equivalent to the current +command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1 +and \-0 is invalid. +If +.I last +is not specified, it is set to +the current command for listing (so that +.if n ``fc \-l \-10'' +.if t \f(CWfc \-l \-10\fP +prints the last 10 commands) and to +.I first +otherwise. +If +.I first +is not specified, it is set to the previous +command for editing and \-16 for listing. +.sp 1 +The +.B \-n +option suppresses +the command numbers when listing. The +.B \-r +option reverses the order of +the commands. If the +.B \-l +option is given, +the commands are listed on +standard output. Otherwise, the editor given by +.I ename +is invoked +on a file containing those commands. If +.I ename +is not given, the +value of the +.SM +.B FCEDIT +variable is used, and +the value of +.SM +.B EDITOR +if +.SM +.B FCEDIT +is not set. If neither variable is set, +.FN vi +is used. When editing is complete, the edited commands are +echoed and executed. +.sp 1 +In the second form, \fIcommand\fP is re-executed after each instance +of \fIpat\fP is replaced by \fIrep\fP. +\fICommand\fP is interpreted the same as \fIfirst\fP above. +A useful alias to use with this is +.if n ``r="fc -s"'', +.if t \f(CWr='fc \-s'\fP, +so that typing +.if n ``r cc'' +.if t \f(CWr cc\fP +runs the last command beginning with +.if n ``cc'' +.if t \f(CWcc\fP +and typing +.if n ``r'' +.if t \f(CWr\fP +re-executes the last command. +.sp 1 +If the first form is used, the return value is 0 unless an invalid +option is encountered or +.I first +or +.I last +specify history lines out of range. +If the +.B \-e +option is supplied, the return value is the value of the last +command executed or failure if an error occurs with the temporary +file of commands. If the second form is used, the return status +is that of the command re-executed, unless +.I cmd +does not specify a valid history line, in which case +.B fc +returns failure. +.TP +\fBfg\fP [\fIjobspec\fP] +Resume +.I jobspec +in the foreground, and make it the current job. +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +The return value is that of the command placed into the foreground, +or failure if run when job control is disabled or, when run with +job control enabled, if +.I jobspec +does not specify a valid job or +.I jobspec +specifies a job that was started without job control. +.TP +\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP] +.B getopts +is used by shell procedures to parse positional parameters. +.I optstring +contains the option characters to be recognized; if a character +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +The colon and question mark characters may not be used as +option characters. +Each time it is invoked, +.B getopts +places the next option in the shell variable +.IR name , +initializing +.I name +if it does not exist, +and the index of the next argument to be processed into the +variable +.SM +.BR OPTIND . +.SM +.B OPTIND +is initialized to 1 each time the shell or a shell script +is invoked. When an option requires an argument, +.B getopts +places that argument into the variable +.SM +.BR OPTARG . +The shell does not reset +.SM +.B OPTIND +automatically; it must be manually reset between multiple +calls to +.B getopts +within the same shell invocation if a new set of parameters +is to be used. +.sp 1 +When the end of options is encountered, \fBgetopts\fP exits with a +return value greater than zero. +.SM +.B OPTIND +is set to the index of the first non-option argument, +and \fIname\fP is set to ?. +.sp 1 +.B getopts +normally parses the positional parameters, but if more arguments are +supplied as +.I arg +values, +.B getopts +parses those instead. +.sp 1 +.B getopts +can report errors in two ways. If the first character of +.I optstring +is a colon, +.I silent +error reporting is used. In normal operation, diagnostic messages +are printed when invalid options or missing option arguments are +encountered. +If the variable +.SM +.B OPTERR +is set to 0, no error messages will be displayed, even if the first +character of +.I optstring +is not a colon. +.sp 1 +If an invalid option is seen, +.B getopts +places ? into +.I name +and, if not silent, +prints an error message and unsets +.SM +.BR OPTARG . +If +.B getopts +is silent, +the option character found is placed in +.SM +.B OPTARG +and no diagnostic message is printed. +.sp 1 +If a required argument is not found, and +.B getopts +is not silent, +a question mark (\^\fB?\fP\^) is placed in +.IR name , +.SM +.B OPTARG +is unset, and a diagnostic message is printed. +If +.B getopts +is silent, then a colon (\^\fB:\fP\^) is placed in +.I name +and +.SM +.B OPTARG +is set to the option character found. +.sp 1 +.B getopts +returns true if an option, specified or unspecified, is found. +It returns false if the end of options is encountered or an +error occurs. +.TP +\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP] +Each time \fBhash\fP is invoked, +the full pathname of the command +.I name +is determined by searching +the directories in +.B $PATH +and remembered. Any previously-remembered pathname is discarded. +If the +.B \-p +option is supplied, no path search is performed, and +.I filename +is used as the full filename of the command. +The +.B \-r +option causes the shell to forget all +remembered locations. +The +.B \-d +option causes the shell to forget the remembered location of each \fIname\fP. +If the +.B \-t +option is supplied, the full pathname to which each \fIname\fP corresponds +is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, +the \fIname\fP is printed before the hashed full pathname. +The +.B \-l +option causes output to be displayed in a format that may be reused as input. +If no arguments are given, or if only \fB\-l\fP is supplied, +information about remembered commands is printed. +The return status is true unless a +.I name +is not found or an invalid option is supplied. +.TP +\fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP] +Display helpful information about builtin commands. If +.I pattern +is specified, +.B help +gives detailed help on all commands matching +.IR pattern ; +otherwise help for all the builtins and shell control structures +is printed. +.RS +.PD 0 +.TP +.B \-d +Display a short description of each \fIpattern\fP +.TP +.B \-m +Display the description of each \fIpattern\fP in a manpage-like format +.TP +.B \-s +Display only a short usage synopsis for each \fIpattern\fP +.PD +.PP +The return status is 0 unless no command matches +.IR pattern . +.RE +.TP +\fBhistory [\fIn\fP] +.PD 0 +.TP +\fBhistory\fP \fB\-c\fP +.TP +\fBhistory \-d\fP \fIoffset\fP +.TP +\fBhistory \-d\fP \fIstart\fP\-\fIend\fP +.TP +\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] +.TP +\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] +.TP +\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] +.PD +With no options, display the command +history list with line numbers. Lines listed +with a +.B * +have been modified. An argument of +.I n +lists only the last +.I n +lines. +If the shell variable +.SM +.B HISTTIMEFORMAT +is set and not null, +it is used as a format string for \fIstrftime\fP(3) to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. +If \fIfilename\fP is supplied, it is used as the +name of the history file; if not, the value of +.SM +.B HISTFILE +is used. Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-c +Clear the history list by deleting all the entries. +.TP +\fB\-d\fP \fIoffset\fP +Delete the history entry at position \fIoffset\fP. +If \fIoffset\fP is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of \-1 refers to the current +\fBhistory -d\fP command. +.TP +\fB\-d\fP \fIstart\fP\-\fIend\fP +Delete the range of history entries between positions \fIstart\fP and +\fIend\fP, inclusive. +Positive and negative values for \fIstart\fP and \fIend\fP +are interpreted as described above. +.TP +.B \-a +Append the ``new'' history lines to the history file. +These are history lines entered since the beginning of the current +\fBbash\fP session, but not already appended to the history file. +.TP +.B \-n +Read the history lines not already read from the history +file into the current history list. These are lines +appended to the history file since the beginning of the +current \fBbash\fP session. +.TP +.B \-r +Read the contents of the history file +and append them to the current history list. +.TP +.B \-w +Write the current history list to the history file, overwriting the +history file's contents. +.TP +.B \-p +Perform history substitution on the following \fIargs\fP and display +the result on the standard output. +Does not store the results in the history list. +Each \fIarg\fP must be quoted to disable normal history expansion. +.TP +.B \-s +Store the +.I args +in the history list as a single entry. The last command in the +history list is removed before the +.I args +are added. +.PD +.PP +If the +.SM +.B HISTTIMEFORMAT +variable is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. +When the history file is read, lines beginning with the history +comment character followed immediately by a digit are interpreted +as timestamps for the following history entry. +The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +\fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the +history expansion supplied as an argument to \fB\-p\fP fails. +.RE +.TP +\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] +.PD 0 +.TP +\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] +.PD +The first form lists the active jobs. The options have the following +meanings: +.RS +.PD 0 +.TP +.B \-l +List process IDs +in addition to the normal information. +.TP +.B \-n +Display information only about jobs that have changed status since +the user was last notified of their status. +.TP +.B \-p +List only the process ID of the job's process group +leader. +.TP +.B \-r +Display only running jobs. +.TP +.B \-s +Display only stopped jobs. +.PD +.PP +If +.I jobspec +is given, output is restricted to information about that job. +The return status is 0 unless an invalid option is encountered +or an invalid +.I jobspec +is supplied. +.PP +If the +.B \-x +option is supplied, +.B jobs +replaces any +.I jobspec +found in +.I command +or +.I args +with the corresponding process group ID, and executes +.I command +passing it +.IR args , +returning its exit status. +.RE +.TP +\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... +.PD 0 +.TP +\fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP] +.PD +Send the signal named by +.I sigspec +or +.I signum +to the processes named by +.I pid +or +.IR jobspec . +.I sigspec +is either a case-insensitive signal name such as +.SM +.B SIGKILL +(with or without the +.SM +.B SIG +prefix) or a signal number; +.I signum +is a signal number. +If +.I sigspec +is not present, then +.SM +.B SIGTERM +is assumed. +An argument of +.B \-l +lists the signal names. +If any arguments are supplied when +.B \-l +is given, the names of the signals corresponding to the arguments are +listed, and the return status is 0. +The \fIexit_status\fP argument to +.B \-l +is a number specifying either a signal number or the exit status of +a process terminated by a signal. +The +.B \-L +option is equivalent to \fB\-l\fP. +.B kill +returns true if at least one signal was successfully sent, or false +if an error occurs or an invalid option is encountered. +.TP +\fBlet\fP \fIarg\fP [\fIarg\fP ...] +Each +.I arg +is an arithmetic expression to be evaluated (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +If the last +.I arg +evaluates to 0, +.B let +returns 1; 0 is returned otherwise. +.TP +\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ] +For each argument, a local variable named +.I name +is created, and assigned +.IR value . +The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. +When +.B local +is used within a function, it causes the variable +.I name +to have a visible scope restricted to that function and its children. +If \fIname\fP is \-, the set of shell options is made local to the function +in which \fBlocal\fP is invoked: shell options changed using the +\fBset\fP builtin inside the function are restored to their original values +when the function returns. +The restore is effected as if a series of \fBset\fP commands were executed +to restore the values that were in place before the function. +With no operands, +.B local +writes a list of local variables to the standard output. It is +an error to use +.B local +when not within a function. The return status is 0 unless +.B local +is used outside a function, an invalid +.I name +is supplied, or +\fIname\fP is a readonly variable. +.TP +.B logout +Exit a login shell. +.TP +\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD 0 +.TP +\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD +Read lines from the standard input into the indexed array variable +.IR array , +or from file descriptor +.I fd +if the +.B \-u +option is supplied. +The variable +.SM +.B MAPFILE +is the default \fIarray\fP. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-d +The first character of \fIdelim\fP is used to terminate each input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line +when it reads a NUL character. +.TP +.B \-n +Copy at most +.I count +lines. If \fIcount\fP is 0, all lines are copied. +.TP +.B \-O +Begin assigning to +.I array +at index +.IR origin . +The default index is 0. +.TP +.B \-s +Discard the first \fIcount\fP lines read. +.TP +.B \-t +Remove a trailing \fIdelim\fP (default newline) from each line read. +.TP +.B \-u +Read lines from file descriptor \fIfd\fP instead of the standard input. +.TP +.B \-C +Evaluate +.I callback +each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies +.IR quantum . +.TP +.B \-c +Specify the number of lines read between each call to +.IR callback . +.PD +.PP +If +.B \-C +is specified without +.BR \-c , +the default quantum is 5000. +When \fIcallback\fP is evaluated, it is supplied the index of the next +array element to be assigned and the line to be assigned to that element +as additional arguments. +\fIcallback\fP is evaluated after the line is read but before the +array element is assigned. +.PP +If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP +before assigning to it. +.PP +\fBmapfile\fP returns successfully unless an invalid option or option +argument is supplied, \fIarray\fP is invalid or unassignable, or if +\fIarray\fP is not an indexed array. +.RE +.TP +\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] +Removes entries from the directory stack. +The elements are numbered from 0 starting at the first directory +listed by \fBdirs\fP. +With no arguments, \fBpopd\fP +removes the top directory from the stack, and +changes to the new top directory. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Removes the \fIn\fPth entry counting from the left of the list +shown by +.BR dirs , +starting with zero, from the stack. +For example: +.if n ``popd +0'' +.if t \f(CWpopd +0\fP +removes the first directory, +.if n ``popd +1'' +.if t \f(CWpopd +1\fP +the second. +.TP +\fB\-\fP\fIn\fP +Removes the \fIn\fPth entry counting from the right of the list +shown by +.BR dirs , +starting with zero. For example: +.if n ``popd -0'' +.if t \f(CWpopd -0\fP +removes the last directory, +.if n ``popd -1'' +.if t \f(CWpopd -1\fP +the next to last. +.PD +.PP +If the top element of the directory stack is modified, and +the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP +builtin to change to the directory at the top of the stack. +If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value. +.PP +Otherwise, +.B popd +returns false if an invalid option is encountered, the directory stack +is empty, or a non-existent directory stack entry is specified. +.PP +If the +.B popd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack, +and the return status is 0. +.RE +.TP +\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] +Write the formatted \fIarguments\fP to the standard output under the +control of the \fIformat\fP. +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 +The \fIformat\fP is a character string which contains three types of objects: +plain characters, which are simply copied to standard output, character +escape sequences, which are converted and copied to the standard output, and +format specifications, each of which causes printing of the next successive +\fIargument\fP. +In addition to the standard \fIprintf\fP(1) format specifications, +\fBprintf\fP interprets the following extensions: +.RS +.PD 0 +.TP +.B %b +causes +\fBprintf\fP to expand backslash escape sequences in the corresponding +\fIargument\fP +in the same way as \fBecho \-e\fP. +.TP +.B %q +causes \fBprintf\fP to output the corresponding +\fIargument\fP in a format that can be reused as shell input. +.TP +.B %Q +like \fB%q\fP, but applies any supplied precision to the \fIargument\fP +before quoting it. +.TP +.B %(\fIdatefmt\fP)T +causes \fBprintf\fP to output the date-time string resulting from using +\fIdatefmt\fP as a format string for \fIstrftime\fP(3). +The corresponding \fIargument\fP is an integer representing the number of +seconds since the epoch. +Two special argument values may be used: \-1 represents the current +time, and \-2 represents the time the shell was invoked. +If no argument is specified, conversion behaves as if \-1 had been given. +This is an exception to the usual \fBprintf\fP behavior. +.PD +.PP +The %b, %q, and %T directives all use the field width and precision +arguments from the format specification and write that many bytes from +(or use that wide a field for) the expanded argument, which usually +contains more characters than the original. +.PP +Arguments to non-string format specifiers are treated as C constants, +except that a leading plus or minus sign is allowed, and if the leading +character is a single or double quote, the value is the ASCII value of +the following character. +.PP +The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. +If the \fIformat\fP requires more \fIarguments\fP than are supplied, the +extra format specifications behave as if a zero value or null string, as +appropriate, had been supplied. +The return value is zero on success, non-zero on failure. +.RE +.TP +\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] +.PD 0 +.TP +\fBpushd\fP [\fB\-n\fP] [\fIdir\fP] +.PD +Adds a directory to the top of the directory stack, or rotates +the stack, making the new top of the stack the current working +directory. +With no arguments, \fBpushd\fP exchanges the top two elements of +the directory stack. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when rotating or +adding directories to the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the left of the list shown by +.BR dirs , +starting with zero) +is at the top. +.TP +\fB\-\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the right of the list shown by +.BR dirs , +starting with zero) is at the top. +.TP +.I dir +Adds +.I dir +to the directory stack at the top +.PD +.PP +After the stack has been modified, if the \fB\-n\fP option was not +supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the +directory at the top of the stack. +If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value. +.PP +Otherwise, if no arguments are supplied, +.B pushd +returns 0 unless the directory stack is empty. +When rotating the directory stack, +.B pushd +returns 0 unless the directory stack is empty or +a non-existent directory stack element is specified. +.PP +If the +.B pushd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack. +.RE +.TP +\fBpwd\fP [\fB\-LP\fP] +Print the absolute pathname of the current working directory. +The pathname printed contains no symbolic links if the +.B \-P +option is supplied or the +.B \-o physical +option to the +.B set +builtin command is enabled. +If the +.B \-L +option is used, the pathname printed may contain symbolic links. +The return status is 0 unless an error occurs while +reading the name of the current directory or an +invalid option is supplied. +.TP +\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...] +One line is read from the standard input, or from the file descriptor +\fIfd\fP supplied as an argument to the \fB\-u\fP option, +split into words as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP, +and the first word +is assigned to the first +.IR name , +the second word to the second +.IR name , +and so on. +If there are more words than names, the remaining words and their +intervening delimiters are assigned to the last +.IR name . +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in +.SM +.B IFS +are used to split the line into words using the same rules the shell +uses for expansion (described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP). +The backslash character (\fB\e\fP) may be used to remove any special +meaning for the next character read and for line continuation. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-a \fIaname\fP +The words are assigned to sequential indices +of the array variable +.IR aname , +starting at 0. +.I aname +is unset before any new values are assigned. +Other \fIname\fP arguments are ignored. +.TP +.B \-d \fIdelim\fP +The first character of \fIdelim\fP is used to terminate the input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBread\fP will terminate a line +when it reads a NUL character. +.TP +.B \-e +If the standard input +is coming from a terminal, +.B readline +(see +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is used to obtain the line. +Readline uses the current (or default, if line editing was not previously +active) editing settings, but uses readline's default filename completion. +.TP +.B \-i \fItext\fP +If +.B readline +is being used to read the line, \fItext\fP is placed into the editing +buffer before editing begins. +.TP +.B \-n \fInchars\fP +\fBread\fP returns after reading \fInchars\fP characters rather than +waiting for a complete line of input, but honors a delimiter if fewer +than \fInchars\fP characters are read before the delimiter. +.TP +.B \-N \fInchars\fP +\fBread\fP returns after reading exactly \fInchars\fP characters rather +than waiting for a complete line of input, unless EOF is encountered or +\fBread\fP times out. +Delimiter characters encountered in the input are +not treated specially and do not cause \fBread\fP to return until +\fInchars\fP characters are read. +The result is not split on the characters in \fBIFS\fP; the intent is +that the variable is assigned exactly the characters read +(with the exception of backslash; see the \fB\-r\fP option below). +.TP +.B \-p \fIprompt\fP +Display \fIprompt\fP on standard error, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. +.TP +.B \-r +Backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not then be used as a line +continuation. +.TP +.B \-s +Silent mode. If input is coming from a terminal, characters are +not echoed. +.TP +.B \-t \fItimeout\fP +Cause \fBread\fP to time out and return failure if a complete line of +input (or a specified number of characters) +is not read within \fItimeout\fP seconds. +\fItimeout\fP may be a decimal number with a fractional portion following +the decimal point. +This option is only effective if \fBread\fP is reading input from a +terminal, pipe, or other special file; it has no effect when reading +from regular files. +If \fBread\fP times out, \fBread\fP saves any partial input read into +the specified variable \fIname\fP. +If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to +read any data. +The exit status is 0 if input is available on the specified file descriptor, +or the read will return EOF, +non-zero otherwise. +The exit status is greater than 128 if the timeout is exceeded. +.TP +.B \-u \fIfd\fP +Read input from file descriptor \fIfd\fP. +.PD +.PP +If no +.I names +are supplied, the line read, +without the ending delimiter but otherwise unmodified, +is assigned to the variable +.SM +.BR REPLY . +The exit status is zero, unless end-of-file is encountered, \fBread\fP +times out (in which case the status is greater than 128), +a variable assignment error (such as assigning to a readonly variable) occurs, +or an invalid file descriptor is supplied as the argument to \fB\-u\fP. +.RE +.TP +\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...] +.PD +The given +\fInames\fP are marked readonly; the values of these +.I names +may not be changed by subsequent assignment. +If the +.B \-f +option is supplied, the functions corresponding to the +\fInames\fP are so +marked. +The +.B \-a +option restricts the variables to indexed arrays; the +.B \-A +option restricts the variables to associative arrays. +If both options are supplied, +.B \-A +takes precedence. +If no +.I name +arguments are given, or if the +.B \-p +option is supplied, a list of all readonly names is printed. +The other options may be used to restrict the output to a subset of +the set of readonly names. +The +.B \-p +option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +The return status is 0 unless an invalid option is encountered, +one of the +.I names +is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBreturn\fP [\fIn\fP] +Causes a function to stop executing and return the value specified by +.I n +to its caller. +If +.I n +is omitted, the return status is that of the last command +executed in the function body. +If \fBreturn\fP is executed by a trap handler, the last command used to +determine the status is the last command executed before the trap handler. +If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command +used to determine the status is the last command executed by the trap +handler before \fBreturn\fP was invoked. +If +.B return +is used outside a function, +but during execution of a script by the +.B . +(\fBsource\fP) command, it causes the shell to stop executing +that script and return either +.I n +or the exit status of the last command executed within the +script as the exit status of the script. +If \fIn\fP is supplied, the return value is its least significant +8 bits. +The return status is non-zero if +.B return +is supplied a non-numeric argument, or +is used outside a +function and not during execution of a script by \fB.\fP\^ or \fBsource\fP. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes after the function or script. +.TP +\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD 0 +.TP +\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD +Without options, display the name and value of each shell variable +in a format that can be reused as input +for setting or resetting the currently-set variables. +Read-only variables cannot be reset. +In \fIposix mode\fP, only shell variables are listed. +The output is sorted according to the current locale. +When options are specified, they set or unset shell attributes. +Any arguments remaining after option processing are treated +as values for the positional parameters and are assigned, in order, to +.BR $1 , +.BR $2 , +.B ... +.BR $\fIn\fP . +Options, if specified, have the following meanings: +.RS +.PD 0 +.TP 8 +.B \-a +Each variable or function that is created or modified is given the +export attribute and marked for export to the environment of +subsequent commands. +.TP 8 +.B \-b +Report the status of terminated background jobs +immediately, rather than before the next primary prompt. This is +effective only when job control is enabled. +.TP 8 +.B \-e +Exit immediately if a +\fIpipeline\fP (which may consist of a single \fIsimple command\fP), +a \fIlist\fP, +or a \fIcompound command\fP +(see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +exits with a non-zero status. +The shell does not exit if the +command that fails is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test following the +.B if +or +.B elif +reserved words, part of any command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted with +.BR ! . +If a compound command other than a subshell +returns a non-zero status because a command failed +while \fB\-e\fP was being ignored, the shell does not exit. +A trap on \fBERR\fP, if set, is executed before the shell exits. +This option applies to the shell environment and each subshell environment +separately (see +.SM +.B "COMMAND EXECUTION ENVIRONMENT" +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +and may cause +subshells to exit before executing all the commands in the subshell. +.if t .sp 0.5 +.if n .sp 1 +If a compound command or shell function executes in a context +where \fB\-e\fP is being ignored, +none of the commands executed within the compound command or function body +will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set +and a command returns a failure status. +If a compound command or shell function sets \fB\-e\fP while executing in +a context where \fB\-e\fP is ignored, that setting will not have any +effect until the compound command or the command containing the function +call completes. +.TP 8 +.B \-f +Disable pathname expansion. +.TP 8 +.B \-h +Remember the location of commands as they are looked up for execution. +This is enabled by default. +.TP 8 +.B \-k +All arguments in the form of assignment statements +are placed in the environment for a command, not just +those that precede the command name. +.TP 8 +.B \-m +Monitor mode. Job control is enabled. This option is on +by default for interactive shells on systems that support +it (see +.SM +.B JOB CONTROL +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +All processes run in a separate process group. +When a background job completes, the shell prints a line +containing its exit status. +.TP 8 +.B \-n +Read commands but do not execute them. +This may be used to check a shell script for syntax errors. +This is ignored by interactive shells. +.TP 8 +.B \-o \fIoption\-name\fP +The \fIoption\-name\fP can be one of the following: +.RS +.TP 8 +.B allexport +Same as +.BR \-a . +.TP 8 +.B braceexpand +Same as +.BR \-B . +.TP 8 +.B emacs +Use an emacs-style command line editing interface. This is enabled +by default when the shell is interactive, unless the shell is started +with the +.B \-\-noediting +option. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B errexit +Same as +.BR \-e . +.TP 8 +.B errtrace +Same as +.BR \-E . +.TP 8 +.B functrace +Same as +.BR \-T . +.TP 8 +.B hashall +Same as +.BR \-h . +.TP 8 +.B histexpand +Same as +.BR \-H . +.TP 8 +.B history +Enable command history, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +This option is on by default in interactive shells. +.TP 8 +.B ignoreeof +The effect is as if the shell command +.if t \f(CWIGNOREEOF=10\fP +.if n ``IGNOREEOF=10'' +had been executed +(see +.B Shell Variables +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B keyword +Same as +.BR \-k . +.TP 8 +.B monitor +Same as +.BR \-m . +.TP 8 +.B noclobber +Same as +.BR \-C . +.TP 8 +.B noexec +Same as +.BR \-n . +.TP 8 +.B noglob +Same as +.BR \-f . +.TP 8 +.B nolog +Currently ignored. +.TP 8 +.B notify +Same as +.BR \-b . +.TP 8 +.B nounset +Same as +.BR \-u . +.TP 8 +.B onecmd +Same as +.BR \-t . +.TP 8 +.B physical +Same as +.BR \-P . +.TP 8 +.B pipefail +If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. +.TP 8 +.B posix +Change the behavior of +.B bash +where the default operation differs +from the POSIX standard to match the standard (\fIposix mode\fP). +See +.SM +.B "SEE ALSO" +.ie \n(zZ=1 in \fIbash(1)\fP +.el below +for a reference to a document that details how posix mode affects +bash's behavior. +.TP 8 +.B privileged +Same as +.BR \-p . +.TP 8 +.B verbose +Same as +.BR \-v . +.TP 8 +.B vi +Use a vi-style command line editing interface. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B xtrace +Same as +.BR \-x . +.sp .5 +.PP +If +.B \-o +is supplied with no \fIoption\-name\fP, the values of the current options are +printed. +If +.B +o +is supplied with no \fIoption\-name\fP, a series of +.B set +commands to recreate the current option settings is displayed on +the standard output. +.RE +.TP 8 +.B \-p +Turn on +.I privileged +mode. In this mode, the +.SM +.B $ENV +and +.SM +.B $BASH_ENV +files are not processed, shell functions are not inherited from the +environment, and the +.SM +.BR SHELLOPTS , +.SM +.BR BASHOPTS , +.SM +.BR CDPATH , +and +.SM +.B GLOBIGNORE +variables, if they appear in the environment, are ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at startup, the effective user id is +not reset. +Turning this option off causes the effective user +and group ids to be set to the real user and group ids. +.TP 8 +.B \-r +Enable restricted shell mode. +This option cannot be unset once it has been set. +.TP 8 +.B \-t +Exit after reading and executing one command. +.TP 8 +.B \-u +Treat unset variables and parameters other than the special +parameters "@" and "*", +or array variables subscripted with "@" or "*", +as an error when performing +parameter expansion. If expansion is attempted on an +unset variable or parameter, the shell prints an error message, and, +if not interactive, exits with a non-zero status. +.TP 8 +.B \-v +Print shell input lines as they are read. +.TP 8 +.B \-x +After expanding each \fIsimple command\fP, +\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or +arithmetic \fBfor\fP command, display the expanded value of +.SM +.BR PS4 , +followed by the command and its expanded arguments +or associated word list. +.TP 8 +.B \-B +The shell performs brace expansion (see +.B Brace Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is on by default. +.TP 8 +.B \-C +If set, +.B bash +does not overwrite an existing file with the +.BR > , +.BR >& , +and +.B <> +redirection operators. This may be overridden when +creating output files by using the redirection operator +.B >| +instead of +.BR > . +.TP 8 +.B \-E +If set, any trap on \fBERR\fP is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The \fBERR\fP trap is normally not inherited in such cases. +.TP 8 +.B \-H +Enable +.B ! +style history substitution. This option is on by +default when the shell is interactive. +.TP 8 +.B \-P +If set, the shell does not resolve symbolic links when executing +commands such as +.B cd +that change the current working directory. It uses the +physical directory structure instead. By default, +.B bash +follows the logical chain of directories when performing commands +which change the current directory. +.TP 8 +.B \-T +If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell +functions, command substitutions, and commands executed in a +subshell environment. +The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited +in such cases. +.TP 8 +.B \-\- +If no arguments follow this option, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +\fIarg\fPs, even if some of them begin with a +.BR \- . +.TP 8 +.B \- +Signal the end of options, cause all remaining \fIarg\fPs to be +assigned to the positional parameters. The +.B \-x +and +.B \-v +options are turned off. +If there are no \fIarg\fPs, +the positional parameters remain unchanged. +.PD +.PP +The options are off by default unless otherwise noted. +Using + rather than \- causes these options to be turned off. +The options can also be specified as arguments to an invocation of +the shell. +The current set of options may be found in +.BR $\- . +The return status is always true unless an invalid option is encountered. +.RE +.TP +\fBshift\fP [\fIn\fP] +The positional parameters from \fIn\fP+1 ... are renamed to +.B $1 +.B .... +Parameters represented by the numbers \fB$#\fP +down to \fB$#\fP\-\fIn\fP+1 are unset. +.I n +must be a non-negative number less than or equal to \fB$#\fP. +If +.I n +is 0, no parameters are changed. +If +.I n +is not given, it is assumed to be 1. +If +.I n +is greater than \fB$#\fP, the positional parameters are not changed. +The return status is greater than zero if +.I n +is greater than +.B $# +or less than zero; otherwise 0. +.TP +\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] +Toggle the values of settings controlling optional shell behavior. +The settings can be either those listed below, or, if the +.B \-o +option is used, those available with the +.B \-o +option to the \fBset\fP builtin command. +With no options, or with the +.B \-p +option, a list of all settable options is displayed, with +an indication of whether or not each is set; +if \fIoptnames\fP are supplied, the output is restricted to those options. +The \fB\-p\fP option causes output to be displayed in a form that +may be reused as input. +Other options have the following meanings: +.RS +.PD 0 +.TP +.B \-s +Enable (set) each \fIoptname\fP. +.TP +.B \-u +Disable (unset) each \fIoptname\fP. +.TP +.B \-q +Suppresses normal output (quiet mode); the return status indicates +whether the \fIoptname\fP is set or unset. +If multiple \fIoptname\fP arguments are given with +.BR \-q , +the return status is zero if all \fIoptnames\fP are enabled; non-zero +otherwise. +.TP +.B \-o +Restricts the values of \fIoptname\fP to be those defined for the +.B \-o +option to the +.B set +builtin. +.PD +.PP +If either +.B \-s +or +.B \-u +is used with no \fIoptname\fP arguments, +.B shopt +shows only those options which are set or unset, respectively. +Unless otherwise noted, the \fBshopt\fP options are disabled (unset) +by default. +.PP +The return status when listing options is zero if all \fIoptnames\fP +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an \fIoptname\fP is not a valid shell +option. +.PP +The list of \fBshopt\fP options is: +.if t .sp .5v +.if n .sp 1v +.PD 0 +.TP 8 +.B assoc_expand_once +If set, the shell suppresses multiple evaluation of associative array +subscripts during arithmetic expression evaluation, while executing +builtins that can perform variable assignments, +and while executing builtins that perform array dereferencing. +.TP 8 +.B autocd +If set, a command name that is the name of a directory is executed as if +it were the argument to the \fBcd\fP command. +This option is only used by interactive shells. +.TP 8 +.B cdable_vars +If set, an argument to the +.B cd +builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. +.TP 8 +.B cdspell +If set, minor errors in the spelling of a directory component in a +.B cd +command will be corrected. +The errors checked for are transposed characters, +a missing character, and one character too many. +If a correction is found, the corrected filename is printed, +and the command proceeds. +This option is only used by interactive shells. +.TP 8 +.B checkhash +If set, \fBbash\fP checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. +.TP 8 +.B checkjobs +If set, \fBbash\fP lists the status of any stopped and running jobs before +exiting an interactive shell. If any jobs are running, this causes +the exit to be deferred until a second exit is attempted without an +intervening command (see +.SM +.B "JOB CONTROL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The shell always postpones exiting if any jobs are stopped. +.TP 8 +.B checkwinsize +If set, \fBbash\fP checks the window size after each external (non-builtin) +command and, if necessary, updates the values of +.SM +.B LINES +and +.SM +.BR COLUMNS . +This option is enabled by default. +.TP 8 +.B cmdhist +If set, +.B bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. +This option is enabled by default, but only has an effect if command +history is enabled, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +.PD 0 +.TP 8 +.B compat31 +.TP 8 +.B compat32 +.TP 8 +.B compat40 +.TP 8 +.B compat41 +.TP 8 +.B compat42 +.TP 8 +.B compat43 +.TP 8 +.B compat44 +.TP 8 +.B compat50 +.PD +These control aspects of the shell's compatibility mode +(see +.SM +.B "SHELL COMPATIBILITY MODE" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +.TP 8 +.B complete_fullquote +If set, +.B bash +quotes all shell metacharacters in filenames and directory names when +performing completion. +If not set, +.B bash +removes metacharacters such as the dollar sign from the set of +characters that will be quoted in completed filenames +when these metacharacters appear in shell variable references in words to be +completed. +This means that dollar signs in variable names that expand to directories +will not be quoted; +however, any dollar signs appearing in filenames will not be quoted, either. +This is active only when bash is using backslashes to quote completed +filenames. +This variable is set by default, which is the default bash behavior in +versions through 4.2. +.TP 8 +.B direxpand +If set, +.B bash +replaces directory names with the results of word expansion when performing +filename completion. This changes the contents of the readline editing +buffer. +If not set, +.B bash +attempts to preserve what the user typed. +.TP 8 +.B dirspell +If set, +.B bash +attempts spelling correction on directory names during word completion +if the directory name initially supplied does not exist. +.TP 8 +.B dotglob +If set, +.B bash +includes filenames beginning with a `.' in the results of pathname +expansion. +The filenames +.B ``.'' +and +.B ``..'' +must always be matched explicitly, even if +.B dotglob +is set. +.TP 8 +.B execfail +If set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the +.B exec +builtin command. An interactive shell does not exit if +.B exec +fails. +.TP 8 +.B expand_aliases +If set, aliases are expanded as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR ALIASES . +This option is enabled by default for interactive shells. +.TP 8 +.B extdebug +If set at shell invocation, +or in a shell startup file, +arrange to execute the debugger profile +before the shell starts, identical to the \fB\-\-debugger\fP option. +If set after invocation, behavior intended for use by debuggers is enabled: +.RS +.TP +.B 1. +The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source +file name and line number corresponding to each function name supplied +as an argument. +.TP +.B 2. +If the command run by the \fBDEBUG\fP trap returns a non-zero value, the +next command is skipped and not executed. +.TP +.B 3. +If the command run by the \fBDEBUG\fP trap returns a value of 2, and the +shell is executing in a subroutine (a shell function or a shell script +executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates +a call to \fBreturn\fP. +.TP +.B 4. +.SM +.B BASH_ARGC +and +.SM +.B BASH_ARGV +are updated as described in their descriptions +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B 5. +Function tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBDEBUG\fP and \fBRETURN\fP traps. +.TP +.B 6. +Error tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBERR\fP trap. +.RE +.TP 8 +.B extglob +If set, the extended pattern matching features described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +\fBPathname Expansion\fP are enabled. +.TP 8 +.B extquote +If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is +performed within \fB${\fP\fIparameter\fP\fB}\fP expansions +enclosed in double quotes. This option is enabled by default. +.TP 8 +.B failglob +If set, patterns which fail to match filenames during pathname expansion +result in an expansion error. +.TP 8 +.B force_fignore +If set, the suffixes specified by the +.SM +.B FIGNORE +shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +See +.SM +\fBSHELL VARIABLES\fP +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +for a description of +.SM +.BR FIGNORE . +This option is enabled by default. +.TP 8 +.B globasciiranges +If set, range expressions used in pattern matching bracket expressions (see +.SM +.B Pattern Matching +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +behave as if in the traditional C locale when performing +comparisons. That is, the current locale's collating sequence +is not taken into account, so +.B b +will not collate between +.B A +and +.BR B , +and upper-case and lower-case ASCII characters will collate together. +.TP 8 +.B globskipdots +If set, pathname expansion will never match the filenames +.B ``.'' +and +.BR ``..'' , +even if the pattern begins with a +.BR ``.'' . +This option is enabled by default. +.TP 8 +.B globstar +If set, the pattern \fB**\fP used in a pathname expansion context will +match all files and zero or more directories and subdirectories. +If the pattern is followed by a \fB/\fP, only directories and +subdirectories match. +.TP 8 +.B gnu_errfmt +If set, shell error messages are written in the standard GNU error +message format. +.TP 8 +.B histappend +If set, the history list is appended to the file named by the value +of the +.SM +.B HISTFILE +variable when the shell exits, rather than overwriting the file. +.TP 8 +.B histreedit +If set, and +.B readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. +.TP 8 +.B histverify +If set, and +.B readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the \fBreadline\fP editing buffer, allowing further modification. +.TP 8 +.B hostcomplete +If set, and +.B readline +is being used, \fBbash\fP will attempt to perform hostname completion when a +word containing a \fB@\fP is being completed (see +.B Completing +under +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is enabled by default. +.TP 8 +.B huponexit +If set, \fBbash\fP will send +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.TP 8 +.B inherit_errexit +If set, command substitution inherits the value of the \fBerrexit\fP option, +instead of unsetting it in the subshell environment. +This option is enabled when \fIposix mode\fP is enabled. +.TP 8 +.B interactive_comments +If set, allow a word beginning with +.B # +to cause that word and all remaining characters on that +line to be ignored in an interactive shell (see +.SM +.B COMMENTS +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This option is enabled by default. +.TP 8 +.B lastpipe +If set, and job control is not active, the shell runs the last command of +a pipeline not executed in the background in the current shell environment. +.TP 8 +.B lithist +If set, and the +.B cmdhist +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. +.TP 8 +.B localvar_inherit +If set, local variables inherit the value and attributes of a variable of +the same name that exists at a previous scope before any new value is +assigned. The nameref attribute is not inherited. +.TP 8 +.B localvar_unset +If set, calling \fBunset\fP on local variables in previous function scopes +marks them so subsequent lookups find them unset until that function +returns. This is identical to the behavior of unsetting local variables +at the current function scope. +.TP 8 +.B login_shell +The shell sets this option if it is started as a login shell (see +.SM +.B "INVOCATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The value may not be changed. +.TP 8 +.B mailwarn +If set, and a file that \fBbash\fP is checking for mail has been +accessed since the last time it was checked, the message ``The mail in +\fImailfile\fP has been read'' is displayed. +.TP 8 +.B no_empty_cmd_completion +If set, and +.B readline +is being used, +.B bash +will not attempt to search the +.SM +.B PATH +for possible completions when +completion is attempted on an empty line. +.TP 8 +.B nocaseglob +If set, +.B bash +matches filenames in a case\-insensitive fashion when performing pathname +expansion (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B nocasematch +If set, +.B bash +matches patterns in a case\-insensitive fashion when performing matching +while executing \fBcase\fP or \fB[[\fP conditional commands, +when performing pattern substitution word expansions, +or when filtering possible completions as part of programmable completion. +.TP 8 +.B noexpand_translation +If set, +.B bash +encloses the translated results of $"..." quoting in single quotes +instead of double quotes. +If the string is not translated, this has no effect. +.TP 8 +.B nullglob +If set, +.B bash +allows patterns which match no +files (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +to expand to a null string, rather than themselves. +.TP 8 +.B patsub_replacement +If set, \fBbash\fP +expands occurrences of \fB&\fP in the replacement string of pattern +substitution to the text matched by the pattern, as described +under \fBParameter Expansion\fP +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B progcomp +If set, the programmable completion facilities (see +\fBProgrammable Completion\fP +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +are enabled. +This option is enabled by default. +.TP 8 +.B progcomp_alias +If set, and programmable completion is enabled, \fBbash\fP treats a command +name that doesn't have any completions as a possible alias and attempts +alias expansion. If it has an alias, \fBbash\fP attempts programmable +completion using the command word resulting from the expanded alias. +.TP 8 +.B promptvars +If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded as described in +.SM +.B PROMPTING +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B restricted_shell +The shell sets this option if it is started in restricted mode +(see +.SM +.B "RESTRICTED SHELL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. +.TP 8 +.B shift_verbose +If set, the +.B shift +builtin prints an error message when the shift count exceeds the +number of positional parameters. +.TP 8 +.B sourcepath +If set, the +\fB.\fP (\fBsource\fP) builtin uses the value of +.SM +.B PATH +to find the directory containing the file supplied as an argument. +This option is enabled by default. +.TP 8 +.B varredir_close +If set, the shell automatically closes file descriptors assigned using the +\fI{varname}\fP redirection syntax (see +.SM +.B REDIRECTION +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +instead of leaving them open when the command completes. +.TP 8 +.B syslog_history +If set, command history is logged to syslog. +.TP 8 +.B xpg_echo +If set, the \fBecho\fP builtin expands backslash-escape sequences +by default. +.RE +.PD +.TP +\fBsuspend\fP [\fB\-f\fP] +Suspend the execution of this shell until it receives a +.SM +.B SIGCONT +signal. A login shell, +or a shell without job control enabled, +cannot be suspended; the +.B \-f +option can be used to override this and force the suspension. +The return status is 0 unless the shell is a login shell +or job control is not enabled +and +.B \-f +is not supplied. +.TP +\fBtest\fP \fIexpr\fP +.PD 0 +.TP +\fB[\fP \fIexpr\fP \fB]\fP +Return a status of 0 (true) or 1 (false) depending on +the evaluation of the conditional expression +.IR expr . +Each operator and operand must be a separate argument. +Expressions are composed of the primaries described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +\fBtest\fP does not accept any options, nor does it accept and ignore +an argument of \fB\-\-\fP as signifying the end of options. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence. +The evaluation depends on the number of arguments; see below. +Operator precedence is used when there are five or more arguments. +.RS +.PD 0 +.TP +.B ! \fIexpr\fP +True if +.I expr +is false. +.TP +.B ( \fIexpr\fP ) +Returns the value of \fIexpr\fP. +This may be used to override the normal precedence of operators. +.TP +\fIexpr1\fP \-\fBa\fP \fIexpr2\fP +True if both +.I expr1 +and +.I expr2 +are true. +.TP +\fIexpr1\fP \-\fBo\fP \fIexpr2\fP +True if either +.I expr1 +or +.I expr2 +is true. +.PD +.PP +\fBtest\fP and \fB[\fP evaluate conditional +expressions using a set of rules based on the number of arguments. +.if t .sp 0.5 +.if n .sp 1 +.PD 0 +.TP +0 arguments +The expression is false. +.TP +1 argument +The expression is true if and only if the argument is not null. +.TP +2 arguments +If the first argument is \fB!\fP, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the expression is true if the unary test is true. +If the first argument is not a valid unary conditional operator, the expression +is false. +.TP +3 arguments +The following conditions are applied in the order listed. +If the second argument is one of the binary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the result of the expression is the result of the binary test using +the first and third arguments as operands. +The \fB\-a\fP and \fB\-o\fP operators are considered binary operators +when there are three arguments. +If the first argument is \fB!\fP, the value is the negation of +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the third argument is +exactly \fB)\fP, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. +.TP +4 arguments +The following conditions are applied in the order listed. +If the first argument is \fB!\fP, the result is the negation of +the three-argument expression composed of the remaining arguments. +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the fourth argument is +exactly \fB)\fP, the result is the two-argument test of the second +and third arguments. +Otherwise, the expression is parsed and evaluated according to +precedence using the rules listed above. +.TP +5 or more arguments +The expression is parsed and evaluated according to precedence +using the rules listed above. +.if t .sp 0.5 +.if n .sp 1 +.LP +When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators +sort lexicographically using ASCII ordering. +.RE +.PD +.TP +.B times +Print the accumulated user and system times for the shell and +for processes run from the shell. The return status is 0. +.TP +\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...] +The command +.I arg +is to be read and executed when the shell receives +signal(s) +.IR sigspec . +If +.I arg +is absent (and there is a single \fIsigspec\fP) or +.BR \- , +each specified signal is +reset to its original disposition (the value it had +upon entrance to the shell). +If +.I arg +is the null string the signal specified by each +.I sigspec +is ignored by the shell and by the commands it invokes. +If +.I arg +is not present and +.B \-p +has been supplied, then the trap commands associated with each +.I sigspec +are displayed. +If no arguments are supplied or if only +.B \-p +is given, +.B trap +prints the list of commands associated with each signal. +The +.B \-l +option causes the shell to print a list of signal names and +their corresponding numbers. +Each +.I sigspec +is either +a signal name defined in <\fIsignal.h\fP>, or a signal number. +Signal names are case insensitive and the +.SM +.B SIG +prefix is optional. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.B EXIT +(0) the command +.I arg +is executed on exit from the shell. +If a +.I sigspec +is +.SM +.BR DEBUG , +the command +.I arg +is executed before every \fIsimple command\fP, \fIfor\fP command, +\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP +command, and before the first command executes in a shell function (see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +Refer to the description of the \fBextdebug\fP option to the +\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap. +If a +.I sigspec +is +.SM +.BR RETURN , +the command +.I arg +is executed each time a shell function or a script executed with +the \fB.\fP or \fBsource\fP builtins finishes executing. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.BR ERR , +the command +.I arg +is executed whenever +a pipeline (which may consist of a single simple +command), a list, or a compound command returns a +non\-zero exit status, +subject to the following conditions. +The +.SM +.B ERR +trap is not executed if the failed +command is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test in an +.I if +statement, part of a command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted using +.BR ! . +These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option. +.if t .sp 0.5 +.if n .sp 1 +Signals ignored upon entry to the shell cannot be trapped, reset or listed. +Trapped signals that are not being ignored are reset to their original +values in a subshell or subshell environment when one is created. +The return status is false if any +.I sigspec +is invalid; otherwise +.B trap +returns true. +.TP +\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...] +With no options, +indicate how each +.I name +would be interpreted if used as a command name. +If the +.B \-t +option is used, +.B type +prints a string which is one of +.IR alias , +.IR keyword , +.IR function , +.IR builtin , +or +.I file +if +.I name +is an alias, shell reserved word, function, builtin, or disk file, +respectively. +If the +.I name +is not found, then nothing is printed, and an exit status of false +is returned. +If the +.B \-p +option is used, +.B type +either returns the name of the disk file +that would be executed if +.I name +were specified as a command name, +or nothing if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +The +.B \-P +option forces a +.SM +.B PATH +search for each \fIname\fP, even if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +If a command is hashed, +.B \-p +and +.B \-P +print the hashed value, which is not necessarily the file that appears +first in +.SM +.BR PATH . +If the +.B \-a +option is used, +.B type +prints all of the places that contain +an executable named +.IR name . +This includes aliases and functions, +if and only if the +.B \-p +option is not also used. +The table of hashed commands is not consulted +when using +.BR \-a . +The +.B \-f +option suppresses shell function lookup, as with the \fBcommand\fP builtin. +.B type +returns true if all of the arguments are found, false if +any are not found. +.TP +\fBulimit\fP [\fB\-HS\fP] \fB\-a\fP +.PD 0 +.TP +\fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]] +.PD +Provides control over the resources available to the shell and to +processes started by it, on systems that allow such control. +The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is +set for the given resource. +A hard limit cannot be increased by a non-root user once it is set; +a soft limit may be increased up to the value of the hard limit. +If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard +limits are set. +The value of +.I limit +can be a number in the unit specified for the resource +or one of the special values +.BR hard , +.BR soft , +or +.BR unlimited , +which stand for the current hard limit, the current soft limit, and +no limit, respectively. +If +.I limit +is omitted, the current value of the soft limit of the resource is +printed, unless the \fB\-H\fP option is given. When more than one +resource is specified, the limit name and unit, if appropriate, +are printed before the value. +Other options are interpreted as follows: +.RS +.PD 0 +.TP +.B \-a +All current limits are reported; no limits are set +.TP +.B \-b +The maximum socket buffer size +.TP +.B \-c +The maximum size of core files created +.TP +.B \-d +The maximum size of a process's data segment +.TP +.B \-e +The maximum scheduling priority ("nice") +.TP +.B \-f +The maximum size of files written by the shell and its children +.TP +.B \-i +The maximum number of pending signals +.TP +.B \-k +The maximum number of kqueues that may be allocated +.TP +.B \-l +The maximum size that may be locked into memory +.TP +.B \-m +The maximum resident set size (many systems do not honor this limit) +.TP +.B \-n +The maximum number of open file descriptors (most systems do not +allow this value to be set) +.TP +.B \-p +The pipe size in 512-byte blocks (this may not be set) +.TP +.B \-q +The maximum number of bytes in POSIX message queues +.TP +.B \-r +The maximum real-time scheduling priority +.TP +.B \-s +The maximum stack size +.TP +.B \-t +The maximum amount of cpu time in seconds +.TP +.B \-u +The maximum number of processes available to a single user +.TP +.B \-v +The maximum amount of virtual memory available to the shell and, on +some systems, to its children +.TP +.B \-x +The maximum number of file locks +.TP +.B \-P +The maximum number of pseudoterminals +.TP +.B \-R +The maximum time a real-time process can run before blocking, in microseconds +.TP +.B \-T +The maximum number of threads +.PD +.PP +If +.I limit +is given, and the +.B \-a +option is not used, +\fIlimit\fP is the new value of the specified resource. +If no option is given, then +.B \-f +is assumed. Values are in 1024-byte increments, except for +.BR \-t , +which is in seconds; +.BR \-R , +which is in microseconds; +.BR \-p , +which is in units of 512-byte blocks; +.BR \-P , +.BR \-T , +.BR \-b , +.BR \-k , +.BR \-n , +and +.BR \-u , +which are unscaled values; +and, when in posix mode, +.B \-c +and +.BR \-f , +which are in 512-byte increments. +The return status is 0 unless an invalid option or argument is supplied, +or an error occurs while setting a new limit. +In POSIX Mode 512-byte blocks are used for the `-c' and `-f' options. +.RE +.TP +\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP] +The user file-creation mask is set to +.IR mode . +If +.I mode +begins with a digit, it +is interpreted as an octal number; otherwise +it is interpreted as a symbolic mode mask similar +to that accepted by +.IR chmod (1). +If +.I mode +is omitted, the current value of the mask is printed. +The +.B \-S +option causes the mask to be printed in symbolic form; the +default output is an octal number. +If the +.B \-p +option is supplied, and +.I mode +is omitted, the output is in a form that may be reused as input. +The return status is 0 if the mode was successfully changed or if +no \fImode\fP argument was supplied, and false otherwise. +.TP +\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] +Remove each \fIname\fP from the list of defined aliases. If +.B \-a +is supplied, all alias definitions are removed. The return +value is true unless a supplied +.I name +is not a defined alias. +.TP +\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...] +For each +.IR name , +remove the corresponding variable or function. +If the +.B \-v +option is given, each +.I name +refers to a shell variable, and that variable is removed. +Read-only variables may not be unset. +If +.B \-f +is specified, each +.I name +refers to a shell function, and the function definition +is removed. +If the +.B \-n +option is supplied, and \fIname\fP is a variable with the \fInameref\fP +attribute, \fIname\fP will be unset rather than the variable it +references. +\fB\-n\fP has no effect if the \fB\-f\fP option is supplied. +If no options are supplied, each \fIname\fP refers to a variable; if +there is no variable by that name, a function with that name, if any, is +unset. +Each unset variable or function is removed from the environment +passed to subsequent commands. +If any of +.SM +.BR BASH_ALIASES , +.SM +.BR BASH_ARGV0 , +.SM +.BR BASH_CMDS , +.SM +.BR BASH_COMMAND , +.SM +.BR BASH_SUBSHELL , +.SM +.BR BASHPID , +.SM +.BR COMP_WORDBREAKS , +.SM +.BR DIRSTACK , +.SM +.BR EPOCHREALTIME , +.SM +.BR EPOCHSECONDS , +.SM +.BR FUNCNAME , +.SM +.BR GROUPS , +.SM +.BR HISTCMD , +.SM +.BR LINENO , +.SM +.BR RANDOM , +.SM +.BR SECONDS , +or +.SM +.B SRANDOM +are unset, they lose their special properties, even if they are +subsequently reset. The exit status is true unless a +.I name +is readonly or may not be unset. +.TP +\fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP] +Wait for each specified child process and return its termination status. +Each +.I id +may be a process +ID or a job specification; if a job spec is given, all processes +in that job's pipeline are waited for. If +.I id +is not given, +\fBwait\fP waits for all running background jobs and +the last-executed process substitution, if its process id is the same as +\fB$!\fP, +and the return status is zero. +If the \fB\-n\fP option is supplied, +\fBwait\fP waits for a single job +from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job, +to complete and returns its exit status. +If none of the supplied arguments is a child of the shell, or if no arguments +are supplied and the shell has no unwaited-for children, the exit status +is 127. +If the \fB\-p\fP option is supplied, the process or job identifier of the job +for which the exit status is returned is assigned to the variable +\fIvarname\fP named by the option argument. +The variable will be unset initially, before any assignment. +This is useful only when the \fB\-n\fP option is supplied. +Supplying the \fB\-f\fP option, when job control is enabled, +forces \fBwait\fP to wait for \fIid\fP to terminate before returning +its status, instead of returning when it changes status. +If +.I id +specifies a non-existent process or job, the return status is 127. +If \fBwait\fP is interrupted by a signal, the return status will be greater +than 128, as described under +.B SIGNALS +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +Otherwise, the return status is the exit status of the last +process or job waited for. +.SH "SHELL COMPATIBILITY MODE" +Bash-4.0 introduced the concept of a \fIshell compatibility level\fP, +specified as a set of options to the shopt builtin ( +.BR compat31 , +.BR compat32 , +.BR compat40 , +.BR compat41 , +and so on). +There is only one current +compatibility level -- each option is mutually exclusive. +The compatibility level is intended to allow users to select behavior +from previous versions that is incompatible with newer versions +while they migrate scripts to use current features and +behavior. It's intended to be a temporary solution. +.PP +This section does not mention behavior that is standard for a particular +version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp +matching operator quotes special regexp characters in the word, which is +default behavior in bash-3.2 and subsequent versions). +.PP +If a user enables, say, \fBcompat32\fP, it may affect the behavior of other +compatibility levels up to and including the current compatibility level. +The idea is that each compatibility level controls behavior that changed +in that version of \fBbash\fP, +but that behavior may have been present in earlier versions. +For instance, the change to use locale-based comparisons with the \fB[[\fP +command came in bash-4.1, and earlier versions used ASCII-based comparisons, +so enabling \fBcompat32\fP will enable ASCII-based comparisons as well. +That granularity may not be sufficient for +all uses, and as a result users should employ compatibility levels carefully. +Read the documentation for a particular feature to find out the +current behavior. +.PP +Bash-4.3 introduced a new shell variable: +.SM +.BR BASH_COMPAT . +The value assigned +to this variable (a decimal version number like 4.2, or an integer +corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the +compatibility level. +.PP +Starting with bash-4.4, Bash has begun deprecating older compatibility +levels. +Eventually, the options will be removed in favor of +.SM +.BR BASH_COMPAT . +.PP +Bash-5.0 is the final version for which there will be an individual shopt +option for the previous version. Users should use +.SM +.B BASH_COMPAT +on bash-5.0 and later versions. +.PP +The following table describes the behavior changes controlled by each +compatibility level setting. +The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the +compatibility level +to \fINN\fP using one of the following mechanisms. +For versions prior to bash-5.0, the compatibility level may be set using +the corresponding \fBcompat\fP\fINN\fP shopt option. +For bash-4.3 and later versions, the +.SM +.B BASH_COMPAT +variable is preferred, +and it is required for bash-5.1 and later versions. +.TP +\fBcompat31\fP +.PD 0 +.RS +.IP \(bu +quoting the rhs of the \fB[[\fP command's regexp matching operator (=~) +has no special effect +.RE +.PD +.TP +\fBcompat32\fP +.PD 0 +.RS +.IP \(bu +interrupting a command list such as "a ; b ; c" causes the execution +of the next command in the list (in bash-4.0 and later versions, +the shell acts as if it received the interrupt, so +interrupting one command in a list aborts the execution of the +entire list) +.RE +.PD +.TP +\fBcompat40\fP +.PD 0 +.RS +.IP \(bu +the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not +consider the current locale when comparing strings; they use ASCII +ordering. +Bash versions prior to bash-4.1 use ASCII collation and +.IR strcmp (3); +bash-4.1 and later use the current locale's collation sequence and +.IR strcoll (3). +.RE +.PD +.TP +\fBcompat41\fP +.PD 0 +.RS +.IP \(bu +in \fIposix\fP mode, \fBtime\fP may be followed by options and still be +recognized as a reserved word (this is POSIX interpretation 267) +.IP \(bu +in \fIposix\fP mode, the parser requires that an even number of single +quotes occur in the \fIword\fP portion of a double-quoted +parameter expansion and treats them specially, so that characters within +the single quotes are considered quoted +(this is POSIX interpretation 221) +.RE +.PD +.TP +\fBcompat42\fP +.PD 0 +.RS +.IP \(bu +the replacement string in double-quoted pattern substitution does not +undergo quote removal, as it does in versions after bash-4.2 +.IP \(bu +in posix mode, single quotes are considered special when expanding +the \fIword\fP portion of a double-quoted parameter expansion +and can be used to quote a closing brace or other special character +(this is part of POSIX interpretation 221); +in later versions, single quotes +are not special within double-quoted word expansions +.RE +.PD +.TP +\fBcompat43\fP +.PD 0 +.RS +.IP \(bu +the shell does not print a warning message if an attempt is made to +use a quoted compound assignment as an argument to declare +(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is +deprecated +.IP \(bu +word expansion errors are considered non-fatal errors that cause the +current command to fail, even in posix mode +(the default behavior is to make them fatal errors that cause the shell +to exit) +.IP \(bu +when executing a shell function, the loop state (while/until/etc.) +is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break +or continue loops in the calling context. Bash-4.4 and later reset +the loop state to prevent this +.RE +.PD +.TP +\fBcompat44\fP +.PD 0 +.RS +.IP \(bu +the shell sets up the values used by +.SM +.B BASH_ARGV +and +.SM +.B BASH_ARGC +so they can expand to the shell's positional parameters even if extended +debugging mode is not enabled +.IP \(bu +a subshell inherits loops from its parent context, so \fBbreak\fP +or \fBcontinue\fP will cause the subshell to exit. +Bash-5.0 and later reset the loop state to prevent the exit +.IP \(bu +variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP +that set attributes continue to affect variables with the same +name in the calling environment even if the shell is not in posix +mode +.RE +.PD +.TP +\fBcompat50\fP +.PD 0 +.RS +.IP \(bu +Bash-5.1 changed the way +.SM +.B $RANDOM +is generated to introduce slightly +more randomness. If the shell compatibility level is set to 50 or +lower, it reverts to the method from bash-5.0 and previous versions, +so seeding the random number generator by assigning a value to +.SM +.B RANDOM +will produce the same sequence as in bash-5.0 +.IP \(bu +If the command hash table is empty, bash versions prior to bash-5.1 +printed an informational message to that effect, even when producing +output that can be reused as input. Bash-5.1 suppresses that message +when the \fB\-l\fP option is supplied. +.RE +.PD +.TP +\fBcompat51\fP +.PD 0 +.RS +.IP \(bu +The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP +and \fB*\fP differently depending on whether the array is indexed or +associative, and differently than in previous versions. +.RE +.PD +.\" bash_builtins +.if \n(zZ=1 .ig zZ +.SH "RESTRICTED SHELL" +.\" rbash.1 +.zY +.PP +If +.B bash +is started with the name +.BR rbash , +or the +.B \-r +option is supplied at invocation, +the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +It behaves identically to +.B bash +with the exception that the following are disallowed or not performed: +.IP \(bu +changing directories with \fBcd\fP +.IP \(bu +setting or unsetting the values of +.SM +.BR SHELL , +.SM +.BR PATH , +.SM +.BR HISTFILE , +.SM +.BR ENV , +or +.SM +.B BASH_ENV +.IP \(bu +specifying command names containing +.B / +.IP \(bu +specifying a filename containing a +.B / +as an argument to the +.B . +builtin command +.IP \(bu +specifying a filename containing a slash as an argument to the +.B history +builtin command +.IP \(bu +specifying a filename containing a slash as an argument to the +.B \-p +option to the +.B hash +builtin command +.IP \(bu +importing function definitions from the shell environment at startup +.IP \(bu +parsing the value of +.SM +.B SHELLOPTS +from the shell environment at startup +.IP \(bu +redirecting output using the >, >|, <>, >&, &>, and >> redirection operators +.IP \(bu +using the +.B exec +builtin command to replace the shell with another command +.IP \(bu +adding or deleting builtin commands with the +.B \-f +and +.B \-d +options to the +.B enable +builtin command +.IP \(bu +using the \fBenable\fP builtin command to enable disabled shell builtins +.IP \(bu +specifying the +.B \-p +option to the +.B command +builtin command +.IP \(bu +turning off restricted mode with +\fBset +r\fP or \fBshopt -u restricted_shell\fP. +.PP +These restrictions are enforced after any startup files are read. +.PP +.ie \n(zY=1 When a command that is found to be a shell script is executed, +.el \{ When a command that is found to be a shell script is executed +(see +.SM +.B "COMMAND EXECUTION" +above), +\} +.B rbash +turns off any restrictions in the shell spawned to execute the +script. +.\" end of rbash.1 +.if \n(zY=1 .ig zY +.SH "SEE ALSO" +.PD 0 +.TP +\fIBash Reference Manual\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE -- +http://pubs.opengroup.org/onlinepubs/9699919799/ +.TP +http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode +.TP +\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) +.TP +\fIemacs\fP(1), \fIvi\fP(1) +.TP +\fIreadline\fP(3) +.PD +.SH FILES +.PD 0 +.TP +.FN /bin/bash +The \fBbash\fP executable +.TP +.FN /etc/profile +The systemwide initialization file, executed for login shells +.TP +.FN /etc/bash.bash_logout +The systemwide login shell cleanup file, executed when a login shell exits +.TP +.FN ~/.bash_profile +The personal initialization file, executed for login shells +.TP +.FN ~/.bashrc +The individual per-interactive-shell startup file +.TP +.FN ~/.bash_logout +The individual login shell cleanup file, executed when a login shell exits +.TP +.FN ~/.bash_history +The default value of \fBHISTFILE\fP, the file in which bash saves the +command history +.TP +.FN ~/.inputrc +Individual \fIreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet.ramey@case.edu +.SH BUG REPORTS +If you find a bug in +.B bash, +you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of +.BR bash . +The latest version is always available from +\fIftp://ftp.gnu.org/pub/gnu/bash/\fP and +\fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP. +.PP +Once you have determined that a bug actually exists, use the +.I bashbug +command to submit a bug report. +If you have a fix, you are encouraged to mail that as well! +Suggestions and `philosophical' bug reports may be mailed +to \fIbug-bash@gnu.org\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +ALL bug reports should include: +.PP +.PD 0 +.TP 20 +The version number of \fBbash\fR +.TP +The hardware and operating system +.TP +The compiler used to compile +.TP +A description of the bug behaviour +.TP +A short script or `recipe' which exercises the bug +.PD +.PP +.I bashbug +inserts the first three items automatically into the template +it provides for filing a bug report. +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet.ramey@case.edu . +.SH BUGS +It's too big and too slow. +.PP +There are some subtle differences between +.B bash +and traditional versions of +.BR sh , +mostly because of the +.SM +.B POSIX +specification. +.PP +Aliases are confusing in some uses. +.PP +Shell builtin commands and functions are not stoppable/restartable. +.PP +Compound commands and command sequences of the form `a ; b ; c' +are not handled gracefully when process suspension is attempted. +When a process is stopped, the shell immediately executes the next +command in the sequence. +It suffices to place the sequence of commands between +parentheses to force it into a subshell, which may be stopped as +a unit. +.PP +Array variables may not (yet) be exported. +.PP +There may be only one active coprocess at a time. +.zZ +.zY diff --git a/upstream/fedora-40/man1/bashbug.1 b/upstream/fedora-40/man1/bashbug.1 new file mode 100644 index 00000000..abcaf482 --- /dev/null +++ b/upstream/fedora-40/man1/bashbug.1 @@ -0,0 +1,67 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Case Western Reserve University +.\" chet@po.cwru.edu +.\" +.\" Last Change: Sun Aug 2 15:39:07 EDT 2020 +.\" +.TH BASHBUG 1 "2020 August 1" "GNU Bash 5.1" +.SH NAME +bashbug \- report a bug in bash +.SH SYNOPSIS +\fBbashbug\fP [\fI--version\fP] [\fI--help\fP] [\fIemail-address\fP] +.SH DESCRIPTION +.B bashbug +is a shell script to help the user compose and mail bug reports +concerning bash in a standard format. +.B bashbug +invokes the editor specified by the environment variable +.SM +.B EDITOR +on a temporary copy of the bug report format outline. The user must +fill in the appropriate fields and exit the editor. +.B bashbug +then mails the completed report to \fIbug-bash@gnu.org\fP, or +\fIemail-address\fP. If the report cannot be mailed, it is saved in the +file \fIdead.bashbug\fP in the invoking user's home directory. +.PP +The bug report format outline consists of several sections. The first +section provides information about the machine, operating system, the +bash version, and the compilation environment. The second section +should be filled in with a description of the bug. The third section +should be a description of how to reproduce the bug. The optional +fourth section is for a proposed fix. Fixes are encouraged. +.SH ENVIRONMENT +.B bashbug +will utilize the following environment variables if they exist: +.TP +.B EDITOR +Specifies the preferred editor. If +.SM +.B EDITOR +is not set, +.B bashbug +attempts to locate a number of alternative editors, including +.BR emacs . +If +.B bashbug +cannot locate any of the alternative editors, it attempts to execute \fBvi\fP. +.TP +.B HOME +Directory in which the failed bug report is saved if the mail fails. +.TP +.B TMPDIR +Directory in which to create temporary files and directories. +.SH "SEE ALSO" +.TP +\fIbash\fP(1) +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet@po.cwru.edu diff --git a/upstream/fedora-40/man1/bc.1 b/upstream/fedora-40/man1/bc.1 new file mode 100644 index 00000000..7ff6a2d7 --- /dev/null +++ b/upstream/fedora-40/man1/bc.1 @@ -0,0 +1,825 @@ +.\" +.\" bc.1 - the *roff document processor source for the bc manual +.\" +.\" This file is part of GNU bc. +.\" Copyright (C) 1991-1994, 1997, 2000, 2003, 2006, 2017 Free Software Foundation, Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License , or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; see the file COPYING. If not, write to: +.\" The Free Software Foundation, Inc. +.\" 51 Franklin Street, Fifth Floor +.\" Boston, MA 02110-1301 USA +.\" +.\" You may contact the author by: +.\" e-mail: philnelson@acm.org +.\" us-mail: Philip A. Nelson +.\" Computer Science Department, 9062 +.\" Western Washington University +.\" Bellingham, WA 98226-9062 +.\" +.\" +.TH bc 1 "2006-06-11" "GNU Project" +.SH NAME +bc - An arbitrary precision calculator language +.SH SYNTAX +\fBbc\fR [ \fB-hlwsqv\fR ] [long-options] [ \fI file ...\fR ] +.SH DESCRIPTION +\fBbc\fR is a language that supports arbitrary precision numbers +with interactive execution of statements. There are some similarities +in the syntax to the C programming language. +A standard math library is available by command line option. +If requested, the math library is defined before processing any files. +\fBbc\fR starts by processing code from all the files listed +on the command line in the order listed. After all files have been +processed, \fBbc\fR reads from the standard input. All code is +executed as it is read. (If a file contains a command to halt the +processor, \fBbc\fR will never read from the standard input.) +.PP +This version of \fBbc\fR contains several extensions beyond +traditional \fBbc\fR implementations and the POSIX draft standard. +Command line options can cause these extensions to print a warning +or to be rejected. This +document describes the language accepted by this processor. +Extensions will be identified as such. +.SS OPTIONS +.IP "-h, --help" +Print the usage and exit. +.IP "-i, --interactive" +Force interactive mode. +.IP "-l, --mathlib" +Define the standard math library. +.IP "-w, --warn" +Give warnings for extensions to POSIX \fBbc\fR. +.IP "-s, --standard" +Process exactly the POSIX \fBbc\fR language. +.IP "-q, --quiet" +Do not print the normal GNU bc welcome. +.IP "-v, --version" +Print the version number and copyright and quit. +.SS NUMBERS +The most basic element in \fBbc\fR is the number. Numbers are +arbitrary precision numbers. This precision is both in the integer +part and the fractional part. All numbers are represented internally +in decimal and all computation is done in decimal. (This version +truncates results from divide and multiply operations.) There are two +attributes of numbers, the length and the scale. The length is the +total number of decimal digits used by \fBbc\fR to represent a number +and the scale is the total number of decimal digits after the decimal +point. For example: +.nf +.RS + .000001 has a length of 6 and scale of 6. + 1935.000 has a length of 7 and a scale of 3. +.RE +.fi +.SS VARIABLES +Numbers are stored in two types of variables, simple variables and +arrays. Both simple variables and array variables are named. Names +begin with a letter followed by any number of letters, digits and +underscores. All letters must be lower case. (Full alpha-numeric +names are an extension. In POSIX \fBbc\fR all names are a single +lower case letter.) The type of variable is clear by the context +because all array variable names will be followed by brackets ([]). +.PP +There are four special variables, \fBscale, ibase, obase,\fR and +\fBlast\fR. \fBscale\fR defines how some operations use digits after the +decimal point. The default value of \fBscale\fR is 0. \fBibase\fR +and \fBobase\fR define the conversion base for input and output +numbers. The default for both input and output is base 10. +\fBlast\fR (an extension) is a variable that has the value of the last +printed number. These will be discussed in further detail where +appropriate. All of these variables may have values assigned to them +as well as used in expressions. +.SS COMMENTS +Comments in \fBbc\fR start with the characters \fB/*\fR and end with +the characters \fB*/\fR. Comments may start anywhere and appear as a +single space in the input. (This causes comments to delimit other +input items. For example, a comment can not be found in the middle of +a variable name.) Comments include any newlines (end of line) between +the start and the end of the comment. +.PP +To support the use of scripts for \fBbc\fR, a single line comment has been +added as an extension. A single line comment starts at a \fB#\fR +character and continues to the next end of the line. The end of line +character is not part of the comment and is processed normally. +.SS EXPRESSIONS +The numbers are manipulated by expressions and statements. Since +the language was designed to be interactive, statements and expressions +are executed as soon as possible. There is no "main" program. Instead, +code is executed as it is encountered. (Functions, discussed in +detail later, are defined when encountered.) +.PP +A simple expression is just a constant. \fBbc\fR converts constants +into internal decimal numbers using the current input base, specified +by the variable \fBibase\fR. (There is an exception in functions.) +The legal values of \fBibase\fR are 2 through 36. (Bases greater than +16 are an extension.) Assigning a value outside this range to +\fBibase\fR will result in a value of 2 or 36. Input numbers may +contain the characters 0-9 and A-Z. (Note: They must be capitals. +Lower case letters are variable names.) Single digit numbers always +have the value of the digit regardless of the value of +\fBibase\fR. (i.e. A = 10.) For multi-digit numbers, \fBbc\fR changes +all input digits greater or equal to ibase to the value of +\fBibase\fR-1. This makes the number \fBZZZ\fR always be the largest +3 digit number of the input base. +.PP +Full expressions are similar to many other high level languages. +Since there is only one kind of number, there are no rules for mixing +types. Instead, there are rules on the scale of expressions. Every +expression has a scale. This is derived from the scale of original +numbers, the operation performed and in many cases, the value of the +variable \fBscale\fR. Legal values of the variable \fBscale\fR are +0 to the maximum number representable by a C integer. +.PP +In the following descriptions of legal expressions, "expr" refers to a +complete expression and "var" refers to a simple or an array variable. +A simple variable is just a +.RS +\fIname\fR +.RE +and an array variable is specified as +.RS +\fIname\fR[\fIexpr\fR] +.RE +Unless specifically +mentioned the scale of the result is the maximum scale of the +expressions involved. +.IP "- expr" +The result is the negation of the expression. +.IP "++ var" +The variable is incremented by one and the new value is the result of +the expression. +.IP "-- var" +The variable +is decremented by one and the new value is the result of the +expression. +.IP "var ++" + The result of the expression is the value of +the variable and then the variable is incremented by one. +.IP "var --" +The result of the expression is the value of the variable and then +the variable is decremented by one. +.IP "expr + expr" +The result of the expression is the sum of the two expressions. +.IP "expr - expr" +The result of the expression is the difference of the two expressions. +.IP "expr * expr" +The result of the expression is the product of the two expressions. +If a and b are the scales of the two expressions, then the scale of the result is: +min(a+b,max(scale,a,b)) +.IP "expr / expr" +The result of the expression is the quotient of the two expressions. +The scale of the result is the value of the variable \fBscale\fR. +.IP "expr % expr" +The result of the expression is the "remainder" and it is computed in the +following way. To compute a%b, first a/b is computed to \fBscale\fR +digits. That result is used to compute a-(a/b)*b to the scale of the +maximum of \fBscale\fR+scale(b) and scale(a). If \fBscale\fR is set +to zero and both expressions are integers this expression is the +integer remainder function. +.IP "expr ^ expr" +The result of the expression is the value of the first raised to the +second. The second expression must be an integer. (If the second +expression is not an integer, a warning is generated and the +expression is truncated to get an integer value.) The scale of the +result is \fBscale\fR if the exponent is negative. If the exponent +is positive the scale of the result is the minimum of the scale of the +first expression times the value of the exponent and the maximum of +\fBscale\fR and the scale of the first expression. (e.g. scale(a^b) += min(scale(a)*b, max( \fBscale,\fR scale(a))).) It should be noted +that expr^0 will always return the value of 1. +.IP "( expr )" +This alters the standard precedence to force the evaluation of the +expression. +.IP "var = expr" +The variable is assigned the value of the expression. +.IP "var = expr" +This is equivalent to "var = var expr" with the exception that +the "var" part is evaluated only once. This can make a difference if +"var" is an array. +.PP +Relational expressions are a special kind of expression +that always evaluate to 0 or 1, 0 if the relation is false and 1 if +the relation is true. These may appear in any legal expression. +(POSIX bc requires that relational expressions are used only in if, +while, and for statements and that only one relational test may be +done in them.) The relational operators are +.IP "expr1 < expr2" +The result is 1 if expr1 is strictly less than expr2. +.IP "expr1 <= expr2" +The result is 1 if expr1 is less than or equal to expr2. +.IP "expr1 > expr2" +The result is 1 if expr1 is strictly greater than expr2. +.IP "expr1 >= expr2" +The result is 1 if expr1 is greater than or equal to expr2. +.IP "expr1 == expr2" +The result is 1 if expr1 is equal to expr2. +.IP "expr1 != expr2" +The result is 1 if expr1 is not equal to expr2. +.PP +Boolean operations are also legal. (POSIX \fBbc\fR does NOT have +boolean operations). The result of all boolean operations are 0 and 1 +(for false and true) as in relational expressions. The boolean +operators are: +.IP "!expr" +The result is 1 if expr is 0. +.IP "expr && expr" +The result is 1 if both expressions are non-zero. +.IP "expr || expr" +The result is 1 if either expression is non-zero. +.PP +The expression precedence is as follows: (lowest to highest) +.nf +.RS +|| operator, left associative +&& operator, left associative +! operator, nonassociative +Relational operators, left associative +Assignment operator, right associative ++ and - operators, left associative +*, / and % operators, left associative +^ operator, right associative +unary - operator, nonassociative +++ and -- operators, nonassociative +.RE +.fi +.PP +This precedence was chosen so that POSIX compliant \fBbc\fR programs +will run correctly. This will cause the use of the relational and +logical operators to have some unusual behavior when used with +assignment expressions. Consider the expression: +.RS +a = 3 < 5 +.RE +.PP +Most C programmers would assume this would assign the result of "3 < +5" (the value 1) to the variable "a". What this does in \fBbc\fR is +assign the value 3 to the variable "a" and then compare 3 to 5. It is +best to use parenthesis when using relational and logical operators +with the assignment operators. +.PP +There are a few more special expressions that are provided in \fBbc\fR. +These have to do with user defined functions and standard +functions. They all appear as "\fIname\fB(\fIparameters\fB)\fR". +See the section on functions for user defined functions. The standard +functions are: +.IP "length ( expression )" +The value of the length function is the number of significant digits in the +expression. +.IP "read ( )" +The read function (an extension) will read a number from the standard +input, regardless of where the function occurs. Beware, this can +cause problems with the mixing of data and program in the standard input. +The best use for this function is in a previously written program that +needs input from the user, but never allows program code to be input +from the user. The value of the read function is the number read from +the standard input using the current value of the variable +\fBibase\fR for the conversion base. +.IP "scale ( expression )" +The value of the scale function is the number of digits after the decimal +point in the expression. +.IP "sqrt ( expression )" +The value of the sqrt function is the square root of the expression. If +the expression is negative, a run time error is generated. +.SS STATEMENTS +Statements (as in most algebraic languages) provide the sequencing of +expression evaluation. In \fBbc\fR statements are executed "as soon +as possible." Execution happens when a newline in encountered and +there is one or more complete statements. Due to this immediate +execution, newlines are very important in \fBbc\fR. In fact, both a +semicolon and a newline are used as statement separators. An +improperly placed newline will cause a syntax error. Because newlines +are statement separators, it is possible to hide a newline by using +the backslash character. The sequence "\e", where is the +newline appears to \fBbc\fR as whitespace instead of a newline. A +statement list is a series of statements separated by semicolons and +newlines. The following is a list of \fBbc\fR statements and what +they do: (Things enclosed in brackets ([]) are optional parts of the +statement.) +.IP "expression" +This statement does one of two things. If the expression starts with +" ...", it is considered to be an assignment +statement. If the expression is not an assignment statement, the +expression is evaluated and printed to the output. After the number +is printed, a newline is printed. For example, "a=1" is an assignment +statement and "(a=1)" is an expression that has an embedded +assignment. All numbers that are printed are printed in the base +specified by the variable \fBobase\fR. The legal values for \fB +obase\fR are 2 through BC_BASE_MAX. (See the section LIMITS.) For +bases 2 through 16, the usual method of writing numbers is used. For +bases greater than 16, \fBbc\fR uses a multi-character digit method +of printing the numbers where each higher base digit is printed as a +base 10 number. The multi-character digits are separated by spaces. +Each digit contains the number of characters required to represent the +base ten value of "obase-1". Since numbers are of arbitrary +precision, some numbers may not be printable on a single output line. +These long numbers will be split across lines using the "\e" as the +last character on a line. The maximum number of characters printed +per line is 70. Due to the interactive nature of \fBbc\fR, printing +a number causes the side effect of assigning the printed value to the +special variable \fBlast\fR. This allows the user to recover the +last value printed without having to retype the expression that +printed the number. Assigning to \fBlast\fR is legal and will +overwrite the last printed value with the assigned value. The newly +assigned value will remain until the next number is printed or another +value is assigned to \fBlast\fR. (Some installations may allow the +use of a single period (.) which is not part of a number as a short +hand notation for for \fBlast\fR.) +.IP "string" +The string is printed to the output. Strings start with a double quote +character and contain all characters until the next double quote character. +All characters are take literally, including any newline. No newline +character is printed after the string. +.IP "\fBprint\fR list" +The print statement (an extension) provides another method of output. +The "list" is a list of strings and expressions separated by commas. +Each string or expression is printed in the order of the list. No +terminating newline is printed. Expressions are evaluated and their +value is printed and assigned to the variable \fBlast\fR. Strings +in the print statement are printed to the output and may contain +special characters. Special characters start with the backslash +character (\e). The special characters recognized by \fBbc\fR are +"a" (alert or bell), "b" (backspace), "f" (form feed), "n" (newline), +"r" (carriage return), "q" (double quote), "t" (tab), and "\e" (backslash). +Any other character following the backslash will be ignored. +.IP "{ statement_list }" +This is the compound statement. It allows multiple statements to be +grouped together for execution. +.IP "\fBif\fR ( expression ) statement1 [\fBelse\fR statement2]" +The if statement evaluates the expression and executes statement1 or +statement2 depending on the value of the expression. If the expression +is non-zero, statement1 is executed. If statement2 is present and +the value of the expression is 0, then statement2 is executed. (The +else clause is an extension.) +.IP "\fBwhile\fR ( expression ) statement" +The while statement will execute the statement while the expression +is non-zero. It evaluates the expression before each execution of +the statement. Termination of the loop is caused by a zero +expression value or the execution of a break statement. +.IP "\fBfor\fR ( [expression1] ; [expression2] ; [expression3] ) statement" +The for statement controls repeated execution of the statement. +Expression1 is evaluated before the loop. Expression2 is evaluated +before each execution of the statement. If it is non-zero, the statement +is evaluated. If it is zero, the loop is terminated. After each +execution of the statement, expression3 is evaluated before the reevaluation +of expression2. If expression1 or expression3 are missing, nothing is +evaluated at the point they would be evaluated. +If expression2 is missing, it is the same as substituting +the value 1 for expression2. (The optional expressions are an +extension. POSIX \fBbc\fR requires all three expressions.) +The following is equivalent code for the for statement: +.nf +.RS +expression1; +while (expression2) { + statement; + expression3; +} +.RE +.fi +.IP "\fBbreak\fR" +This statement causes a forced exit of the most recent enclosing while +statement or for statement. +.IP "\fBcontinue\fR" +The continue statement (an extension) causes the most recent enclosing +for statement to start the next iteration. +.IP "\fBhalt\fR" +The halt statement (an extension) is an executed statement that causes +the \fBbc\fR processor to quit only when it is executed. For example, +"if (0 == 1) halt" will not cause \fBbc\fR to terminate because the halt is +not executed. +.IP "\fBreturn\fR" +Return the value 0 from a function. (See the section on functions.) +.IP "\fBreturn\fR ( expression )" +Return the value of the expression from a function. (See the section on +functions.) As an extension, the parenthesis are not required. +.SS PSEUDO STATEMENTS +These statements are not statements in the traditional sense. They are +not executed statements. Their function is performed at "compile" time. +.IP "\fBlimits\fR" +Print the local limits enforced by the local version of \fBbc\fR. This +is an extension. +.IP "\fBquit\fR" +When the quit statement is read, the \fBbc\fR processor +is terminated, regardless of where the quit statement is found. For +example, "if (0 == 1) quit" will cause \fBbc\fR to terminate. +.IP "\fBwarranty\fR" +Print a longer warranty notice. This is an extension. +.SS FUNCTIONS +Functions provide a method of defining a computation that can be executed +later. Functions in +.B bc +always compute a value and return it to the caller. Function definitions +are "dynamic" in the sense that a function is undefined until a definition +is encountered in the input. That definition is then used until another +definition function for the same name is encountered. The new definition +then replaces the older definition. A function is defined as follows: +.nf +.RS +\fBdefine \fIname \fB( \fIparameters \fB) { \fInewline +\fI auto_list statement_list \fB}\fR +.RE +.fi +A function call is just an expression of the form +"\fIname\fB(\fIparameters\fB)\fR". +.PP +Parameters are numbers or arrays (an extension). In the function definition, +zero or more parameters are defined by listing their names separated by +commas. All parameters are call by value parameters. +Arrays are specified in the parameter definition by +the notation "\fIname\fB[]\fR". In the function call, actual parameters +are full expressions for number parameters. The same notation is used +for passing arrays as for defining array parameters. The named array is +passed by value to the function. Since function definitions are dynamic, +parameter numbers and types are checked when a function is called. Any +mismatch in number or types of parameters will cause a runtime error. +A runtime error will also occur for the call to an undefined function. +.PP +The \fIauto_list\fR is an optional list of variables that are for +"local" use. The syntax of the auto list (if present) is "\fBauto +\fIname\fR, ... ;". (The semicolon is optional.) Each \fIname\fR is +the name of an auto variable. Arrays may be specified by using the +same notation as used in parameters. These variables have their +values pushed onto a stack at the start of the function. The +variables are then initialized to zero and used throughout the +execution of the function. At function exit, these variables are +popped so that the original value (at the time of the function call) +of these variables are restored. The parameters are really auto +variables that are initialized to a value provided in the function +call. Auto variables are different than traditional local variables +because if function A calls function B, B may access function +A's auto variables by just using the same name, unless function B has +called them auto variables. Due to the fact that auto variables and +parameters are pushed onto a stack, \fBbc\fR supports recursive functions. +.PP +The function body is a list of \fBbc\fR statements. Again, statements +are separated by semicolons or newlines. Return statements cause the +termination of a function and the return of a value. There are two +versions of the return statement. The first form, "\fBreturn\fR", returns +the value 0 to the calling expression. The second form, +"\fBreturn ( \fIexpression \fB)\fR", computes the value of the expression +and returns that value to the calling expression. There is an implied +"\fBreturn (0)\fR" at the end of every function. This allows a function +to terminate and return 0 without an explicit return statement. +.PP +Functions also change the usage of the variable \fBibase\fR. All +constants in the function body will be converted using the value of +\fBibase\fR at the time of the function call. Changes of \fBibase\fR +will be ignored during the execution of the function except for the +standard function \fBread\fR, which will always use the current value +of \fBibase\fR for conversion of numbers. +.PP +Several extensions have been added to functions. First, the format of +the definition has been slightly relaxed. The standard requires the +opening brace be on the same line as the \fBdefine\fR keyword and all +other parts must be on following lines. This version of \fBbc\fR will +allow any number of newlines before and after the opening brace of the +function. For example, the following definitions are legal. +.nf +.RS +\f(CW +define d (n) { return (2*n); } +define d (n) + { return (2*n); } +\fR +.RE +.fi +.PP +Functions may be defined as \fBvoid\fR. A void +funtion returns no value and thus may not be used in any place that needs +a value. A void function does not produce any output when called by itself +on an input line. The key word \fBvoid\fR is placed between the key word +\fBdefine\fR and the function name. For example, consider the following +session. +.nf +.RS +\f(CW +define py (y) { print "--->", y, "<---", "\en"; } +define void px (x) { print "--->", x, "<---", "\en"; } +py(1) +--->1<--- +0 +px(1) +--->1<--- +\fR +.RE +.fi +Since \fBpy\fR is not a void function, the call of \fBpy(1)\fR prints +the desired output and then prints a second line that is the value of +the function. Since the value of a function that is not given an +explicit return statement is zero, the zero is printed. For \fBpx(1)\fR, +no zero is printed because the function is a void function. +.PP +Also, call by variable for arrays was added. To declare +a call by variable array, the declaration of the array parameter in the +function definition looks like "\fI*name\fB[]\fR". The call to the +function remains the same as call by value arrays. +.SS MATH LIBRARY +If \fBbc\fR is invoked with the \fB-l\fR option, a math library is preloaded +and the default scale is set to 20. The math functions will calculate their +results to the scale set at the time of their call. +The math library defines the following functions: +.IP "s (\fIx\fR)" +The sine of x, x is in radians. +.IP "c (\fIx\fR)" +The cosine of x, x is in radians. +.IP "a (\fIx\fR)" +The arctangent of x, arctangent returns radians. +.IP "l (\fIx\fR)" +The natural logarithm of x. +.IP "e (\fIx\fR)" +The exponential function of raising e to the value x. +.IP "j (\fIn,x\fR)" +The Bessel function of integer order n of x. +.SS EXAMPLES +In /bin/sh, the following will assign the value of "pi" to the shell +variable \fBpi\fR. +.RS +\f(CW +pi=$(echo "scale=10; 4*a(1)" | bc -l) +\fR +.RE +.PP +The following is the definition of the exponential function used in the +math library. This function is written in POSIX \fBbc\fR. +.nf +.RS +\f(CW +scale = 20 + +/* Uses the fact that e^x = (e^(x/2))^2 + When x is small enough, we use the series: + e^x = 1 + x + x^2/2! + x^3/3! + ... +*/ + +define e(x) { + auto a, d, e, f, i, m, v, z + + /* Check the sign of x. */ + if (x<0) { + m = 1 + x = -x + } + + /* Precondition x. */ + z = scale; + scale = 4 + z + .44*x; + while (x > 1) { + f += 1; + x /= 2; + } + + /* Initialize the variables. */ + v = 1+x + a = x + d = 1 + + for (i=2; 1; i++) { + e = (a *= x) / (d *= i) + if (e == 0) { + if (f>0) while (f--) v = v*v; + scale = z + if (m) return (1/v); + return (v/1); + } + v += e + } +} +\fR +.RE +.fi +.PP +The following is code that uses the extended features of \fBbc\fR to +implement a simple program for calculating checkbook balances. This +program is best kept in a file so that it can be used many times +without having to retype it at every use. +.nf +.RS +\f(CW +scale=2 +print "\enCheck book program!\en" +print " Remember, deposits are negative transactions.\en" +print " Exit by a 0 transaction.\en\en" + +print "Initial balance? "; bal = read() +bal /= 1 +print "\en" +while (1) { + "current balance = "; bal + "transaction? "; trans = read() + if (trans == 0) break; + bal -= trans + bal /= 1 +} +quit +\fR +.RE +.fi +.PP +The following is the definition of the recursive factorial function. +.nf +.RS +\f(CW +define f (x) { + if (x <= 1) return (1); + return (f(x-1) * x); +} +\fR +.RE +.fi +.SS READLINE AND LIBEDIT OPTIONS +GNU \fBbc\fR can be compiled (via a configure option) to use the GNU +\fBreadline\fR input editor library or the BSD \fBlibedit\fR library. +This allows the user to do editing of lines before sending them +to \fBbc\fR. It also allows for a history of previous lines typed. +When this option is selected, \fBbc\fR has one more special variable. +This special variable, \fBhistory\fR is the number of lines of history +retained. For \fBreadline\fR, a value of -1 means that an unlimited +number of history lines are retained. Setting the value of +\fBhistory\fR to a positive number restricts the number of history +lines to the number given. The value of 0 disables the history +feature. The default value is 100. For more information, read the +user manuals for the GNU \fBreadline\fR, \fBhistory\fR and BSD \fBlibedit\fR +libraries. One can not enable both \fBreadline\fR and \fBlibedit\fR +at the same time. +.SS DIFFERENCES +This version of +.B bc +was implemented from the POSIX P1003.2/D11 draft and contains +several differences and extensions relative to the draft and +traditional implementations. +It is not implemented in the traditional way using +.I dc(1). +This version is a single process which parses and runs a byte code +translation of the program. There is an "undocumented" option (-c) +that causes the program to output the byte code to +the standard output instead of running it. It was mainly used for +debugging the parser and preparing the math library. +.PP +A major source of differences is +extensions, where a feature is extended to add more functionality and +additions, where new features are added. +The following is the list of differences and extensions. +.IP "LANG environment" +This version does not conform to the POSIX standard in the processing +of the LANG environment variable and all environment variables starting +with LC_. +.IP "names" +Traditional and POSIX +.B bc +have single letter names for functions, variables and arrays. They have +been extended to be multi-character names that start with a letter and +may contain letters, numbers and the underscore character. +.IP "Strings" +Strings are not allowed to contain NUL characters. POSIX says all characters +must be included in strings. +.IP "last" +POSIX \fBbc\fR does not have a \fBlast\fR variable. Some implementations +of \fBbc\fR use the period (.) in a similar way. +.IP "comparisons" +POSIX \fBbc\fR allows comparisons only in the if statement, the while +statement, and the second expression of the for statement. Also, only +one relational operation is allowed in each of those statements. +.IP "if statement, else clause" +POSIX \fBbc\fR does not have an else clause. +.IP "for statement" +POSIX \fBbc\fR requires all expressions to be present in the for statement. +.IP "&&, ||, !" +POSIX \fBbc\fR does not have the logical operators. +.IP "read function" +POSIX \fBbc\fR does not have a read function. +.IP "print statement" +POSIX \fBbc\fR does not have a print statement . +.IP "continue statement" +POSIX \fBbc\fR does not have a continue statement. +.IP "return statement" +POSIX \fBbc\fR requires parentheses around the return expression. +.IP "array parameters" +POSIX \fBbc\fR does not (currently) support array parameters in full. +The POSIX grammar allows for arrays in function definitions, but does +not provide a method to specify an array as an actual parameter. (This +is most likely an oversight in the grammar.) Traditional implementations +of \fBbc\fR have only call by value array parameters. +.IP "function format" +POSIX \fBbc\fR requires the opening brace on the same line as the +\fBdefine\fR key word and the \fBauto\fR statement on the next line. +.IP "=+, =-, =*, =/, =%, =^" +POSIX \fBbc\fR does not require these "old style" assignment operators to +be defined. This version may allow these "old style" assignments. Use +the limits statement to see if the installed version supports them. If +it does support the "old style" assignment operators, the statement +"a =- 1" will decrement \fBa\fR by 1 instead of setting \fBa\fR to the +value -1. +.IP "spaces in numbers" +Other implementations of \fBbc\fR allow spaces in numbers. For example, +"x=1 3" would assign the value 13 to the variable x. The same statement +would cause a syntax error in this version of \fBbc\fR. +.IP "errors and execution" +This implementation varies from other implementations in terms of what +code will be executed when syntax and other errors are found in the +program. If a syntax error is found in a function definition, error +recovery tries to find the beginning of a statement and continue to +parse the function. Once a syntax error is found in the function, the +function will not be callable and becomes undefined. +Syntax errors in the interactive execution code will invalidate the +current execution block. The execution block is terminated by an +end of line that appears after a complete sequence of statements. +For example, +.nf +.RS +a = 1 +b = 2 +.RE +.fi +has two execution blocks and +.nf +.RS +{ a = 1 + b = 2 } +.RE +.fi +has one execution block. Any runtime error will terminate the execution +of the current execution block. A runtime warning will not terminate the +current execution block. +.IP "Interrupts" +During an interactive session, the SIGINT signal (usually generated by +the control-C character from the terminal) will cause execution of the +current execution block to be interrupted. It will display a "runtime" +error indicating which function was interrupted. After all runtime +structures have been cleaned up, a message will be printed to notify the +user that \fBbc\fR is ready for more input. All previously defined functions +remain defined and the value of all non-auto variables are the value at +the point of interruption. All auto variables and function parameters +are removed during the +clean up process. During a non-interactive +session, the SIGINT signal will terminate the entire run of \fBbc\fR. +.SS LIMITS +The following are the limits currently in place for this +.B bc +processor. Some of them may have been changed by an installation. +Use the limits statement to see the actual values. +.IP "BC_BASE_MAX" +The maximum output base is currently set at 999. The maximum input base +is 16. +.IP "BC_DIM_MAX" +This is currently an arbitrary limit of 65535 as distributed. Your +installation may be different. +.IP "BC_SCALE_MAX" +The number of digits after the decimal point is limited to INT_MAX digits. +Also, the number of digits before the decimal point is limited to INT_MAX +digits. +.IP "BC_STRING_MAX" +The limit on the number of characters in a string is INT_MAX characters. +.IP "exponent" +The value of the exponent in the raise operation (^) is limited to LONG_MAX. +.IP "variable names" +The current limit on the number of unique names is 32767 for each of +simple variables, arrays and functions. +.SH ENVIRONMENT VARIABLES +The following environment variables are processed by \fBbc\fR: +.IP "POSIXLY_CORRECT" +This is the same as the \fB-s\fR option. +.IP "BC_ENV_ARGS" +This is another mechanism to get arguments to \fBbc\fR. The +format is the same as the command line arguments. These arguments +are processed first, so any files listed in the environment arguments +are processed before any command line argument files. This allows +the user to set up "standard" options and files to be processed +at every invocation of \fBbc\fR. The files in the environment +variables would typically contain function definitions for functions +the user wants defined every time \fBbc\fR is run. +.IP "BC_LINE_LENGTH" +This should be an integer specifying the number of characters in an +output line for numbers. This includes the backslash and newline characters +for long numbers. As an extension, the value of zero disables the +multi-line feature. Any other value of this variable that is less than +3 sets the line length to 70. +.SH DIAGNOSTICS +If any file on the command line can not be opened, \fBbc\fR will report +that the file is unavailable and terminate. Also, there are compile +and run time diagnostics that should be self-explanatory. +.SH BUGS +Error recovery is not very good yet. +.PP +Email bug reports to +.BR bug-bc@gnu.org . +Be sure to include the word ``bc'' somewhere in the ``Subject:'' field. +.SH AUTHOR +.nf +Philip A. Nelson +philnelson@acm.org +.fi +.SH ACKNOWLEDGEMENTS +The author would like to thank Steve Sommars (Steve.Sommars@att.com) for +his extensive help in testing the implementation. Many great suggestions +were given. This is a much better product due to his involvement. diff --git a/upstream/fedora-40/man1/bioradtopgm.1 b/upstream/fedora-40/man1/bioradtopgm.1 new file mode 100644 index 00000000..7f24e015 --- /dev/null +++ b/upstream/fedora-40/man1/bioradtopgm.1 @@ -0,0 +1,66 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Bioradtopbm User Manual" 0 "28 June 1993" "netpbm documentation" + +.SH NAME +bioradtopgm - convert a Biorad confocal file into a PGM image + +.UN synopsis +.SH SYNOPSIS + +\fBbioradtopgm\fP +[\fB-image#\fP] +[\fIimagedata\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBbioradtopgm\fP reads a Biorad confocal file as input and +produces a PGM image as output. If the resulting image is upside +down, run it through \fBpamflip -tb\fP. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBbioradtopgm\fP recognizes the following +command line option: + + +.TP +\fB-image#\fP +A Biorad image file may contain more than one image. With this option, +you can specify which image to extract (only one at a time). The first +image in the file has number zero. If no +image number is supplied, only information about the image size and +the number of images in the input is printed out. No output is produced. + + +.UN seealso +.SH SEE ALSO +.BR "pamflip" (1)\c +\&, +.BR "pgm" (1)\c +\& + +.UN authors +.SH AUTHORS + +Copyright (C) 1993 by Oliver Trepte +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/bioradtopgm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/bison.1 b/upstream/fedora-40/man1/bison.1 new file mode 100644 index 00000000..c1bb7a23 --- /dev/null +++ b/upstream/fedora-40/man1/bison.1 @@ -0,0 +1,285 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.4. +.TH BISON "1" "September 2021" "GNU Bison 3.8.2" "User Commands" +.SH NAME +bison \- GNU Project parser generator (yacc replacement) +.SH SYNOPSIS +.B bison +[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR +.SH DESCRIPTION +.I Bison +is a parser generator in the style of +.IR yacc (1). +It should be upwardly compatible with input files designed +for +.IR yacc . +.PP +Input files should follow the +.I yacc +convention of ending in +.BR .y . +Unlike +.IR yacc , +the generated files do not have fixed names, but instead use the prefix +of the input file. +Moreover, if you need to put +.I C++ +code in the input file, you can end his name by a C++-like extension +(.ypp or .y++), then bison will follow your extension to name the +output file (.cpp or .c++). +For instance, a grammar description file named +.B parse.yxx +would produce the generated parser in a file named +.BR parse.tab.cxx , +instead of +.IR yacc 's +.B y.tab.c +or old +.I Bison +version's +.BR parse.tab.c . +.PP +This description of the options that can be given to +.I bison +is adapted from the node +.B Invocation +in the +.B bison.texi +manual, which should be taken as authoritative. +.PP +.I Bison +supports both traditional single-letter options and mnemonic long +option names. Long option names are indicated with +.B \-\- +instead of +.BR \- . +Abbreviations for option names are allowed as long as they +are unique. When a long option takes an argument, like +.BR \-\-file-prefix , +connect the option name and the argument with +.BR = . +.PP +Generate a deterministic LR or generalized LR (GLR) parser employing +LALR(1), IELR(1), or canonical LR(1) parser tables. +.PP +Mandatory arguments to long options are mandatory for short options too. +The same is true for optional arguments. +.SS "Operation Modes:" +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help and exit +.TP +\fB\-V\fR, \fB\-\-version\fR +output version information and exit +.TP +\fB\-\-print\-localedir\fR +output directory containing locale\-dependent data +and exit +.TP +\fB\-\-print\-datadir\fR +output directory containing skeletons and XSLT +and exit +.TP +\fB\-u\fR, \fB\-\-update\fR +apply fixes to the source grammar file and exit +.TP +\fB\-f\fR, \fB\-\-feature\fR[=\fI\,FEATURES\/\fR] +activate miscellaneous features +.SS "FEATURES is a list of comma separated words that can include:" +.TP +caret, diagnostics\-show\-caret +show errors with carets +.TP +fixit, diagnostics\-parseable\-fixits +show machine\-readable fixes +.TP +syntax\-only +do not generate any file +.TP +all +all of the above +.TP +none +disable all of the above +.SS "Diagnostics:" +.TP +\fB\-W\fR, \fB\-\-warnings\fR[=\fI\,CATEGORY\/\fR] +report the warnings falling in CATEGORY +.TP +\fB\-\-color\fR[=\fI\,WHEN\/\fR] +whether to colorize the diagnostics +.TP +\fB\-\-style\fR=\fI\,FILE\/\fR +specify the CSS FILE for colorizer diagnostics +.SS "Warning categories include:" +.TP +conflicts\-sr +S/R conflicts (enabled by default) +.TP +conflicts\-rr +R/R conflicts (enabled by default) +.TP +counterexamples, cex +generate conflict counterexamples +.TP +dangling\-alias +string aliases not attached to a symbol +.TP +deprecated +obsolete constructs +.TP +empty\-rule +empty rules without %empty +.TP +midrule\-values +unset or unused midrule values +.TP +precedence +useless precedence and associativity +.TP +yacc +incompatibilities with POSIX Yacc +.TP +other +all other warnings (enabled by default) +.TP +all +all the warnings except 'counterexamples', 'dangling\-alias' and 'yacc' +.TP +no\-CATEGORY +turn off warnings in CATEGORY +.TP +none +turn off all the warnings +.TP +error[=CATEGORY] +treat warnings as errors +.SS "WHEN can be one of the following:" +.TP +always, yes +colorize the output +.TP +never, no +don't colorize the output +.TP +auto, tty +colorize if the output device is a tty +.SS "Tuning the Parser:" +.TP +\fB\-L\fR, \fB\-\-language\fR=\fI\,LANGUAGE\/\fR +specify the output programming language +.TP +\fB\-S\fR, \fB\-\-skeleton\fR=\fI\,FILE\/\fR +specify the skeleton to use +.TP +\fB\-t\fR, \fB\-\-debug\fR +instrument the parser for tracing +same as '\-Dparse.trace' +.TP +\fB\-\-locations\fR +enable location support +.TP +\fB\-D\fR, \fB\-\-define=NAME\fR[=\fI\,VALUE\/\fR] +similar to '%define NAME VALUE' +.TP +\fB\-F\fR, \fB\-\-force\-define=NAME\fR[=\fI\,VALUE\/\fR] +override '%define NAME VALUE' +.TP +\fB\-p\fR, \fB\-\-name\-prefix\fR=\fI\,PREFIX\/\fR +prepend PREFIX to the external symbols +deprecated by '\-Dapi.prefix={PREFIX}' +.TP +\fB\-l\fR, \fB\-\-no\-lines\fR +don't generate '#line' directives +.TP +\fB\-k\fR, \fB\-\-token\-table\fR +include a table of token names +.TP +\fB\-y\fR, \fB\-\-yacc\fR +emulate POSIX Yacc +.SS "Output Files:" +.TP +\fB\-H\fR, \fB\-\-header\fR=\fI\,[FILE]\/\fR +also produce a header file +.TP +\fB\-d\fR +likewise but cannot specify FILE (for POSIX Yacc) +.TP +\fB\-r\fR, \fB\-\-report\fR=\fI\,THINGS\/\fR +also produce details on the automaton +.TP +\fB\-\-report\-file\fR=\fI\,FILE\/\fR +write report to FILE +.TP +\fB\-v\fR, \fB\-\-verbose\fR +same as '\-\-report=state' +.TP +\fB\-b\fR, \fB\-\-file\-prefix\fR=\fI\,PREFIX\/\fR +specify a PREFIX for output files +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +leave output to FILE +.TP +\fB\-g\fR, \fB\-\-graph\fR[=\fI\,FILE\/\fR] +also output a graph of the automaton +.TP +\fB\-\-html\fR[=\fI\,FILE\/\fR] +also output an HTML report of the automaton +.TP +\fB\-x\fR, \fB\-\-xml\fR[=\fI\,FILE\/\fR] +also output an XML report of the automaton +.TP +\fB\-M\fR, \fB\-\-file\-prefix\-map\fR=\fI\,OLD=NEW\/\fR replace prefix OLD with NEW when writing file paths +in output files +.SS "THINGS is a list of comma separated words that can include:" +.TP +states +describe the states +.TP +itemsets +complete the core item sets with their closure +.TP +lookaheads +explicitly associate lookahead tokens to items +.TP +solved +describe shift/reduce conflicts solving +.TP +counterexamples, cex +generate conflict counterexamples +.TP +all +include all the above information +.TP +none +disable the report +.SH AUTHOR +Written by Robert Corbett and Richard Stallman. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Bison home page: . +.br +General help using GNU software: . +.br +For complete documentation, run: info bison. +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +.br +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.BR lex (1), +.BR flex (1), +.BR yacc (1). +.PP +The full documentation for +.B bison +is maintained as a Texinfo manual. If the +.B info +and +.B bison +programs are properly installed at your site, the command +.IP +.B info bison +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/bmptopnm.1 b/upstream/fedora-40/man1/bmptopnm.1 new file mode 100644 index 00000000..bd8777cb --- /dev/null +++ b/upstream/fedora-40/man1/bmptopnm.1 @@ -0,0 +1,96 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Bmptopnm User Manual" 0 "05 December 2018" "netpbm documentation" + +.SH NAME +bmptopnm - convert a BMP file into a PBM, PGM, or PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBbmptopnm\fP + +[\fB-verbose\fP] + +[\fIbmpfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBbmptopnm\fP reads a Microsoft Windows or OS/2 BMP file as +input. and produces a PBM, PGM, or PNM image as output. If the input +is colormapped and contains only black and white, the output is PBM. +If the input is colormapped and contains only black white and gray, +the output is PGM. Otherwise, the output is PPM. +.PP +\fBbmptopnm\fP understands BMP files compressed with run length +encoding (RLE4/RLE8), but not if that encoding includes a "delta" +(which is rare). \fBbmptopnm\fP recognizes the delta and issues an +error message. +.PP +Before Netpbm 10.75 (June 2016), \fBbmptopnm\fP could not convert +Version 4 or Version 5 Windows BMP images. +.PP +\fBbmptopnm\fP cannot convert BMP files compressed with JPEG or PNG +encoding. It recognizes the compression and issues an error message. Before +Netpbm 10.32 (February 2006), \fBbmptopnm\fP couldn't convert RLE8 BMP files +either, and before Netpbm 10.85 (December 2018), it couldn't convert RLE4 +(between 10.32 and 10.85, it would act like it recognized the format, but +produce garbage output). +.PP +Before Netpbm 10.18 (September 2003), this program could not convert +BMP images with the BI_BITFIELDS format ("compression type"). It would +recognize the format and issue an error message. +.PP +\fBbmptopnm\fP cannot convert OS/2 BMP files with 16 bits per +pixel (only because the author did not have a complete specification +for them). It recognizes the format and issues an error message. +Before Netpbm 10.16 (June 2003), it also could not convert Windows BMP +files with 16 bits per pixel. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBbmptopnm\fP recognizes the following +command line option: + + + +.TP +\fB-verbose\fP +Report contents of the BMP header to the standard error. + + + +.UN seealso +.SH SEE ALSO +.BR "ppmtobmp" (1)\c +\&, +.BR "ppmtowinicon" (1)\c +\&, +.BR "ppm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1992 by David W. Sanderson. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/bmptopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/bmptoppm.1 b/upstream/fedora-40/man1/bmptoppm.1 new file mode 100644 index 00000000..cb49f7aa --- /dev/null +++ b/upstream/fedora-40/man1/bmptoppm.1 @@ -0,0 +1,29 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Bmptoppm User Manual" 0 "March 2002" "netpbm documentation" + +.SH NAME + +bmptoppm - replaced by bmptopnm + +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBbmptoppm\fP was replaced in Netpbm 9.25 (March 2002) by +.BR "bmptopnm" (1)\c +\&. +.PP +\fBbmptopnm\fP is backward compatible with \fBbmptoppm\fP except that +it generates PBM and PGM output when it is more appropriate than PPM. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/bmptoppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/bootctl.1 b/upstream/fedora-40/man1/bootctl.1 new file mode 100644 index 00000000..945a1a98 --- /dev/null +++ b/upstream/fedora-40/man1/bootctl.1 @@ -0,0 +1,682 @@ +'\" t +.TH "BOOTCTL" "1" "" "systemd 255" "bootctl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +bootctl \- Control EFI firmware boot settings and manage boot loader +.SH "SYNOPSIS" +.HP \w'\fBbootctl\fR\ 'u +\fBbootctl\fR [OPTIONS...] {COMMAND} +.SH "DESCRIPTION" +.PP +\fBbootctl\fR +can check the EFI firmware and boot loader status, list and manage available boot loaders and boot loader entries, and install, update, or remove the +\fBsystemd-boot\fR(7) +boot loader on the current system\&. +.SH "GENERIC EFI FIRMWARE/BOOT LOADER COMMANDS" +.PP +These commands are available on any EFI system, regardless of the boot loader used\&. +.PP +\fBstatus\fR +.RS 4 +Shows brief information about the system firmware, the boot loader that was used to boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware\*(Aqs list of boot loaders and the current default boot loader entry\&. If no command is specified, this is the implied default\&. +.sp +See the example below for details of the output\&. +.sp +Added in version 239\&. +.RE +.PP +\fBreboot\-to\-firmware\fR [\fIBOOL\fR] +.RS 4 +Query or set the "Reboot\-Into\-Firmware\-Setup" flag of the EFI firmware\&. Takes a boolean argument which controls whether to show the firmware setup on next system reboot\&. If the argument is omitted shows the current status of the flag, or whether the flag is supported\&. This controls the same flag as +\fBsystemctl reboot \-\-firmware\-setup\fR, but is more low\-level and allows setting the flag independently from actually requesting a reboot\&. +.sp +Hint: use +\fBsystemctl reboot \-\-firmware\-setup\fR +to reboot into firmware setup once\&. See +\fBsystemctl\fR(1) +for details\&. +.sp +Added in version 251\&. +.RE +.SH "BOOT LOADER SPECIFICATION COMMANDS" +.PP +These commands are available for all boot loaders that implement the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, such as +\fBsystemd\-boot\fR\&. +.PP +\fBlist\fR +.RS 4 +Shows all available boot loader entries implementing the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, as well as any other entries discovered or automatically generated by a boot loader implementing the +\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2\&. JSON output may be requested with +\fB\-\-json=\fR\&. +.sp +See the example below for details of the output\&. +.sp +Added in version 239\&. +.RE +.PP +\fBunlink\fR \fIID\fR +.RS 4 +Removes a boot loader entry including the files it refers to\&. Takes a single boot loader entry ID string or a glob pattern as argument\&. Referenced files such as kernel or initrd are only removed if no other entry refers to them\&. +.sp +Added in version 253\&. +.RE +.PP +\fBcleanup\fR +.RS 4 +Removes files from the ESP and XBOOTLDR partitions that belong to the entry token but are not referenced in any boot loader entries\&. +.sp +Added in version 253\&. +.RE +.SH "BOOT LOADER INTERFACE COMMANDS" +.PP +These commands are available for all boot loaders that implement the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2 +and the +\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2, such as +\fBsystemd\-boot\fR\&. +.PP +\fBset\-default\fR \fIID\fR, \fBset\-oneshot\fR \fIID\fR +.RS 4 +Sets the default boot loader entry\&. Takes a single boot loader entry ID string or a glob pattern as argument\&. The +\fBset\-oneshot\fR +command will set the default entry only for the next boot, the +\fBset\-default\fR +will set it persistently for all future boots\&. +.sp +\fBbootctl list\fR +can be used to list available boot loader entries and their IDs\&. +.sp +In addition, the boot loader entry ID may be specified as one of: +\fB@default\fR, +\fB@oneshot\fR +or +\fB@current\fR, which correspond to the current default boot loader entry for all future boots, the current default boot loader entry for the next boot, and the currently booted boot loader entry\&. These special IDs are resolved to the current values of the EFI variables +\fILoaderEntryDefault\fR, +\fILoaderEntryOneShot\fR +and +\fILoaderEntrySelected\fR, see +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2 +for details\&. These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot loader entry for all future boots, but may be used for other operations too\&. +.sp +If set to +\fB@saved\fR +the chosen entry will be saved as an EFI variable on every boot and automatically selected the next time the boot loader starts\&. +.sp +When an empty string ("") is specified as the ID, then the corresponding EFI variable will be unset\&. +.sp +Hint: use +\fBsystemctl reboot \-\-boot\-loader\-entry=\fR\fB\fIID\fR\fR +to reboot into a specific boot entry and +\fBsystemctl reboot \-\-boot\-loader\-menu=\fR\fB\fItimeout\fR\fR +to reboot into the boot loader menu once\&. See +\fBsystemctl\fR(1) +for details\&. +.sp +Added in version 240\&. +.RE +.PP +\fBset\-timeout\fR \fITIMEOUT\fR, \fBset\-timeout\-oneshot\fR \fITIMEOUT\fR +.RS 4 +Sets the boot loader menu timeout in seconds\&. The +\fBset\-timeout\-oneshot\fR +command will set the timeout only for the next boot\&. See +\fBsystemd.time\fR(7) +for details about the syntax of time spans\&. +.sp +If this is set to +\fBmenu\-disabled\fR +or +\fBmenu\-hidden\fR +or +\fB0\fR, no menu is shown and the default entry will be booted immediately, while setting this to +\fBmenu\-force\fR +disables the timeout while always showing the menu\&. When an empty string ("") is specified the bootloader will revert to its default menu timeout\&. +.sp +Added in version 250\&. +.RE +.SH "SYSTEMD\-BOOT COMMANDS" +.PP +These commands manage the +\fBsystemd\-boot\fR +EFI boot loader, and do not work in conjunction with other boot loaders\&. +.PP +\fBinstall\fR +.RS 4 +Installs +\fBsystemd\-boot\fR +into the EFI system partition\&. A copy of +\fBsystemd\-boot\fR +will be stored as the EFI default/fallback loader at +\fIESP\fR/EFI/BOOT/BOOT*\&.EFI\&. The boot loader is then added to the top of the firmware\*(Aqs boot loader list\&. +.sp +Added in version 239\&. +.RE +.PP +\fBupdate\fR +.RS 4 +Updates all installed versions of +\fBsystemd-boot\fR(7), if the available version is newer than the version installed in the EFI system partition\&. This also includes the EFI default/fallback loader at +\fIESP\fR/EFI/BOOT/BOOT*\&.EFI\&. The boot loader is then added to end of the firmware\*(Aqs boot loader list if missing\&. +.sp +Added in version 239\&. +.RE +.PP +\fBremove\fR +.RS 4 +Removes all installed versions of +\fBsystemd\-boot\fR +from the EFI system partition and the firmware\*(Aqs boot loader list\&. +.sp +Added in version 239\&. +.RE +.PP +\fBis\-installed\fR +.RS 4 +Checks whether +\fBsystemd\-boot\fR +is installed in the ESP\&. Note that a single ESP might host multiple boot loaders; this hence checks whether +\fBsystemd\-boot\fR +is one (of possibly many) installed boot loaders \(em and neither whether it is the default nor whether it is registered in any EFI variables\&. +.sp +Added in version 243\&. +.RE +.PP +\fBrandom\-seed\fR +.RS 4 +Generates a random seed and stores it in the EFI System Partition (ESP), for use by the +\fBsystemd\-boot\fR +boot loader\&. If a random seed already exists in the ESP it is refreshed\&. Also generates a random \*(Aqsystem token\*(Aq and stores it persistently as an EFI variable, if one has not been set before\&. If the boot loader finds the random seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the OS and a new seed to store in the ESP from the combination of both\&. The random seed passed to the OS is credited to the kernel\*(Aqs entropy pool by the system manager during early boot, and permits userspace to boot up with an entropy pool fully initialized very early on\&. Also see +\fBsystemd-boot-random-seed.service\fR(8)\&. +.sp +See +\m[blue]\fBRandom Seeds\fR\m[]\&\s-2\u[3]\d\s+2 +for further information\&. +.sp +Added in version 243\&. +.RE +.SH "KERNEL IMAGE COMMANDS" +.PP +\fBkernel\-identify\fR \fIkernel\fR +.RS 4 +Takes a kernel image as argument\&. Checks what kind of kernel the image is\&. Returns one of +"uki", +"pe", and +"unknown"\&. +.sp +Added in version 253\&. +.RE +.PP +\fBkernel\-inspect\fR \fIkernel\fR +.RS 4 +Takes a kernel image as argument\&. Prints details about the image\&. +.sp +Added in version 253\&. +.RE +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fB\-\-esp\-path=\fR +.RS 4 +Path to the EFI System Partition (ESP)\&. If not specified, +/efi/, +/boot/, and +/boot/efi/ +are checked in turn\&. It is recommended to mount the ESP to +/efi/, if possible\&. +.RE +.PP +\fB\-\-boot\-path=\fR +.RS 4 +Path to the Extended Boot Loader partition, as defined in the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. If not specified, +/boot/ +is checked\&. It is recommended to mount the Extended Boot Loader partition to +/boot/, if possible\&. +.RE +.PP +\fB\-\-root=\fR\fB\fIroot\fR\fR +.RS 4 +Takes a directory path as an argument\&. All paths will be prefixed with the given alternate +\fIroot\fR +path, including config search paths\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-image=\fR\fB\fIimage\fR\fR +.RS 4 +Takes a path to a disk image file or block device node\&. If specified, all operations are applied to file system in the indicated disk image\&. This option is similar to +\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[4]\d\s+2\&. For further information on supported disk images, see +\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR +.RS 4 +Takes an image policy string as argument, as per +\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via +\fB\-\-image=\fR, see above\&. If not specified defaults to the +"*" +policy, i\&.e\&. all recognized file systems in the image are used\&. +.RE +.PP +\fB\-\-install\-source=\fR +.RS 4 +When installing binaries with +\fB\-\-root=\fR +or +\fB\-\-image=\fR, selects where to source them from\&. Takes one of +"auto" +(the default), +"image" +or +"host"\&. With +"auto" +binaries will be picked from the specified directory or image, and if not found they will be picked from the host\&. With +"image" +or +"host" +no fallback search will be performed if the binaries are not found in the selected source\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-p\fR, \fB\-\-print\-esp\-path\fR +.RS 4 +This option modifies the behaviour of +\fBstatus\fR\&. Only prints the path to the EFI System Partition (ESP) to standard output and exits\&. +.sp +Added in version 236\&. +.RE +.PP +\fB\-x\fR, \fB\-\-print\-boot\-path\fR +.RS 4 +This option modifies the behaviour of +\fBstatus\fR\&. Only prints the path to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard output and exit\&. This command is useful to determine where to place boot loader entries, as they are preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise\&. +.sp +Boot Loader Specification Type #1 entries should generally be placed in the directory +"$(bootctl \-x)/loader/entries/"\&. Existence of that directory may also be used as indication that boot loader entry support is available on the system\&. Similarly, Boot Loader Specification Type #2 entries should be placed in the directory +"$(bootctl \-x)/EFI/Linux/"\&. +.sp +Note that this option (similarly to the +\fB\-\-print\-boot\-path\fR +option mentioned above), is available independently from the boot loader used, i\&.e\&. also without +\fBsystemd\-boot\fR +being installed\&. +.sp +Added in version 242\&. +.RE +.PP +\fB\-R\fR, \fB\-\-print\-root\-device\fR +.RS 4 +Print the path to the block device node backing the root file system of the local OS\&. This prints a path such as +/dev/nvme0n1p5\&. If the root file system is backed by dm\-crypt/LUKS or dm\-verity the underlying block device is returned\&. If the root file system is backed by multiple block devices (as supported by btrfs) the operation will fail\&. If the switch is specified twice (i\&.e\&. +\fB\-RR\fR) and the discovered block device is a partition device the "whole" block device it belongs to is determined and printed (e\&.g\&. +/dev/nvme0n1)\&. If the root file system is +"tmpfs" +(or a similar in\-memory file system), the block device backing +/usr/ +is returned if applicable\&. If the root file system is a network file system (e\&.g\&. NFS, CIFS) the operation will fail\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-no\-variables\fR +.RS 4 +Do not touch the firmware\*(Aqs boot loader list stored in EFI variables\&. +.sp +Added in version 220\&. +.RE +.PP +\fB\-\-graceful\fR +.RS 4 +Ignore failure when the EFI System Partition cannot be found, when EFI variables cannot be written, or a different or newer boot loader is already installed\&. Currently only applies to +\fBis\-installed\fR, +\fBupdate\fR, and +\fBrandom\-seed\fR +verbs\&. +.sp +Added in version 244\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Suppress printing of the results of various commands and also the hints about ESP being unavailable\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-make\-entry\-directory=yes|no\fR +.RS 4 +Controls creation and deletion of the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2 +Type #1 entry directory on the file system containing resources such as kernel and initrd images during +\fBinstall\fR +and +\fBremove\fR, respectively\&. The directory is named after the entry token, as specified with +\fB\-\-entry\-token=\fR +parameter described below, and is placed immediately below the +\fI$BOOT\fR +root directory (i\&.e\&. beneath the file system returned by the +\fB\-\-print\-boot\-path\fR +option, see above)\&. Defaults to +"no"\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-entry\-token=\fR +.RS 4 +Controls how to name and identify boot loader entries for this OS installation\&. Accepted during +\fBinstall\fR, and takes one of +"auto", +"machine\-id", +"os\-id", +"os\-image\-id" +or an arbitrary string prefixed by +"literal:" +as argument\&. +.sp +If set to +\fBmachine\-id\fR +the entries are named after the machine ID of the running system (e\&.g\&. +"b0e793a9baf14b5fa13ecbe84ff637ac")\&. See +\fBmachine-id\fR(5) +for details about the machine ID concept and file\&. +.sp +If set to +\fBos\-id\fR +the entries are named after the OS ID of the running system, i\&.e\&. the +\fIID=\fR +field of +\fBos-release\fR(5) +(e\&.g\&. +"fedora")\&. Similarly, if set to +\fBos\-image\-id\fR +the entries are named after the OS image ID of the running system, i\&.e\&. the +\fIIMAGE_ID=\fR +field of +os\-release +(e\&.g\&. +"vendorx\-cashier\-system")\&. +.sp +If set to +\fBauto\fR +(the default), the +/etc/kernel/entry\-token +file will be read if it exists, and the stored value used\&. Otherwise if the local machine ID is initialized it is used\&. Otherwise +\fIIMAGE_ID=\fR +from +os\-release +will be used, if set\&. Otherwise, +\fIID=\fR +from +os\-release +will be used, if set\&. +.sp +Unless set to +"machine\-id", or when +\fB\-\-make\-entry\-directory=yes\fR +is used the selected token string is written to a file +/etc/kernel/entry\-token, to ensure it will be used for future entries\&. This file is also read by +\fBkernel-install\fR(8), in order to identify under which name to generate boot loader entries for newly installed kernels, or to determine the entry names for removing old ones\&. +.sp +Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option\&. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted) +\fI$BOOT\fR +partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-all\-architectures\fR +.RS 4 +Install binaries for all supported EFI architectures (this implies +\fB\-\-no\-variables\fR)\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-efi\-boot\-option\-description=\fR +.RS 4 +Description of the entry added to the firmware\*(Aqs boot option list\&. Defaults to +"Linux Boot Manager"\&. +.sp +Using the default entry name +"Linux Boot Manager" +is generally preferable as only one bootloader installed to a single ESP partition should be used to boot any number of OS installations found on the various disks installed in the system\&. Specifically distributions should not use this flag to install a branded entry in the boot option list\&. However in situations with multiple disks, each with their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in the firmware\*(Aqs boot option menu\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-dry\-run\fR +.RS 4 +Dry run for +\fBunlink\fR +and +\fBcleanup\fR\&. +.sp +In dry run mode, the unlink and cleanup operations only print the files that would get deleted without actually deleting them\&. +.sp +Added in version 253\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +Shows output formatted as JSON\&. Expects one of +"short" +(for the shortest possible output without any redundant whitespace or line breaks), +"pretty" +(for a pretty version of the same, with indentation and line breaks) or +"off" +(to turn off JSON output, the default)\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.SH "SIGNED \&.EFI FILES" +.PP +\fBbootctl\fR +\fBinstall\fR +and +\fBupdate\fR +will look for a +\fBsystemd\-boot\fR +file ending with the +"\&.efi\&.signed" +suffix first, and copy that instead of the normal +"\&.efi" +file\&. This allows distributions or end\-users to provide signed images for UEFI SecureBoot\&. +.SH "EXIT STATUS" +.PP +On success, 0 is returned, a non\-zero failure code otherwise\&. +\fBbootctl \-\-print\-root\-device\fR +returns exit status 80 in case the root file system is not backed by single block device, and other non\-zero exit statuses on other errors\&. +.SH "ENVIRONMENT" +.PP +If +\fI$SYSTEMD_RELAX_ESP_CHECKS=1\fR +is set the validation checks for the ESP are relaxed, and the path specified with +\fB\-\-esp\-path=\fR +may refer to any kind of file system on any kind of partition\&. +.PP +Similarly, +\fI$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1\fR +turns off some validation checks for the Extended Boot Loader partition\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Output from status and list\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBbootctl status\fR +System: + Firmware: UEFI 2\&.40 (\fIfirmware\-version\fR) ← firmware vendor and version + Secure Boot: disabled (setup) ← Secure Boot status + TPM2 Support: yes + Boot into FW: supported ← does the firmware support booting into itself + +Current Boot Loader: ← details about sd\-boot or another boot loader + Product: systemd\-boot \fIversion\fR implementing the \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2 + Features: ✓ Boot counting + ✓ Menu timeout control + ✓ One\-shot menu timeout control + ✓ Default entry control + ✓ One\-shot entry control + ✓ Support for XBOOTLDR partition + ✓ Support for passing random seed to OS + ✓ Load drop\-in drivers + ✓ Boot loader sets ESP information + ✓ Menu can be disabled + ESP: /dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000 + File: └─/EFI/systemd/systemd\-bootx64\&.efi + +Random Seed: ← random seed used for entropy in early boot + Passed to OS: yes + System Token: set + Exists: yes + +Available Boot Loaders on ESP: + ESP: /boot/efi (/dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000) + File: └─/EFI/systemd/systemd\-bootx64\&.efi (systemd\-boot 251 + File: └─/EFI/BOOT/BOOTX64\&.EFI (systemd\-boot 251 + +Boot Loaders Listed in EFI Variables: + Title: Linux Boot Manager + ID: 0x0001 + Status: active, boot\-order + Partition: /dev/disk/by\-partuuid/\&... + File: └─/EFI/systemd/systemd\-bootx64\&.efi + + Title: Fedora + ID: 0x0000 + Status: active, boot\-order + Partition: /dev/disk/by\-partuuid/\&... + File: └─/EFI/fedora/shimx64\&.efi + + Title: Linux\-Firmware\-Updater + ID: 0x0002 + Status: active, boot\-order + Partition: /dev/disk/by\-partuuid/\&... + File: └─/EFI/fedora/fwupdx64\&.efi + +Boot Loader Entries: + $BOOT: /boot/efi (/dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000) + +Default Boot Loader Entry: + type: Boot Loader Specification Type #1 (\&.conf) + title: Fedora Linux 36 (Workstation Edition) + id: \&... + source: /boot/efi/loader/entries/\fIentry\-token\fR\-\fIkernel\-version\fR\&.conf + version: \fIkernel\-version\fR + machine\-id: \&... + linux: /\fIentry\-token\fR/\fIkernel\-version\fR/linux + initrd: /\fIentry\-token\fR/\fIkernel\-version\fR/initrd + options: root=\&... +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBbootctl list\fR +Boot Loader Entries: + type: Boot Loader Specification Type #1 (\&.conf) + title: Fedora Linux 36 (Workstation Edition) (default) (selected) + id: \&... + source: /boot/efi/loader/entries/\fIentry\-token\fR\-\fIkernel\-version\fR\&.conf + version: \fIkernel\-version\fR + machine\-id: \&... + linux: /\fIentry\-token\fR/\fIkernel\-version\fR/linux + initrd: /\fIentry\-token\fR/\fIkernel\-version\fR/initrd + options: root=\&... + + type: Boot Loader Specification Type #2 (\&.efi) + title: Fedora Linux 35 (Workstation Edition) + id: \&... + source: /boot/efi/EFI/Linux/fedora\-\fIkernel\-version\fR\&.efi + version: \fIkernel\-version\fR + machine\-id: \&... + linux: /EFI/Linux/fedora\-\fIkernel\-version\fR\&.efi + options: root=\&... + + type: Automatic + title: Reboot Into Firmware Interface + id: auto\-reboot\-to\-firmware\-setup + source: /sys/firmware/efi/efivars/LoaderEntries\-4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4f +.fi +.if n \{\ +.RE +.\} +.PP +In the listing, +"(default)" +specifies the entry that will be used by default, and +"(selected)" +specifies the entry that was selected the last time (i\&.e\&. is currently running)\&. +.SH "SEE ALSO" +.PP +\fBsystemd-boot\fR(7), +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, +\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2, +\fBsystemd-boot-random-seed.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +Boot Loader Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/boot_loader_specification +.RE +.IP " 2." 4 +Boot Loader Interface +.RS 4 +\%https://systemd.io/BOOT_LOADER_INTERFACE +.RE +.IP " 3." 4 +Random Seeds +.RS 4 +\%https://systemd.io/RANDOM_SEEDS +.RE +.IP " 4." 4 +Discoverable Partitions Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification +.RE diff --git a/upstream/fedora-40/man1/brushtopbm.1 b/upstream/fedora-40/man1/brushtopbm.1 new file mode 100644 index 00000000..64096a81 --- /dev/null +++ b/upstream/fedora-40/man1/brushtopbm.1 @@ -0,0 +1,54 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Brushtopbm User Manual" 0 "28 August 1988" "netpbm documentation" + +.SH NAME +brushtopbm - convert a doodle brush file into a PBM image + +.UN synopsis +.SH SYNOPSIS + +\fBbrushtopbm\fP +[\fIbrushfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBbrushtopbm\fP reads a Xerox doodle brush file as input. and +produces a portable bitmap as output. +.PP +Note that there is currently no pbmtobrush tool. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBbrushtopbm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "pbm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1988 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/brushtopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/busctl.1 b/upstream/fedora-40/man1/busctl.1 new file mode 100644 index 00000000..ed53281e --- /dev/null +++ b/upstream/fedora-40/man1/busctl.1 @@ -0,0 +1,583 @@ +'\" t +.TH "BUSCTL" "1" "" "systemd 255" "busctl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +busctl \- Introspect the bus +.SH "SYNOPSIS" +.HP \w'\fBbusctl\fR\ 'u +\fBbusctl\fR [OPTIONS...] [COMMAND] [\fINAME\fR...] +.SH "DESCRIPTION" +.PP +\fBbusctl\fR +may be used to introspect and monitor the D\-Bus bus\&. +.SH "COMMANDS" +.PP +The following commands are understood: +.PP +\fBlist\fR +.RS 4 +Show all peers on the bus, by their service names\&. By default, shows both unique and well\-known names, but this may be changed with the +\fB\-\-unique\fR +and +\fB\-\-acquired\fR +switches\&. This is the default operation if no command is specified\&. +.sp +Added in version 209\&. +.RE +.PP +\fBstatus\fR [\fISERVICE\fR] +.RS 4 +Show process information and credentials of a bus service (if one is specified by its unique or well\-known name), a process (if one is specified by its numeric PID), or the owner of the bus (if no parameter is specified)\&. +.sp +Added in version 209\&. +.RE +.PP +\fBmonitor\fR [\fISERVICE\fR...] +.RS 4 +Dump messages being exchanged\&. If +\fISERVICE\fR +is specified, show messages to or from this peer, identified by its well\-known or unique name\&. Otherwise, show all messages on the bus\&. Use +Ctrl+C +to terminate the dump\&. +.sp +Added in version 209\&. +.RE +.PP +\fBcapture\fR [\fISERVICE\fR...] +.RS 4 +Similar to +\fBmonitor\fR +but writes the output in pcapng format (for details, see +\m[blue]\fBPCAP Next Generation (pcapng) Capture File Format\fR\m[]\&\s-2\u[1]\d\s+2)\&. Make sure to redirect standard output to a file or pipe\&. Tools like +\fBwireshark\fR(1) +may be used to dissect and view the resulting files\&. +.sp +Added in version 218\&. +.RE +.PP +\fBtree\fR [\fISERVICE\fR...] +.RS 4 +Shows an object tree of one or more services\&. If +\fISERVICE\fR +is specified, show object tree of the specified services only\&. Otherwise, show all object trees of all services on the bus that acquired at least one well\-known name\&. +.sp +Added in version 218\&. +.RE +.PP +\fBintrospect\fR \fISERVICE\fR \fIOBJECT\fR [\fIINTERFACE\fR] +.RS 4 +Show interfaces, methods, properties and signals of the specified object (identified by its path) on the specified service\&. If the interface argument is passed, the output is limited to members of the specified interface\&. +.sp +Added in version 218\&. +.RE +.PP +\fBcall\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIMETHOD\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]] +.RS 4 +Invoke a method and show the response\&. Takes a service name, object path, interface name and method name\&. If parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To suppress output of the returned data, use the +\fB\-\-quiet\fR +option\&. +.sp +Added in version 218\&. +.RE +.PP +\fBemit\fR \fIOBJECT\fR \fIINTERFACE\fR \fISIGNAL\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]] +.RS 4 +Emit a signal\&. Takes an object path, interface name and method name\&. If parameters shall be passed, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To specify the destination of the signal, use the +\fB\-\-destination=\fR +option\&. +.sp +Added in version 242\&. +.RE +.PP +\fBget\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR... +.RS 4 +Retrieve the current value of one or more object properties\&. Takes a service name, object path, interface name and property name\&. Multiple properties may be specified at once, in which case their values will be shown one after the other, separated by newlines\&. The output is, by default, in terse format\&. Use +\fB\-\-verbose\fR +for a more elaborate output format\&. +.sp +Added in version 218\&. +.RE +.PP +\fBset\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR \fISIGNATURE\fR \fIARGUMENT\fR... +.RS 4 +Set the current value of an object property\&. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings\&. +.sp +Added in version 218\&. +.RE +.PP +\fBhelp\fR +.RS 4 +Show command syntax help\&. +.sp +Added in version 209\&. +.RE +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fB\-\-address=\fR\fB\fIADDRESS\fR\fR +.RS 4 +Connect to the bus specified by +\fIADDRESS\fR +instead of using suitable defaults for either the system or user bus (see +\fB\-\-system\fR +and +\fB\-\-user\fR +options)\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-show\-machine\fR +.RS 4 +When showing the list of peers, show a column containing the names of containers they belong to\&. See +\fBsystemd-machined.service\fR(8)\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-unique\fR +.RS 4 +When showing the list of peers, show only "unique" names (of the form +":\fInumber\fR\&.\fInumber\fR")\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-acquired\fR +.RS 4 +The opposite of +\fB\-\-unique\fR +\(em only "well\-known" names will be shown\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-activatable\fR +.RS 4 +When showing the list of peers, show only peers which have actually not been activated yet, but may be started automatically if accessed\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-match=\fR\fB\fIMATCH\fR\fR +.RS 4 +When showing messages being exchanged, show only the subset matching +\fIMATCH\fR\&. See +\fBsd_bus_add_match\fR(3)\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-\-size=\fR +.RS 4 +When used with the +\fBcapture\fR +command, specifies the maximum bus message size to capture ("snaplen")\&. Defaults to 4096 bytes\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-list\fR +.RS 4 +When used with the +\fBtree\fR +command, shows a flat list of object paths instead of a tree\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +When used with the +\fBcall\fR +command, suppresses display of the response message payload\&. Note that even if this option is specified, errors returned will still be printed and the tool will indicate success or failure with the process exit code\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-verbose\fR +.RS 4 +When used with the +\fBcall\fR +or +\fBget\-property\fR +command, shows output in a more verbose format\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-xml\-interface\fR +.RS 4 +When used with the +\fBintrospect\fR +call, dump the XML description received from the D\-Bus +\fBorg\&.freedesktop\&.DBus\&.Introspectable\&.Introspect\fR +call instead of the normal output\&. +.sp +Added in version 243\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +When used with the +\fBcall\fR +or +\fBget\-property\fR +command, shows output formatted as JSON\&. Expects one of +"short" +(for the shortest possible output without any redundant whitespace or line breaks) or +"pretty" +(for a pretty version of the same, with indentation and line breaks)\&. Note that transformation from D\-Bus marshalling to JSON is done in a loss\-less way, which means type information is embedded into the JSON object tree\&. +.sp +Added in version 240\&. +.RE +.PP +\fB\-j\fR +.RS 4 +Equivalent to +\fB\-\-json=pretty\fR +when invoked interactively from a terminal\&. Otherwise equivalent to +\fB\-\-json=short\fR, in particular when the output is piped to some other program\&. +.sp +Added in version 240\&. +.RE +.PP +\fB\-\-expect\-reply=\fR\fIBOOL\fR +.RS 4 +When used with the +\fBcall\fR +command, specifies whether +\fBbusctl\fR +shall wait for completion of the method call, output the returned method response data, and return success or failure via the process exit code\&. If this is set to +"no", the method call will be issued but no response is expected, the tool terminates immediately, and thus no response can be shown, and no success or failure is returned via the exit code\&. To only suppress output of the reply message payload, use +\fB\-\-quiet\fR +above\&. Defaults to +"yes"\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-auto\-start=\fR\fIBOOL\fR +.RS 4 +When used with the +\fBcall\fR +or +\fBemit\fR +command, specifies whether the method call should implicitly activate the called service, should it not be running yet but is configured to be auto\-started\&. Defaults to +"yes"\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-allow\-interactive\-authorization=\fR\fIBOOL\fR +.RS 4 +When used with the +\fBcall\fR +command, specifies whether the services may enforce interactive authorization while executing the operation, if the security policy is configured for this\&. Defaults to +"yes"\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-timeout=\fR\fISECS\fR +.RS 4 +When used with the +\fBcall\fR +command, specifies the maximum time to wait for method call completion\&. If no time unit is specified, assumes seconds\&. The usual other units are understood, too (ms, us, s, min, h, d, w, month, y)\&. Note that this timeout does not apply if +\fB\-\-expect\-reply=no\fR +is used, as the tool does not wait for any reply message then\&. When not specified or when set to 0, the default of +"25s" +is assumed\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-augment\-creds=\fR\fIBOOL\fR +.RS 4 +Controls whether credential data reported by +\fBlist\fR +or +\fBstatus\fR +shall be augmented with data from +/proc/\&. When this is turned on, the data shown is possibly inconsistent, as the data read from +/proc/ +might be more recent than the rest of the credential information\&. Defaults to +"yes"\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-\-watch\-bind=\fR\fIBOOL\fR +.RS 4 +Controls whether to wait for the specified +\fBAF_UNIX\fR +bus socket to appear in the file system before connecting to it\&. Defaults to off\&. When enabled, the tool will watch the file system until the socket is created and then connect to it\&. +.sp +Added in version 237\&. +.RE +.PP +\fB\-\-destination=\fR\fISERVICE\fR +.RS 4 +Takes a service name\&. When used with the +\fBemit\fR +command, a signal is emitted to the specified service\&. +.sp +Added in version 242\&. +.RE +.PP +\fB\-\-user\fR +.RS 4 +Talk to the service manager of the calling user, rather than the service manager of the system\&. +.RE +.PP +\fB\-\-system\fR +.RS 4 +Talk to the service manager of the system\&. This is the implied default\&. +.RE +.PP +\fB\-H\fR, \fB\-\-host=\fR +.RS 4 +Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by +"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by +":", and then a container name, separated by +"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with +\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&. +.RE +.PP +\fB\-M\fR, \fB\-\-machine=\fR +.RS 4 +Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating +"@" +character\&. If the special string +"\&.host" +is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus: +"\-\-user \-\-machine=lennart@\&.host")\&. If the +"@" +syntax is not used, the connection is made as root user\&. If the +"@" +syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and +"\&.host" +are implied\&. +.RE +.PP +\fB\-l\fR, \fB\-\-full\fR +.RS 4 +Do not ellipsize the output in +\fBlist\fR +command\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +\fB\-\-no\-legend\fR +.RS 4 +Do not print the legend, i\&.e\&. column headers and the footer with hints\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.SH "PARAMETER FORMATTING" +.PP +The +\fBcall\fR +and +\fBset\-property\fR +commands take a signature string followed by a list of parameters formatted as string (for details on D\-Bus signature strings, see the +\m[blue]\fBType system chapter of the D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2)\&. For simple types, each parameter following the signature should simply be the parameter\*(Aqs value formatted as string\&. Positive boolean values may be formatted as +"true", +"yes", +"on", or +"1"; negative boolean values may be specified as +"false", +"no", +"off", or +"0"\&. For arrays, a numeric argument for the number of entries followed by the entries shall be specified\&. For variants, the signature of the contents shall be specified, followed by the contents\&. For dictionaries and structs, the contents of them shall be directly specified\&. +.PP +For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +s jawoll +.fi +.if n \{\ +.RE +.\} +.sp +is the formatting of a single string +"jawoll"\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +as 3 hello world foobar +.fi +.if n \{\ +.RE +.\} +.sp +is the formatting of a string array with three entries, +"hello", +"world" +and +"foobar"\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +a{sv} 3 One s Eins Two u 2 Yes b true +.fi +.if n \{\ +.RE +.\} +.sp +is the formatting of a dictionary array that maps strings to variants, consisting of three entries\&. The string +"One" +is assigned the string +"Eins"\&. The string +"Two" +is assigned the 32\-bit unsigned integer 2\&. The string +"Yes" +is assigned a positive boolean\&. +.PP +Note that the +\fBcall\fR, +\fBget\-property\fR, +\fBintrospect\fR +commands will also generate output in this format for the returned data\&. Since this format is sometimes too terse to be easily understood, the +\fBcall\fR +and +\fBget\-property\fR +commands may generate a more verbose, multi\-line output when passed the +\fB\-\-verbose\fR +option\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Write and Read a Property\fR +.PP +The following two commands first write a property and then read it back\&. The property is found on the +"/org/freedesktop/systemd1" +object of the +"org\&.freedesktop\&.systemd1" +service\&. The name of the property is +"LogLevel" +on the +"org\&.freedesktop\&.systemd1\&.Manager" +interface\&. The property contains a single string: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# busctl set\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel s debug +# busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel +s "debug" +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Terse and Verbose Output\fR +.PP +The following two commands read a property that contains an array of strings, and first show it in terse format, followed by verbose format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment +as 2 "LANG=en_US\&.UTF\-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" +$ busctl get\-property \-\-verbose org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment +ARRAY "s" { + STRING "LANG=en_US\&.UTF\-8"; + STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; +}; +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Invoking a Method\fR +.PP +The following command invokes the +"StartUnit" +method on the +"org\&.freedesktop\&.systemd1\&.Manager" +interface of the +"/org/freedesktop/systemd1" +object of the +"org\&.freedesktop\&.systemd1" +service, and passes it two strings +"cups\&.service" +and +"replace"\&. As a result of the method call, a single object path parameter is received and shown: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# busctl call org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager StartUnit ss "cups\&.service" "replace" +o "/org/freedesktop/systemd1/job/42684" +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBdbus-daemon\fR(1), +\m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[3]\d\s+2, +\fBsd-bus\fR(3), +\fBvarlinkctl\fR(1), +\fBsystemd\fR(1), +\fBmachinectl\fR(1), +\fBwireshark\fR(1) +.SH "NOTES" +.IP " 1." 4 +PCAP Next Generation (pcapng) Capture File Format +.RS 4 +\%https://github.com/pcapng/pcapng/ +.RE +.IP " 2." 4 +Type system chapter of the D-Bus specification +.RS 4 +\%https://dbus.freedesktop.org/doc/dbus-specification.html#type-system +.RE +.IP " 3." 4 +D-Bus +.RS 4 +\%https://www.freedesktop.org/wiki/Software/dbus +.RE diff --git a/upstream/fedora-40/man1/bzdiff.1 b/upstream/fedora-40/man1/bzdiff.1 new file mode 100644 index 00000000..adb7a8e7 --- /dev/null +++ b/upstream/fedora-40/man1/bzdiff.1 @@ -0,0 +1,47 @@ +\"Shamelessly copied from zmore.1 by Philippe Troin +\"for Debian GNU/Linux +.TH BZDIFF 1 +.SH NAME +bzcmp, bzdiff \- compare bzip2 compressed files +.SH SYNOPSIS +.B bzcmp +[ cmp_options ] file1 +[ file2 ] +.br +.B bzdiff +[ diff_options ] file1 +[ file2 ] +.SH DESCRIPTION +.I Bzcmp +and +.I bzdiff +are used to invoke the +.I cmp +or the +.I diff +program on bzip2 compressed files. All options specified are passed +directly to +.I cmp +or +.IR diff "." +If only 1 file is specified, then the files compared are +.I file1 +and an uncompressed +.IR file1 ".bz2." +If two files are specified, then they are uncompressed if necessary and fed to +.I cmp +or +.IR diff "." +The exit status from +.I cmp +or +.I diff +is preserved. +.SH "SEE ALSO" +cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1) +.SH BUGS +Messages from the +.I cmp +or +.I diff +programs refer to temporary filenames instead of those specified. diff --git a/upstream/fedora-40/man1/bzgrep.1 b/upstream/fedora-40/man1/bzgrep.1 new file mode 100644 index 00000000..930af8c7 --- /dev/null +++ b/upstream/fedora-40/man1/bzgrep.1 @@ -0,0 +1,56 @@ +\"Shamelessly copied from zmore.1 by Philippe Troin +\"for Debian GNU/Linux +.TH BZGREP 1 +.SH NAME +bzgrep, bzfgrep, bzegrep \- search possibly bzip2 compressed files for a regular expression +.SH SYNOPSIS +.B bzgrep +[ grep_options ] +.BI [\ -e\ ] " pattern" +.IR filename ".\|.\|." +.br +.B bzegrep +[ egrep_options ] +.BI [\ -e\ ] " pattern" +.IR filename ".\|.\|." +.br +.B bzfgrep +[ fgrep_options ] +.BI [\ -e\ ] " pattern" +.IR filename ".\|.\|." +.SH DESCRIPTION +.IR Bzgrep +is used to invoke the +.I grep +on bzip2-compressed files. All options specified are passed directly to +.I grep. +If no file is specified, then the standard input is decompressed +if necessary and fed to grep. +Otherwise the given files are uncompressed if necessary and fed to +.I grep. +.PP +If +.I bzgrep +is invoked as +.I bzegrep +or +.I bzfgrep +then +.I egrep +or +.I fgrep +is used instead of +.I grep. +If the GREP environment variable is set, +.I bzgrep +uses it as the +.I grep +program to be invoked. For example: + + for sh: GREP=fgrep bzgrep string files + for csh: (setenv GREP fgrep; bzgrep string files) +.SH AUTHOR +Charles Levert (charles@comm.polymtl.ca). Adapted to bzip2 by Philippe +Troin for Debian GNU/Linux. +.SH "SEE ALSO" +grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1) diff --git a/upstream/fedora-40/man1/bzip2.1 b/upstream/fedora-40/man1/bzip2.1 new file mode 100644 index 00000000..50d6c939 --- /dev/null +++ b/upstream/fedora-40/man1/bzip2.1 @@ -0,0 +1,465 @@ +.PU +.TH bzip2 1 +.SH NAME +bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8 +.br +bzcat \- decompresses files to stdout +.br +bzip2recover \- recovers data from damaged bzip2 files + +.SH SYNOPSIS +.ll +8 +.B bzip2 +.RB [ " \-cdfkqstvzVL123456789 " ] +[ +.I "filenames \&..." +] +.ll -8 +.br +.B bunzip2 +.RB [ " \-fkvsVL " ] +[ +.I "filenames \&..." +] +.br +.B bzcat +.RB [ " \-s " ] +[ +.I "filenames \&..." +] +.br +.B bzip2recover +.I "filename" + +.SH DESCRIPTION +.I bzip2 +compresses files using the Burrows-Wheeler block sorting +text compression algorithm, and Huffman coding. Compression is +generally considerably better than that achieved by more conventional +LZ77/LZ78-based compressors, and approaches the performance of the PPM +family of statistical compressors. + +The command-line options are deliberately very similar to +those of +.I GNU gzip, +but they are not identical. + +.I bzip2 +expects a list of file names to accompany the +command-line flags. Each file is replaced by a compressed version of +itself, with the name "original_name.bz2". +Each compressed file +has the same modification date, permissions, and, when possible, +ownership as the corresponding original, so that these properties can +be correctly restored at decompression time. File name handling is +naive in the sense that there is no mechanism for preserving original +file names, permissions, ownerships or dates in filesystems which lack +these concepts, or have serious file name length restrictions, such as +MS-DOS. + +.I bzip2 +and +.I bunzip2 +will by default not overwrite existing +files. If you want this to happen, specify the \-f flag. + +If no file names are specified, +.I bzip2 +compresses from standard +input to standard output. In this case, +.I bzip2 +will decline to +write compressed output to a terminal, as this would be entirely +incomprehensible and therefore pointless. + +.I bunzip2 +(or +.I bzip2 \-d) +decompresses all +specified files. Files which were not created by +.I bzip2 +will be detected and ignored, and a warning issued. +.I bzip2 +attempts to guess the filename for the decompressed file +from that of the compressed file as follows: + + filename.bz2 becomes filename + filename.bz becomes filename + filename.tbz2 becomes filename.tar + filename.tbz becomes filename.tar + anyothername becomes anyothername.out + +If the file does not end in one of the recognised endings, +.I .bz2, +.I .bz, +.I .tbz2 +or +.I .tbz, +.I bzip2 +complains that it cannot +guess the name of the original file, and uses the original name +with +.I .out +appended. + +As with compression, supplying no +filenames causes decompression from +standard input to standard output. + +.I bunzip2 +will correctly decompress a file which is the +concatenation of two or more compressed files. The result is the +concatenation of the corresponding uncompressed files. Integrity +testing (\-t) +of concatenated +compressed files is also supported. + +You can also compress or decompress files to the standard output by +giving the \-c flag. Multiple files may be compressed and +decompressed like this. The resulting outputs are fed sequentially to +stdout. Compression of multiple files +in this manner generates a stream +containing multiple compressed file representations. Such a stream +can be decompressed correctly only by +.I bzip2 +version 0.9.0 or +later. Earlier versions of +.I bzip2 +will stop after decompressing +the first file in the stream. + +.I bzcat +(or +.I bzip2 -dc) +decompresses all specified files to +the standard output. + +.I bzip2 +will read arguments from the environment variables +.I BZIP2 +and +.I BZIP, +in that order, and will process them +before any arguments read from the command line. This gives a +convenient way to supply default arguments. + +Compression is always performed, even if the compressed +file is slightly +larger than the original. Files of less than about one hundred bytes +tend to get larger, since the compression mechanism has a constant +overhead in the region of 50 bytes. Random data (including the output +of most file compressors) is coded at about 8.05 bits per byte, giving +an expansion of around 0.5%. + +As a self-check for your protection, +.I +bzip2 +uses 32-bit CRCs to +make sure that the decompressed version of a file is identical to the +original. This guards against corruption of the compressed data, and +against undetected bugs in +.I bzip2 +(hopefully very unlikely). The +chances of data corruption going undetected is microscopic, about one +chance in four billion for each file processed. Be aware, though, that +the check occurs upon decompression, so it can only tell you that +something is wrong. It can't help you +recover the original uncompressed +data. You can use +.I bzip2recover +to try to recover data from +damaged files. + +Unlike +.I GNU gzip, +.I bzip2 +will not create a cascade of +.I .bz2 +suffixes even when using the +.I --force +option: + + filename.bz2 does not become filename.bz2.bz2 + +Return values: 0 for a normal exit, 1 for environmental problems (file +not found, invalid flags, I/O errors, &c), 2 to indicate a corrupt +compressed file, 3 for an internal consistency error (eg, bug) which +caused +.I bzip2 +to panic. + +.SH OPTIONS +.TP +.B \-c --stdout +Compress or decompress to standard output. +.TP +.B \-d --decompress +Force decompression. +.I bzip2, +.I bunzip2 +and +.I bzcat +are +really the same program, and the decision about what actions to take is +done on the basis of which name is used. This flag overrides that +mechanism, and forces +.I bzip2 +to decompress. +.TP +.B \-z --compress +The complement to \-d: forces compression, regardless of the +invocation name. +.TP +.B \-t --test +Check integrity of the specified file(s), but don't decompress them. +This really performs a trial decompression and throws away the result. +.TP +.B \-f --force +Force overwrite of output files. Normally, +.I bzip2 +will not overwrite +existing output files. Also forces +.I bzip2 +to break hard links +to files, which it otherwise wouldn't do. + +bzip2 normally declines to decompress files which don't have the +correct magic header bytes. If forced (-f), however, it will pass +such files through unmodified. This is how GNU gzip behaves. +.TP +.B \-k --keep +Keep (don't delete) input files during compression +or decompression. +.TP +.B \-s --small +Reduce memory usage, for compression, decompression and testing. Files +are decompressed and tested using a modified algorithm which only +requires 2.5 bytes per block byte. This means any file can be +decompressed in 2300k of memory, albeit at about half the normal speed. + +During compression, \-s selects a block size of 200k, which limits +memory use to around the same figure, at the expense of your compression +ratio. In short, if your machine is low on memory (8 megabytes or +less), use \-s for everything. See MEMORY MANAGEMENT below. +.TP +.B \-q --quiet +Suppress non-essential warning messages. Messages pertaining to +I/O errors and other critical events will not be suppressed. +.TP +.B \-v --verbose +Verbose mode -- show the compression ratio for each file processed. +Further \-v's increase the verbosity level, spewing out lots of +information which is primarily of interest for diagnostic purposes. +.TP +.B \-L --license -V --version +Display the software version, license terms and conditions. +.TP +.B \-1 (or \-\-fast) to \-9 (or \-\-best) +Set the block size to 100 k, 200 k .. 900 k when compressing. Has no +effect when decompressing. See MEMORY MANAGEMENT below. +The \-\-fast and \-\-best aliases are primarily for GNU gzip +compatibility. In particular, \-\-fast doesn't make things +significantly faster. +And \-\-best merely selects the default behaviour. +.TP +.B \-- +Treats all subsequent arguments as file names, even if they start +with a dash. This is so you can handle files with names beginning +with a dash, for example: bzip2 \-- \-myfilename. +.TP +.B \--repetitive-fast --repetitive-best +These flags are redundant in versions 0.9.5 and above. They provided +some coarse control over the behaviour of the sorting algorithm in +earlier versions, which was sometimes useful. 0.9.5 and above have an +improved algorithm which renders these flags irrelevant. + +.SH MEMORY MANAGEMENT +.I bzip2 +compresses large files in blocks. The block size affects +both the compression ratio achieved, and the amount of memory needed for +compression and decompression. The flags \-1 through \-9 +specify the block size to be 100,000 bytes through 900,000 bytes (the +default) respectively. At decompression time, the block size used for +compression is read from the header of the compressed file, and +.I bunzip2 +then allocates itself just enough memory to decompress +the file. Since block sizes are stored in compressed files, it follows +that the flags \-1 to \-9 are irrelevant to and so ignored +during decompression. + +Compression and decompression requirements, +in bytes, can be estimated as: + + Compression: 400k + ( 8 x block size ) + + Decompression: 100k + ( 4 x block size ), or + 100k + ( 2.5 x block size ) + +Larger block sizes give rapidly diminishing marginal returns. Most of +the compression comes from the first two or three hundred k of block +size, a fact worth bearing in mind when using +.I bzip2 +on small machines. +It is also important to appreciate that the decompression memory +requirement is set at compression time by the choice of block size. + +For files compressed with the default 900k block size, +.I bunzip2 +will require about 3700 kbytes to decompress. To support decompression +of any file on a 4 megabyte machine, +.I bunzip2 +has an option to +decompress using approximately half this amount of memory, about 2300 +kbytes. Decompression speed is also halved, so you should use this +option only where necessary. The relevant flag is -s. + +In general, try and use the largest block size memory constraints allow, +since that maximises the compression achieved. Compression and +decompression speed are virtually unaffected by block size. + +Another significant point applies to files which fit in a single block +-- that means most files you'd encounter using a large block size. The +amount of real memory touched is proportional to the size of the file, +since the file is smaller than a block. For example, compressing a file +20,000 bytes long with the flag -9 will cause the compressor to +allocate around 7600k of memory, but only touch 400k + 20000 * 8 = 560 +kbytes of it. Similarly, the decompressor will allocate 3700k but only +touch 100k + 20000 * 4 = 180 kbytes. + +Here is a table which summarises the maximum memory usage for different +block sizes. Also recorded is the total compressed size for 14 files of +the Calgary Text Compression Corpus totalling 3,141,622 bytes. This +column gives some feel for how compression varies with block size. +These figures tend to understate the advantage of larger block sizes for +larger files, since the Corpus is dominated by smaller files. + + Compress Decompress Decompress Corpus + Flag usage usage -s usage Size + + -1 1200k 500k 350k 914704 + -2 2000k 900k 600k 877703 + -3 2800k 1300k 850k 860338 + -4 3600k 1700k 1100k 846899 + -5 4400k 2100k 1350k 845160 + -6 5200k 2500k 1600k 838626 + -7 6100k 2900k 1850k 834096 + -8 6800k 3300k 2100k 828642 + -9 7600k 3700k 2350k 828642 + +.SH RECOVERING DATA FROM DAMAGED FILES +.I bzip2 +compresses files in blocks, usually 900kbytes long. Each +block is handled independently. If a media or transmission error causes +a multi-block .bz2 +file to become damaged, it may be possible to +recover data from the undamaged blocks in the file. + +The compressed representation of each block is delimited by a 48-bit +pattern, which makes it possible to find the block boundaries with +reasonable certainty. Each block also carries its own 32-bit CRC, so +damaged blocks can be distinguished from undamaged ones. + +.I bzip2recover +is a simple program whose purpose is to search for +blocks in .bz2 files, and write each block out into its own .bz2 +file. You can then use +.I bzip2 +\-t +to test the +integrity of the resulting files, and decompress those which are +undamaged. + +.I bzip2recover +takes a single argument, the name of the damaged file, +and writes a number of files "rec00001file.bz2", +"rec00002file.bz2", etc, containing the extracted blocks. +The output filenames are designed so that the use of +wildcards in subsequent processing -- for example, +"bzip2 -dc rec*file.bz2 > recovered_data" -- processes the files in +the correct order. + +.I bzip2recover +should be of most use dealing with large .bz2 +files, as these will contain many blocks. It is clearly +futile to use it on damaged single-block files, since a +damaged block cannot be recovered. If you wish to minimise +any potential data loss through media or transmission errors, +you might consider compressing with a smaller +block size. + +.SH PERFORMANCE NOTES +The sorting phase of compression gathers together similar strings in the +file. Because of this, files containing very long runs of repeated +symbols, like "aabaabaabaab ..." (repeated several hundred times) may +compress more slowly than normal. Versions 0.9.5 and above fare much +better than previous versions in this respect. The ratio between +worst-case and average-case compression time is in the region of 10:1. +For previous versions, this figure was more like 100:1. You can use the +\-vvvv option to monitor progress in great detail, if you want. + +Decompression speed is unaffected by these phenomena. + +.I bzip2 +usually allocates several megabytes of memory to operate +in, and then charges all over it in a fairly random fashion. This means +that performance, both for compressing and decompressing, is largely +determined by the speed at which your machine can service cache misses. +Because of this, small changes to the code to reduce the miss rate have +been observed to give disproportionately large performance improvements. +I imagine +.I bzip2 +will perform best on machines with very large caches. + +.SH CAVEATS +I/O error messages are not as helpful as they could be. +.I bzip2 +tries hard to detect I/O errors and exit cleanly, but the details of +what the problem is sometimes seem rather misleading. + +This manual page pertains to version 1.0.8 of +.I bzip2. +Compressed data created by this version is entirely forwards and +backwards compatible with the previous public releases, versions +0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 1.0.2 and above, but with the following +exception: 0.9.0 and above can correctly decompress multiple +concatenated compressed files. 0.1pl2 cannot do this; it will stop +after decompressing just the first file in the stream. + +.I bzip2recover +versions prior to 1.0.2 used 32-bit integers to represent +bit positions in compressed files, so they could not handle compressed +files more than 512 megabytes long. Versions 1.0.2 and above use +64-bit ints on some platforms which support them (GNU supported +targets, and Windows). To establish whether or not bzip2recover was +built with such a limitation, run it without arguments. In any event +you can build yourself an unlimited version if you can recompile it +with MaybeUInt64 set to be an unsigned 64-bit integer. + + + +.SH AUTHOR +Julian Seward, jseward@acm.org. + +https://sourceware.org/bzip2/ + +The ideas embodied in +.I bzip2 +are due to (at least) the following +people: Michael Burrows and David Wheeler (for the block sorting +transformation), David Wheeler (again, for the Huffman coder), Peter +Fenwick (for the structured coding model in the original +.I bzip, +and many refinements), and Alistair Moffat, Radford Neal and Ian Witten +(for the arithmetic coder in the original +.I bzip). +I am much +indebted for their help, support and advice. See the manual in the +source distribution for pointers to sources of documentation. Christian +von Roques encouraged me to look for faster sorting algorithms, so as to +speed up compression. Bela Lubkin encouraged me to improve the +worst-case compression performance. +Donna Robinson XMLised the documentation. +The bz* scripts are derived from those of GNU gzip. +Many people sent patches, helped +with portability problems, lent machines, gave advice and were generally +helpful. diff --git a/upstream/fedora-40/man1/bzmore.1 b/upstream/fedora-40/man1/bzmore.1 new file mode 100644 index 00000000..b437d3b0 --- /dev/null +++ b/upstream/fedora-40/man1/bzmore.1 @@ -0,0 +1,152 @@ +.\"Shamelessly copied from zmore.1 by Philippe Troin +.\"for Debian GNU/Linux +.TH BZMORE 1 +.SH NAME +bzmore, bzless \- file perusal filter for crt viewing of bzip2 compressed text +.SH SYNOPSIS +.B bzmore +[ name ... ] +.br +.B bzless +[ name ... ] +.SH NOTE +In the following description, +.I bzless +and +.I less +can be used interchangeably with +.I bzmore +and +.I more. +.SH DESCRIPTION +.I Bzmore +is a filter which allows examination of compressed or plain text files +one screenful at a time on a soft-copy terminal. +.I bzmore +works on files compressed with +.I bzip2 +and also on uncompressed files. +If a file does not exist, +.I bzmore +looks for a file of the same name with the addition of a .bz2 suffix. +.PP +.I Bzmore +normally pauses after each screenful, printing --More-- +at the bottom of the screen. +If the user then types a carriage return, one more line is displayed. +If the user hits a space, +another screenful is displayed. Other possibilities are enumerated later. +.PP +.I Bzmore +looks in the file +.I /etc/termcap +to determine terminal characteristics, +and to determine the default window size. +On a terminal capable of displaying 24 lines, +the default window size is 22 lines. +Other sequences which may be typed when +.I bzmore +pauses, and their effects, are as follows (\fIi\fP is an optional integer +argument, defaulting to 1) : +.PP +.IP \fIi\|\fP +display +.I i +more lines, (or another screenful if no argument is given) +.PP +.IP ^D +display 11 more lines (a ``scroll''). +If +.I i +is given, then the scroll size is set to \fIi\|\fP. +.PP +.IP d +same as ^D (control-D) +.PP +.IP \fIi\|\fPz +same as typing a space except that \fIi\|\fP, if present, becomes the new +window size. Note that the window size reverts back to the default at the +end of the current file. +.PP +.IP \fIi\|\fPs +skip \fIi\|\fP lines and print a screenful of lines +.PP +.IP \fIi\|\fPf +skip \fIi\fP screenfuls and print a screenful of lines +.PP +.IP "q or Q" +quit reading the current file; go on to the next (if any) +.PP +.IP "e or q" +When the prompt --More--(Next file: +.IR file ) +is printed, this command causes bzmore to exit. +.PP +.IP s +When the prompt --More--(Next file: +.IR file ) +is printed, this command causes bzmore to skip the next file and continue. +.PP +.IP = +Display the current line number. +.PP +.IP \fIi\|\fP/expr +search for the \fIi\|\fP-th occurrence of the regular expression \fIexpr.\fP +If the pattern is not found, +.I bzmore +goes on to the next file (if any). +Otherwise, a screenful is displayed, starting two lines before the place +where the expression was found. +The user's erase and kill characters may be used to edit the regular +expression. +Erasing back past the first column cancels the search command. +.PP +.IP \fIi\|\fPn +search for the \fIi\|\fP-th occurrence of the last regular expression entered. +.PP +.IP !command +invoke a shell with \fIcommand\|\fP. +The character `!' in "command" are replaced with the +previous shell command. The sequence "\\!" is replaced by "!". +.PP +.IP ":q or :Q" +quit reading the current file; go on to the next (if any) +(same as q or Q). +.PP +.IP . +(dot) repeat the previous command. +.PP +The commands take effect immediately, i.e., it is not necessary to +type a carriage return. +Up to the time when the command character itself is given, +the user may hit the line kill character to cancel the numerical +argument being formed. +In addition, the user may hit the erase character to redisplay the +--More-- message. +.PP +At any time when output is being sent to the terminal, the user can +hit the quit key (normally control\-\\). +.I Bzmore +will stop sending output, and will display the usual --More-- +prompt. +The user may then enter one of the above commands in the normal manner. +Unfortunately, some output is lost when this is done, due to the +fact that any characters waiting in the terminal's output queue +are flushed when the quit signal occurs. +.PP +The terminal is set to +.I noecho +mode by this program so that the output can be continuous. +What you type will thus not show on your terminal, except for the / and ! +commands. +.PP +If the standard output is not a teletype, then +.I bzmore +acts just like +.I bzcat, +except that a header is printed before each file. +.SH FILES +.DT +/etc/termcap Terminal data base +.SH "SEE ALSO" +more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1) diff --git a/upstream/fedora-40/man1/c++filt.1 b/upstream/fedora-40/man1/c++filt.1 new file mode 100644 index 00000000..b2a53fdd --- /dev/null +++ b/upstream/fedora-40/man1/c++filt.1 @@ -0,0 +1,298 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "C++FILT 1" +.TH C++FILT 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +c++filt \- demangle C++ and Java symbols +.SH SYNOPSIS +.IX Header "SYNOPSIS" +c++filt [\fB\-_\fR|\fB\-\-strip\-underscore\fR] + [\fB\-n\fR|\fB\-\-no\-strip\-underscore\fR] + [\fB\-p\fR|\fB\-\-no\-params\fR] + [\fB\-t\fR|\fB\-\-types\fR] + [\fB\-i\fR|\fB\-\-no\-verbose\fR] + [\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR] + [\fB\-R\fR|\fB\-\-recurse\-limit\fR] + [\fB\-s\fR \fIformat\fR|\fB\-\-format=\fR\fIformat\fR] + [\fB\-\-help\fR] [\fB\-\-version\fR] [\fIsymbol\fR...] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The C++ and Java languages provide function overloading, which means +that you can write many functions with the same name, providing that +each function takes parameters of different types. In order to be +able to distinguish these similarly named functions C++ and Java +encode them into a low-level assembler name which uniquely identifies +each different version. This process is known as \fImangling\fR. The +\&\fBc++filt\fR +[1] +program does the inverse mapping: it decodes (\fIdemangles\fR) low-level +names into user-level names so that they can be read. +.PP +Every alphanumeric word (consisting of letters, digits, underscores, +dollars, or periods) seen in the input is a potential mangled name. +If the name decodes into a C++ name, the C++ name replaces the +low-level name in the output, otherwise the original word is output. +In this way you can pass an entire assembler source file, containing +mangled names, through \fBc++filt\fR and see the same source file +containing demangled names. +.PP +You can also use \fBc++filt\fR to decipher individual symbols by +passing them on the command line: +.PP +.Vb 1 +\& c++filt +.Ve +.PP +If no \fIsymbol\fR arguments are given, \fBc++filt\fR reads symbol +names from the standard input instead. All the results are printed on +the standard output. The difference between reading names from the +command line versus reading names from the standard input is that +command-line arguments are expected to be just mangled names and no +checking is performed to separate them from surrounding text. Thus +for example: +.PP +.Vb 1 +\& c++filt \-n _Z1fv +.Ve +.PP +will work and demangle the name to "f()" whereas: +.PP +.Vb 1 +\& c++filt \-n _Z1fv, +.Ve +.PP +will not work. (Note the extra comma at the end of the mangled +name which makes it invalid). This command however will work: +.PP +.Vb 1 +\& echo _Z1fv, | c++filt \-n +.Ve +.PP +and will display "f(),", i.e., the demangled name followed by a +trailing comma. This behaviour is because when the names are read +from the standard input it is expected that they might be part of an +assembler source file where there might be extra, extraneous +characters trailing after a mangled name. For example: +.PP +.Vb 1 +\& .type _Z1fv, @function +.Ve +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB\-_\fR 4 +.IX Item "-_" +.PD 0 +.IP \fB\-\-strip\-underscore\fR 4 +.IX Item "--strip-underscore" +.PD +On some systems, both the C and C++ compilers put an underscore in front +of every name. For example, the C name \f(CW\*(C`foo\*(C'\fR gets the low-level +name \f(CW\*(C`_foo\*(C'\fR. This option removes the initial underscore. Whether +\&\fBc++filt\fR removes the underscore by default is target dependent. +.IP \fB\-n\fR 4 +.IX Item "-n" +.PD 0 +.IP \fB\-\-no\-strip\-underscore\fR 4 +.IX Item "--no-strip-underscore" +.PD +Do not remove the initial underscore. +.IP \fB\-p\fR 4 +.IX Item "-p" +.PD 0 +.IP \fB\-\-no\-params\fR 4 +.IX Item "--no-params" +.PD +When demangling the name of a function, do not display the types of +the function's parameters. +.IP \fB\-t\fR 4 +.IX Item "-t" +.PD 0 +.IP \fB\-\-types\fR 4 +.IX Item "--types" +.PD +Attempt to demangle types as well as function names. This is disabled +by default since mangled types are normally only used internally in +the compiler, and they can be confused with non-mangled names. For example, +a function called "a" treated as a mangled type name would be +demangled to "signed char". +.IP \fB\-i\fR 4 +.IX Item "-i" +.PD 0 +.IP \fB\-\-no\-verbose\fR 4 +.IX Item "--no-verbose" +.PD +Do not include implementation details (if any) in the demangled +output. +.IP \fB\-r\fR 4 +.IX Item "-r" +.PD 0 +.IP \fB\-R\fR 4 +.IX Item "-R" +.IP \fB\-\-recurse\-limit\fR 4 +.IX Item "--recurse-limit" +.IP \fB\-\-no\-recurse\-limit\fR 4 +.IX Item "--no-recurse-limit" +.IP \fB\-\-recursion\-limit\fR 4 +.IX Item "--recursion-limit" +.IP \fB\-\-no\-recursion\-limit\fR 4 +.IX Item "--no-recursion-limit" +.PD +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an infinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. +.Sp +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. +.Sp +The \fB\-r\fR option is a synonym for the +\&\fB\-\-no\-recurse\-limit\fR option. The \fB\-R\fR option is a +synonym for the \fB\-\-recurse\-limit\fR option. +.IP "\fB\-s\fR \fIformat\fR" 4 +.IX Item "-s format" +.PD 0 +.IP \fB\-\-format=\fR\fIformat\fR 4 +.IX Item "--format=format" +.PD +\&\fBc++filt\fR can decode various methods of mangling, used by +different compilers. The argument to this option selects which +method it uses: +.RS 4 +.ie n .IP """auto""" 4 +.el .IP \f(CWauto\fR 4 +.IX Item "auto" +Automatic selection based on executable (the default method) +.ie n .IP """gnu""" 4 +.el .IP \f(CWgnu\fR 4 +.IX Item "gnu" +the one used by the GNU C++ compiler (g++) +.ie n .IP """lucid""" 4 +.el .IP \f(CWlucid\fR 4 +.IX Item "lucid" +the one used by the Lucid compiler (lcc) +.ie n .IP """arm""" 4 +.el .IP \f(CWarm\fR 4 +.IX Item "arm" +the one specified by the C++ Annotated Reference Manual +.ie n .IP """hp""" 4 +.el .IP \f(CWhp\fR 4 +.IX Item "hp" +the one used by the HP compiler (aCC) +.ie n .IP """edg""" 4 +.el .IP \f(CWedg\fR 4 +.IX Item "edg" +the one used by the EDG compiler +.ie n .IP """gnu\-v3""" 4 +.el .IP \f(CWgnu\-v3\fR 4 +.IX Item "gnu-v3" +the one used by the GNU C++ compiler (g++) with the V3 ABI. +.ie n .IP """java""" 4 +.el .IP \f(CWjava\fR 4 +.IX Item "java" +the one used by the GNU Java compiler (gcj) +.ie n .IP """gnat""" 4 +.el .IP \f(CWgnat\fR 4 +.IX Item "gnat" +the one used by the GNU Ada compiler (GNAT). +.RE +.RS 4 +.RE +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Print a summary of the options to \fBc++filt\fR and exit. +.IP \fB\-\-version\fR 4 +.IX Item "--version" +Print the version number of \fBc++filt\fR and exit. +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH FOOTNOTES +.IX Header "FOOTNOTES" +.IP 1. 4 +MS-DOS does not allow \f(CW\*(C`+\*(C'\fR characters in file names, so on +MS-DOS this program is named \fBCXXFILT\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +the Info entries for \fIbinutils\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/cameratopam.1 b/upstream/fedora-40/man1/cameratopam.1 new file mode 100644 index 00000000..ce9fdde5 --- /dev/null +++ b/upstream/fedora-40/man1/cameratopam.1 @@ -0,0 +1,192 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Cameratopam User Manual" 0 "12 April 2005" "netpbm documentation" + +.SH NAME +cameratopam - convert raw camera image to PAM + +.UN synopsis +.SH SYNOPSIS + +\fBcameratopam\fP + +[\fIinput_file_name\fP] + +[\fB-identify_only\fP] +[\fB-quick_interpolate\fP] +[\fB-half_size\fP] +[\fB-four_color_rgb\fP] +[\fB-document_mode\fP] +[\fB-balance_auto\fP] +[\fB-balance_camera\fP] +[\fB-red_scale=\fP\fIfloat\fP] +[\fB-blue_scale=\fP\fIfloat\fP] +[\fB-bright=\fP\fIfraction\fP] +[\fB-no_clip_color\fP] +[\fB-rgb\fP] +[\fB-use_secondary\fP] +[\fB-linear\fP] +[\fB-verbose\fP] +.PP +All options can be abbreviated to their shortest unique prefix. You +may use two hyphens instead of one to designate an option. You may +use either white space or an equals sign between an option name and +its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBcameratopam\fP converts from any of dozens of raw camera image +formats to PAM. +.PP +Digital still cameras often can produce images in a special raw +format in addition to something more standard such as TIFF or JFIF +(JPEG). Software supplied with the camera allows you to manipulate +the image using information which is lost when the camera converts to +the common format. A particular camera model often has a unique raw +format. + + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBcameratopam\fP recognizes the following +command line options: + + +.TP +\fB-identify_only\fP +Report to Standard Error the format of the input image but don't +generate an output image. Program fails if it cannot recognize the +format. + +.TP +\fB-verbose\fP +Report to Standard Error details of the processing. + +.TP +\fB-quick_interpolate\fP +Use simple bilinear interpolation for quick results. The default +is to use a slow, high-quality adaptive algorithm. + +.TP +\fB-half_size\fP +Half-size the output image. Instead of interpolating, reduce +each 2x2 block of sensors to one pixel. Much faster than +\fB-quick_interpolate\fP. + +.TP +\fB-four_color_rgb\fP +Interpolate RGB as four colors. This causes a slight loss of +detail, so use this only if you see false 2x2 mesh patterns in blue +sky. + +.TP +\fB-document_mode\fP +Show the raw data as a grayscale image with no interpolation. +This is good for photographing black and white documents. + +.TP +\fB-balance_auto\fP +Automatic color balance. The default is to use a fixed +color balance based on a white card photographed in sunlight. + +.TP +\fB-balance_camera\fP +Use the color balance specified by the camera. If +\fBcameratopam\fP can't find this, it prints a warning and reverts to +the default. + +.TP +\fB-red_scale=\fP\fIfloat\fP +.TP +\fB-blue_scale\fP\fIfloat\fP +Further adjust the color balance by multiplying the red and blue +channels by these values. Both default to 1.0. + +.TP +\fB-bright=\fP\fIfloat\fP +Change the output brightness. Default is 1.0. + +.TP +\fB-no_clip_color\fP +By default, \fBcameratoapm\fP clips all colors to prevent pink +hues in the highlights. Combine this option with +\fB-bright=0.25\fP to leave the image data completely unclipped. + +.TP +\fB-rgb\fP +Write raw camera colors to the output file. By default, +\fBcameratoapm\fP converts to sRGB colorspace. + +.TP +\fB-use_secondary\fP +For cameras based on the Fuji Super CCD SR, this option causes +\fBcameratopam\fP to use the secondary sensors, in effect +underexposing the image by four stops to reveal detail in the +highlights. \fBcameratopam\fP silently ignores this option for all +other cameras. + +.TP +\fB-linear\fP +This option causes \fBcameratopam\fP to generate a variation on +PAM that has "linear" color samples. In true PAM, each +sample in the image raster is gamma-corrected; i.e. it is essentially +proportional to brightness. With the \fBlinear\fP option, +\fBcameratopam\fP generates an image in which the samples are instead +proportional to light intensity. +.sp +Without \fB-linear\fP, the image maxval is 255, so the image +contains one byte per sample. With \fB-linear\fP, the maxval is +65535, so the image contains two bytes per sample. +.sp +Without \fB-linear\fP, \fBcameratopam\fP uses a 99th percentile +white point. With \fB-linear\fP, it doesn't. I don't know what that +means. + + + + +.UN seealso +.SH SEE ALSO +.BR "411toppm" (1)\c +\&, +.BR "pamflip" (1)\c +\&, +.BR "pam" (1)\c +\&, + +.UN history +.SH HISTORY +.PP +\fBcameratopam\fP was new in Netpbm 10.28 (June 2005). +.PP +It was derived from the program +.UR https://dechifro.org/dcraw/ +\fBdcraw\fP by Dave Coffin +.UE +\&, by Bryan Henderson in April 2005. Bryan replaced the part +that generates the Netpbm output image and removed the Adobe Photoshop +output function. Bryan changed the command syntax and made other +small changes to make the program consistent with Netpbm. He also +split the source code into manageable pieces (\fBdcraw\fP had a +single 5000 line source file). +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/cameratopam.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/captoinfo.1m b/upstream/fedora-40/man1/captoinfo.1m new file mode 100644 index 00000000..7bec27d3 --- /dev/null +++ b/upstream/fedora-40/man1/captoinfo.1m @@ -0,0 +1,234 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: captoinfo.1m,v 1.58 2023/12/23 16:28:31 tom Exp $ +.TH captoinfo 1M 2023-12-23 "ncurses 6.4" "User commands" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +.SH NAME +\fB\%captoinfo\fP \- +convert a \fItermcap\fP description into a \fI\%term\%info\fP description +.SH SYNOPSIS +.B captoinfo +.RI [ tic-option ] +.RI [ file +\&.\|.\|.] +.P +.B "captoinfo \-V" +.SH DESCRIPTION +\fB\%captoinfo\fP translates terminal descriptions. +It looks in each given text \fIfile\fP for \fI\%termcap\fP entries and, +for each one found, +writes an equivalent \fI\%\%term\%info\fP description to the standard +output stream. +\fI\%termcap\fP \fBtc\fP capabilities translate to \fI\%\%term\%info\fP +\*(``\fBuse\fP\*('' capabilities. +.PP +If no \fIfile\fPs are specified, +\fB\%captoinfo\fP interprets the content of the environment variable +\fI\%TERMCAP\fP as a file name, +and extracts only the entry for the terminal named in the environment +variable \fITERM\fP from it. +If the environment variable \fI\%TERMCAP\fP is not set, +\fB\%captoinfo\fP reads +.I \%/etc/termcap. +.PP +This utility is implemented as a link to \fB\%tic\fP(1M), +with the latter's +.B \-I +option implied. +You can use other \fB\%tic\fP options such as +.BR \-1 , +.BR \-f , +.BR \-v , +.BR \-w , +and +.BR \-x . +The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated +with this program and exits with a successful status. +.SS "Translations from Nonstandard Capabilities" +\fB\%captoinfo\fP translates some obsolete, +nonstandard capabilities into standard +(SVr4/XSI Curses) +\fI\%\%term\%info\fP capabilities. +It issues a diagnostic to the standard error stream for each, +inviting the user to check that it has not mistakenly translated an +unknown or mistyped capability name. +.PP +.TS +center; +Cb S +Cb Cb Cb Cb +Cb Cb C Lb. +Name +Obsolete Standard Origin \f(BIterminfo\fP capability +_ +BO mr AT&T enter_reverse_mode +CI vi AT&T cursor_invisible +CV ve AT&T cursor_normal +DS mh AT&T enter_dim_mode +EE me AT&T exit_attribute_mode +FE LF AT&T label_on +FL LO AT&T label_off +XS mk AT&T enter_secure_mode +EN @7 XENIX key_end +GE ae XENIX exit_alt_charset_mode +GS as XENIX enter_alt_charset_mode +HM kh XENIX key_home +LD kL XENIX key_dl +PD kN XENIX key_npage +PN po XENIX prtr_off +PS pf XENIX prtr_on +PU kP XENIX key_ppage +RT @8 XENIX kent +UP ku XENIX kcuu1 +KA k; Tektronix key_f10 +KB F1 Tektronix key_f11 +KC F2 Tektronix key_f12 +KD F3 Tektronix key_f13 +KE F4 Tektronix key_f14 +KF F5 Tektronix key_f15 +BC Sb Tektronix set_background +FC Sf Tektronix set_foreground +HS mh IRIX enter_dim_mode +.TE +.PP +XENIX \fI\%termcap\fP had a set of extension capabilities, +corresponding to box drawing characters of CCSID +(\*(``code page\*('') 437, +as follows. +.PP +.TS +center; +cb cb +cb l . +\f(BItermcap\fP Name Graphic +_ +G2 upper left corner +G3 lower left corner +G1 upper right corner +G4 lower right corner +GR tee pointing right +GL tee pointing left +GU tee pointing up +GD tee pointing down +GH horizontal line +GV vertical line +GC intersection +G6 double upper left corner +G7 double lower left corner +G5 double upper right corner +G8 double lower right corner +Gr double tee pointing right +Gr double tee pointing left +Gu double tee pointing up +Gd double tee pointing down +Gh double horizontal line +Gv double vertical line +Gc double intersection +.\" TODO: There are about 40 box drawing code points in CCSID 437; +.\" were there no XENIX capabilities for the mixed single- and double- +.\" line intersections? +.\" +.\" TODO: GG doesn't seem to fit with the others; explain it. +GG ACS magic cookie count +.TE +.PP +\fB\%captoinfo\fP composes single-line capabilities into an \fBacsc\fP +string, +and discards \fBGG\fP and double-line capabilities with a warning +diagnostic. +.PP +IBM's AIX has a \fI\%\%term\%info\fP facility descended from SVr1 +\fI\%\%term\%info\fP, +but which is incompatible with the SVr4 format. +\fB\%captoinfo\fP translates the following AIX extensions. +.PP +.TS +center; +cb cb +l l . +IBM XSI +_ +ksel kslt +kbtab kcbt +font0 s0ds +font1 s1ds +font2 s2ds +font3 s3ds +.TE +.PP +Additionally, +this program translates the AIX \fBbox1\fP capability to an \fBacsc\fP +string. +.PP +The HP-UX \fI\%\%term\%info\fP library supports two nonstandard +\fI\%\%term\%info\fP capabilities, +\fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock). +\fB\%captoinfo\fP discards these with a warning message. +.SH FILES +.TP +.I /etc/termcap +default \fI\%termcap\fP terminal capability database +.SH PORTABILITY +X/Open Curses, +Issue 7 (2009) describes \fBtic\fP briefly, +but omits this program. +.PP +SVr4 systems provide \fB\%captoinfo\fP as a separate application from +\fBtic\fP. +Its +.B \-v +option does not accept a trace level argument +.I n; +repeat +.B \-v +.I n +times instead. +.PP +NetBSD does not provide this application. +.SH AUTHORS +Eric S. Raymond +and +.br +Thomas E. Dickey +.SH SEE ALSO +\fB\%infocmp\fP(1M), +\fB\%tic\fP(1M), +\fB\%curses\fP(3X), +\fB\%terminfo\fP(5) diff --git a/upstream/fedora-40/man1/cat.1 b/upstream/fedora-40/man1/cat.1 new file mode 100644 index 00000000..d5d83585 --- /dev/null +++ b/upstream/fedora-40/man1/cat.1 @@ -0,0 +1,75 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CAT "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +cat \- concatenate files and print on the standard output +.SH SYNOPSIS +.B cat +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Concatenate FILE(s) to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.TP +\fB\-A\fR, \fB\-\-show\-all\fR +equivalent to \fB\-vET\fR +.TP +\fB\-b\fR, \fB\-\-number\-nonblank\fR +number nonempty output lines, overrides \fB\-n\fR +.TP +\fB\-e\fR +equivalent to \fB\-vE\fR +.TP +\fB\-E\fR, \fB\-\-show\-ends\fR +display $ at end of each line +.TP +\fB\-n\fR, \fB\-\-number\fR +number all output lines +.TP +\fB\-s\fR, \fB\-\-squeeze\-blank\fR +suppress repeated empty output lines +.TP +\fB\-t\fR +equivalent to \fB\-vT\fR +.TP +\fB\-T\fR, \fB\-\-show\-tabs\fR +display TAB characters as ^I +.TP +\fB\-u\fR +(ignored) +.TP +\fB\-v\fR, \fB\-\-show\-nonprinting\fR +use ^ and M\- notation, except for LFD and TAB +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH EXAMPLES +.TP +cat f \- g +Output f's contents, then standard input, then g's contents. +.TP +cat +Copy standard input to standard output. +.SH AUTHOR +Written by Torbjorn Granlund and Richard M. Stallman. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBtac\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) cat invocation\(aq diff --git a/upstream/fedora-40/man1/cdda2ogg.1 b/upstream/fedora-40/man1/cdda2ogg.1 new file mode 100644 index 00000000..f07c7336 --- /dev/null +++ b/upstream/fedora-40/man1/cdda2ogg.1 @@ -0,0 +1,108 @@ +'\" +.TH "cdda2ogg" "1" +.SH "NAME" +cdda2ogg \(em extract audio CD audio tracks and encode them +.SH "SYNOPSIS" +.PP +.B cdda2ogg +.PP +.SH "DESCRIPTION" +.PP +.B cdda2ogg is a simple script that uses the +.B icedax +command to extract all audio tracks with the +.B icedax +command and encode them using the +.B ogg123 +encoder. The scripts are not intended to be full-featured music archiving +programs, but only for quick storing of few audio data. +It does not use databases like CDDB or have any extra features. You may look +at +.B icedax +if you need them. +.PP +.B ogg123 +is provided by the +.B vorbis-tools +which needs to be installed separately. +See +.B www.ogg.org +for more information. + +.SH "CONFIGURATION" +.PP +.B cdda2ogg +have predefined values for reading and labeling of the target files. +You can overwrite them with following environment variables: + +.IP "CDDA_DEVICE" 10 +Source device specification to get the data from. + +.IP "LIST" 10 +List of track numbers to be read, separated by spaces. + +.IP "CDDA2WAV" 10 +Defines the command to run the cdda2wav program + +.IP "CDDA2WAV_OPTS" 10 +Miscellaneous options passed to +.IR $CDDA2WAV . + +.IP "MP_CODER" 10 +The encoder program. + +.IP "MP_OPTIONS" 10 +Additional options passed to +.IR $MP_CODER . + +.IP "FILEPREFIX" 10 +The base part of the filename of resulting audio files. This can also be specified as the first argument to the script. + +.PP +See cdda2ogg script file to get the default values +.PP +System administrator can also set default values by creating of a shell +include file, defining the variables for the POSIX shell, and storing them as +/etc/default/cdda2ogg. +.SH "EXAMPLES" +.PP +.B CDDA_DEVICE=/dev/cdrom1 cdda2ogg +.br +just stores every track in this device in audiotrackNUMBER.ogg +.PP +.PP +.B LIST="1 5 7" cdda2ogg PartsOfBestOfFoo +.br +stores the selected tracks from the default cdrom device as 01-PartsOfBestOfFoo.ogg, 05-PartsOfBestOfFoo.ogg, 07-PartsOfBestOfFoo.ogg. + +.SH "SEE ALSO" +.BR icedax (1) +.SH "AUTHOR" +.PP +This manpage describes the program implementation of +.B +cdda2ogg +as shipped by the cdrkit distribution. See +.B +http://alioth.debian.org/projects/debburn/ +for details. It is a spinoff from the original program distributed by the cdrtools project. However, the cdrtools developers are not involved in the development of this spinoff and therefore shall not be made responsible for any problem caused by it. Do not try to get support for this program by contacting the original authors. +.PP +If you have support questions, send them to +.PP +.B +debburn-devel@lists.alioth.debian.org +.br +.PP +If you have definitely found a bug, send a mail to this list or to +.PP +.B +submit@bugs.debian.org +.br +.PP +writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body. +.PP +This manual page was written by Eduard Bloch +(blade@debian.org) for the +.B "Debian GNU/Linux system (but may be used by others). Permission is granted +to copy, distribute and/or modify this document under the terms of the GNU +General Public License, Version 2 as published by the Free Software Foundation. diff --git a/upstream/fedora-40/man1/chattr.1 b/upstream/fedora-40/man1/chattr.1 new file mode 100644 index 00000000..1ba1bf18 --- /dev/null +++ b/upstream/fedora-40/man1/chattr.1 @@ -0,0 +1,299 @@ +.\" -*- nroff -*- +.TH CHATTR 1 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +chattr \- change file attributes on a Linux file system +.SH SYNOPSIS +.B chattr +[ +.B \-RVf +] +[ +.B \-v +.I version +] +[ +.B \-p +.I project +] +[ +.I mode +] +.I files... +.SH DESCRIPTION +.B chattr +changes the file attributes on a Linux file system. +.PP +The format of a symbolic +.I mode +is +.BR +-= [ aAcCdDeFijmPsStTux ]. +.PP +The operator +.RB ' + ' +causes the selected attributes to be added to the +existing attributes of the files; +.RB ' - ' +causes them to be removed; and +.RB ' = ' +causes them to be the only attributes that the files have. +.PP +The letters +.RB ' aAcCdDeFijmPsStTux ' +select the new attributes for the files: +append only +.RB ( a ), +no atime updates +.RB ( A ), +compressed +.RB ( c ), +no copy on write +.RB ( C ), +no dump +.RB ( d ), +synchronous directory updates +.RB ( D ), +extent format +.RB ( e ), +case-insensitive directory lookups +.RB ( F ), +immutable +.RB ( i ), +data journaling +.RB ( j ), +don't compress +.RB ( m ), +project hierarchy +.RB ( P ), +secure deletion +.RB ( s ), +synchronous updates +.RB ( S ), +no tail-merging +.RB ( t ), +top of directory hierarchy +.RB ( T ), +undeletable +.RB ( u ), +and direct access for files +.RB ( x ). +.PP +The following attributes are read-only, and may be listed by +.BR lsattr (1) +but not modified by chattr: +encrypted +.RB ( E ), +indexed directory +.RB ( I ), +inline data +.RB ( N ), +and verity +.RB ( V ). +.PP +Not all flags are supported or utilized by all file systems; refer to +file system-specific man pages such as +.BR btrfs (5), +.BR ext4 (5), +.BR mkfs.f2fs (8), +and +.BR xfs (5) +for more file system-specific details. +.SH OPTIONS +.TP +.B \-R +Recursively change attributes of directories and their contents. +.TP +.B \-V +Be verbose with chattr's output and print the program version. +.TP +.B \-f +Suppress most error messages. +.TP +.BI \-v " version" +Set the file's version/generation number. +.TP +.BI \-p " project" +Set the file's project number. +.SH ATTRIBUTES +.TP +.B a +A file with the 'a' attribute set can only be opened in append mode for +writing. Only the superuser or a process possessing the +CAP_LINUX_IMMUTABLE capability can set or clear this attribute. +.TP +.B A +When a file with the 'A' attribute set is accessed, its atime record is +not modified. This avoids a certain amount of disk I/O for laptop +systems. +.TP +.B c +A file with the 'c' attribute set is automatically compressed on the disk +by the kernel. A read from this file returns uncompressed data. A write to +this file compresses data before storing them on the disk. Note: please +make sure to read the bugs and limitations section at the end of this +document. (Note: For btrfs, If the 'c' flag is set, then the 'C' flag +cannot be set. Also conflicts with btrfs mount option 'nodatasum') +.TP +.B C +A file with the 'C' attribute set will not be subject to copy-on-write +updates. This flag is only supported on file systems which perform +copy-on-write. (Note: For btrfs, the 'C' flag should be +set on new or empty files. If it is set on a file which already has +data blocks, it is undefined when the blocks assigned to the file will +be fully stable. If the 'C' flag is set on a directory, it will have no +effect on the directory, but new files created in that directory will +have the No_COW attribute set. If the 'C' flag is set, then the 'c' flag +cannot be set.) +.TP +.B d +A file with the 'd' attribute set is not a candidate for backup when the +.BR dump (8) +program is run. +.TP +.B D +When a directory with the 'D' attribute set is modified, +the changes are written synchronously to the disk; this is equivalent to +the 'dirsync' mount option applied to a subset of the files. +.TP +.B e +The 'e' attribute indicates that the file is using extents for mapping +the blocks on disk. It may not be removed using +.BR chattr (1). +.TP +.B E +A file, directory, or symlink with the 'E' attribute set is encrypted by the +file system. This attribute may not be set or cleared using +.BR chattr (1), +although it can be displayed by +.BR lsattr (1). +.TP +.B F +A directory with the 'F' attribute set indicates that all the path +lookups inside that directory are made in a case-insensitive fashion. +This attribute can only be changed in empty directories on file systems +with the casefold feature enabled. +.TP +.B i +A file with the 'i' attribute cannot be modified: it cannot be deleted or +renamed, no link can be created to this file, most of the file's +metadata can not be modified, and the file can not be opened in write mode. +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE +capability can set or clear this attribute. +.TP +.B I +The 'I' attribute is used by the htree code to indicate that a directory +is being indexed using hashed trees. It may not be set or cleared using +.BR chattr (1), +although it can be displayed by +.BR lsattr (1). +.TP +.B j +A file with the 'j' attribute has all of its data written to the ext3 or +ext4 journal before being written to the file itself, if the file system +is mounted with the "data=ordered" or "data=writeback" options and the +file system has a journal. When the file system is mounted with the +"data=journal" option all file data is already journalled and this +attribute has no effect. Only the superuser or a process possessing the +CAP_SYS_RESOURCE capability can set or clear this attribute. +.TP +.B m +A file with the 'm' attribute is excluded from compression on file +systems that support per-file compression. +.TP +.B N +A file with the 'N' attribute set indicates that the file has data +stored inline, within the inode itself. It may not be set or cleared +using +.BR chattr (1), +although it can be displayed by +.BR lsattr (1). +.TP +.B P +A directory with the 'P' attribute set will enforce a hierarchical +structure for project id's. This means that files and directories created +in the directory will inherit the project id of the directory, rename +operations are constrained so when a file or directory is moved into +another directory, that the project ids must match. In addition, a +hard link to file can only be created when the project id for the file +and the destination directory match. +.TP +.B s +When a file with the 's' attribute set is deleted, its blocks are zeroed +and written back to the disk. Note: please make sure to read the bugs +and limitations section at the end of this document. +.TP +.B S +When a file with the 'S' attribute set is modified, +the changes are written synchronously to the disk; this is equivalent to +the 'sync' mount option applied to a subset of the files. +.TP +.B t +A file with the 't' attribute will not have a partial block fragment at +the end of the file merged with other files (for those file systems which +support tail-merging). This is necessary for applications such as LILO +which read the file system directly, and which don't understand tail-merged +files. Note: As of this writing, the ext2, ext3, and ext4 file systems do +not support tail-merging. +.TP +.B T +A directory with the 'T' attribute will be deemed to be the top of +directory hierarchies for the purposes of the Orlov block allocator. +This is a hint to the block allocator used by ext3 and ext4 that the +subdirectories under this directory are not related, and thus should be +spread apart for allocation purposes. For example it is a very good +idea to set the 'T' attribute on the /home directory, so that /home/john +and /home/mary are placed into separate block groups. For directories +where this attribute is not set, the Orlov block allocator will try to +group subdirectories closer together where possible. +.TP +.B u +When a file with the 'u' attribute set is deleted, its contents are +saved. This allows the user to ask for its undeletion. Note: please +make sure to read the bugs and limitations section at the end of this +document. +.TP +.B x +A file with the 'x' requests the use of direct access (dax) mode, if the +kernel supports DAX. This can be overridden by the 'dax=never' mount +option. For more information see the kernel documentation for dax: +. +.IP +If the attribute is set on an existing directory, it will be inherited +by all files and subdirectories that are subsequently created in the +directory. If an existing directory has contained some files and +subdirectories, modifying the attribute on the parent directory doesn't +change the attributes on these files and subdirectories. +.TP +.B V +A file with the 'V' attribute set has fs-verity enabled. It cannot be +written to, and the file system will automatically verify all data read +from it against a cryptographic hash that covers the entire file's +contents, e.g. via a Merkle tree. This makes it possible to efficiently +authenticate the file. This attribute may not be set or cleared using +.BR chattr (1), +although it can be displayed by +.BR lsattr (1). +.PP +.SH AUTHOR +.B chattr +was written by Remy Card . It is currently being +maintained by Theodore Ts'o . +.SH BUGS AND LIMITATIONS +The 'c', 's', and 'u' attributes are not honored +by the ext2, ext3, and ext4 file systems as implemented in the current +mainline Linux kernels. +Setting 'a' and 'i' attributes will not affect the ability to write +to already existing file descriptors. +.PP +The 'j' option is only useful for ext3 and ext4 file systems. +.PP +The 'D' option is only useful on Linux kernel 2.5.19 and later. +.SH AVAILABILITY +.B chattr +is part of the e2fsprogs package and is available from +http://e2fsprogs.sourceforge.net. +.SH SEE ALSO +.BR lsattr (1), +.BR btrfs (5), +.BR ext4 (5), +.BR mkfs.f2fs (8), +.BR xfs (5). diff --git a/upstream/fedora-40/man1/chcon.1 b/upstream/fedora-40/man1/chcon.1 new file mode 100644 index 00000000..af89d954 --- /dev/null +++ b/upstream/fedora-40/man1/chcon.1 @@ -0,0 +1,92 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CHCON "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +chcon \- change file security context +.SH SYNOPSIS +.B chcon +[\fI\,OPTION\/\fR]... \fI\,CONTEXT FILE\/\fR... +.br +.B chcon +[\fI\,OPTION\/\fR]... [\fI\,-u USER\/\fR] [\fI\,-r ROLE\/\fR] [\fI\,-l RANGE\/\fR] [\fI\,-t TYPE\/\fR] \fI\,FILE\/\fR... +.br +.B chcon +[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Change the SELinux security context of each FILE to CONTEXT. +With \fB\-\-reference\fR, change the security context of each FILE to that of RFILE. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-\-dereference\fR +affect the referent of each symbolic link (this is +the default), rather than the symbolic link itself +.TP +\fB\-h\fR, \fB\-\-no\-dereference\fR +affect symbolic links instead of any referenced file +.TP +\fB\-u\fR, \fB\-\-user\fR=\fI\,USER\/\fR +set user USER in the target security context +.TP +\fB\-r\fR, \fB\-\-role\fR=\fI\,ROLE\/\fR +set role ROLE in the target security context +.TP +\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR +set type TYPE in the target security context +.TP +\fB\-l\fR, \fB\-\-range\fR=\fI\,RANGE\/\fR +set range RANGE in the target security context +.TP +\fB\-\-no\-preserve\-root\fR +do not treat '/' specially (the default) +.TP +\fB\-\-preserve\-root\fR +fail to operate recursively on '/' +.TP +\fB\-\-reference\fR=\fI\,RFILE\/\fR +use RFILE's security context rather than specifying +a CONTEXT value +.TP +\fB\-R\fR, \fB\-\-recursive\fR +operate on files and directories recursively +.TP +\fB\-v\fR, \fB\-\-verbose\fR +output a diagnostic for every file processed +.PP +The following options modify how a hierarchy is traversed when the \fB\-R\fR +option is also specified. If more than one is specified, only the final +one takes effect. +.TP +\fB\-H\fR +if a command line argument is a symbolic link +to a directory, traverse it +.TP +\fB\-L\fR +traverse every symbolic link to a directory +encountered +.TP +\fB\-P\fR +do not traverse any symbolic links (default) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by Russell Coker and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) chcon invocation\(aq diff --git a/upstream/fedora-40/man1/chgrp.1 b/upstream/fedora-40/man1/chgrp.1 new file mode 100644 index 00000000..8ab8f0d7 --- /dev/null +++ b/upstream/fedora-40/man1/chgrp.1 @@ -0,0 +1,93 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CHGRP "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +chgrp \- change group ownership +.SH SYNOPSIS +.B chgrp +[\fI\,OPTION\/\fR]... \fI\,GROUP FILE\/\fR... +.br +.B chgrp +[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Change the group of each FILE to GROUP. +With \fB\-\-reference\fR, change the group of each FILE to that of RFILE. +.TP +\fB\-c\fR, \fB\-\-changes\fR +like verbose but report only when a change is made +.TP +\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR +suppress most error messages +.TP +\fB\-v\fR, \fB\-\-verbose\fR +output a diagnostic for every file processed +.TP +\fB\-\-dereference\fR +affect the referent of each symbolic link (this is +the default), rather than the symbolic link itself +.TP +\fB\-h\fR, \fB\-\-no\-dereference\fR +affect symbolic links instead of any referenced file +(useful only on systems that can change the +ownership of a symlink) +.TP +\fB\-\-no\-preserve\-root\fR +do not treat '/' specially (the default) +.TP +\fB\-\-preserve\-root\fR +fail to operate recursively on '/' +.TP +\fB\-\-reference\fR=\fI\,RFILE\/\fR +use RFILE's group rather than specifying a GROUP. +RFILE is always dereferenced if a symbolic link. +.TP +\fB\-R\fR, \fB\-\-recursive\fR +operate on files and directories recursively +.PP +The following options modify how a hierarchy is traversed when the \fB\-R\fR +option is also specified. If more than one is specified, only the final +one takes effect. +.TP +\fB\-H\fR +if a command line argument is a symbolic link +to a directory, traverse it +.TP +\fB\-L\fR +traverse every symbolic link to a directory +encountered +.TP +\fB\-P\fR +do not traverse any symbolic links (default) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH EXAMPLES +.TP +chgrp staff /u +Change the group of /u to "staff". +.TP +chgrp \-hR staff /u +Change the group of /u and subfiles to "staff". +.SH AUTHOR +Written by David MacKenzie and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBchown\fP(1), \fBchown\fP(2) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) chgrp invocation\(aq diff --git a/upstream/fedora-40/man1/chmod.1 b/upstream/fedora-40/man1/chmod.1 new file mode 100644 index 00000000..c0869f14 --- /dev/null +++ b/upstream/fedora-40/man1/chmod.1 @@ -0,0 +1,174 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CHMOD "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +chmod \- change file mode bits +.SH SYNOPSIS +.B chmod +[\fI\,OPTION\/\fR]... \fI\,MODE\/\fR[\fI\,,MODE\/\fR]... \fI\,FILE\/\fR... +.br +.B chmod +[\fI\,OPTION\/\fR]... \fI\,OCTAL-MODE FILE\/\fR... +.br +.B chmod +[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR... +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR chmod . +.B chmod +changes the file mode bits of each given file according to +.IR mode , +which can be either a symbolic representation of changes to make, or +an octal number representing the bit pattern for the new mode bits. +.PP +The format of a symbolic mode is [\c +\fBugoa\fP.\|.\|.][[\fB-+=\fP][\fIperms\fP.\|.\|.].\|.\|.], +where +.I "perms" +is either zero or more letters from the set +\fBrwxXst\fP, or a single letter from the set \fBugo\fP. +Multiple symbolic +modes can be given, separated by commas. +.PP +A combination of the letters \fBugoa\fP controls which users' access +to the file will be changed: the user who owns it (\fBu\fP), other +users in the file's group (\fBg\fP), other users not in the file's +group (\fBo\fP), or all users (\fBa\fP). If none of these are given, +the effect is as if (\fBa\fP) were +given, but bits that are set in the umask are not affected. +.PP +The operator \fB+\fP causes the selected file mode bits to be added to +the existing file mode bits of each file; \fB-\fP causes them to be +removed; and \fB=\fP causes them to be added and causes unmentioned +bits to be removed except that a directory's unmentioned set user and +group ID bits are not affected. +.PP +The letters \fBrwxXst\fP select file mode bits for the affected users: +read (\fBr\fP), write (\fBw\fP), execute (or search for directories) +(\fBx\fP), execute/search only if the file is a directory or already +has execute permission for some user (\fBX\fP), set user or group ID +on execution (\fBs\fP), restricted deletion flag or sticky bit +(\fBt\fP). Instead of one or more of these letters, you can specify +exactly one of the letters \fBugo\fP: the permissions granted to the +user who owns the file (\fBu\fP), the permissions granted to other +users who are members of the file's group (\fBg\fP), +and the permissions granted to users that are in neither of the two preceding +categories (\fBo\fP). +.PP +A numeric mode is from one to four octal digits (0\-7), derived by +adding up the bits with values 4, 2, and 1. Omitted digits are +assumed to be leading zeros. +The first digit selects the set user ID (4) and set group ID (2) and +restricted deletion or sticky (1) attributes. The second digit +selects permissions for the user who owns the file: read (4), write (2), +and execute (1); the third selects permissions for other users in the +file's group, with the same values; and the fourth for other users not +in the file's group, with the same values. +.PP +.B chmod +never changes the permissions of symbolic links; the +.B chmod +system call cannot change their permissions. This is not a problem +since the permissions of symbolic links are never used. +However, for each symbolic link listed on the command line, +.B chmod +changes the permissions of the pointed-to file. +In contrast, +.B chmod +ignores symbolic links encountered during recursive directory +traversals. +.SH "SETUID AND SETGID BITS" +.B chmod +clears the set-group-ID bit of a +regular file if the file's group ID does not match the user's +effective group ID or one of the user's supplementary group IDs, +unless the user has appropriate privileges. Additional restrictions +may cause the set-user-ID and set-group-ID bits of +.I MODE +or +.I RFILE +to be ignored. This behavior depends on the policy and +functionality of the underlying +.B chmod +system call. When in +doubt, check the underlying system behavior. +.PP +For directories +.B chmod +preserves set-user-ID and set-group-ID bits unless you +explicitly specify otherwise. You can set or clear the bits with +symbolic modes like +.B u+s +and +.BR g\-s . +To clear these bits for directories with a numeric mode requires +an additional leading zero like +.BR 00755 , +leading minus like +.BR \-6000 , +or leading equals like +.BR =755 . +.SH "RESTRICTED DELETION FLAG OR STICKY BIT" +The restricted deletion flag or sticky bit is a single bit, whose +interpretation depends on the file type. For directories, it prevents +unprivileged users from removing or renaming a file in the directory +unless they own the file or the directory; this is called the +.I "restricted deletion flag" +for the directory, and is commonly found on world-writable directories +like \fB/tmp\fP. For regular files on some older systems, the bit +saves the program's text image on the swap device so it will load more +quickly when run; this is called the +.IR "sticky bit" . +.SH OPTIONS +.PP +Change the mode of each FILE to MODE. +With \fB\-\-reference\fR, change the mode of each FILE to that of RFILE. +.TP +\fB\-c\fR, \fB\-\-changes\fR +like verbose but report only when a change is made +.TP +\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR +suppress most error messages +.TP +\fB\-v\fR, \fB\-\-verbose\fR +output a diagnostic for every file processed +.TP +\fB\-\-no\-preserve\-root\fR +do not treat '/' specially (the default) +.TP +\fB\-\-preserve\-root\fR +fail to operate recursively on '/' +.TP +\fB\-\-reference\fR=\fI\,RFILE\/\fR +use RFILE's mode instead of specifying MODE values. +RFILE is always dereferenced if a symbolic link. +.TP +\fB\-R\fR, \fB\-\-recursive\fR +change files and directories recursively +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Each MODE is of the form '[ugoa]*([\-+=]([rwxXst]*|[ugo]))+|[\-+=][0\-7]+'. +.SH AUTHOR +Written by David MacKenzie and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBchmod\fP(2) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) chmod invocation\(aq diff --git a/upstream/fedora-40/man1/chown.1 b/upstream/fedora-40/man1/chown.1 new file mode 100644 index 00000000..aa12977a --- /dev/null +++ b/upstream/fedora-40/man1/chown.1 @@ -0,0 +1,125 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CHOWN "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +chown \- change file owner and group +.SH SYNOPSIS +.B chown +[\fI\,OPTION\/\fR]... [\fI\,OWNER\/\fR][\fI\,:\/\fR[\fI\,GROUP\/\fR]] \fI\,FILE\/\fR... +.br +.B chown +[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR... +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR chown . +.B chown +changes the user and/or group ownership of each given file. If +only an owner (a user name or numeric user ID) is given, that user is made the +owner of each given file, and the files' group is not changed. If the +owner is followed by a colon and a group name (or numeric group ID), +with no spaces between them, the group ownership of the files is +changed as well. If a colon but no group name follows the user name, +that user is made the owner of the files and the group of the files is +changed to that user's login group. If the colon and group are given, +but the owner is omitted, only the group of the files is changed; +in this case, +.B chown +performs the same function as +.BR chgrp . +If only a colon is given, or if the entire operand is empty, neither the +owner nor the group is changed. +.SH OPTIONS +.PP +Change the owner and/or group of each FILE to OWNER and/or GROUP. +With \fB\-\-reference\fR, change the owner and group of each FILE to those of RFILE. +.TP +\fB\-c\fR, \fB\-\-changes\fR +like verbose but report only when a change is made +.TP +\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR +suppress most error messages +.TP +\fB\-v\fR, \fB\-\-verbose\fR +output a diagnostic for every file processed +.TP +\fB\-\-dereference\fR +affect the referent of each symbolic link (this is +the default), rather than the symbolic link itself +.TP +\fB\-h\fR, \fB\-\-no\-dereference\fR +affect symbolic links instead of any referenced file +(useful only on systems that can change the +ownership of a symlink) +.TP +\fB\-\-from\fR=\fI\,CURRENT_OWNER\/\fR:CURRENT_GROUP +change the owner and/or group of each file only if +its current owner and/or group match those specified +here. Either may be omitted, in which case a match +is not required for the omitted attribute +.TP +\fB\-\-no\-preserve\-root\fR +do not treat '/' specially (the default) +.TP +\fB\-\-preserve\-root\fR +fail to operate recursively on '/' +.TP +\fB\-\-reference\fR=\fI\,RFILE\/\fR +use RFILE's owner and group rather than specifying +OWNER:GROUP values. RFILE is always dereferenced. +.TP +\fB\-R\fR, \fB\-\-recursive\fR +operate on files and directories recursively +.PP +The following options modify how a hierarchy is traversed when the \fB\-R\fR +option is also specified. If more than one is specified, only the final +one takes effect. +.TP +\fB\-H\fR +if a command line argument is a symbolic link +to a directory, traverse it +.TP +\fB\-L\fR +traverse every symbolic link to a directory +encountered +.TP +\fB\-P\fR +do not traverse any symbolic links (default) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Owner is unchanged if missing. Group is unchanged if missing, but changed +to login group if implied by a ':' following a symbolic OWNER. +OWNER and GROUP may be numeric as well as symbolic. +.SH EXAMPLES +.TP +chown root /u +Change the owner of /u to "root". +.TP +chown root:staff /u +Likewise, but also change its group to "staff". +.TP +chown \-hR root /u +Change the owner of /u and subfiles to "root". +.SH AUTHOR +Written by David MacKenzie and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBchown\fP(2) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) chown invocation\(aq diff --git a/upstream/fedora-40/man1/chroot.1 b/upstream/fedora-40/man1/chroot.1 new file mode 100644 index 00000000..d8484db4 --- /dev/null +++ b/upstream/fedora-40/man1/chroot.1 @@ -0,0 +1,63 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CHROOT "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +chroot \- run command or interactive shell with special root directory +.SH SYNOPSIS +.B chroot +[\fI\,OPTION\/\fR] \fI\,NEWROOT \/\fR[\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...] +.br +.B chroot +\fI\,OPTION\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Run COMMAND with root directory set to NEWROOT. +.TP +\fB\-\-groups\fR=\fI\,G_LIST\/\fR +specify supplementary groups as g1,g2,..,gN +.TP +\fB\-\-userspec\fR=\fI\,USER\/\fR:GROUP +specify user and group (ID or name) to use +.TP +\fB\-\-skip\-chdir\fR +do not change working directory to '/' +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +If no command is given, run '"$SHELL" \fB\-i\fR' (default: '/bin/sh \fB\-i\fR'). +.SS "Exit status:" +.TP +125 +if the chroot command itself fails +.TP +126 +if COMMAND is found but cannot be invoked +.TP +127 +if COMMAND cannot be found +.TP +\- +the exit status of COMMAND otherwise +.SH AUTHOR +Written by Roland McGrath. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBchroot\fP(2) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) chroot invocation\(aq diff --git a/upstream/fedora-40/man1/chvt.1 b/upstream/fedora-40/man1/chvt.1 new file mode 100644 index 00000000..d015b05c --- /dev/null +++ b/upstream/fedora-40/man1/chvt.1 @@ -0,0 +1,31 @@ +.\" @(#)chvt.1 1.0 970126 aeb +.TH CHVT 1 "26 January 1997" "kbd" +.SH NAME +chvt \- change foreground virtual terminal +.SH SYNOPSIS +.B chvt +[\fI\,option\/\fR...] +.I N +.SH DESCRIPTION +The command +.B chvt +.I N +makes +.I /dev/ttyN +the foreground terminal. +(The corresponding screen is created if it did not exist yet. +To get rid of unused VTs, +use +.BR deallocvt (1).) +The key combination +.RI (Ctrl-)LeftAlt-F N +(with +.I N +in the range 1-12) usually has a similar effect. +.SH OPTIONS +.TP +.I "\-V, \-\-version" +print program version and exit. +.TP +.I "\-h, \-\-help" +show this text and exit. diff --git a/upstream/fedora-40/man1/ci.1 b/upstream/fedora-40/man1/ci.1 new file mode 100644 index 00000000..db759253 --- /dev/null +++ b/upstream/fedora-40/man1/ci.1 @@ -0,0 +1,944 @@ +.ds Rv 5.10.1 +.ds Dt 2024-01-26 +.ds i \&\s-1ISO\s0 +.ds r \&\s-1RCS\s0 +.ds u \&\s-1UTC\s0 +.ds o \*r file +.if n .ds - \%-- +.if t .ds - \(em +.TH CI 1 "\*(Dt" "GNU RCS \*(Rv" +.SH NAME +ci \- check in RCS revisions +.SH SYNOPSIS +.B ci +.RI [ options ] " file " .\|.\|. +.SH DESCRIPTION +.B ci +stores new revisions into \*os. +Each file name matching an \*r suffix +is taken to be an \*o. +All others +are assumed to be working files containing new revisions. +.B ci +deposits the contents of each working file +into the corresponding \*o. +If only a working file is given, +.B ci +tries to find the corresponding \*o in an \*r subdirectory +and then in the working file's directory. +For more details, see +.SM "FILE NAMING" +below. +.PP +For +.B ci +to work, the caller's login must be on the access list, +except if the access list is empty or the caller is the superuser or the +owner of the file. +To append a new revision to an existing branch, the tip revision on +that branch must be locked by the caller. Otherwise, only a +new branch can be created. This restriction is not enforced +for the owner of the file if non-strict locking is used +(see +.BR rcs (1)). +A lock held by someone else can be broken with the +.B rcs +command. +.PP +Unless the +.B \-f +option is given, +.B ci +checks whether the revision to be deposited differs from the preceding one. +If not, instead of creating a new revision +.B ci +reverts to the preceding one. +To revert, ordinary +.B ci +removes the working file and any lock; +.B "ci\ \-l" +keeps and +.B "ci\ \-u" +removes any lock, and then they both generate a new working file much as if +.B "co\ \-l" +or +.B "co\ \-u" +had been applied to the preceding revision. +When reverting, any +.B \-n +and +.B \-s +options apply to the preceding revision. +.PP +For each revision deposited, +.B ci +prompts for a log message. +The log message should summarize the change and must be terminated by +end-of-file or by a line containing +.BR \&. "\ by" +itself. +If several files are checked in +.B ci +asks whether to reuse the +previous log message. +If the standard input is not a terminal, +.B ci +suppresses the prompt +and uses the same log message for all files. +See also +.BR \-m . +.PP +If the \*o does not exist, +.B ci +creates it and +deposits the contents of the working file as the initial revision +(default number: +.BR 1.1 ). +The access list is initialized to empty. +Instead of the log message, +.B ci +requests descriptive text (see +.B \-t +below). +.PP +The number +.I rev +of the deposited revision can be given by any of the options +.BR \-f , +.BR \-i , +.BR \-I , +.BR \-j , +.BR \-k , +.BR \-l , +.BR \-M , +.BR \-q , +.BR \-r , +or +.BR \-u . +.I rev +can be symbolic, numeric, or mixed. +Symbolic names in +.I rev +must already be defined; +see the +.B \-n +and +.B \-N +options for assigning names during checkin. +If +.I rev +is +.BR $ , +.B ci +determines the revision number from keyword values in the working file. +.PP +If +.I rev +begins with a period, +then the default branch (normally the trunk) is prepended to it. +If +.I rev +is a branch number followed by a period, +then the latest revision on that branch is used. +.PP +If +.I rev +is a revision number, it must be higher than the latest +one on the branch to which +.I rev +belongs, or must start a new branch. +.PP +If +.I rev +is a branch rather than a revision number, +the new revision is appended to that branch. The level number is obtained +by incrementing the tip revision number of that branch. +If +.I rev +indicates a non-existing branch, +that branch is created with the initial revision numbered +.IB rev .1\f1.\fP +.br +.ne 8 +.PP +If +.I rev +is omitted, +.B ci +tries to derive the new revision number from +the caller's last lock. If the caller has locked the tip revision of a branch, +the new revision is appended to that branch. +The new revision number is obtained +by incrementing the tip revision number. +If the caller locked a non-tip revision, a new branch is started at +that revision by incrementing the highest branch number at that revision. +The default initial branch and level numbers are +.BR 1 . +.PP +If +.I rev +is omitted and the caller has no lock, but owns +the file and locking +is not set to +.IR strict , +then the revision is appended to the +default branch (normally the trunk; see the +.B \-b +option of +.BR rcs (1)). +.PP +Exception: On the trunk, revisions can be appended to the end, but +not inserted. +.SH OPTIONS +.TP +.BI \-r rev +Check in revision +.IR rev . +.TP +.BR \-r +The bare +.B \-r +option (without any revision) has an unusual meaning in +.BR ci . +With other \*r commands, a bare +.B \-r +option specifies the most recent revision on the default branch, +but with +.BR ci , +a bare +.B \-r +option reestablishes the default behavior of releasing a lock and +removing the working file, and is used to override any default +.B \-l +or +.B \-u +options established by shell aliases or scripts. +.TP +.BR \-l [\f2rev\fP] +works like +.BR \-r , +except it performs an additional +.B "co\ \-l" +for the +deposited revision. Thus, the deposited revision is immediately +checked out again and locked. +This is useful for saving a revision although one wants to continue +editing it after the checkin. +.TP +.BR \-u [\f2rev\fP] +works like +.BR \-l , +except that the deposited revision is not locked. +This lets one read the working file +immediately after checkin. +.RS +.PP +The +.BR \-l , +bare +.BR \-r , +and +.B \-u +options are mutually exclusive and silently override each other. +For example, +.B "ci\ \-u\ \-r" +is equivalent to +.B "ci\ \-r" +because bare +.B \-r +overrides +.BR \-u . +.RE +.TP +.BR \-f [\f2rev\fP] +forces a deposit; the new revision is deposited even it is not different +from the preceding one. +.TP +.BR \-k [\f2rev\fP] +searches the working file for keyword values to determine its revision number, +creation date, state, and author (see +.BR co (1)), +and assigns these +values to the deposited revision, rather than computing them locally. +It also generates a default login message noting the login of the caller +and the actual checkin date. +This option is useful for software distribution. A revision that is sent to +several sites should be checked in with the +.B \-k +option at these sites to +preserve the original number, date, author, and state. +The extracted keyword values and the default log message can be overridden +with the options +.BR \-d , +.BR \-m , +.BR \-s , +.BR \-w , +and any option that carries a revision number. +.TP +.BR \-q [\f2rev\fP] +quiet mode; diagnostic output is not printed. +A revision that is not different from the preceding one is not deposited, +unless +.B \-f +is given. +.TP +.BR \-i [\f2rev\fP] +initial checkin; report an error if the \*o already exists. +This avoids race conditions in certain applications. +.TP +.BR \-j [\f2rev\fP] +just checkin and do not initialize; +report an error if the \*o does not already exist. +.TP +.BR \-I [\f2rev\fP] +interactive mode; +the user is prompted and questioned +even if the standard input is not a terminal. +.TP +.BR \-d "[\f2date\fP]" +uses +.I date +for the checkin date and time. +The +.I date +is specified in free format as explained in +.BR co (1). +This is useful for lying about the checkin date, and for +.B \-k +if no date is available. +If +.I date +is empty, the working file's time of last modification is used. +.TP +.BR \-M [\f2rev\fP] +Set the modification time on any new working file +to be the date of the retrieved revision. +For example, +.BI "ci\ \-d\ \-M\ \-u" "\ f" +does not alter +.IR f 's +modification time, even if +.IR f 's +contents change due to keyword substitution. +Use this option with care; it can confuse +.BR make (1). +.TP +.BR \-m [\fP\f2msg\fP] +uses the string +.I msg +as the log message for all revisions checked in. +If +.I msg +is omitted, it defaults to "*** empty log message ***". +By convention, log messages that start with +.B # +are comments and are ignored by programs like GNU Emacs's +.B vc +package. +Also, log messages that start with +.BI { clumpname } +(followed by white space) are meant to be clumped together if possible, +even if they are associated with different files; the +.BI { clumpname } +label is used only for clumping, +and is not considered to be part of the log message itself. +.TP +.BI \-n "name" +assigns the symbolic name +.I name +to the number of the checked-in revision. +.B ci +prints an error message if +.I name +is already assigned to another +number. +.TP +.BI \-N "name" +same as +.BR \-n , +except that it overrides a previous assignment of +.IR name . +.TP +.BI \-s "state" +sets the state of the checked-in revision to the identifier +.IR state . +The default state is +.BR Exp . +.TP +.BI \-t file +writes descriptive text from the contents of the named +.I file +into the \*o, +deleting the existing text. +The +.I file +cannot begin with +.BR \- . +.TP +.BI \-t\- string +Write descriptive text from the +.I string +into the \*o, deleting the existing text. +.RS +.PP +The +.B \-t +option, in both its forms, has effect only during an initial checkin; +it is silently ignored otherwise. +.PP +During the initial checkin, if +.B \-t +is not given, +.B ci +obtains the text from standard input, +terminated by end-of-file or by a line containing +.BR \&. "\ by" +itself. +The user is prompted for the text if interaction is possible; see +.BR \-I . +.PP +For backward compatibility with older versions of \*r, a bare +.B \-t +option is ignored. +.RE +.TP +.B \-T +Set the \*o's modification time to the new revision's time +if the former precedes the latter and there is a new revision; +preserve the \*o's modification time otherwise. +If you have locked a revision, +.B ci +usually updates the \*o's modification time to the current time, +because the lock is stored in the \*o +and removing the lock requires changing the \*o. +This can create an \*o newer than the working file in one of two ways: +first, +.B "ci\ \-M" +can create a working file with a date before the current time; +second, when reverting to the previous revision +the \*o can change while the working file remains unchanged. +These two cases can cause excessive recompilation caused by a +.BR make (1) +dependency of the working file on the \*o. +The +.B \-T +option inhibits this recompilation by lying about the \*o's date. +Use this option with care; it can suppress recompilation even when +a checkin of one working file should affect +another working file associated with the same \*o. +For example, suppose the \*o's time is 01:00, +the (changed) working file's time is 02:00, +some other copy of the working file has a time of 03:00, +and the current time is 04:00. +Then +.B "ci\ \-d\ \-T" +sets the \*o's time to 02:00 instead of the usual 04:00; +this causes +.BR make (1) +to think (incorrectly) that the other copy is newer than the \*o. +.TP +.BI \-w "login" +uses +.I login +for the author field of the deposited revision. +Useful for lying about the author, and for +.B \-k +if no author is available. +.TP +.BI \-V +Print \*r's version number. +.TP +.BI \-V n +Emulate \*r version +.IR n . +See +.BR co (1) +for details. +.TP +.BI \-x "suffixes" +specifies the suffixes for \*os. +A nonempty suffix matches any file name ending in the suffix. +An empty suffix matches any file name of the form +.BI RCS/ frag +or +.IB frag1 /RCS/ frag2. +The +.B \-x +option can specify a list of suffixes +separated by +.BR / . +For example, +.B \-x,v/ +specifies two suffixes: +.B ,v +and the empty suffix. +If two or more suffixes are specified, +they are tried in order when looking for an \*o; +the first one that works is used for that file. +If no \*o is found but an \*o can be created, +the suffixes are tried in order +to determine the new \*o's name. +The default for +.IR suffixes +is installation-dependent; normally it is +.B ,v/ +for hosts like Unix that permit commas in file names, +and is empty (i.e. just the empty suffix) for other hosts. +.TP +.BI \-z zone +specifies the date output format in keyword substitution, +and specifies the default time zone for +.I date +in the +.BI \-d date +option. +The +.I zone +should be empty, a numeric \*u offset, or the special string +.B LT +for local time. +The default is an empty +.IR zone , +which uses the traditional \*r format of \*u without any time zone indication +and with slashes separating the parts of the date; +otherwise, times are output in \*i 8601 format with time zone indication. +For example, if local time is January 11, 1990, 8pm Pacific Standard Time, +eight hours west of \*u, +then the time is output as follows: +.RS +.LP +.RS +.nf +.ta \w'\f3\-z+05:30\fP 'u +\w'\f31990-01-11 09:30:00+05:30\fP 'u +.ne 4 +\f2option\fP \f2time output\fP +\f3\-z\fP \f31990/01/12 04:00:00\fP \f2(default)\fP +\f3\-zLT\fP \f31990-01-11 20:00:00\-08\fP +\f3\-z+05:30\fP \f31990-01-12 09:30:00+05:30\fP +.ta 4n +4n +4n +4n +.fi +.RE +.LP +The +.B \-z +option does not affect dates stored in \*os, +which are always \*u. +.SH "FILE NAMING" +Pairs of \*os and working files can be specified in three ways +(see also the +example section). +.PP +1) Both the \*o and the working file are given. +The \*o name is of the form +.IB frag1 / workfileX +and the working file name is of the form +.IB frag2 / workfile +where +.IB frag1 / +and +.IB frag2 / +are (possibly different or empty) file names, +.I workfile +is a file name, and +.I X +is an \*r suffix. +If +.I X +is empty, +.IB frag1 / +must start with +.B RCS/ +or must contain +.BR /RCS/ . +.PP +2) Only the \*o is given. +Then the working file is created in the current +directory and its name is derived from the \*o name +by removing +.IB frag1 / +and the suffix +.IR X . +.PP +3) Only the working file is given. +Then +.B ci +considers each \*r suffix +.I X +in turn, looking for an \*o of the form +.IB frag2 /RCS/ workfileX +or (if the former is not found and +.I X +is nonempty) +.IB frag2 / workfileX. +.PP +If the \*o is specified without a file name in 1) and 2), +.B ci +looks for the \*o first in the directory +.B ./RCS +and then in the current +directory. +.PP +.B ci +reports an error if an attempt to open an \*o fails for an unusual reason, +even if the \*o's name is just one of several possibilities. +For example, to suppress use of \*r commands in a directory +.IR d , +create a regular file named +.IB d /RCS +so that casual attempts to use \*r commands in +.I d +fail because +.IB d /RCS +is not a directory. +.SH EXAMPLES +Suppose +.B ,v +is an \*r suffix and the current directory contains a subdirectory +.B RCS +with an \*o +.BR io.c,v . +Then each of the following commands check in a copy of +.B io.c +into +.B RCS/io.c,v +as the latest revision, removing +.BR io.c . +.LP +.RS +.nf +.ft 3 +ci io.c; ci RCS/io.c,v; ci io.c,v; +ci io.c RCS/io.c,v; ci io.c io.c,v; +ci RCS/io.c,v io.c; ci io.c,v io.c; +.ft +.fi +.RE +.PP +Suppose instead that the empty suffix +is an \*r suffix and the current directory contains a subdirectory +.B RCS +with an \*o +.BR io.c . +The each of the following commands checks in a new revision. +.LP +.RS +.nf +.ft 3 +ci io.c; ci RCS/io.c; +ci io.c RCS/io.c; +ci RCS/io.c io.c; +.ft +.fi +.RE +.SH "FILE MODES" +An \*o created by +.B ci +inherits the read and execute permissions +from the working file. If the \*o exists already, +.B ci +preserves its read and execute permissions. +.B ci +always turns off all write permissions of \*os. +.SH FILES +Temporary files are created in the directory containing +the working file, and also in the temporary directory (see +.B \s-1TMPDIR\s0 +under +.BR \s-1ENVIRONMENT\s0 ). +A semaphore file or files are created in the directory containing the \*o. +With a nonempty suffix, the semaphore names begin with +the first character of the suffix; therefore, do not specify an suffix +whose first character could be that of a working file name. +With an empty suffix, the semaphore names end with +.B _ +so working file names should not end in +.BR _ . +.PP +.B ci +never changes an \*o or working file. +Normally, +.B ci +unlinks the file and creates a new one; +but instead of breaking a chain of one or more symbolic links to an \*o, +it unlinks the destination file instead. +Therefore, +.B ci +breaks any hard or symbolic links to any working file it changes; +and hard links to \*os are ineffective, +but symbolic links to \*os are preserved. +.PP +The effective user must be able to +search and write the directory containing the \*o. +Normally, the real user must be able to +read the \*r and working files +and to search and write the directory containing the working file; +however, some older hosts +cannot easily switch between real and effective users, +so on these hosts the effective user is used for all accesses. +The effective user is the same as the real user +unless your copies of +.B ci +and +.B co +have setuid privileges. +As described in the next section, +these privileges yield extra security if +the effective user owns all \*os and directories, +and if only the effective user can write \*r directories. +.PP +Users can control access to \*os by setting the permissions +of the directory containing the files; only users with write access +to the directory can use \*r commands to change its \*os. +For example, in hosts that allow a user to belong to several groups, +one can make a group's \*r directories writable to that group only. +This approach suffices for informal projects, +but it means that any group member can arbitrarily change the group's \*os, +and can even remove them entirely. +Hence more formal projects sometimes distinguish between an \*r administrator, +who can change the \*os at will, and other project members, +who can check in new revisions but cannot otherwise change the \*os. +.SH "SETUID USE" +To prevent anybody but their \*r administrator from deleting revisions, +a set of users can employ setuid privileges as follows. +.nr n \w'\(bu'+2n-1/1n +.ds n \nn +.if \n(.g .if r an-tag-sep .ds n \w'\(bu'u+\n[an-tag-sep]u +.IP \(bu \*n +Check that the host supports \*r setuid use. +Consult a trustworthy expert if there are any doubts. +It is best if the +.B seteuid +system call works as described in Posix 1003.1a Draft 5, +because \*r can switch back and forth easily +between real and effective users, even if the real user is +.BR root . +If not, the second best is if the +.B setuid +system call supports saved setuid +(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990); +this fails only if the real or effective user is +.BR root . +If \*r detects any failure in setuid, it quits immediately. +.IP \(bu \nn +Choose a user +.I A +to serve as \*r administrator for the set of users. +Only +.I A +can invoke the +.B rcs +command on the users' \*os. +.I A +should not be +.B root +or any other user with special powers. +Mutually suspicious sets of users should use different administrators. +.IP \(bu \nn +Choose a file name +.I B +to be a directory of files to be executed by the users. +.IP \(bu \nn +Have +.I A +set up +.I B +to contain copies of +.B ci +and +.B co +that are setuid to +.I A +by copying the commands from their standard installation directory +.I D +as follows: +.LP +.RS +.nf +.ne 3 +\f3mkdir\fP \f2B\fP +\f3cp\fP \f2D\fP\^\f3/c[io]\fP \f2B\fP +\f3chmod go\-w,u+s\fP \f2B\fP\f3/c[io]\fP +.fi +.RE +.IP \(bu \nn +Have each user prepend +.I B +to their command search path as follows: +.LP +.RS +.nf +.ne 2 +\f3PATH=\fP\f2B\fP\f3:$PATH; export PATH\fP # ordinary shell +\f3set path=(\fP\f2B\fP \f3$path)\fP # C shell +.fi +.RE +.IP \(bu \nn +Have +.I A +create each \*r directory +.I R +with write access only to +.I A +as follows: +.LP +.RS +.nf +.ne 2 +\f3mkdir\fP \f2R\fP +\f3chmod go\-w\fP \f2R\fP +.fi +.RE +.IP \(bu \nn +If you want to let only certain users read the \*os, +put the users into a group +.IR G , +and have +.I A +further protect the \*r directory as follows: +.LP +.RS +.nf +.ne 2 +\f3chgrp\fP \f2G R\fP +\f3chmod g\-w,o\-rwx\fP \f2R\fP +.fi +.RE +.IP \(bu \nn +Have +.I A +copy old \*os (if any) into +.IR R , +to ensure that +.I A +owns them. +.IP \(bu \nn +An \*o's access list limits who can check in and lock revisions. +The default access list is empty, +which grants checkin access to anyone who can read the \*o. +If you want limit checkin access, +have +.I A +invoke +.B "rcs\ \-a" +on the file; see +.BR rcs (1). +In particular, +.BI "rcs\ \-e\ \-a" A +limits access to just +.IR A . +.IP \(bu \nn +Have +.I A +initialize any new \*os with +.B "rcs\ \-i" +before initial checkin, adding the +.B \-a +option if you want to limit checkin access. +.IP \(bu \nn +Give setuid privileges only to +.BR ci , +.BR co , +and +.BR rcsclean ; +do not give them to +.B rcs +or to any other command. +.IP \(bu \nn +Do not use other setuid commands to invoke \*r commands; +setuid is trickier than you think! +.SH ENVIRONMENT +.TP +.B \s-1RCSINIT\s0 +Options prepended to the argument list, separated by spaces. +A backslash escapes spaces within an option. +The +.B \s-1RCSINIT\s0 +options are prepended to the argument lists of most \*r commands. +Useful +.B \s-1RCSINIT\s0 +options include +.BR \-q , +.BR \-V , +.BR \-x , +and +.BR \-z . +.TP +.B \s-1RCS_MEM_LIMIT\s0 +Normally, for speed, commands either memory map or copy into memory +the \*o if its size is less than the +.IR memory-limit , +currently defaulting to ``unlimited''. +Otherwise (or if the initially-tried speedy ways fail), +the commands fall back to using +standard i/o routines. +You can adjust the memory limit by setting +.B \s-1RCS_MEM_LIMIT\s0 +to a numeric value +.IR lim +(measured in kilobytes). +An empty value is silently ignored. +As a side effect, specifying +.B \s-1RCS_MEM_LIMIT\s0 +inhibits fall-back to slower routines. +.TP +.B \s-1TMPDIR\s0 +Name of the temporary directory. +If not set, the environment variables +.B \s-1TMP\s0 +and +.B \s-1TEMP\s0 +are inspected instead and the first value found is taken; +if none of them are set, +a host-dependent default is used, typically +.BR /tmp . +.SH DIAGNOSTICS +For each revision, +.B ci +prints the \*o, the working file, and the number +of both the deposited and the preceding revision. +The exit status is zero if and only if all operations were successful. +.ds EY 1990, 1991, 1992, 1993, 1994, 1995 +.SH IDENTIFICATION +Author: Walter F. Tichy. +.br +Manual Page Revision: \*(Rv; Release Date: \*(Dt. +.br +Copyright \(co 2010-2022 Thien-Thi Nguyen. +.br +Copyright \(co \*(EY Paul Eggert. +.br +Copyright \(co 1982, 1988, 1989 Walter F. Tichy. +.br +.SH "SEE ALSO" +.BR co (1), +.BR emacs (1), +.BR ident (1), +.BR make (1), +.BR rcs (1), +.BR rcsclean (1), +.BR rcsdiff (1), +.BR rcsmerge (1), +.BR rlog (1), +.BR setuid (2), +.BR rcsfile (5). +.PP +.PP +Walter F. Tichy, +\*r\*-A System for Version Control, +.I "Software\*-Practice & Experience" +.BR 15 , +7 (July 1985), 637-654. +.PP +The full documentation for \*r is maintained as a Texinfo manual. +If the +.BR info (1) +and \*r programs are properly installed at your site, the command +.IP +.B info rcs +.PP +should give you access to the complete manual. +Additionally, the \*r homepage: +.IP +.B http://www.gnu.org/software/rcs/ +.PP +has news and links to the latest release, development site, etc. diff --git a/upstream/fedora-40/man1/cifsiostat.1 b/upstream/fedora-40/man1/cifsiostat.1 new file mode 100644 index 00000000..ef507139 --- /dev/null +++ b/upstream/fedora-40/man1/cifsiostat.1 @@ -0,0 +1,154 @@ +.\" cifsiostat manual page - (C) 2020 Sebastien Godard (sysstat orange.fr) +.TH CIFSIOSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- +.SH NAME +cifsiostat \- Report CIFS statistics. + +.SH SYNOPSIS +.ie 'yes'no' \{ +.B cifsiostat [ \-h ] [ \-k | \-m ] [ \-t ] [ \-V ] [ \-\-debuginfo ] [ \-\-dec={ 0 | 1 | 2 } ] [ \-\-human ] [ \-\-pretty ] [ +.IB "interval " "[ " "count " "] ]" +.\} +.el \{ +.B cifsiostat [ \-h ] [ \-k | \-m ] [ \-t ] [ \-V ] [ \-\-dec={ 0 | 1 | 2 } ] [ \-\-human ] [ \-\-pretty ] [ +.IB "interval " "[ " "count " "] ]" +.\} + +.SH DESCRIPTION +The +.B cifsiostat +command displays statistics about read and write operations +on CIFS filesystems. +.PP +.RI "The " "interval" +parameter specifies the amount of time in seconds between +each report. The first report contains statistics for the time since +system startup (boot). Each subsequent report contains statistics +collected during the interval since the previous report. +A report consists of a CIFS header row followed by +a line of statistics for each CIFS filesystem that is mounted. +.RI "The " "count " "parameter can be specified in conjunction with the " "interval " +.RI "parameter. If the " "count " "parameter is specified, the value of " "count " +.RI "determines the number of reports generated at " "interval " "seconds apart. If the " "interval " +.RI "parameter is specified without the " "count " "parameter, the " +.BR "cifsiostat " "command generates reports continuously." + +.SH REPORT +The CIFS report provides statistics for each mounted CIFS filesystem. +The report shows the following fields: + +.IP Filesystem: +This columns shows the mount point of the CIFS filesystem. +.IP "rB/s (rkB/s, rMB/s)" +Indicate the average number of bytes (kilobytes, megabytes) read per second. +.IP "wB/s (wkB/s, wMB/s)" +Indicate the average number of bytes (kilobytes, megabytes) written per second. +.IP rop/s +Indicate the number of 'read' operations that were issued to the filesystem +per second. +.IP wop/s +Indicate the number of 'write' operations that were issued to the filesystem +per second. +.IP fo/s +Indicate the number of open files per second. +.IP fc/s +Indicate the number of closed files per second. +.IP fd/s +Indicate the number of deleted files per second. + +.SH OPTIONS +.if 'yes'no' \{ +.TP +.B \-\-debuginfo +Print debug output to stderr. +.\} +.TP +.B \-\-dec={ 0 | 1 | 2 } +Specify the number of decimal places to use (0 to 2, default value is 2). +.TP +.B \-h +This option is equivalent to specifying +.BR "\-\-human \-\-pretty" "." +.TP +.B \-\-human +Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.) +The units displayed with this option supersede any other default units (e.g. +kilobytes, sectors...) associated with the metrics. +.TP +.B \-k +Display statistics in kilobytes per second. +.TP +.B \-m +Display statistics in megabytes per second. +.TP +.B \-\-pretty +Make the CIFS report easier to read by a human. +.TP +.B \-t +Print the time for each report displayed. The timestamp format may depend +on the value of the +.BR "S_TIME_FORMAT " "environment variable (see below)." +.TP +.B \-V +Print version number then exit. + +.SH ENVIRONMENT +.RB "The " "cifsiostat " "command takes into account the following environment variables: " +.TP +.B S_COLORS +By default statistics are displayed in color when the output is connected to a terminal. +Use this variable to change the settings. Possible values for this variable are +.BR "never" ", " "always " "or " "auto " "(the latter is equivalent to the default settings)." +.br +Please note that the color (being red, yellow, or some other color) used to display a value +is not indicative of any kind of issue simply because of the color. It only indicates different +ranges of values. +.TP +.B S_COLORS_SGR +Specify the colors and other attributes used to display statistics on the terminal. +Its value is a colon-separated list of capabilities that defaults to +.BR "I=32;22:N=34;1:Z=34;22" "." +Supported capabilities are: +.RS +.TP +.B I= +SGR substring for filesystem names. +.TP +.B N= +SGR substring for non-zero statistics values. +.TP +.B Z= +SGR substring for zero values. +.RE +.TP +.B S_TIME_FORMAT +If this variable exists and its value is +.B ISO +then the current locale will be ignored when printing the date in the report +header. The +.B cifsiostat +command will use the ISO 8601 format (YYYY-MM-DD) instead. +.RB "The timestamp displayed with option " "\-t " "will also be compliant with ISO 8601 format." + +.SH BUG +.IR "/proc " "filesystem must be mounted for" +.BR "cifsiostat " "to work." +.PP +.RB "Although " "cifsiostat" +speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)... +A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes. + +.SH FILE +.IR "/proc/fs/cifs/Stats " "contains CIFS statistics." + +.SH AUTHORS +Written by Ivana Varekova (varekova redhat.com) +.br +Maintained by Sebastien Godard (sysstat orange.fr) + +.SH SEE ALSO +.BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "iostat" "(1)," +.BR "tapestat" "(1), " "nfsiostat" "(1)" + +.I https://github.com/sysstat/sysstat +.br +.I https://sysstat.github.io/ diff --git a/upstream/fedora-40/man1/cistopbm.1 b/upstream/fedora-40/man1/cistopbm.1 new file mode 100644 index 00000000..2bd444b4 --- /dev/null +++ b/upstream/fedora-40/man1/cistopbm.1 @@ -0,0 +1,71 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Cistopbm User Manual" 0 "13 August 2020" "netpbm documentation" + +.SH NAME +cistopbm - convert Compuserve RLE image to PBM + +.UN synopsis +.SH SYNOPSIS + +\fBcistopbm\fP +[\fB-i\fP] +[\fIcisfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBcistopbm\fP reads a Compuserve RLE file as input. +and produces a PBM image as output. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBcistopbm\fP recognizes the following +command line option: + + +.TP +\fB-i\fP +Inverse: Reverse the mapping of foreground/background to black/white. + + + +.UN seealso +.SH SEE ALSO +.BR "pbmtocis" (1)\c +\&, +.BR "pbm" (1)\c +\& +.UR https://web.archive.org/web/20140721001738/staticweb.rasip.fer.hr/research/compress/algorithms_run-length_coding.htm +CompuServe RLE file format +.UE +\& + +.UN history +.SH HISTORY +.PP +\fBcistopbm\fP was new in Netpbm 10.48 (September 2009). + +.UN author +.SH AUTHOR + +Copyright (C) 2009 John Elliot +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/cistopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/cksum.1 b/upstream/fedora-40/man1/cksum.1 new file mode 100644 index 00000000..2cd81cc2 --- /dev/null +++ b/upstream/fedora-40/man1/cksum.1 @@ -0,0 +1,120 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CKSUM "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +cksum \- compute and verify file checksums +.SH SYNOPSIS +.B cksum +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print or verify checksums. +By default use the 32 bit CRC algorithm. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-a\fR, \fB\-\-algorithm\fR=\fI\,TYPE\/\fR +select the digest type to use. See DIGEST below. +.TP +\fB\-\-base64\fR +emit base64\-encoded digests, not hexadecimal +.TP +\fB\-c\fR, \fB\-\-check\fR +read checksums from the FILEs and check them +.TP +\fB\-l\fR, \fB\-\-length\fR=\fI\,BITS\/\fR +digest length in bits; must not exceed the max for +the blake2 algorithm and must be a multiple of 8 +.TP +\fB\-\-raw\fR +emit a raw binary digest, not hexadecimal +.TP +\fB\-\-tag\fR +create a BSD\-style checksum (the default) +.TP +\fB\-\-untagged\fR +create a reversed style checksum, without digest type +.TP +\fB\-z\fR, \fB\-\-zero\fR +end each output line with NUL, not newline, +and disable file name escaping +.SS "The following five options are useful only when verifying checksums:" +.TP +\fB\-\-ignore\-missing\fR +don't fail or report status for missing files +.TP +\fB\-\-quiet\fR +don't print OK for each successfully verified file +.TP +\fB\-\-status\fR +don't output anything, status code shows success +.TP +\fB\-\-strict\fR +exit non\-zero for improperly formatted checksum lines +.TP +\fB\-w\fR, \fB\-\-warn\fR +warn about improperly formatted checksum lines +.TP +\fB\-\-debug\fR +indicate which implementation used +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SS "DIGEST determines the digest algorithm and default output format:" +.TP +sysv +(equivalent to sum \fB\-s\fR) +.TP +bsd +(equivalent to sum \fB\-r\fR) +.TP +crc +(equivalent to cksum) +.TP +md5 +(equivalent to md5sum) +.TP +sha1 +(equivalent to sha1sum) +.TP +sha224 +(equivalent to sha224sum) +.TP +sha256 +(equivalent to sha256sum) +.TP +sha384 +(equivalent to sha384sum) +.TP +sha512 +(equivalent to sha512sum) +.TP +blake2b +(equivalent to b2sum) +.TP +sm3 +(only available through cksum) +.PP +When checking, the input should be a former output of this program, +or equivalent standalone program. +.SH AUTHOR +Written by Padraig Brady and Q. Frank Xia. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) cksum invocation\(aq diff --git a/upstream/fedora-40/man1/clear.1 b/upstream/fedora-40/man1/clear.1 new file mode 100644 index 00000000..c034b0ea --- /dev/null +++ b/upstream/fedora-40/man1/clear.1 @@ -0,0 +1,186 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: clear.1,v 1.46 2023/12/16 20:32:22 tom Exp $ +.TH clear 1 2023-12-16 "ncurses 6.4" "User commands" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ie t .ds ' \(aq +.el .ds ' ' +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. +.SH NAME +\fB\%clear\fP \- +clear the terminal screen +.SH SYNOPSIS +.B clear +.RB [ \-x ] +.RB [ \-T\ \c +.IR terminal-type ] +.PP +.B "clear \-V" +.SH DESCRIPTION +\fB\%clear\fP clears your terminal's screen and its scrollback buffer, +if any. +\fB\%clear\fP retrieves the terminal type from the environment +variable \fITERM\fP, +then consults the \fIterminfo\fP terminal capability database entry for +that type to determine how to perform these actions. +.PP +The capabilities to clear the screen and scrollback buffer are named +\*(``clear\*('' and \*(``E3\*('', respectively. +The latter is a \fIuser-defined capability\fP, +applying an extension mechanism introduced in \fI\%ncurses\fP 5.0 +(1999). +.SH OPTIONS +\fB\%clear\fP recognizes the following options. +.TP 9 \" "-T type" + 2n +.B \-T \fItype\fP +produces instructions suitable for the terminal \fItype\fP. +Normally, +this option is unnecessary, +because the terminal type is inferred from the environment variable +\fITERM\fP. +If this option is specified, +\fB\%clear\fP ignores the environment variables \fILINES\fP and +\fI\%COLUMNS\fP as well. +.TP +.B \-V +reports the version of \fI\%ncurses\fP associated with this program and +exits with a successful status. +.TP +.B \-x +prevents \fB\%clear\fP from attempting to clear the scrollback buffer. +.SH PORTABILITY +Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 +(POSIX.1-2008) nor X/Open Curses Issue 7 documents \fB\%clear\fP. +.PP +The latter documents \fBtput\fP, +which could be used to replace this utility either via a shell script or +by an alias +(such as a symbolic link) +to run \fB\%tput\fP as \fB\%clear\fP. +.SH HISTORY +A \fBclear\fP command using the \fItermcap\fP database and library +appeared in 2BSD (1979). +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c +Eighth Edition Unix (1985) later included it. +.PP +The commercial Unix arm of AT&T adapted a different BSD program +(\fBtset\fP) to make a new command, +\fBtput\fP, +and replaced the \fBclear\fP program with a shell script that called +\*(``\fBtput clear\fP\*(''. +.PP +.RS 4 +.EX +/usr/bin/tput ${1:+\-T$1} clear 2> /dev/null +exit +.EE +.RE +.PP +In 1989, when Keith Bostic revised the BSD \fBtput\fP command +to make it similar to AT&T's \fBtput\fP, +he added a \fBclear\fP shell script as well. +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\ +.\" tput/clear.sh +.PP +.RS 4 +.EX +exec tput clear +.EE +.RE +.PP +The remainder of the script in each case is a copyright notice. +.PP +In 1995, +\fI\%ncurses\fP's \fBclear\fP began by adapting BSD's original +\fBclear\fP command to use \fIterminfo\fP. +The \fBE3\fP extension came later. +.bP +In June 1999, \fIxterm\fP provided an extension to the standard control +sequence for clearing the screen. +Rather than clearing just the visible part of the screen using +.RS 8 +.PP +.EX +printf \*'\e033[2J\*' +.EE +.RE +.IP +one could clear the scrollback buffer as well by using +.RS 8 +.PP +.EX +printf \*'\e033[\fB3\fPJ\*' +.EE +.RE +.IP +instead. +\*(``XTerm Control Sequences\fP\*('' documents this feature as +originating with \fIxterm\fP. +.bP +A few other terminal emulators adopted it, +such as PuTTY in 2006. +.bP +In April 2011, a Red Hat developer submitted a patch to the Linux +kernel, modifying its console driver to do the same thing. +Documentation of this change, +appearing in Linux 3.0, +did not mention \fIxterm\fP, +although that program was cited in the Red Hat bug report (#683733) +motivating the feature. +.bP +Subsequently, +more terminal developers adopted the feature. +The next relevant step was to change the \fI\%ncurses\fP \fBclear\fP +program in 2013 to incorporate this extension. +.bP +In 2013, +the \fBE3\fP capability was not exercised by +\*(``\fB\%tput clear\fP\*(''. +That oversight was addressed in 2016 by reorganizing \fB\%tput\fP to +share its logic with \fB\%clear\fP and \fB\%tset\fP. +.SH SEE ALSO +\fB\%tput\fP(1), +\fB\%xterm\fP(1), +\fB\%terminfo\fP(5) diff --git a/upstream/fedora-40/man1/cmp.1 b/upstream/fedora-40/man1/cmp.1 new file mode 100644 index 00000000..a9ea06a6 --- /dev/null +++ b/upstream/fedora-40/man1/cmp.1 @@ -0,0 +1,76 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.40.4. +.TH CMP "1" "May 2023" "diffutils 3.10" "User Commands" +.SH NAME +cmp \- compare two files byte by byte +.SH SYNOPSIS +.B cmp +[\fIOPTION\fR]... \fIFILE1 \fR[\fIFILE2 \fR[\fISKIP1 \fR[\fISKIP2\fR]]] +.SH DESCRIPTION +Compare two files byte by byte. +.PP +The optional SKIP1 and SKIP2 specify the number of bytes to skip +at the beginning of each file (zero by default). +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-b\fR, \fB\-\-print\-bytes\fR +print differing bytes +.TP +\fB\-i\fR, \fB\-\-ignore\-initial\fR=\fISKIP\fR +skip first SKIP bytes of both inputs +.TP +\fB\-i\fR, \fB\-\-ignore\-initial\fR=\fISKIP1\fR:SKIP2 +skip first SKIP1 bytes of FILE1 and +first SKIP2 bytes of FILE2 +.TP +\fB\-l\fR, \fB\-\-verbose\fR +output byte numbers and differing byte values +.TP +\fB\-n\fR, \fB\-\-bytes\fR=\fILIMIT\fR +compare at most LIMIT bytes +.TP +\fB\-s\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR +suppress all normal output +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +output version information and exit +.PP +SKIP values may be followed by the following multiplicative suffixes: +kB 1000, K 1024, MB 1,000,000, M 1,048,576, +GB 1,000,000,000, G 1,073,741,824, and so on for T, P, E, Z, Y. +.PP +If a FILE is '\-' or missing, read standard input. +Exit status is 0 if inputs are the same, 1 if different, 2 if trouble. +.SH AUTHOR +Written by Torbjorn Granlund and David MacKenzie. +.SH "REPORTING BUGS" +Report bugs to: bug\-diffutils@gnu.org +.br +GNU diffutils home page: +.br +General help using GNU software: +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR diff (1), +.BR diff3 (1), +.BR sdiff (1) +.PP +The full documentation for +.B cmp +is maintained as a Texinfo manual. If the +.B info +and +.B cmp +programs are properly installed at your site, the command +.IP +.B info cmp +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/cmuwmtopbm.1 b/upstream/fedora-40/man1/cmuwmtopbm.1 new file mode 100644 index 00000000..0ccc16f7 --- /dev/null +++ b/upstream/fedora-40/man1/cmuwmtopbm.1 @@ -0,0 +1,54 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Cmuwmtopbm User Manual" 0 "15 April 1989" "netpbm documentation" + +.SH NAME +cmuwmtopbm - convert a CMU window manager bitmap into a PBM image + +.UN synopsis +.SH SYNOPSIS + +\fBcmuwmtopbm\fP +[\fIcmuwmfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBcmuwmtopbm\fP reads a CMU window manager bitmap as input. and +produces a PBM image as output. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBcmuwmtopbm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "pbmtocmuwm" (1)\c +\&, +.BR "pbm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1989 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/cmuwmtopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/co.1 b/upstream/fedora-40/man1/co.1 new file mode 100644 index 00000000..6f80d63b --- /dev/null +++ b/upstream/fedora-40/man1/co.1 @@ -0,0 +1,805 @@ +.ds Rv 5.10.1 +.ds Dt 2024-01-26 +.ds i \&\s-1ISO\s0 +.ds r \&\s-1RCS\s0 +.ds u \&\s-1UTC\s0 +.ds o \*r file +.if n .ds - \%-- +.if t .ds - \(em +.TH CO 1 "\*(Dt" "GNU RCS \*(Rv" +.SH NAME +co \- check out RCS revisions +.SH SYNOPSIS +.B co +.RI [ options ] " file " .\|.\|. +.SH DESCRIPTION +.B co +retrieves a revision from each \*o and stores it into +the corresponding working file. +.PP +Filenames matching an \*r suffix denote \*os; +all others denote working files. +Names are paired as explained in +.BR ci (1). +.PP +Revisions of an \*o can be checked out locked or unlocked. Locking a +revision prevents overlapping updates. A revision checked out for reading or +processing (e.g., compiling) need not be locked. A revision checked out +for editing and later checkin must normally be locked. Checkout with locking +fails if the revision to be checked out is currently locked by another user. +(A lock can be broken with +.BR rcs "(1).)\ \&" +Checkout with locking also requires the caller to be on the access list of +the \*o, unless he is the owner of the +file or the superuser, or the access list is empty. +Checkout without locking is not subject to accesslist restrictions, and is +not affected by the presence of locks. +.PP +A revision is selected by options for revision or branch number, +checkin date/time, author, or state. +When the selection options +are applied in combination, +.B co +retrieves the latest revision +that satisfies all of them. +If none of the selection options +is specified, +.B co +retrieves the latest revision +on the default branch (normally the trunk, see the +.B \-b +option of +.BR rcs (1)). +A revision or branch number can be attached +to any of the options +.BR \-f , +.BR \-I , +.BR \-l , +.BR \-M , +.BR \-p , +.BR \-q , +.BR \-r , +or +.BR \-u . +The options +.B \-d +(date), +.B \-s +(state), and +.B \-w +(author) +retrieve from a single branch, the +.I selected +branch, +which is either specified by one of +.BR \-f , +\&.\|.\|., +.BR \-u , +or the default branch. +.PP +A +.B co +command applied to an \*o +with no revisions creates a zero-length working file. +.B co +always performs keyword substitution (see below). +.SH OPTIONS +.TP +.BR \-r [\f2rev\fP] +retrieves the latest revision whose number is less than or equal to +.IR rev . +If +.I rev +indicates a branch rather than a revision, +the latest revision on that branch is retrieved. +If +.I rev +is omitted, the latest revision on the default branch +(see the +.B \-b +option of +.BR rcs (1)) +is retrieved. +If +.I rev +is +.BR $ , +.B co +determines the revision number from keyword values in the working file. +Otherwise, a revision is composed of one or more numeric or symbolic fields +separated by periods. +If +.I rev +begins with a period, +then the default branch (normally the trunk) is prepended to it. +If +.I rev +is a branch number followed by a period, +then the latest revision on that branch is used. +The numeric equivalent of a symbolic field +is specified with the +.B \-n +option of the commands +.BR ci (1) +and +.BR rcs (1). +.TP +.BR \-l [\f2rev\fP] +same as +.BR \-r , +except that it also locks the retrieved revision for +the caller. +.TP +.BR \-u [\f2rev\fP] +same as +.BR \-r , +except that it unlocks the retrieved revision if it was +locked by the caller. If +.I rev +is omitted, +.B \-u +retrieves the revision locked by the caller, if there is one; otherwise, +it retrieves the latest revision on the default branch. +.TP +.BR \-f [\f2rev\fP] +forces the overwriting of the working file; +useful in connection with +.BR \-q . +See also +.SM "FILE MODES" +below. +.TP +.B \-kkv +Generate keyword strings using the default form, e.g.\& +.B "$\&Revision: \*(Rv $" +for the +.B Revision +keyword. +A locker's name is inserted in the value of the +.BR Header , +.BR Id , +and +.B Locker +keyword strings +only as a file is being locked, +i.e. by +.B "ci\ \-l" +and +.BR "co\ \-l". +This is the default. +.TP +.B \-kkvl +Like +.BR \-kkv , +except that a locker's name is always inserted +if the given revision is currently locked. +.TP +.B \-kk +Generate only keyword names in keyword strings; omit their values. +See +.SM "KEYWORD SUBSTITUTION" +below. +For example, for the +.B Revision +keyword, generate the string +.B $\&Revision$ +instead of +.BR "$\&Revision: \*(Rv $" . +This option is useful to ignore differences due to keyword substitution +when comparing different revisions of a file. +Log messages are inserted after +.B $\&Log$ +keywords even if +.B \-kk +is specified, +since this tends to be more useful when merging changes. +.TP +.B \-ko +Generate the old keyword string, +present in the working file just before it was checked in. +For example, for the +.B Revision +keyword, generate the string +.B "$\&Revision: 1.1 $" +instead of +.B "$\&Revision: \*(Rv $" +if that is how the string appeared when the file was checked in. +This can be useful for file formats +that cannot tolerate any changes to substrings +that happen to take the form of keyword strings. +.TP +.B \-kb +Generate a binary image of the old keyword string. +This acts like +.BR \-ko , +except it performs all working file input and output in binary mode. +This makes little difference on Posix and Unix hosts, +but on DOS-like hosts one should use +.B "rcs\ \-i\ \-kb" +to initialize an \*o intended to be used for binary files. +Also, on all hosts, +.BR rcsmerge (1) +normally refuses to merge files when +.B \-kb +is in effect. +.TP +.B \-kv +Generate only keyword values for keyword strings. +For example, for the +.B Revision +keyword, generate the string +.B \*(Rv +instead of +.BR "$\&Revision: \*(Rv $" . +This can help generate files in programming languages where it is hard to +strip keyword delimiters like +.B "$\&Revision:\ $" +from a string. +However, further keyword substitution cannot be performed once the +keyword names are removed, so this option should be used with care. +Because of this danger of losing keywords, +this option cannot be combined with +.BR \-l , +and the owner write permission of the working file is turned off; +to edit the file later, check it out again without +.BR \-kv . +.TP +.BR \-p [\f2rev\fP] +prints the retrieved revision on the standard output rather than storing it +in the working file. +This option is useful when +.B co +is part of a pipe. +.TP +.BR \-q [\f2rev\fP] +quiet mode; diagnostics are not printed. +.TP +.BR \-I [\f2rev\fP] +interactive mode; +the user is prompted and questioned +even if the standard input is not a terminal. +.TP +.BI \-d date +retrieves the latest revision on the selected branch whose checkin date/time is +less than or equal to +.IR date . +The date and time can be given in free format. +The time zone +.B LT +stands for local time; +other common time zone names are understood. +For example, the following +.IR date s +are equivalent +if local time is January 11, 1990, 8pm Pacific Standard Time, +eight hours west of Coordinated Universal Time (\*u): +.RS +.LP +.RS +.nf +.ta \w'\f3Thu, 11 Jan 1990 20:00:00 \-0800\fP 'u +.ne 10 +\f38:00 pm lt\fP +\f34:00 AM, Jan. 12, 1990\fP default is \*u +\f31990-01-12 04:00:00+00\fP \*i 8601 (\*u) +\f31990-01-11 20:00:00\-08\fP \*i 8601 (local time) +\f31990/01/12 04:00:00\fP traditional \*r format +\f3Thu Jan 11 20:00:00 1990 LT\fP output of \f3ctime\fP(3) + \f3LT\fP +\f3Thu Jan 11 20:00:00 PST 1990\fP output of \f3date\fP(1) +\f3Fri Jan 12 04:00:00 GMT 1990\fP +\f3Thu, 11 Jan 1990 20:00:00 \-0800\fP Internet RFC 822 +\f312-January-1990, 04:00 WET\fP +.ta 4n +4n +4n +4n +.fi +.RE +.LP +Most fields in the date and time can be defaulted. +The default time zone is normally \*u, but this can be overridden by the +.B \-z +option. +The other defaults are determined in the order year, month, day, +hour, minute, and second (most to least significant). At least one of these +fields must be provided. For omitted fields that are of higher significance +than the highest provided field, the time zone's current values are assumed. +For all other omitted fields, +the lowest possible values are assumed. +For example, without +.BR \-z , +the date +.B "20, 10:30" +defaults to +10:30:00 \*u of the 20th of the \*u time zone's current month and year. +The date/time must be quoted if it contains spaces. +.RE +.TP +.BR \-M [\f2rev\fP] +Set the modification time on the new working file +to be the date of the retrieved revision. +Use this option with care; it can confuse +.BR make (1). +.TP +.BI \-s state +retrieves the latest revision on the selected branch whose state is set to +.IR state . +.TP +.BI \-S +Enable +.I self-same +mode. +In this mode, the owner of a lock is unimportant, just that it exists. +Effectively, this means the user cannot check out the same revision twice. +.TP +.B \-T +Preserve the modification time on the \*o +even if the \*o changes because a lock is added or removed. +This option can suppress extensive recompilation caused by a +.BR make (1) +dependency of some other copy of the working file on the \*o. +Use this option with care; it can suppress recompilation even when it is needed, +i.e. when the change of lock +would mean a change to keyword strings in the other working file. +.TP +.BR \-w [\f2login\fP] +retrieves the latest revision on the selected branch which was checked in +by the user with login name +.IR login . +If the argument +.I login +is +omitted, the caller's login is assumed. +.TP +.BI \-j joinlist +generates a new revision which is the join of the revisions on +.IR joinlist . +This option is largely obsoleted by +.BR rcsmerge (1) +but is retained for backwards compatibility. +.RS +.PP +The +.I joinlist +is a comma-separated list of pairs of the form +.IB rev2 : rev3, +where +.I rev2 +and +.I rev3 +are (symbolic or numeric) +revision numbers. +For the initial such pair, +.I rev1 +denotes the revision selected +by the above options +.BR \-f , +\&.\|.\|., +.BR \-w . +For all other pairs, +.I rev1 +denotes the revision generated by the previous pair. +(Thus, the output +of one join becomes the input to the next.) +.PP +For each pair, +.B co +joins revisions +.I rev1 +and +.I rev3 +with respect to +.IR rev2 . +This means that all changes that transform +.I rev2 +into +.I rev1 +are applied to a copy of +.IR rev3 . +This is particularly useful if +.I rev1 +and +.I rev3 +are the ends of two branches that have +.I rev2 +as a common ancestor. If +.IR rev1 < rev2 < rev3 +on the same branch, +joining generates a new revision which is like +.I rev3, +but with all changes that lead from +.I rev1 +to +.I rev2 +undone. +If changes from +.I rev2 +to +.I rev1 +overlap with changes from +.I rev2 +to +.I rev3, +.B co +reports overlaps as described in +.BR merge (1). +.PP +For the initial pair, +.I rev2 +can be omitted. The default is the common +ancestor. +If any of the arguments indicate branches, the latest revisions +on those branches are assumed. +The options +.B \-l +and +.B \-u +lock or unlock +.IR rev1 . +.RE +.TP +.BI \-V +Print \*r's version number. +.TP +.BI \-V n +Emulate \*r version +.I n, +where +.I n +can be +.BR 3 , +.BR 4 , +or +.BR 5 . +This can be useful when interchanging \*os with others who are +running older versions of \*r. +To see which version of \*r your correspondents are running, have them invoke +.BR "rcs \-V" ; +this works with newer versions of \*r. +If it doesn't work, have them invoke +.B rlog +on an \*o; +if none of the first few lines of output contain the string +.B branch: +it is version 3; +if the dates' years have just two digits, it is version 4; +otherwise, it is version 5. +An \*o generated while emulating version 3 loses its default branch. +An \*r revision generated while emulating version 4 or earlier has +a time stamp that is off by up to 13 hours. +A revision extracted while emulating version 4 or earlier contains +abbreviated dates of the form +.IB yy / mm / dd +and can also contain different white space and line prefixes +in the substitution for +.BR $\&Log$ . +.TP +.BI \-x "suffixes" +Use +.I suffixes +to characterize \*os. +See +.BR ci (1) +for details. +.TP +.BI \-z zone +specifies the date output format in keyword substitution, +and specifies the default time zone for +.I date +in the +.BI \-d date +option. +The +.I zone +should be empty, a numeric \*u offset, or the special string +.B LT +for local time. +The default is an empty +.IR zone , +which uses the traditional \*r format of \*u without any time zone indication +and with slashes separating the parts of the date; +otherwise, times are output in \*i 8601 format with time zone indication. +For example, if local time is January 11, 1990, 8pm Pacific Standard Time, +eight hours west of \*u, +then the time is output as follows: +.RS +.LP +.RS +.nf +.ta \w'\f3\-z+05:30\fP 'u +\w'\f31990-01-11 09:30:00+05:30\fP 'u +.ne 4 +\f2option\fP \f2time output\fP +\f3\-z\fP \f31990/01/12 04:00:00\fP \f2(default)\fP +\f3\-zLT\fP \f31990-01-11 20:00:00\-08\fP +\f3\-z+05:30\fP \f31990-01-12 09:30:00+05:30\fP +.ta 4n +4n +4n +4n +.fi +.RE +.LP +The +.B \-z +option does not affect dates stored in \*os, +which are always \*u. +.RE +.SH "KEYWORD SUBSTITUTION" +Strings of the form +.BI $ keyword $ +and +.BI $ keyword : .\|.\|. $ +embedded in +the text are replaced +with strings of the form +.BI $ keyword : value $ +where +.I keyword +and +.I value +are pairs listed below. +Keywords can be embedded in literal strings +or comments to identify a revision. +.PP +Initially, the user enters strings of the form +.BI $ keyword $ . +On checkout, +.B co +replaces these strings with strings of the form +.BI $ keyword : value $ . +If a revision containing strings of the latter form +is checked back in, the value fields will be replaced during the next +checkout. +Thus, the keyword values are automatically updated on checkout. +This automatic substitution can be modified by the +.B \-k +options. +.PP +Keywords and their corresponding values: +.TP +.B $\&Author$ +The login name of the user who checked in the revision. +.TP +.B $\&Date$ +The date and time the revision was checked in. +With +.BI \-z zone +a numeric time zone offset is appended; otherwise, the date is \*u. +.TP +.B $\&Header$ +A standard header containing the full \*o name, the +revision number, the date and time, the author, the state, +and the locker (if locked). +With +.BI \-z zone +a numeric time zone offset is appended to the date; otherwise, the date is \*u. +.TP +.B $\&Id$ +Same as +.BR $\&Header$ , +except that the \*o name is without the directory components. +.TP +.B $\&Locker$ +The login name of the user who locked the revision (empty if not locked). +.TP +.B $\&Log$ +The log message supplied during checkin, preceded by a header +containing the \*o name, the revision number, the author, and the date +and time. +With +.BI \-z zone +a numeric time zone offset is appended; otherwise, the date is \*u. +Existing log messages are +.I not +replaced. +Instead, the new log message is inserted after +.BR $\&Log: .\|.\|. $ . +This is useful for +accumulating a complete change log in a source file. +.RS +.LP +Each inserted line is prefixed by the string that prefixes the +.B $\&Log$ +line. For example, if the +.B $\&Log$ +line is +.RB \*(lq "//\ $\&Log: tan.cc\ $" \*(rq, +\*r prefixes each line of the log with +.RB \*(lq "//\ " \*(rq. +This is useful for languages with comments that go to the end of the line. +The convention for other languages is to use a +.RB \*(lq " \(** " \(rq +prefix inside a multiline comment. +For example, the initial log comment of a C program +conventionally is of the following form: +.RS +.LP +.nf +.ft 3 +.ne 3 +/\(** +.in +\w'/'u +\(** $\&Log$ +\(**/ +.in +.ft +.fi +.RE +.LP +For backwards compatibility with older versions of \*r, if the log prefix is +.B /\(** +or +.B (\(** +surrounded by optional white space, inserted log lines contain a space +instead of +.B / +or +.BR ( ; +however, this usage is obsolescent and should not be relied on. +.RE +.TP +.B $\&Name$ +The symbolic name used to check out the revision, if any. +For example, +.B "co\ \-rJoe" +generates +.BR "$\&Name:\ Joe\ $" . +Plain +.B co +generates just +.BR "$\&Name:\ \ $" . +.TP +.B $\&RCSfile$ +The \*o name without directory components. +.TP +.B $\&Revision$ +The revision number assigned to the revision. +.TP +.B $\&Source$ +The full \*o name. +.TP +.B $\&State$ +The state assigned to the revision with the +.B \-s +option of +.BR rcs (1) +or +.BR ci (1). +.PP +The following characters in keyword values are represented by escape sequences +to keep keyword strings well-formed. +.LP +.RS +.nf +.ne 6 +.ta \w'newline 'u +\f2char escape sequence\fP +tab \f3\et\fP +newline \f3\en\fP +space \f3\e040 +$ \e044 +\e \e\e\fP +.fi +.RE +.SH "FILE MODES" +The working file inherits the read and execute permissions from the \*r +file. In addition, the owner write permission is turned on, unless +.B \-kv +is set or the file +is checked out unlocked and locking is set to strict (see +.BR rcs (1)). +.PP +If a file with the name of the working file exists already and has write +permission, +.B co +aborts the checkout, +asking beforehand if possible. +If the existing working file is +not writable or +.B \-f +is given, the working file is deleted without asking. +.SH FILES +.B co +accesses files much as +.BR ci (1) +does, except that it does not need to read the working file +unless a revision number of +.B $ +is specified. +.SH ENVIRONMENT +.TP +.B \s-1RCSINIT\s0 +Options prepended to the argument list, separated by spaces. +A backslash escapes spaces within an option. +The +.B \s-1RCSINIT\s0 +options are prepended to the argument lists of most \*r commands. +Useful +.B \s-1RCSINIT\s0 +options include +.BR \-q , +.BR \-V , +.BR \-x , +and +.BR \-z . +.TP +.B \s-1RCS_MEM_LIMIT\s0 +Normally, for speed, commands either memory map or copy into memory +the \*o if its size is less than the +.IR memory-limit , +currently defaulting to ``unlimited''. +Otherwise (or if the initially-tried speedy ways fail), +the commands fall back to using +standard i/o routines. +You can adjust the memory limit by setting +.B \s-1RCS_MEM_LIMIT\s0 +to a numeric value +.IR lim +(measured in kilobytes). +An empty value is silently ignored. +As a side effect, specifying +.B \s-1RCS_MEM_LIMIT\s0 +inhibits fall-back to slower routines. +.TP +.B \s-1TMPDIR\s0 +Name of the temporary directory. +If not set, the environment variables +.B \s-1TMP\s0 +and +.B \s-1TEMP\s0 +are inspected instead and the first value found is taken; +if none of them are set, +a host-dependent default is used, typically +.BR /tmp . +.SH DIAGNOSTICS +The \*o name, the working file name, +and the revision number retrieved are +written to the diagnostic output. +The exit status is zero if and only if all operations were successful. +.ds EY 1990, 1991, 1992, 1993, 1994, 1995 +.SH IDENTIFICATION +Author: Walter F. Tichy. +.br +Manual Page Revision: \*(Rv; Release Date: \*(Dt. +.br +Copyright \(co 2010-2022 Thien-Thi Nguyen. +.br +Copyright \(co \*(EY Paul Eggert. +.br +Copyright \(co 1982, 1988, 1989 Walter F. Tichy. +.br +.SH "SEE ALSO" +.BR ci (1), +.BR ctime (3), +.BR date (1), +.BR ident (1), +.BR make (1), +.BR rcs (1), +.BR rcsclean (1), +.BR rcsdiff (1), +.BR rcsmerge (1), +.BR rlog (1), +.BR rcsfile (5). +.PP +Walter F. Tichy, +\*r\*-A System for Version Control, +.I "Software\*-Practice & Experience" +.BR 15 , +7 (July 1985), 637-654. +.PP +The full documentation for \*r is maintained as a Texinfo manual. +If the +.BR info (1) +and \*r programs are properly installed at your site, the command +.IP +.B info rcs +.PP +should give you access to the complete manual. +Additionally, the \*r homepage: +.IP +.B http://www.gnu.org/software/rcs/ +.PP +has news and links to the latest release, development site, etc. +.SH LIMITS +Links to the \*r and working files are not preserved. +.PP +There is no way to selectively suppress the expansion of keywords, except +by writing them differently. In nroff and troff, this is done by embedding the +null-character +.B \e& +into the keyword. +.br diff --git a/upstream/fedora-40/man1/comm.1 b/upstream/fedora-40/man1/comm.1 new file mode 100644 index 00000000..92d485ad --- /dev/null +++ b/upstream/fedora-40/man1/comm.1 @@ -0,0 +1,76 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH COMM "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +comm \- compare two sorted files line by line +.SH SYNOPSIS +.B comm +[\fI\,OPTION\/\fR]... \fI\,FILE1 FILE2\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Compare sorted files FILE1 and FILE2 line by line. +.PP +When FILE1 or FILE2 (not both) is \-, read standard input. +.PP +With no options, produce three\-column output. Column one contains +lines unique to FILE1, column two contains lines unique to FILE2, +and column three contains lines common to both files. +.TP +\fB\-1\fR +suppress column 1 (lines unique to FILE1) +.TP +\fB\-2\fR +suppress column 2 (lines unique to FILE2) +.TP +\fB\-3\fR +suppress column 3 (lines that appear in both files) +.TP +\fB\-\-check\-order\fR +check that the input is correctly sorted, even +if all input lines are pairable +.TP +\fB\-\-nocheck\-order\fR +do not check that the input is correctly sorted +.TP +\fB\-\-output\-delimiter\fR=\fI\,STR\/\fR +separate columns with STR +.TP +\fB\-\-total\fR +output a summary +.TP +\fB\-z\fR, \fB\-\-zero\-terminated\fR +line delimiter is NUL, not newline +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Note, comparisons honor the rules specified by 'LC_COLLATE'. +.SH EXAMPLES +.TP +comm \-12 file1 file2 +Print only lines present in both file1 and file2. +.TP +comm \-3 file1 file2 +Print lines in file1 not in file2, and vice versa. +.SH AUTHOR +Written by Richard M. Stallman and David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBjoin\fP(1), \fBuniq\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) comm invocation\(aq diff --git a/upstream/fedora-40/man1/compress.1 b/upstream/fedora-40/man1/compress.1 new file mode 100644 index 00000000..a1270e51 --- /dev/null +++ b/upstream/fedora-40/man1/compress.1 @@ -0,0 +1,295 @@ +.TH COMPRESS 1 local +.SH NAME +compress, uncompress, zcat \- compress and expand data +.SH SYNOPSIS +.ll +8 +.B compress +[ +.B \-f +] [ +.B \-k +] [ +.B \-v +] [ +.B \-c +] [ +.B \-V +] [ +.B \-r +] [ +.B \-b +.I bits +] [ +.B \-\- +] [ +.I "name \&..." +] +.ll -8 +.br +.B uncompress +[ +.B \-f +] [ +.B \-k +] [ +.B \-v +] [ +.B \-c +] [ +.B \-V +] [ +.B \-\- +] [ +.I "name \&..." +] +.br +.B zcat +[ +.B \-V +] [ +.B \-\- +] [ +.I "name \&..." +] +.SH DESCRIPTION +.I Compress +reduces the size of the named files using adaptive Lempel\-Ziv coding. +Whenever possible, +each file is replaced by one with the extension +.B "\&.Z," +while keeping the same ownership modes, access and modification times. +If no files are specified, the standard input is compressed to the +standard output. +.I Compress +will only attempt to compress regular files. +In particular, it will ignore symbolic links. If a file has multiple +hard links, +.I compress +will refuse to compress it unless the +.B \-f +flag is given. +.PP +If +.B \-f +is not given and +.I compress +is run in the foreground, +the user is prompted as to whether an existing file should be overwritten. +.PP +Compressed files can be restored to their original form using +.I uncompress +or +.I zcat. +.PP +.I uncompress +takes a list of files on its command line and replaces each +file whose name ends with +.B "\&.Z" +and which begins with the correct magic number with an uncompressed +file without the +.B "\&.Z." +The uncompressed file will have the mode, ownership and +timestamps of the compressed file. +.PP +The +.B \-k +option makes +.I compress/uncompress +keep the input files instead of automatically removing them. +.PP +The +.B \-c +option makes +.I compress/uncompress +write to the standard output; no files are changed. +.PP +.I zcat +is identical to +.I uncompress +.B \-c. +.I zcat +uncompresses either a list of files on the command line or its +standard input and writes the uncompressed data on standard output. +.I zcat +will uncompress files that have the correct magic number whether +they have a +.B "\&.Z" +suffix or not. +.PP +If the +.B \-r +flag is specified, +.I compress +will operate recursively. If any of the file names specified on the command +line are directories, +.I compress +will descend into the directory and compress all the files it finds there. +When compressing, any files already compressed will be ignored, and when +decompressing, any files already decompressed will be ignored. +.PP +The +.B \-V +flag tells each of these programs to print its version and patchlevel, +along with any preprocessor flags specified during compilation, on +stderr before doing any compression or uncompression. +.PP +.I Compress +uses the modified Lempel\-Ziv algorithm popularized in +"A Technique for High Performance Data Compression", +Terry A. Welch, +.I "IEEE Computer," +vol. 17, no. 6 (June 1984), pp. 8\-19. +Common substrings in the file are first replaced by 9\-bit codes 257 and up. +When code 512 is reached, the algorithm switches to 10\-bit codes and +continues to use more bits until the +limit specified by the +.B \-b +flag is reached (default 16). +.I Bits +must be between 9 and 16. The default can be changed in the source to allow +.I compress +to be run on a smaller machine. +.PP +After the +.I bits +limit is attained, +.I compress +periodically checks the compression ratio. If it is increasing, +.I compress +continues to use the existing code dictionary. However, +if the compression ratio decreases, +.I compress +discards the table of substrings and rebuilds it from scratch. This allows +the algorithm to adapt to the next "block" of the file. +.PP +Note that the +.B \-b +flag is omitted for +.I uncompress, +since the +.I bits +parameter specified during compression +is encoded within the output, along with +a magic number to ensure that neither decompression of random data nor +recompression of compressed data is attempted. +.PP +.ne 8 +The amount of compression obtained depends on the size of the +input, the number of +.I bits +per code, and the distribution of common substrings. +Typically, text such as source code or English +is reduced by 50\-60%. +Compression is generally much better than that achieved by +Huffman coding (as used in +.IR pack ), +or adaptive Huffman coding +.RI ( compact ), +and takes less time to compute. +.PP +Under the +.B \-v +option, +a message is printed yielding the percentage of +reduction for each file compressed. +.PP +.B \-\- +may be used to halt option parsing and force all remaining arguments to be +treated as paths. +.SH "DIAGNOSTICS" +Exit status is normally 0; +if the last file is larger after (attempted) compression, the status is 2; +if an error occurs, exit status is 1. +.PP +Usage: compress [\-dfvcVr] [\-b maxbits] [file ...] +.in +8 +Invalid options were specified on the command line. +.in -8 +Missing maxbits +.in +8 +Maxbits must follow +.BR \-b \. +.in -8 +.IR file : +not in compressed format +.in +8 +The file specified to +.I uncompress +has not been compressed. +.in -8 +.IR file : +compressed with +.I xx +bits, can only handle +.I yy +bits +.in +8 +.I File +was compressed by a program that could deal with +more +.I bits +than the compress code on this machine. +Recompress the file with smaller +.IR bits \. +.in -8 +.IR file : +already has .Z suffix \-\- no change +.in +8 +The file is assumed to be already compressed. +Rename the file and try again. +.in -8 +.IR file : +filename too long to tack on .Z +.in +8 +The file cannot be compressed because its name is longer than +12 characters. +Rename and try again. +This message does not occur on BSD systems. +.in -8 +.I file +already exists; do you wish to overwrite (y or n)? +.in +8 +Respond "y" if you want the output file to be replaced; "n" if not. +.in -8 +uncompress: corrupt input +.in +8 +A SIGSEGV violation was detected which usually means that the input file has +been corrupted. +.in -8 +Compression: +.I "xx.xx%" +.in +8 +Percentage of the input saved by compression. +(Relevant only for +.BR \-v \.) +.in -8 +\-\- not a regular file or directory: ignored +.in +8 +When the input file is not a regular file or directory, +(e.g. a symbolic link, socket, FIFO, device file), it is +left unaltered. +.in -8 +\-\- has +.I xx +other links: unchanged +.in +8 +The input file has links; it is left unchanged. See +.IR ln "(1)" +for more information. Use the +.B \-f +flag to force compression of multiply\-linked files. +.in -8 +\-\- file unchanged +.in +8 +No savings is achieved by +compression. The input remains virgin. +.in -8 +.SH "BUGS" +Although compressed files are compatible between machines with large memory, +.BR \-b \12 +should be used for file transfer to architectures with +a small process data space (64KB or less, as exhibited by the DEC PDP +series, the Intel 80286, etc.) +.SH "SEE ALSO" +.BR pack (1), +.BR compact (1) diff --git a/upstream/fedora-40/man1/consoletype.1 b/upstream/fedora-40/man1/consoletype.1 new file mode 100644 index 00000000..ebd1d88c --- /dev/null +++ b/upstream/fedora-40/man1/consoletype.1 @@ -0,0 +1,44 @@ +.TH CONSOLETYPE 1 "Red Hat, Inc" "RH" \" -*- nroff -*- +.SH NAME +\fBconsoletype +\- print type of the console connected to standard input +.SH SYNOPSIS +\fBconsoletype [\fIstdout\fR] [\fIfg\fR] +.SH DESCRIPTION +\fBconsoletype +prints the type of console connected to standard input, and checks +whether the console connected to standard input is the current +foreground virtual console. With no arguments, it prints +\fIvt\fR +if console is a virtual terminal (/dev/tty* or /dev/console device if not on +a serial console), +\fIserial\fR +if standard input is a serial console (/dev/console or /dev/ttyS*) and +\fIpty\fR +if standard input is a pseudo terminal. +.SH RETURN VALUE +\fBconsoletype +when passed no arguments returns +.TP +\fI0 +if on virtual terminal +.TP +\fI1 +if on serial console +.TP +\fI2 +if on a pseudo terminal. +.TP +When passed the \fIstdout\fR argument, \fBconsoletype\fR returns +.TP +\fI0 +in all cases, and prints the console type to stdout. +.TP +When passed the \fIfg\fR argument, \fBconsoletype\fR returns +.TP +\fI0 +if the console connected to standard input is the current virtual +terminal +.TP +\fI1 +otherwise. diff --git a/upstream/fedora-40/man1/coredumpctl.1 b/upstream/fedora-40/man1/coredumpctl.1 new file mode 100644 index 00000000..fc6d03da --- /dev/null +++ b/upstream/fedora-40/man1/coredumpctl.1 @@ -0,0 +1,467 @@ +'\" t +.TH "COREDUMPCTL" "1" "" "systemd 255" "coredumpctl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +coredumpctl \- Retrieve and process saved core dumps and metadata +.SH "SYNOPSIS" +.HP \w'\fBcoredumpctl\fR\ 'u +\fBcoredumpctl\fR [OPTIONS...] {COMMAND} [PID|COMM|EXE|MATCH...] +.SH "DESCRIPTION" +.PP +\fBcoredumpctl\fR +is a tool that can be used to retrieve and process core dumps and metadata which were saved by +\fBsystemd-coredump\fR(8)\&. +.SH "COMMANDS" +.PP +The following commands are understood: +.PP +\fBlist\fR +.RS 4 +List core dumps captured in the journal matching specified characteristics\&. If no command is specified, this is the implied default\&. +.sp +The output is designed to be human readable and contains a table with the following columns: +.PP +TIME +.RS 4 +The timestamp of the crash, as reported by the kernel\&. +.sp +Added in version 233\&. +.RE +.PP +PID +.RS 4 +The identifier of the process that crashed\&. +.sp +Added in version 233\&. +.RE +.PP +UID, GID +.RS 4 +The user and group identifiers of the process that crashed\&. +.sp +Added in version 233\&. +.RE +.PP +SIGNAL +.RS 4 +The signal that caused the process to crash, when applicable\&. +.sp +Added in version 233\&. +.RE +.PP +COREFILE +.RS 4 +Information whether the coredump was stored, and whether it is still accessible: +"none" +means the core was not stored, +"\-" +means that it was not available (for example because the process was not terminated by a signal), +"present" +means that the core file is accessible by the current user, +"journal" +means that the core was stored in the +"journal", +"truncated" +is the same as one of the previous two, but the core was too large and was not stored in its entirety, +"error" +means that the core file cannot be accessed, most likely because of insufficient permissions, and +"missing" +means that the core was stored in a file, but this file has since been removed\&. +.sp +Added in version 233\&. +.RE +.PP +EXE +.RS 4 +The full path to the executable\&. For backtraces of scripts this is the name of the interpreter\&. +.sp +Added in version 233\&. +.RE +.sp +It\*(Aqs worth noting that different restrictions apply to data saved in the journal and core dump files saved in +/var/lib/systemd/coredump, see overview in +\fBsystemd-coredump\fR(8)\&. Thus it may very well happen that a particular core dump is still listed in the journal while its corresponding core dump file has already been removed\&. +.sp +Added in version 215\&. +.RE +.PP +\fBinfo\fR +.RS 4 +Show detailed information about the last core dump or core dumps matching specified characteristics captured in the journal\&. +.sp +Added in version 215\&. +.RE +.PP +\fBdump\fR +.RS 4 +Extract the last core dump matching specified characteristics\&. The core dump will be written on standard output, unless an output file is specified with +\fB\-\-output=\fR\&. +.sp +Added in version 215\&. +.RE +.PP +\fBdebug\fR +.RS 4 +Invoke a debugger on the last core dump matching specified characteristics\&. By default, +\fBgdb\fR(1) +will be used\&. This may be changed using the +\fB\-\-debugger=\fR +option or the +\fI$SYSTEMD_DEBUGGER\fR +environment variable\&. Use the +\fB\-\-debugger\-arguments=\fR +option to pass extra command line arguments to the debugger\&. +.sp +Added in version 239\&. +.RE +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +\fB\-\-no\-legend\fR +.RS 4 +Do not print the legend, i\&.e\&. column headers and the footer with hints\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +Shows output formatted as JSON\&. Expects one of +"short" +(for the shortest possible output without any redundant whitespace or line breaks), +"pretty" +(for a pretty version of the same, with indentation and line breaks) or +"off" +(to turn off JSON output, the default)\&. +.RE +.PP +\fB\-1\fR +.RS 4 +Show information of the most recent core dump only, instead of listing all known core dumps\&. Equivalent to +\fB\-\-reverse \-n 1\fR\&. +.sp +Added in version 215\&. +.RE +.PP +\fB\-n\fR \fIINT\fR +.RS 4 +Show at most the specified number of entries\&. The specified parameter must be an integer greater or equal to 1\&. +.sp +Added in version 248\&. +.RE +.PP +\fB\-S\fR, \fB\-\-since\fR +.RS 4 +Only print entries which are since the specified date\&. +.sp +Added in version 233\&. +.RE +.PP +\fB\-U\fR, \fB\-\-until\fR +.RS 4 +Only print entries which are until the specified date\&. +.sp +Added in version 233\&. +.RE +.PP +\fB\-r\fR, \fB\-\-reverse\fR +.RS 4 +Reverse output so that the newest entries are displayed first\&. +.sp +Added in version 233\&. +.RE +.PP +\fB\-F\fR \fIFIELD\fR, \fB\-\-field=\fR\fIFIELD\fR +.RS 4 +Print all possible data values the specified field takes in matching core dump entries of the journal\&. +.sp +Added in version 215\&. +.RE +.PP +\fB\-o\fR \fIFILE\fR, \fB\-\-output=\fR\fIFILE\fR +.RS 4 +Write the core to +\fBFILE\fR\&. +.sp +Added in version 215\&. +.RE +.PP +\fB\-\-debugger=\fR\fIDEBUGGER\fR +.RS 4 +Use the given debugger for the +\fBdebug\fR +command\&. If not given and +\fI$SYSTEMD_DEBUGGER\fR +is unset, then +\fBgdb\fR(1) +will be used\&. +.sp +Added in version 239\&. +.RE +.PP +\fB\-A\fR \fIARGS\fR, \fB\-\-debugger\-arguments=\fR\fIARGS\fR +.RS 4 +Pass the given +\fIARGS\fR +as extra command line arguments to the debugger\&. Quote as appropriate when +\fIARGS\fR +contain whitespace\&. (See Examples\&.) +.sp +Added in version 248\&. +.RE +.PP +\fB\-\-file=\fR\fB\fIGLOB\fR\fR +.RS 4 +Takes a file glob as an argument\&. If specified, coredumpctl will operate on the specified journal files matching +\fIGLOB\fR +instead of the default runtime and system journal paths\&. May be specified multiple times, in which case files will be suitably interleaved\&. +.sp +Added in version 246\&. +.RE +.PP +\fB\-D\fR \fIDIR\fR, \fB\-\-directory=\fR\fIDIR\fR +.RS 4 +Use the journal files in the specified +\fBDIR\fR\&. +.sp +Added in version 225\&. +.RE +.PP +\fB\-\-root=\fR\fB\fIROOT\fR\fR +.RS 4 +Use root directory +\fBROOT\fR +when searching for coredumps\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-image=\fR\fB\fIimage\fR\fR +.RS 4 +Takes a path to a disk image file or block device node\&. If specified, all operations are applied to file system in the indicated disk image\&. This option is similar to +\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see +\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&. +.sp +Added in version 252\&. +.RE +.PP +\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR +.RS 4 +Takes an image policy string as argument, as per +\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via +\fB\-\-image=\fR, see above\&. If not specified defaults to the +"*" +policy, i\&.e\&. all recognized file systems in the image are used\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Suppresses informational messages about lack of access to journal files and possible in\-flight coredumps\&. +.sp +Added in version 233\&. +.RE +.PP +\fB\-\-all\fR +.RS 4 +Look at all available journal files in +/var/log/journal/ +(excluding journal namespaces) instead of only local ones\&. +.sp +Added in version 250\&. +.RE +.SH "MATCHING" +.PP +A match can be: +.PP +\fIPID\fR +.RS 4 +Process ID of the process that dumped core\&. An integer\&. +.sp +Added in version 215\&. +.RE +.PP +\fICOMM\fR +.RS 4 +Name of the executable (matches +\fBCOREDUMP_COMM=\fR)\&. Must not contain slashes\&. +.sp +Added in version 215\&. +.RE +.PP +\fIEXE\fR +.RS 4 +Path to the executable (matches +\fBCOREDUMP_EXE=\fR)\&. Must contain at least one slash\&. +.sp +Added in version 215\&. +.RE +.PP +\fIMATCH\fR +.RS 4 +General journalctl match filter, must contain an equals sign ("=")\&. See +\fBjournalctl\fR(1)\&. +.sp +Added in version 215\&. +.RE +.SH "EXIT STATUS" +.PP +On success, 0 is returned; otherwise, a non\-zero failure code is returned\&. Not finding any matching core dumps is treated as failure\&. +.SH "ENVIRONMENT" +.PP +\fI$SYSTEMD_DEBUGGER\fR +.RS 4 +Use the given debugger for the +\fBdebug\fR +command\&. See the +\fB\-\-debugger=\fR +option\&. +.sp +Added in version 239\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&List all the core dumps of a program\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ coredumpctl list /usr/lib64/firefox/firefox +TIME PID UID GID SIG COREFILE EXE SIZE +Tue \&... 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox \- +Wed \&... 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox \- +Fri \&... 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28\&.7M +.fi +.if n \{\ +.RE +.\} +.PP +The journal has three entries pertaining to +/usr/lib64/firefox/firefox, and only the last entry still has an available core file (in external storage on disk)\&. +.PP +Note that +coredumpctl +needs access to the journal files to retrieve the relevant entries from the journal\&. Thus, an unprivileged user will normally only see information about crashing programs of this user\&. +.PP +\fBExample\ \&2.\ \&Invoke gdb on the last core dump\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ coredumpctl debug +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Use gdb to display full register info from the last core dump\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ coredumpctl debug \-\-debugger\-arguments="\-batch \-ex \*(Aqinfo all\-registers\*(Aq" +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Show information about a core dump matched by PID\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ coredumpctl info 6654 + PID: 6654 (bash) + UID: 1000 (user) + GID: 1000 (user) + Signal: 11 (SEGV) + Timestamp: Mon 2021\-01\-01 00:00:01 CET (20s ago) + Command Line: bash \-c $\*(Aqkill \-SEGV $$\*(Aq + Executable: /usr/bin/bash + Control Group: /user\&.slice/user\-1000\&.slice/\&... + Unit: user@1000\&.service + User Unit: vte\-spawn\-\&...\&.scope + Slice: user\-1000\&.slice + Owner UID: 1000 (user) + Boot ID: \&... + Machine ID: \&... + Hostname: \&... + Storage: /var/lib/systemd/coredump/core\&.bash\&.1000\&.\&...\&.zst (present) + Size on Disk: 51\&.7K + Message: Process 130414 (bash) of user 1000 dumped core\&. + + Stack trace of thread 130414: + #0 0x00007f398142358b kill (libc\&.so\&.6 + 0x3d58b) + #1 0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09) + #2 0x0000558c2c79dc59 execute_builtin\&.lto_priv\&.0 (bash + 0x51c59) + #3 0x0000558c2c79709c execute_simple_command (bash + 0x4b09c) + #4 0x0000558c2c798408 execute_command_internal (bash + 0x4c408) + #5 0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc) + #6 0x0000558c2c85415c run_one_command\&.isra\&.0 (bash + 0x10815c) + #7 0x0000558c2c77d040 main (bash + 0x31040) + #8 0x00007f398140db75 __libc_start_main (libc\&.so\&.6 + 0x27b75) + #9 0x0000558c2c77dd1e _start (bash + 0x31d1e) +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&5.\ \&Extract the last core dump of /usr/bin/bar to a file named bar\&.coredump\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ coredumpctl \-o bar\&.coredump dump /usr/bin/bar +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd-coredump\fR(8), +\fBcoredump.conf\fR(5), +\fBsystemd-journald.service\fR(8), +\fBgdb\fR(1) +.SH "NOTES" +.IP " 1." 4 +Discoverable Partitions Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification +.RE diff --git a/upstream/fedora-40/man1/cp.1 b/upstream/fedora-40/man1/cp.1 new file mode 100644 index 00000000..0d15e57d --- /dev/null +++ b/upstream/fedora-40/man1/cp.1 @@ -0,0 +1,197 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CP "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +cp \- copy files and directories +.SH SYNOPSIS +.B cp +[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,SOURCE DEST\/\fR +.br +.B cp +[\fI\,OPTION\/\fR]... \fI\,SOURCE\/\fR... \fI\,DIRECTORY\/\fR +.br +.B cp +[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY SOURCE\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-a\fR, \fB\-\-archive\fR +same as \fB\-dR\fR \fB\-\-preserve\fR=\fI\,all\/\fR +.TP +\fB\-\-attributes\-only\fR +don't copy the file data, just the attributes +.TP +\fB\-\-backup\fR[=\fI\,CONTROL\/\fR] +make a backup of each existing destination file +.TP +\fB\-b\fR +like \fB\-\-backup\fR but does not accept an argument +.TP +\fB\-\-copy\-contents\fR +copy contents of special files when recursive +.TP +\fB\-d\fR +same as \fB\-\-no\-dereference\fR \fB\-\-preserve\fR=\fI\,links\/\fR +.TP +\fB\-\-debug\fR +explain how a file is copied. Implies \fB\-v\fR +.TP +\fB\-f\fR, \fB\-\-force\fR +if an existing destination file cannot be +opened, remove it and try again (this option +is ignored when the \fB\-n\fR option is also used) +.TP +\fB\-i\fR, \fB\-\-interactive\fR +prompt before overwrite (overrides a previous \fB\-n\fR +option) +.TP +\fB\-H\fR +follow command\-line symbolic links in SOURCE +.TP +\fB\-l\fR, \fB\-\-link\fR +hard link files instead of copying +.TP +\fB\-L\fR, \fB\-\-dereference\fR +always follow symbolic links in SOURCE +.TP +\fB\-n\fR, \fB\-\-no\-clobber\fR +do not overwrite an existing file (overrides a +\fB\-u\fR or previous \fB\-i\fR option). See also \fB\-\-update\fR +.TP +\fB\-P\fR, \fB\-\-no\-dereference\fR +never follow symbolic links in SOURCE +.TP +\fB\-p\fR +same as \fB\-\-preserve\fR=\fI\,mode\/\fR,ownership,timestamps +.TP +\fB\-\-preserve\fR[=\fI\,ATTR_LIST\/\fR] +preserve the specified attributes +.TP +\fB\-\-no\-preserve\fR=\fI\,ATTR_LIST\/\fR +don't preserve the specified attributes +.TP +\fB\-\-parents\fR +use full source file name under DIRECTORY +.TP +\fB\-R\fR, \fB\-r\fR, \fB\-\-recursive\fR +copy directories recursively +.TP +\fB\-\-reflink\fR[=\fI\,WHEN\/\fR] +control clone/CoW copies. See below +.TP +\fB\-\-remove\-destination\fR +remove each existing destination file before +attempting to open it (contrast with \fB\-\-force\fR) +.TP +\fB\-\-sparse\fR=\fI\,WHEN\/\fR +control creation of sparse files. See below +.TP +\fB\-\-strip\-trailing\-slashes\fR +remove any trailing slashes from each SOURCE +argument +.TP +\fB\-s\fR, \fB\-\-symbolic\-link\fR +make symbolic links instead of copying +.TP +\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR +override the usual backup suffix +.TP +\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR +copy all SOURCE arguments into DIRECTORY +.TP +\fB\-T\fR, \fB\-\-no\-target\-directory\fR +treat DEST as a normal file +.TP +\fB\-\-update\fR[=\fI\,UPDATE\/\fR] +control which existing files are updated; +UPDATE={all,none,older(default)}. See below +.TP +\fB\-u\fR +equivalent to \fB\-\-update\fR[=\fI\,older\/\fR] +.TP +\fB\-v\fR, \fB\-\-verbose\fR +explain what is being done +.TP +\fB\-x\fR, \fB\-\-one\-file\-system\fR +stay on this file system +.TP +\fB\-Z\fR +set SELinux security context of destination +file to default type +.TP +\fB\-\-context\fR[=\fI\,CTX\/\fR] +like \fB\-Z\fR, or if CTX is specified then set the +SELinux or SMACK security context to CTX +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +ATTR_LIST is a comma\-separated list of attributes. Attributes are 'mode' for +permissions (including any ACL and xattr permissions), 'ownership' for user +and group, 'timestamps' for file timestamps, 'links' for hard links, 'context' +for security context, 'xattr' for extended attributes, and 'all' for all +attributes. +.PP +By default, sparse SOURCE files are detected by a crude heuristic and the +corresponding DEST file is made sparse as well. That is the behavior +selected by \fB\-\-sparse\fR=\fI\,auto\/\fR. Specify \fB\-\-sparse\fR=\fI\,always\/\fR to create a sparse DEST +file whenever the SOURCE file contains a long enough sequence of zero bytes. +Use \fB\-\-sparse\fR=\fI\,never\/\fR to inhibit creation of sparse files. +.PP +UPDATE controls which existing files in the destination are replaced. +\&'all' is the default operation when an \fB\-\-update\fR option is not specified, +and results in all existing files in the destination being replaced. +\&'none' is similar to the \fB\-\-no\-clobber\fR option, in that no files in the +destination are replaced, but also skipped files do not induce a failure. +\&'older' is the default operation when \fB\-\-update\fR is specified, and results +in files being replaced if they're older than the corresponding source file. +.PP +When \fB\-\-reflink\fR[=\fI\,always\/\fR] is specified, perform a lightweight copy, where the +data blocks are copied only when modified. If this is not possible the copy +fails, or if \fB\-\-reflink\fR=\fI\,auto\/\fR is specified, fall back to a standard copy. +Use \fB\-\-reflink\fR=\fI\,never\/\fR to ensure a standard copy is performed. +.PP +The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX. +The version control method may be selected via the \fB\-\-backup\fR option or through +the VERSION_CONTROL environment variable. Here are the values: +.TP +none, off +never make backups (even if \fB\-\-backup\fR is given) +.TP +numbered, t +make numbered backups +.TP +existing, nil +numbered if numbered backups exist, simple otherwise +.TP +simple, never +always make simple backups +.PP +As a special case, cp makes a backup of SOURCE when the force and backup +options are given and SOURCE and DEST are the same name for an existing, +regular file. +.SH AUTHOR +Written by Torbjorn Granlund, David MacKenzie, and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBinstall\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) cp invocation\(aq diff --git a/upstream/fedora-40/man1/cpio.1 b/upstream/fedora-40/man1/cpio.1 new file mode 100644 index 00000000..670277c8 --- /dev/null +++ b/upstream/fedora-40/man1/cpio.1 @@ -0,0 +1,438 @@ +.\" DO NOT MODIFY THIS FILE! It was (partly) generated by help2man from +.\" cpio --help/cpio --version output and partly patched by downstream +.\" package maintainers. +.TH CPIO 1L \" -*- nroff -*- +.SH NAME +cpio \- copy files to and from archives +.SH __WARNING__ +.PP +The cpio utility is considered LEGACY based on POSIX specification. Users are +encouraged to use other archiving tools for archive creation. + +If you decided to use cpio, you should almost always force cpio to use the +ustar format in copy-out mode by the -H option (cpio -o -H ustar). This is +because the ustar format is well defined in POSIX specification and thus +readable by wide range of other archiving tools (including tar e.g.). + +By default, GNU cpio uses (for historical reasons) the very old binary format +('bin') which has significant problems nowadays, e.g. with storing big inode +numbers (see the Red Hat bug #952313). + +Note also that these days the modern 'pax' archive format should be considered +as the default -- but this format is not implemented in GNU cpio. You should, +again, consider using other archivers (e.g. 'tar --format=pax'). + +.SH SYNOPSIS +\&\fBCopy-out mode\fR +.PP +In copy-out mode, cpio copies files into an archive. It reads a list +of filenames, one per line, on the standard input, and writes the +archive onto the standard output. A typical way to generate the list +of filenames is with the find command; you should give find the \-depth +option to minimize problems with permissions on directories that are +unreadable. see \*(lqOptions\*(rq. +.PP +.B cpio +{\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-D DIR] +[\-M message] [\-O [[user@]host:]archive] [\-F [[user@]host:]archive] +[\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-warning=FLAG] +[\-\-message=message][\-\-null] [\-\-reset\-access\-time] [\-\-verbose] +[\-\-dot] [\-\-append] [\-\-block\-size=blocks] [\-\-dereference] +[\-\-io\-size=bytes] [\-\-rsh\-command=command] [\-\-license] [\-\-usage] +[\-\-help] [\-\-version] +< name-list [> archive] +.PP +\&\fBCopy-in mode\fR +.PP +In copy-in mode, cpio copies files out of an archive or lists the +archive contents. It reads the archive from the standard input. Any +non-option command line arguments are shell globbing patterns; only +files in the archive whose names match one or more of those patterns are +copied from the archive. Unlike in the shell, an initial `\fB.\fR' in a +filename does match a wildcard at the start of a pattern, and a `\fB/\fR' in a +filename can match wildcards. If no patterns are given, all files are +extracted. see \*(lqOptions\*(rq. +.PP +.B cpio +{\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format] +[\-D DIR] +[\-M message] [\-R [user][:.][group]] [\-I [[user@]host:]archive] +[\-F [[user@]host:]archive] [\-\-file=[[user@]host:]archive] +[\-\-make-directories] [\-\-nonmatching] [\-\-preserve-modification-time] +[\-\-numeric-uid-gid] [\-\-rename] [\-t|\-\-list] [\-\-swap-bytes] [\-\-swap] +[\-\-dot] [\-\-warning=FLAG] [\-\-unconditional] [\-\-verbose] +[\-\-block-size=blocks] [\-\-swap-halfwords] [\-\-io-size=bytes] +[\-\-pattern-file=file] [\-\-format=format] [\-\-owner=[user][:.][group]] +[\-\-no-preserve-owner] [\-\-message=message] +[\-\-force\-local] [\-\-no\-absolute\-filenames] [\-\-absolute\-filenames] +[\-\-sparse] [\-\-only\-verify\-crc] [\-\-to\-stdout] [\-\-quiet] +[\-\-ignore\-devno] [\-\-renumber\-inodes] [\-\-device\-independent] +[\-\-reproducible] +[\-\-rsh-command=command] [\-\-license] [\-\-usage] [\-\-help] +[\-\-version] [pattern...] [< archive] +.PP +\&\fBCopy-pass mode\fR +.PP +In copy-pass mode, cpio copies files from one directory tree to +another, combining the copy-out and copy-in steps without actually +using an archive. It reads the list of files to copy from the standard +input; the directory into which it will copy them is given as a +non-option argument. see \*(lqOptions\*(rq. +.PP +.B cpio +{\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]] [\-D DIR] +[\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet] +[\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot] +[\-\-warning=FLAG] [\-\-dereference] [\-\-owner=[user][:.][group]] +[\-\-no-preserve-owner] [\-\-sparse] [\-\-license] [\-\-usage] [\-\-help] +[\-\-version] destination-directory < name-list +.PP +.SH DESCRIPTION +GNU cpio is a tool for creating and extracting archives, or copying +files from one place to another. It handles a number of cpio formats as +well as reading and writing tar files. +.PP +Following archive formats are supported: binary, old ASCII, new ASCII, crc, HPUX binary, HPUX old +ASCII, old tar, and POSIX.1 tar. The tar format is provided for compatibility with the tar program. By +default, cpio creates binary format archives, for compatibility with older cpio programs. When extracting +from archives, cpio automatically recognizes which kind of archive it is reading and can read archives created +on machines with a different byte-order. +.PP +.SS "Main operation mode:" +.TP +\fB\-i\fR, \fB\-\-extract\fR +Extract files from an archive (run in copy\-in +mode) +.TP +\fB\-o\fR, \fB\-\-create\fR +Create the archive (run in copy\-out mode) +.TP +\fB\-p\fR, \fB\-\-pass\-through\fR +Run in copy\-pass mode +.TP +\fB\-t\fR, \fB\-\-list\fR +Print a table of contents of the input +.SS "Operation modifiers valid in any mode:" +.TP +\fB\-\-block\-size\fR=\fI\,BLOCK\-SIZE\/\fR +Set the I/O block size to BLOCK\-SIZE * 512 +bytes +.TP +\fB\-B\fR +Set the I/O block size to 5120 bytes. +Initially the block size is 512 bytes. +.TP +\fB\-c\fR +Identical to "\-H newc", use the new (SVR4) +portable format. If you wish the old portable +(ASCII) archive format, use "\-H odc" instead. +.TP +\fB\-C\fR, \fB\-\-io\-size\fR=\fI\,NUMBER\/\fR +Set the I/O block size to the given NUMBER of +bytes +.TP +\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +Change to directory DIR +.TP +\fB\-\-force\-local\fR +With \-F, \-I, or \-O, take the archive file name to be a local file +even if it contains a colon, which would ordinarily indicate a +remote host name. +.TP +\fB\-H\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR +Use given archive FORMAT. +The valid formats are listed below; the same names are also recognized in +all\-caps. The default in copy-in mode is to automatically detect the archive +format, and in copy-out mode is `\fBbin\fR'. +.TP +`bin' +The obsolete binary format. +.TP +`odc' +The old (\s-1POSIX\s0.1) portable format. +.TP +`newc' +The new (\s-1SVR4\s0) portable format, which supports file systems +having more than 65536 i\-nodes. +.TP +`crc' +The new (\s-1SVR4\s0) portable format with a checksum (Sum32) added. +.TP +`tar' +The old tar format. +.TP +`ustar' +The \s-1POSIX\s0.1 tar format. Also recognizes \s-1GNU\s0 tar archives, +which are similar but not identical. +.TP +`hpbin' +The obsolete binary format used by \s-1HPUX\s0's cpio (which stores +device files differently). +.TP +`hpodc' +The portable format used by \s-1HPUX\s0's cpio (which stores device +files differently). +.TP +\fB\-\-quiet\fR +Do not print the number of blocks copied +.TP +\fB\-R\fR, \fB\-\-owner\fR=\fI\,[USER][\/\fR:.][GROUP] +Set the ownership of all files created to the +specified USER and/or GROUP. +Either the user, the group, or both, must be present. If the group is omitted +but the \&\*(lq:\*(rq or \*(lq.\*(rq separator is given, use the given user's +login group. Only the super-user can change files' ownership in copy\-in mode. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +List the files processed, or with `\fB\-t\fR', give an `\fBls \-l\fR' style +table of contents listing. In a verbose table of contents of a +ustar archive, user and group names in the archive that do not +exist on the local system are replaced by the names that +correspond locally to the numeric \s-1UID\s0 and \s-1GID\s0 stored in the +archive. +.TP +\fB\-V\fR, \fB\-\-dot\fR +Print a "." for each file processed +.TP +\fB\-W\fR, \fB\-\-warning\fR=\fI\,FLAG\/\fR +Control warning display. Currently FLAG is one of +\&'none', 'truncate', 'all'. Multiple options +accumulate. +.SS "Operation modifiers valid in copy-in and copy-out modes:" +.TP +\fB\-F\fR, \fB\-\-file\fR=\fI\,[[USER\/\fR@]HOST:]FILE\-NAME +Use this FILE\-NAME instead of standard input or +output. Optional USER and HOST specify the user +and host names in case of a remote archive +.TP +\fB\-M\fR, \fB\-\-message\fR=\fI\,STRING\/\fR +Print \s-1STRING\s0 when the end of a volume of the backup media (such +as a tape or a floppy disk) is reached, to prompt the user to +insert a new volume. If \s-1STRING\s0 contains the string \*(lq%d\*(rq, it is +replaced by the current volume number (starting at 1). +.TP +\fB\-\-rsh\-command\fR=\fI\,COMMAND\/\fR +Use COMMAND instead of rsh +(typically /usr/bin/ssh) +.SS "Operation modifiers valid only in copy-in mode:" +.TP +\fB\-b\fR, \fB\-\-swap\fR +Swap both halfwords of words and bytes of +halfwords in the data. Equivalent to \fB\-sS\fR +Use this option to convert 32\-bit integers between big-endian and little-endian +machines. +.TP +\fB\-f\fR, \fB\-\-nonmatching\fR +Only copy files that do not match any of the given +patterns +.TP +\fB\-I\fR [[USER@]HOST:]FILE\-NAME +Archive filename to use instead of standard input. +Optional USER and HOST specify the user and host +names in case of a remote archive +.TP +\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR +In the verbose table of contents listing, show +numeric UID and GID +.TP +\fB\-r\fR, \fB\-\-rename\fR +Interactively rename files +.TP +\fB\-s\fR, \fB\-\-swap\-bytes\fR +Swap the bytes of each halfword in the files +.TP +\fB\-S\fR, \fB\-\-swap\-halfwords\fR +Swap the halfwords of each word (4 bytes) in the +files +.TP +\fB\-\-to\-stdout\fR +Extract files to standard output +.TP +\fB\-E\fR, \fB\-\-pattern\-file\fR=\fI\,FILE\/\fR +Read additional patterns specifying filenames to +extract or list from FILE +.TP +\fB\-\-only\-verify\-crc\fR +When reading a CRC format archive, only verify the +checksum of each file in the archive, don't +actually extract the files +.SS "Operation modifiers valid only in copy-out mode:" +.TP +\fB\-A\fR, \fB\-\-append\fR +Append to an existing archive. +The archive must be a disk file specified with the \-O or \-F (\-file) option. +.TP +\fB\-\-device\-independent\fR, \fB\-\-reproducible\fR +Create device\-independent (reproducible) archives +.TP +\fB\-\-ignore\-devno\fR +Don't store device numbers +.TP +\fB\-O\fR [[USER@]HOST:]FILE\-NAME +Archive filename to use instead of standard +output. Optional USER and HOST specify the user +and host names in case of a remote archive +.TP +\fB\-\-renumber\-inodes\fR +Renumber inodes +.SS "Operation modifiers valid only in copy-pass mode:" +.TP +\fB\-l\fR, \fB\-\-link\fR +Link files instead of copying them, when +possible +.SS "Operation modifiers valid in copy-in and copy-out modes:" +.TP +\fB\-\-absolute\-filenames\fR +Do not strip file system prefix components from +the file names +.TP +\fB\-\-no\-absolute\-filenames\fR +Create all files relative to the current +directory +.SS "Operation modifiers valid in copy-out and copy-pass modes:" +.TP +\fB\-0\fR, \fB\-\-null\fR +Filenames in the list are delimited by null +characters instead of newlines, so that files whose names contain newlines can +be archived. \s-1GNU\s0 find is one way to produce a list of null-terminated +filenames. +.TP +\fB\-a\fR, \fB\-\-reset\-access\-time\fR +Reset the access times of files after reading them, so that it +does not look like they have just been read. +.TP +\fB\-L\fR, \fB\-\-dereference\fR +Dereference symbolic links (copy the files +that they point to instead of copying the links). +.SS "Operation modifiers valid in copy-in and copy-pass modes:" +.TP +\fB\-d\fR, \fB\-\-make\-directories\fR +Create leading directories where needed +.TP +\fB\-m\fR, \fB\-\-preserve\-modification\-time\fR +Retain previous file modification times when +creating files +.TP +\fB\-\-no\-preserve\-owner\fR +Do not change the ownership of the files; leave them owned by the +user extracting them. This is the default for non-root users, so +that users on System V don't inadvertently give away files. This +option can be used in copy-in mode and copy-pass mode +.TP +\fB\-\-sparse\fR +Write files with large blocks of zeros as sparse +files +.TP +\fB\-u\fR, \fB\-\-unconditional\fR +Replace all files unconditionally +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. + +.PP +.SH EXAMPLES +When creating an archive, cpio takes the list of files to be +processed from the standard input, and then sends the archive to the +standard output, or to the device defined by the `\fB\-F\fR' option. +Usually find or ls is used to provide this list to +the standard input. In the following example you can see the +possibilities for archiving the contents of a single directory. +.PP +.B % ls | cpio \-ov > directory.cpio +.PP +The `\fB\-o\fR' option creates the archive, and the `\fB\-v\fR' option prints the +names of the files archived as they are added. Notice that the options +can be put together after a single `\fB\-\fR' or can be placed separately on +the command line. The `\fB>\fR' redirects the cpio output to the file +`\fBdirectory.cpio\fR'. +.PP +If you wanted to archive an entire directory tree, the find command +can provide the file list to cpio: +.PP +.B % find . \-print \-depth | cpio \-ov > tree.cpio +.PP +This will take all the files in the current directory, the +directories below and place them in the archive tree.cpio. Again the +`\fB\-o\fR' creates an archive, and the `\fB\-v\fR' option shows you the name of the +files as they are archived. see \*(lqCopy\-out mode\*(rq. Using the `\fB.\fR' in +the find statement will give you more flexibility when doing restores, +as it will save file names with a relative path vice a hard wired, +absolute path. The `\fB\-depth\fR' option forces `\fBfind\fR' to print of the +entries in a directory before printing the directory itself. This +limits the effects of restrictive directory permissions by printing the +directory entries in a directory before the directory name itself. +.PP +Extracting an archive requires a bit more thought because cpio will +not create directories by default. Another characteristic, is it will +not overwrite existing files unless you tell it to. +.PP +.B % cpio \-iv < directory.cpio +.PP +This will retrieve the files archived in the file directory.cpio and +place them in the present directory. The `\fB\-i\fR' option extracts the +archive and the `\fB\-v\fR' shows the file names as they are extracted. If +you are dealing with an archived directory tree, you need to use the +`\fB\-d\fR' option to create directories as necessary, something like: +.PP +.B % cpio \-idv < tree.cpio +.PP +This will take the contents of the archive tree.cpio and extract it +to the current directory. If you try to extract the files on top of +files of the same name that already exist (and have the same or later +modification time) cpio will not extract the file unless told to do so +by the \-u option. see \*(lqCopy\-in mode\*(rq. +.PP +In copy-pass mode, cpio copies files from one directory tree to +another, combining the copy-out and copy-in steps without actually +using an archive. It reads the list of files to copy from the standard +input; the directory into which it will copy them is given as a +non-option argument. see \*(lqCopy\-pass mode\*(rq. +.PP +.B % find . \-depth \-print0 | cpio \-\-null \-pvd new-dir +.PP +The example shows copying the files of the present directory, and +sub-directories to a new directory called new\-dir. Some new options are +the `\fB\-print0\fR' available with \s-1GNU\s0 find, combined with the `\fB\-\-null\fR' +option of cpio. These two options act together to send file names +between find and cpio, even if special characters are embedded in the +file names. Another is `\fB\-p\fR', which tells cpio to pass the files it +finds to the directory `\fBnew-dir\fR'. + + +.SH AUTHOR +Written by Phil Nelson, David MacKenzie, John Oleynick, +and Sergey Poznyakoff. +.SH "REPORTING BUGS" +Report bugs to . +Report bugs in this manual page via https://bugzilla.redhat.com. +.SH COPYRIGHT +Copyright \(co 2015 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B cpio +is maintained as a Texinfo manual. If the +.B info +and +.B cpio +programs are properly installed at your site, the command +.IP +.B info cpio +.PP +should give you access to the complete manual. + +The online copy of the documentation is available at the following address: +.PP +http://www.gnu.org/software/cpio/manual diff --git a/upstream/fedora-40/man1/cronnext.1 b/upstream/fedora-40/man1/cronnext.1 new file mode 100644 index 00000000..5dab9fb9 --- /dev/null +++ b/upstream/fedora-40/man1/cronnext.1 @@ -0,0 +1,86 @@ +.TH CRONNEXT 1 "2017-06-11" "cronie" "User Commands" +.SH NAME +cronnext \- time of next job cron will execute +.SH SYNOPSIS +.TP 9 +.B cronnext +[\fB-i \fIusers\fR] [\fB-e \fIusers\fR] [\fB-s\fR] +[\fB-a\fR] +[\fB-t \fItime\fR] [\fB-q \fItime\fR] [\fB-j \fIcommand\fR] +[\fB-l\fR] [\fB-c\fR] [\fB-f\fR] [\fB-h\fR] [\fB-V\fR] +[file]... +.SH DESCRIPTION +Determine the time cron will execute the next job. Without arguments, it +prints that time considering all crontabs, in number of seconds since the +Epoch, rounded to the minute. This number can be converted into other formats +using +.BR date (1), +like +.B date --date @43243254 + +The file arguments are optional. If provided, +.I cronnext +uses them as crontabs instead of the ones installed in the system. +.SH OPTIONS +.TP +.BI "\-i " user,user,user,... +Consider only the crontabs of the specified users. Use +.B *system* +for the system crontab. +.TP +.BI "\-e " user,user,user,... +Do not consider the crontabs of the specified users. +.TP +.B \-s +Do not consider the system crontab, usually the +.I /etc/crontab +file. The system crontab usually contains the hourly, daily, weekly and +monthly crontabs, which might be better dealt with +.BR anacron (8). +.TP +.BI \-a +Use the crontabs installed in the system in addition to the ones passed as +file arguments. This is implicit if no file is passed. +.TP +.BI "\-t " time +Determine the next job from this time, instead of now. The time is +expressed in number of seconds since the Epoch, as obtained for example by +.BR "date +%s --date \(dqnow + 2 hours\(dq" , +and is internally rounded to the minute. +.TP +.BI "\-q " time +Do not check jobs over this time, expressed in the same way as in option +.BR -t . +.TP +.BI "\-j " command +Only look for jobs that contain \fIcommand\fP as a substring. +.TP +.B \-l +Print the whole entries of the jobs that are the next to be executed by cron. +The default is to only print their next time of execution. +.TP +.B \-c +Print every entry in every crontab with the next time it is executed. +.TP +.B \-f +Print all jobs that are executed in the given interval. Requires option +\fB-q\fR. +.TP +.B \-h +Print usage output and exit. +.TP +.B \-V +Print version and exit. +.SH AUTHOR +.MT sgerwk@aol.com +Marco Migliori +.ME +.SH SEE ALSO +.BR cron (8), +.BR cron (1), +.BR crontab (5), +.BR crontab (1), +.BR anacron (8), +.BR anacrontab (5), +.BR atq (1), +.BR date (1) diff --git a/upstream/fedora-40/man1/crontab.1 b/upstream/fedora-40/man1/crontab.1 new file mode 100644 index 00000000..ef03955d --- /dev/null +++ b/upstream/fedora-40/man1/crontab.1 @@ -0,0 +1,264 @@ +.\"/* Copyright 1988,1990,1993 by Paul Vixie +.\" * All rights reserved +.\" */ +.\" +.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Modified 2010/09/12 by Colin Dean, Durham University IT Service, +.\" to add clustering support. +.\" +.\" $Id: crontab.1,v 1.7 2004/01/23 19:03:32 vixie Exp $ +.\" +.TH CRONTAB 1 "2019-10-29" "cronie" "User Commands" +.SH NAME +crontab \- maintains crontab files for individual users +.SH SYNOPSIS +.B crontab +.RB [ -u +.IR user ] +.RI < "file" +.RB | \ - > +.br +.B crontab +.RB [ -T ] +.RI < "file" +.RB | \ - > +.br +.B crontab +.RB [ -u +.IR user ] +.RB < -l " | " -r " | " -e >\ [ -i ] +.RB [ -s ] +.br +.B crontab +.BR -n \ [ +.IR "hostname " ] +.br +.B crontab +.BR -c +.br +.B crontab +.BR -V +.SH DESCRIPTION +.I Crontab +is the program used to install a crontab table +.IR file , +remove or list the existing tables used to serve the +.BR cron (8) +daemon. Each user can have their own crontab, and though these are files +in +.IR /var/spool/ , +they are not intended to be edited directly. For SELinux in MLS mode, +you can define more crontabs for each range. For more information, see +.BR selinux (8). +.PP +In this version of +.IR Cron +it is possible to use a network-mounted shared +.I /var/spool/cron +across a cluster of hosts and specify that only one of the hosts should +run the crontab jobs in the particular directory at any one time. You +may also use +.BR crontab +from any of these hosts to edit the same shared set of crontab files, and +to set and query which host should run the crontab jobs. +.PP +Scheduling cron jobs with +.BR crontab +can be allowed or disallowed for different users. For this purpose, use the +.I cron.allow +and +.I cron.deny +files. If the +.I cron.allow +file exists, a user must be listed in it to be allowed to use +.BR crontab . +If the +.I cron.allow +file does not exist but the +.I cron.deny +file does exist, then a user must +.I not +be listed in the +.I cron.deny +file in order to use +.BR crontab. +If neither of these files exist, then only the super user is allowed to use +.BR crontab . +.PP +Another way to restrict the scheduling of cron jobs beyond +.BR crontab +is to use PAM authentication in +.I /etc/security/access.conf +to set up users, which are allowed or disallowed to use +.BR crontab +or modify system cron jobs in the +.IR /etc/cron.d/ +directory. +.PP +The temporary directory can be set in an environment variable. If it is +not set by the user, the +.I /tmp +directory is used. +.PP +When listing a crontab on a terminal the output will be colorized unless +an environment variable +.I NO_COLOR +is set. +.PP +On edition or deletion of the crontab, a backup of the last crontab will be saved to +.I $XDG_CACHE_HOME/crontab/crontab.bak +or +.I $XDG_CACHE_HOME/crontab/crontab..bak +if +.B -u +is used. +If the +.I XDG_CACHE_HOME +environment variable is not set, +.I $HOME/.cache +will be used instead. +.PP +.SH "OPTIONS" +.TP +.B "\-u" +Specifies the name of the user whose crontab is to be modified. If this +option is not used, +.BR crontab +examines "your" crontab, i.e., the crontab of the person executing the +command. If no crontab exists for a particular user, it is created for +them the first time the +.B crontab -u +command is used under their username. +.TP +.B "\-T" +Test the crontab file syntax without installing it. +Once an issue is found, the validation is interrupted, so this will not return all the existing issues at the same execution. +.TP +.B "\-l" +Displays the current crontab on standard output. +.TP +.B "\-r" +Removes the current crontab. +.TP +.B "\-e" +Edits the current crontab using the editor specified by the +.I VISUAL +or +.I EDITOR +environment variables. After you exit from the editor, the modified +crontab will be installed automatically. +.TP +.B "\-i" +This option modifies the +.B "\-r" +option to prompt the user for a 'y/Y' response before actually removing +the crontab. +.TP +.B "\-s" +Appends the current SELinux security context string as an MLS_LEVEL +setting to the crontab file before editing / replacement occurs - see the +documentation of MLS_LEVEL in +.BR crontab (5). +.TP +.B "\-n" +This option is relevant only if +.BR cron (8) +was started with the +.B \-c +option, to enable clustering support. It is used to set the host in the +cluster which should run the jobs specified in the crontab files in the +.I /var/spool/cron +directory. If a hostname is supplied, the host whose hostname returned +by +.BR gethostname (2) +matches the supplied hostname, will be selected to run the selected cron jobs subsequently. If there +is no host in the cluster matching the supplied hostname, or you explicitly specify +an empty hostname, then the selected jobs will not be run at all. If the hostname +is omitted, the name of the local host returned by +.BR gethostname (2) +is used. Using this option has no effect on the +.I /etc/crontab +file and the files in the +.I /etc/cron.d +directory, which are always run, and considered host-specific. For more +information on clustering support, see +.BR cron (8). +.TP +.B "\-c" +This option is only relevant if +.BR cron (8) +was started with the +.B \-c +option, to enable clustering support. It is used to query which host in +the cluster is currently set to run the jobs specified in the crontab +files in the directory +.I /var/spool/cron +, as set using the +.B \-n +option. +.TP +.B "\-V" +Print version and exit. +.SH CAVEATS +The files +.I cron.allow +and +.I cron.deny +cannot be used to restrict the execution of cron jobs; they only restrict the +use of +.BR crontab . +In particular, restricting access to +.BR crontab +has no effect on an existing +.I crontab +of a user. Its jobs will continue to be executed until the crontab is removed. +.PP +The files +.I cron.allow +and +.I cron.deny +must be readable by the user invoking +.BR crontab . +If this is not the case, then they are treated as non-existent. +.SH "SEE ALSO" +.BR crontab (5), +.BR cron (8) +.SH FILES +.nf +/etc/cron.allow +/etc/cron.deny +.fi +.SH STANDARDS +The +.I crontab +command conforms to IEEE Std1003.2-1992 (``POSIX'') with one exception: +For replacing the current crontab with data from standard input the +.B \- +has to be specified on the command line if the standard input is a TTY. +This new command syntax differs from previous versions of Vixie Cron, +as well as from the classic SVR3 syntax. +.SH DIAGNOSTICS +An informative usage message appears if you run a crontab with a faulty +command defined in it. +.SH AUTHOR +.MT vixie@isc.org +Paul Vixie +.ME +.br +.MT colin@colin-dean.org +Colin Dean +.ME diff --git a/upstream/fedora-40/man1/csplit.1 b/upstream/fedora-40/man1/csplit.1 new file mode 100644 index 00000000..6f00320f --- /dev/null +++ b/upstream/fedora-40/man1/csplit.1 @@ -0,0 +1,77 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CSPLIT "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +csplit \- split a file into sections determined by context lines +.SH SYNOPSIS +.B csplit +[\fI\,OPTION\/\fR]... \fI\,FILE PATTERN\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Output pieces of FILE separated by PATTERN(s) to files 'xx00', 'xx01', ..., +and output byte counts of each piece to standard output. +.PP +Read standard input if FILE is \- +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-b\fR, \fB\-\-suffix\-format\fR=\fI\,FORMAT\/\fR +use sprintf FORMAT instead of %02d +.TP +\fB\-f\fR, \fB\-\-prefix\fR=\fI\,PREFIX\/\fR +use PREFIX instead of 'xx' +.TP +\fB\-k\fR, \fB\-\-keep\-files\fR +do not remove output files on errors +.TP +\fB\-\-suppress\-matched\fR +suppress the lines matching PATTERN +.TP +\fB\-n\fR, \fB\-\-digits\fR=\fI\,DIGITS\/\fR +use specified number of digits instead of 2 +.TP +\fB\-s\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR +do not print counts of output file sizes +.TP +\fB\-z\fR, \fB\-\-elide\-empty\-files\fR +suppress empty output files +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SS "Each PATTERN may be:" +.TP +INTEGER +copy up to but not including specified line number +.TP +/REGEXP/[OFFSET] +copy up to but not including a matching line +.TP +%REGEXP%[OFFSET] +skip to, but not including a matching line +.TP +{INTEGER} +repeat the previous pattern specified number of times +.TP +{*} +repeat the previous pattern as many times as possible +.PP +A line OFFSET is an integer optionally preceded by '+' or '\-' +.SH AUTHOR +Written by Stuart Kemp and David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) csplit invocation\(aq diff --git a/upstream/fedora-40/man1/csv2rec.1 b/upstream/fedora-40/man1/csv2rec.1 new file mode 100644 index 00000000..2c83f5d4 --- /dev/null +++ b/upstream/fedora-40/man1/csv2rec.1 @@ -0,0 +1,51 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.4. +.TH CSV2REC "1" "April 2022" "csv2rec 1.9" "User Commands" +.SH NAME +csv2rec \- csv to rec converter +.SH SYNOPSIS +.B csv2rec +[\fI\,OPTIONS\/\fR]... [\fI\,CSV_FILE\/\fR] +.SH DESCRIPTION +Convert csv data into rec data. +.TP +\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR +type name for the converted records; if this +parameter is omitted then no type is used. +.TP +\fB\-s\fR, \fB\-\-strict\fR +be strict parsing the csv file. +.TP +\fB\-e\fR, \fB\-\-omit\-empty\fR +omit empty fields. +.TP +\fB\-\-help\fR +print a help message and exit. +.TP +\fB\-\-version\fR +show version and exit. +.SH AUTHOR +Written by Jose E. Marchesi. +.SH "REPORTING BUGS" +Report bugs to: bug\-recutils@gnu.org +.br +GNU recutils home page: +.br +General help using GNU software: +.SH COPYRIGHT +Copyright \(co 2010\-2020 Jose E. Marchesi. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B csv2rec +is maintained as a Texinfo manual. If the +.B info +and +.B csv2rec +programs are properly installed at your site, the command +.IP +.B info recutils +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/cut.1 b/upstream/fedora-40/man1/cut.1 new file mode 100644 index 00000000..d82378ea --- /dev/null +++ b/upstream/fedora-40/man1/cut.1 @@ -0,0 +1,85 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH CUT "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +cut \- remove sections from each line of files +.SH SYNOPSIS +.B cut +\fI\,OPTION\/\fR... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print selected parts of lines from each FILE to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-b\fR, \fB\-\-bytes\fR=\fI\,LIST\/\fR +select only these bytes +.TP +\fB\-c\fR, \fB\-\-characters\fR=\fI\,LIST\/\fR +select only these characters +.TP +\fB\-d\fR, \fB\-\-delimiter\fR=\fI\,DELIM\/\fR +use DELIM instead of TAB for field delimiter +.TP +\fB\-f\fR, \fB\-\-fields\fR=\fI\,LIST\/\fR +select only these fields; also print any line +that contains no delimiter character, unless +the \fB\-s\fR option is specified +.TP +\fB\-n\fR +with \fB\-b\fR: don't split multibyte characters +.TP +\fB\-\-complement\fR +complement the set of selected bytes, characters +or fields +.TP +\fB\-s\fR, \fB\-\-only\-delimited\fR +do not print lines not containing delimiters +.TP +\fB\-\-output\-delimiter\fR=\fI\,STRING\/\fR +use STRING as the output delimiter +the default is to use the input delimiter +.TP +\fB\-z\fR, \fB\-\-zero\-terminated\fR +line delimiter is NUL, not newline +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Use one, and only one of \fB\-b\fR, \fB\-c\fR or \fB\-f\fR. Each LIST is made up of one +range, or many ranges separated by commas. Selected input is written +in the same order that it is read, and is written exactly once. +Each range is one of: +.TP +N +N'th byte, character or field, counted from 1 +.TP +N\- +from N'th byte, character or field, to end of line +.TP +N\-M +from N'th to M'th (included) byte, character or field +.TP +\fB\-M\fR +from first to M'th (included) byte, character or field +.SH AUTHOR +Written by David M. Ihnat, David MacKenzie, and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) cut invocation\(aq diff --git a/upstream/fedora-40/man1/date.1 b/upstream/fedora-40/man1/date.1 new file mode 100644 index 00000000..8081bac0 --- /dev/null +++ b/upstream/fedora-40/man1/date.1 @@ -0,0 +1,269 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DATE "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +date \- print or set the system date and time +.SH SYNOPSIS +.B date +[\fI\,OPTION\/\fR]... [\fI\,+FORMAT\/\fR] +.br +.B date +[\fI\,-u|--utc|--universal\/\fR] [\fI\,MMDDhhmm\/\fR[[\fI\,CC\/\fR]\fI\,YY\/\fR][\fI\,.ss\/\fR]] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Display date and time in the given FORMAT. +With \fB\-s\fR, or with [MMDDhhmm[[CC]YY][.ss]], set the date and time. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-d\fR, \fB\-\-date\fR=\fI\,STRING\/\fR +display time described by STRING, not 'now' +.TP +\fB\-\-debug\fR +annotate the parsed date, +and warn about questionable usage to stderr +.TP +\fB\-f\fR, \fB\-\-file\fR=\fI\,DATEFILE\/\fR +like \fB\-\-date\fR; once for each line of DATEFILE +.TP +\fB\-I[FMT]\fR, \fB\-\-iso\-8601\fR[=\fI\,FMT\/\fR] +output date/time in ISO 8601 format. +FMT='date' for date only (the default), +\&'hours', 'minutes', 'seconds', or 'ns' +for date and time to the indicated precision. +Example: 2006\-08\-14T02:34:56\-06:00 +.TP +\fB\-\-resolution\fR +output the available resolution of timestamps +Example: 0.000000001 +.TP +\fB\-R\fR, \fB\-\-rfc\-email\fR +output date and time in RFC 5322 format. +Example: Mon, 14 Aug 2006 02:34:56 \fB\-0600\fR +.TP +\fB\-\-rfc\-3339\fR=\fI\,FMT\/\fR +output date/time in RFC 3339 format. +FMT='date', 'seconds', or 'ns' +for date and time to the indicated precision. +Example: 2006\-08\-14 02:34:56\-06:00 +.TP +\fB\-r\fR, \fB\-\-reference\fR=\fI\,FILE\/\fR +display the last modification time of FILE +.TP +\fB\-s\fR, \fB\-\-set\fR=\fI\,STRING\/\fR +set time described by STRING +.TP +\fB\-u\fR, \fB\-\-utc\fR, \fB\-\-universal\fR +print or set Coordinated Universal Time (UTC) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +All options that specify the date to display are mutually exclusive. +I.e.: \fB\-\-date\fR, \fB\-\-file\fR, \fB\-\-reference\fR, \fB\-\-resolution\fR. +.PP +FORMAT controls the output. Interpreted sequences are: +.TP +%% +a literal % +.TP +%a +locale's abbreviated weekday name (e.g., Sun) +.TP +%A +locale's full weekday name (e.g., Sunday) +.TP +%b +locale's abbreviated month name (e.g., Jan) +.TP +%B +locale's full month name (e.g., January) +.TP +%c +locale's date and time (e.g., Thu Mar 3 23:05:25 2005) +.TP +%C +century; like %Y, except omit last two digits (e.g., 20) +.TP +%d +day of month (e.g., 01) +.TP +%D +date; same as %m/%d/%y +.TP +%e +day of month, space padded; same as %_d +.TP +%F +full date; like %+4Y\-%m\-%d +.TP +%g +last two digits of year of ISO week number (see %G) +.TP +%G +year of ISO week number (see %V); normally useful only with %V +.TP +%h +same as %b +.TP +%H +hour (00..23) +.TP +%I +hour (01..12) +.TP +%j +day of year (001..366) +.TP +%k +hour, space padded ( 0..23); same as %_H +.TP +%l +hour, space padded ( 1..12); same as %_I +.TP +%m +month (01..12) +.TP +%M +minute (00..59) +.TP +%n +a newline +.TP +%N +nanoseconds (000000000..999999999) +.TP +%p +locale's equivalent of either AM or PM; blank if not known +.TP +%P +like %p, but lower case +.TP +%q +quarter of year (1..4) +.TP +%r +locale's 12\-hour clock time (e.g., 11:11:04 PM) +.TP +%R +24\-hour hour and minute; same as %H:%M +.TP +%s +seconds since the Epoch (1970\-01\-01 00:00 UTC) +.TP +%S +second (00..60) +.TP +%t +a tab +.TP +%T +time; same as %H:%M:%S +.TP +%u +day of week (1..7); 1 is Monday +.TP +%U +week number of year, with Sunday as first day of week (00..53) +.TP +%V +ISO week number, with Monday as first day of week (01..53) +.TP +%w +day of week (0..6); 0 is Sunday +.TP +%W +week number of year, with Monday as first day of week (00..53) +.TP +%x +locale's date representation (e.g., 12/31/99) +.TP +%X +locale's time representation (e.g., 23:13:48) +.TP +%y +last two digits of year (00..99) +.TP +%Y +year +.TP +%z ++hhmm numeric time zone (e.g., \fB\-0400\fR) +.TP +%:z ++hh:mm numeric time zone (e.g., \fB\-04\fR:00) +.TP +%::z ++hh:mm:ss numeric time zone (e.g., \fB\-04\fR:00:00) +.TP +%:::z +numeric time zone with : to necessary precision (e.g., \fB\-04\fR, +05:30) +.TP +%Z +alphabetic time zone abbreviation (e.g., EDT) +.PP +By default, date pads numeric fields with zeroes. +The following optional flags may follow '%': +.TP +\- +(hyphen) do not pad the field +.TP +_ +(underscore) pad with spaces +.TP +0 +(zero) pad with zeros +.TP ++ +pad with zeros, and put '+' before future years with >4 digits +.TP +^ +use upper case if possible +.TP +# +use opposite case if possible +.PP +After any flags comes an optional field width, as a decimal number; +then an optional modifier, which is either +E to use the locale's alternate representations if available, or +O to use the locale's alternate numeric symbols if available. +.SH EXAMPLES +Convert seconds since the Epoch (1970\-01\-01 UTC) to a date +.IP +\f(CW$ date --date='@2147483647'\fR +.PP +Show the time on the west coast of the US (use \fBtzselect\fP(1) to find TZ) +.IP +\f(CW$ TZ='America/Los_Angeles' date\fR +.PP +Show the local time for 9AM next Friday on the west coast of the US +.IP +\f(CW$ date --date='TZ="America/Los_Angeles" 09:00 next Fri'\fR +.SH "DATE STRING" +.\" NOTE: keep this paragraph in sync with the one in touch.x +The --date=STRING is a mostly free format human readable date string +such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or +even "next Thursday". A date string may contain items indicating +calendar date, time of day, time zone, day of week, relative time, +relative date, and numbers. An empty string indicates the beginning +of the day. The date string format is more complex than is easily +documented here but is fully described in the info documentation. +.SH AUTHOR +Written by David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) date invocation\(aq diff --git a/upstream/fedora-40/man1/dc.1 b/upstream/fedora-40/man1/dc.1 new file mode 100644 index 00000000..1c666493 --- /dev/null +++ b/upstream/fedora-40/man1/dc.1 @@ -0,0 +1,520 @@ +.\" +.\" dc.1 - the *roff document processor source for the dc manual +.\" +.\" This file is part of GNU dc. +.\" Copyright (C) 1994, 1997, 1998, 2000, 2001, 2005, 2006, 2008, 2013, 2016 +.\" Free Software Foundation, Inc. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.2 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +.\" Texts. +.\" +.TH dc 1 "2008-05-22" "GNU Project" +.ds dc \fIdc\fP +.ds Dc \fIdc\fP +.SH NAME +dc \- an arbitrary precision calculator +.SH SYNOPSIS +dc [-V] [--version] [-h] [--help] + [-e scriptexpression] [--expression=scriptexpression] + [-f scriptfile] [--file=scriptfile] + [file ...] +.SH DESCRIPTION +.PP +\*(Dc is a reverse-polish desk calculator which supports +unlimited precision arithmetic. +It also allows you to define and call macros. +Normally \*(dc reads from the standard input; +if any command arguments are given to it, they are filenames, +and \*(dc reads and executes the contents of the files before reading +from standard input. +All normal output is to standard output; +all error output is to standard error. +.PP +A reverse-polish calculator stores numbers on a stack. +Entering a number pushes it on the stack. +Arithmetic operations pop arguments off the stack and push the results. +.PP +To enter a number in +.IR dc , +type the digits +(using upper case letters +.I A +through +.I F +as "digits" when working +with input bases greater than ten), +with an optional decimal point. +Exponential notation is not supported. +To enter a negative number, +begin the number with ``_''. +``-'' cannot be used for this, +as it is a binary operator for subtraction instead. +To enter two numbers in succession, +separate them with spaces or newlines. +These have no meaning as commands. +.SH OPTIONS +\*(Dc may be invoked with the following command-line options: +.TP +.B -V +.TP +.B --version +Print out the version of \*(dc that is being run and a copyright notice, +then exit. +.TP +.B -h +.TP +.B --help +Print a usage message briefly summarizing these command-line options +and the bug-reporting address, +then exit. +.TP +.B -e \fIscript\fP +.TP +.BI --expression= script +Add the commands in +.I script +to the set of commands to be run while processing the input. +.TP +.B -f \fIscript-file\fP +.TP +.BI --file= script-file +Add the commands contained in the file +.I script-file +to the set of commands to be run while processing the input. +.PP +If any command-line parameters remain after processing the above, +these parameters are interpreted as the names of input files to +be processed. +A file name of +.B - +refers to the standard input stream. +The standard input will processed if no script files or +expressions are specified. +.PD +.SH +Printing Commands +.TP +.B p +Prints the value on the top of the stack, +without altering the stack. +A newline is printed after the value. +.TP +.B n +Prints the value on the top of the stack, popping it off, +and does not print a newline after. +.TP +.B P +Pops off the value on top of the stack. +If it it a string, it is simply printed without a trailing newline. +Otherwise it is a number, and the integer portion of its absolute +value is printed out as a "base (UCHAR_MAX+1)" byte stream. +Assuming that (UCHAR_MAX+1) is 256 +(as it is on most machines with 8-bit bytes), +the sequence \fBKSK0k1/_1Ss [ls*]Sxd0>x +[256~Ssd0qaPlxx] +dsxxsx0sqLqsxLxLK+k\fP +could also accomplish this function. +(Much of the complexity of the above native-dc code is due +to the ~ computing the characters backwards, +and the desire to ensure that all registers wind up back +in their original states.) +.TP +.B f +Prints the entire contents of the stack +.ig +and the contents of all of the registers, +.. +without altering anything. +This is a good command to use if you are lost or want +to figure out what the effect of some command has been. +.PD +.SH +Arithmetic +.TP +.B + +Pops two values off the stack, adds them, +and pushes the result. +The precision of the result is determined only +by the values of the arguments, +and is enough to be exact. +.TP +.B - +Pops two values, +subtracts the first one popped from the second one popped, +and pushes the result. +.TP +.B * +Pops two values, multiplies them, and pushes the result. +The number of fraction digits in the result depends on +the current precision value and the number of fraction +digits in the two arguments. +.TP +.B / +Pops two values, +divides the second one popped from the first one popped, +and pushes the result. +The number of fraction digits is specified by the precision value. +.TP +.B % +Pops two values, +computes the remainder of the division that the +.B / +command would do, +and pushes that. +The value computed is the same as that computed by +the sequence \fBSd dld/ Ld*-\fP . +.TP +.B ~ +Pops two values, +divides the second one popped from the first one popped. +The quotient is pushed first, and the remainder is pushed next. +The number of fraction digits used in the division +is specified by the precision value. +(The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish +this function, with slightly different error checking.) +.TP +.B ^ +Pops two values and exponentiates, +using the first value popped as the exponent +and the second popped as the base. +The fraction part of the exponent is ignored. +The precision value specifies the number of fraction +digits in the result. +.TP +.B | +Pops three values and computes a modular exponentiation. +The first value popped is used as the reduction modulus; +this value must be a non-zero number, +and should be an integer. +The second popped is used as the exponent; +this value must be a non-negative number, +and any fractional part of this exponent will be ignored. +The third value popped is the base which gets exponentiated, +which should be an integer. +For small integers this is like the sequence \fBSm^Lm%\fP, +but, unlike \fB^\fP, this command will work with arbitrarily large exponents. +.TP +.B v +Pops one value, +computes its square root, +and pushes that. +The maximum of the precision value and the precision of the argument +is used to determine the number of fraction digits in the result. +.PP +Most arithmetic operations are affected by the ``precision value'', +which you can set with the +.B k +command. +The default precision value is zero, +which means that all arithmetic except for +addition and subtraction produces integer results. +.SH +Stack Control +.TP +.B c +Clears the stack, rendering it empty. +.TP +.B d +Duplicates the value on the top of the stack, +pushing another copy of it. +Thus, ``4d*p'' computes 4 squared and prints it. +.TP +.B r +Reverses the order of (swaps) the top two values on the stack. +(This can also be accomplished with the sequence \fBSaSbLaLb\fP.) +.TP +.B R +Pops the top-of-stack as an integer +.IR n . +Cyclically rotates the top +.I n +items on the updated stack. +If +.I n +is positive, then the rotation direction will make the topmost +element the second-from top; +if +.I n +is negative, then the rotation will make the topmost element the +.IR n -th +element from the top. +If the stack depth is less than +.IR n , +then the entire stack is rotated (in the appropriate direction), +without any error being reported. +.SH +Registers +.PP +\*(Dc provides at least 256 memory registers, +each named by a single character. +You can store a number or a string in a register and retrieve it later. +.TP +.BI s r +Pop the value off the top of the stack and store +it into register +.IR r . +.TP +.BI l r +Copy the value in register +.I r +and push it onto the stack. +The value 0 is retrieved if the register is uninitialized. +This does not alter the contents of +.IR r . +.PP +Each register also contains its own stack. +The current register value is the top of the register's stack. +.TP +.BI S r +Pop the value off the top of the (main) stack and +push it onto the stack of register +.IR r . +The previous value of the register becomes inaccessible. +.TP +.BI L r +Pop the value off the top of register +.IR r 's +stack and push it onto the main stack. +The previous value +in register +.IR r 's +stack, if any, +is now accessible via the +.BI l r +command. +.ig +.PP +The +.B f +command prints a list of all registers that have contents stored in them, +together with their contents. +Only the current contents of each register +(the top of its stack) +is printed. +.. +.SH +Parameters +.PP +\*(Dc has three parameters that control its operation: +the precision, the input radix, and the output radix. +The precision specifies the number +of fraction digits to keep in the result of most arithmetic operations. +The input radix controls the interpretation of numbers typed in; +all numbers typed in use this radix. +The output radix is used for printing numbers. +.PP +The input and output radices are separate parameters; +you can make them unequal, +which can be useful or confusing. +The input radix must be between 2 and 16 inclusive. +The output radix must be at least 2. +The precision must be zero or greater. +The precision is always measured in decimal digits, +regardless of the current input or output radix. +.TP +.B i +Pops the value off the top of the stack +and uses it to set the input radix. +.TP +.B o +Pops the value off the top of the stack +and uses it to set the output radix. +.TP +.B k +Pops the value off the top of the stack +and uses it to set the precision. +.TP +.B I +Pushes the current input radix on the stack. +.TP +.B O +Pushes the current output radix on the stack. +.TP +.B K +Pushes the current precision on the stack. +.SH +Strings +.PP +\*(Dc has a limited ability to operate on strings +as well as on numbers; +the only things you can do with strings are +print them and execute them as macros +(which means that the contents of the string are processed as +\*(dc commands). +All registers and the stack can hold strings, +and \*(dc always knows whether any given object is a string or a number. +Some commands such as arithmetic operations demand numbers +as arguments and print errors if given strings. +Other commands can accept either a number or a string; +for example, the +.B p +command can accept either and prints the object +according to its type. +.TP +.BI [ characters ] +Makes a string containing +.I characters +(contained between balanced +.B [ +and +.B ] +characters), +and pushes it on the stack. +For example, +.B [foo]P +prints the characters +.B foo +(with no newline). +.TP +.B a +The top-of-stack is popped. +If it was a number, then the low-order byte of this number +is converted into a string and pushed onto the stack. +Otherwise the top-of-stack was a string, +and the first character of that string is pushed back. +.TP +.B x +Pops a value off the stack and executes it as a macro. +Normally it should be a string; +if it is a number, +it is simply pushed back onto the stack. +For example, +.B [1p]x +executes the macro +.B 1p +which pushes +.B 1 +on the stack and prints +.B 1 +on a separate line. +.PP +Macros are most often stored in registers; +.B [1p]sa +stores a macro to print +.B 1 +into register +.BR a , +and +.B lax +invokes this macro. +.TP +.BI > r +Pops two values off the stack and compares them +assuming they are numbers, +executing the contents of register +.I r +as a macro if the original top-of-stack +is greater. +Thus, +.B 1 2>a +will invoke register +.BR a 's +contents and +.B 2 1>a +will not. +.TP +.BI !> r +Similar but invokes the macro if the original top-of-stack is +not greater than (less than or equal to) what was the second-to-top. +.TP +.BI < r +Similar but invokes the macro if the original top-of-stack is less. +.TP +.BI !< r +Similar but invokes the macro if the original top-of-stack is +not less than (greater than or equal to) what was the second-to-top. +.TP +.BI = r +Similar but invokes the macro if the two numbers popped are equal. +.TP +.BI != r +Similar but invokes the macro if the two numbers popped are not equal. +.ig +This can also be validly used to compare two strings for equality. +.. +.TP +.B ? +Reads a line from the terminal and executes it. +This command allows a macro to request input from the user. +.TP +.B q +exits from a macro and also from the macro which invoked it. +If called from the top level, +or from a macro which was called directly from the top level, +the +.B q +command will cause \*(dc to exit. +.TP +.B Q +Pops a value off the stack and uses it as a count +of levels of macro execution to be exited. +Thus, +.B 3Q +exits three levels. +The +.B Q +command will never cause \*(dc to exit. +.SH +Status Inquiry +.TP +.B Z +Pops a value off the stack, +calculates the number of decimal digits it has +(or number of characters, if it is a string) +and pushes that number. +The digit count for a number does +.I not +include any leading zeros, +even if those appear to the right of the radix point. +.TP +.B X +Pops a value off the stack, +calculates the number of fraction digits it has, +and pushes that number. +For a string, +the value pushed is +.\" -1. +0. +.TP +.B z +Pushes the current stack depth: +the number of objects on the stack before the execution of the +.B z +command. +.SH +Miscellaneous +.TP +.B ! +Will run the rest of the line as a system command. +Note that parsing of the !<, !=, and !> commands take precedence, +so if you want to run a command starting with <, =, or > you will +need to add a space after the !. +.TP +.B # +Will interpret the rest of the line as a comment. +.TP +.BI : r +Will pop the top two values off of the stack. +The old second-to-top value will be stored in the array +.IR r , +indexed by the old top-of-stack value. +.TP +.BI ; r +Pops the top-of-stack and uses it as an index into +the array +.IR r . +The selected value is then pushed onto the stack. +.P +Note that each stacked instance of a register has its own +array associated with it. +Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1, +because the 2 was stored in an instance of 0:a that +was later popped. +.SH +BUGS +.PP +Email bug reports to +.BR bug-dc@gnu.org . diff --git a/upstream/fedora-40/man1/dd.1 b/upstream/fedora-40/man1/dd.1 new file mode 100644 index 00000000..295b2eaf --- /dev/null +++ b/upstream/fedora-40/man1/dd.1 @@ -0,0 +1,176 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DD "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.B dd +[\fI\,OPERAND\/\fR]... +.br +.B dd +\fI\,OPTION\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Copy a file, converting and formatting according to the operands. +.TP +bs=BYTES +read and write up to BYTES bytes at a time (default: 512); +overrides ibs and obs +.TP +cbs=BYTES +convert BYTES bytes at a time +.TP +conv=CONVS +convert the file as per the comma separated symbol list +.TP +count=N +copy only N input blocks +.TP +ibs=BYTES +read up to BYTES bytes at a time (default: 512) +.TP +if=FILE +read from FILE instead of stdin +.TP +iflag=FLAGS +read as per the comma separated symbol list +.TP +obs=BYTES +write BYTES bytes at a time (default: 512) +.TP +of=FILE +write to FILE instead of stdout +.TP +oflag=FLAGS +write as per the comma separated symbol list +.TP +seek=N +(or oseek=N) skip N obs\-sized output blocks +.TP +skip=N +(or iseek=N) skip N ibs\-sized input blocks +.TP +status=LEVEL +The LEVEL of information to print to stderr; +\&'none' suppresses everything but error messages, +\&'noxfer' suppresses the final transfer statistics, +\&'progress' shows periodic transfer statistics +.PP +N and BYTES may be followed by the following multiplicative suffixes: +c=1, w=2, b=512, kB=1000, K=1024, MB=1000*1000, M=1024*1024, xM=M, +GB=1000*1000*1000, G=1024*1024*1024, and so on for T, P, E, Z, Y, R, Q. +Binary prefixes can be used, too: KiB=K, MiB=M, and so on. +If N ends in 'B', it counts bytes not blocks. +.PP +Each CONV symbol may be: +.TP +ascii +from EBCDIC to ASCII +.TP +ebcdic +from ASCII to EBCDIC +.TP +ibm +from ASCII to alternate EBCDIC +.TP +block +pad newline\-terminated records with spaces to cbs\-size +.TP +unblock +replace trailing spaces in cbs\-size records with newline +.TP +lcase +change upper case to lower case +.TP +ucase +change lower case to upper case +.TP +sparse +try to seek rather than write all\-NUL output blocks +.TP +swab +swap every pair of input bytes +.TP +sync +pad every input block with NULs to ibs\-size; when used +with block or unblock, pad with spaces rather than NULs +.TP +excl +fail if the output file already exists +.TP +nocreat +do not create the output file +.TP +notrunc +do not truncate the output file +.TP +noerror +continue after read errors +.TP +fdatasync +physically write output file data before finishing +.TP +fsync +likewise, but also write metadata +.PP +Each FLAG symbol may be: +.TP +append +append mode (makes sense only for output; conv=notrunc suggested) +.TP +direct +use direct I/O for data +.TP +directory +fail unless a directory +.TP +dsync +use synchronized I/O for data +.TP +sync +likewise, but also for metadata +.TP +fullblock +accumulate full blocks of input (iflag only) +.TP +nonblock +use non\-blocking I/O +.TP +noatime +do not update access time +.TP +nocache +Request to drop cache. See also oflag=sync +.TP +noctty +do not assign controlling terminal from file +.TP +nofollow +do not follow symlinks +.PP +Sending a USR1 signal to a running 'dd' process makes it +print I/O statistics to standard error and then resume copying. +.PP +Options are: +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by Paul Rubin, David MacKenzie, and Stuart Kemp. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) dd invocation\(aq diff --git a/upstream/fedora-40/man1/ddate.1 b/upstream/fedora-40/man1/ddate.1 new file mode 100644 index 00000000..3dd1c401 --- /dev/null +++ b/upstream/fedora-40/man1/ddate.1 @@ -0,0 +1,115 @@ +.\" All Rites Reversed. This file is in the PUBLIC DOMAIN. +.\" Kallisti. +.TH DDATE 1 "Bureaucracy 3161" "ddate" "Emperor Norton User Command" +.SH NAME +ddate \- convert Gregorian dates to Discordian dates +.SH SYNOPSIS +.B ddate +.RI [ \fB+\fPformat] +.RI [ date ] +.SH DESCRIPTION +.B ddate +prints the date in Discordian date format. +.PP +If called with no arguments, +.B ddate +will get the current system date, convert this to the Discordian +date format and print this on the standard output. Alternatively, a +Gregorian date may be specified on the command line, in the form of a numerical +day, month and year. +.PP +If a format string is specified, the Discordian date will be printed in +a format specified by the string. This mechanism works similarly to the +format string mechanism of +.B date(1), +only almost completely differently. The fields are: +.IP %A +Full name of the day of the week (i.e., Sweetmorn) +.IP %a +Abbreviated name of the day of the week (i.e., SM) +.IP %B +Full name of the season (i.e., Chaos) +.IP %b +Abbreviated name of the season (i.e., Chs) +.IP %d +Ordinal number of day in season (i.e., 23) +.IP %e +Cardinal number of day in season (i.e., 23rd) +.IP %H +Name of current Holyday, if any +.IP %N +Magic code to prevent rest of format from being printed unless today is +a Holyday. +.IP %n +Newline +.IP %t +Tab +.IP %X +Number of days remaining until X-Day. (Not valid if the SubGenius options +are not compiled in.) +.IP %{ +.IP %} +Used to enclose the part of the string which is to be replaced with the +words "St. Tib's Day" if the current day is St. Tib's Day. +.IP %\. +Try it and see. +.bp +.SH EXAMPLES +.nf +% ddate +.br +Sweetmorn, Bureaucracy 42, 3161 YOLD +.PP +% ddate +'Today is %{%A, the %e of %B%}, %Y. %N%nCelebrate %H' +.br +Today is Sweetmorn, the 42nd of Bureaucracy, 3161. +.PP +% ddate +"It's %{%A, the %e of %B%}, %Y. %N%nCelebrate %H" 26 9 1995 +.br +It's Prickle-Prickle, the 50th of Bureaucracy, 3161. +.br +Celebrate Bureflux +.PP +% ddate +"Today's %{%A, the %e of %B%}, %Y. %N%nCelebrate %H" 29 2 1996 +.br +Today's St. Tib's Day, 3162. +.br + +.SH BUGS + +.B ddate(1) +will produce undefined behavior if asked to produce the date for St. Tib's +day and its format string does not contain the St. Tib's Day delimiters +%{ and %}. + +.SH NOTE + +After `X-Day' passed without incident, the Church of the SubGenius +declared that it had got the year upside down - X-Day is actually in 8661 AD +rather than 1998 AD. Thus, the True X-Day is Cfn 40, 9827. + +.SH AUTHOR +.nh +Original program by Druel the Chaotic aka Jeremy Johnson (mpython@gnu.ai.mit.edu) +.br +Major rewrite by Lee H:. O:. Smith, KYTP, aka Andrew Bulhak (acb@dev.null.org) +.br +Gregorian B.C.E. dates fixed by Chaplain Nyan the Wiser, aka Dan Dart (ntw@dandart.co.uk) +.br +Five tons of flax. + +.SH DISTRIBUTION POLICY + +Public domain. All rites reversed. + +.SH SEE ALSO + +date(1), +.br +http://www.subgenius.com/ +.br +Malaclypse the Younger, +.I "Principia Discordia, Or How I Found Goddess And What I Did To Her When I Found Her" + +.SH AVAILABILITY +The ddate command is available from https://github.com/bo0ts/ddate. diff --git a/upstream/fedora-40/man1/ddbugtopbm.1 b/upstream/fedora-40/man1/ddbugtopbm.1 new file mode 100644 index 00000000..5bf76bb7 --- /dev/null +++ b/upstream/fedora-40/man1/ddbugtopbm.1 @@ -0,0 +1,117 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Ddbugtopbm User Manual" 0 "21 August 2002" "netpbm documentation" + +.SH NAME +ddbugtopbm - convert Diddle or DiddleBug sketches to PBM files + +.UN synopsis +.SH SYNOPSIS + +\fBddbugtopbm\fP + +.UN examples +.SH EXAMPLES + +.nf +\fBddbugtopbm ...\fP +.SH ARGUMENTS +.INDENT 0.0 +.TP +.B \fB\fP +The package to install the associated debuginfo package for. +.UNINDENT +.SH OPTIONS +.sp +All general DNF options are accepted, see \fIOptions\fP in \fBdnf(8)\fP for details. +.SH CONFIGURATION +.sp +\fB/etc/dnf/plugins/debuginfo\-install.conf\fP +.sp +The minimal content of conf file should contain \fBmain\fP sections with \fBenabled\fP and +\fBautoupdate\fP parameter. +.INDENT 0.0 +.TP +.B \fBautoupdate\fP +A boolean option which controls updates of debuginfo packages. If options is enabled +and there are debuginfo packages installed it automatically enables all configured +debuginfo repositories. +(Disabled by default.) +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.TP +.B \fBdnf debuginfo\-install foobar\fP +Install the debuginfo packages for the foobar package. +.TP +.B \fBdnf upgrade \-\-enablerepo=*\-debuginfo \-debuginfo\fP +Upgrade debuginfo package of a . +.TP +.B \fBdnf upgrade \-\-enablerepo=*\-debuginfo \(dq*\-debuginfo\(dq\fP +Upgrade all debuginfo packages. +.UNINDENT +.SH AUTHOR +See AUTHORS in your Core DNF Plugins distribution +.SH COPYRIGHT +2024, Red Hat, Licensed under GPLv2+ +.\" Generated by docutils manpage writer. +. diff --git a/upstream/fedora-40/man1/df.1 b/upstream/fedora-40/man1/df.1 new file mode 100644 index 00000000..693e3073 --- /dev/null +++ b/upstream/fedora-40/man1/df.1 @@ -0,0 +1,123 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DF "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +df \- report file system space usage +.SH SYNOPSIS +.B df +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR df . +.B df +displays the amount of space available on the file system +containing each file name argument. If no file name is given, the +space available on all currently mounted file systems is shown. +Space is shown in 1K blocks by default, unless the environment +variable POSIXLY_CORRECT is set, in which case 512-byte blocks are +used. +.PP +If an argument is the absolute file name of a device node containing a +mounted file system, +.B df +shows the space available on that file system rather than on the +file system containing the device node. This version of +.B df +cannot show the space available on unmounted file systems, because on +most kinds of systems doing so requires non-portable intimate +knowledge of file system structures. +.SH OPTIONS +.PP +Show information about the file system on which each FILE resides, +or all file systems by default. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-a\fR, \fB\-\-all\fR +include pseudo, duplicate, inaccessible file systems +.TP +\fB\-B\fR, \fB\-\-block\-size\fR=\fI\,SIZE\/\fR +scale sizes by SIZE before printing them; e.g., +\&'\-BM' prints sizes in units of 1,048,576 bytes; +see SIZE format below +.TP +\fB\-\-direct\fR +show statistics for a file instead of mount point +.TP +\fB\-h\fR, \fB\-\-human\-readable\fR +print sizes in powers of 1024 (e.g., 1023M) +.TP +\fB\-H\fR, \fB\-\-si\fR +print sizes in powers of 1000 (e.g., 1.1G) +.TP +\fB\-i\fR, \fB\-\-inodes\fR +list inode information instead of block usage +.TP +\fB\-k\fR +like \fB\-\-block\-size\fR=\fI\,1K\/\fR +.TP +\fB\-l\fR, \fB\-\-local\fR +limit listing to local file systems +.TP +\fB\-\-no\-sync\fR +do not invoke sync before getting usage info (default) +.TP +\fB\-\-output\fR[=\fI\,FIELD_LIST\/\fR] +use the output format defined by FIELD_LIST, +or print all fields if FIELD_LIST is omitted. +.TP +\fB\-P\fR, \fB\-\-portability\fR +use the POSIX output format +.TP +\fB\-\-sync\fR +invoke sync before getting usage info +.TP +\fB\-\-total\fR +elide all entries insignificant to available space, +and produce a grand total +.TP +\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR +limit listing to file systems of type TYPE +.TP +\fB\-T\fR, \fB\-\-print\-type\fR +print file system type +.TP +\fB\-x\fR, \fB\-\-exclude\-type\fR=\fI\,TYPE\/\fR +limit listing to file systems not of type TYPE +.TP +\fB\-v\fR +(ignored) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Display values are in units of the first available SIZE from \fB\-\-block\-size\fR, +and the DF_BLOCK_SIZE, BLOCK_SIZE and BLOCKSIZE environment variables. +Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set). +.PP +The SIZE argument is an integer and optional unit (example: 10K is 10*1024). +Units are K,M,G,T,P,E,Z,Y,R,Q (powers of 1024) or KB,MB,... (powers of 1000). +Binary prefixes can be used, too: KiB=K, MiB=M, and so on. +.PP +FIELD_LIST is a comma\-separated list of columns to be included. Valid +field names are: 'source', 'fstype', 'itotal', 'iused', 'iavail', 'ipcent', +\&'size', 'used', 'avail', 'pcent', 'file' and 'target' (see info page). +.SH AUTHOR +Written by Torbjorn Granlund, David MacKenzie, and Paul Eggert. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) df invocation\(aq diff --git a/upstream/fedora-40/man1/dialog.1 b/upstream/fedora-40/man1/dialog.1 new file mode 100644 index 00000000..62aea4ac --- /dev/null +++ b/upstream/fedora-40/man1/dialog.1 @@ -0,0 +1,2083 @@ +'\" t +.\" $Id: dialog.1,v 1.236 2024/01/01 11:24:25 tom Exp $ +.\" Copyright 2005-2023,2024 Thomas E. Dickey +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU Lesser General Public License, version 2.1 +.\" as published by the Free Software Foundation. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" Lesser General Public License for more details. +.\" +.\" You should have received a copy of the GNU Lesser General Public +.\" License along with this program; if not, write to +.\" Free Software Foundation, Inc. +.\" 51 Franklin St., Fifth Floor +.\" Boston, MA 02110, USA. +.\" +.\" definitions for renaming +.ds p dialog +.ds l dialog +.ds L Dialog +.ds D DIALOG +.\" +.ie n .ds CW R +.el \{ +.ie \n(.g .ds CW CR +.el .ds CW CW +.\} +. +.de ES +.ne 8 +.IP +.. +.de Ex +.RS +7 +.PP +.nf +.ft \*(CW +.. +.de Ee +.fi +.ft R +.RE +.. +.\" Bulleted paragraph +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ie t .ds ' \(aq +.el .ds ' ' +.\}", +. +.TH \*D "" 2024-01-01 "" "User commands" +.SH NAME +dialog \- +display dialog boxes from shell scripts +.SH SYNOPSIS +\fB\*p \-\-clear\fP +.br +.BI "\*p \-\-create\-rc " file +.br +\fB\*p \-\-print\-maxsize\fP +.br +\fB\*p\fP +\fIcommon-options\fP +\fIbox-options\fP +.SH DESCRIPTION +\fB\*L\fP +is a program that will let you present a variety of questions or +display messages using dialog boxes from a shell script. +These types of dialog boxes are implemented +(though not all are necessarily compiled into \fB\*p\fR): +.RS +.LP +.nh +.na +.BR buildlist ", " +.BR calendar ", " +.BR checklist ", " +.BR dselect ", " +.BR editbox ", " +.BR form ", " +.BR fselect ", " +.BR gauge ", " +.BR infobox ", " +.BR inputbox ", " +.BR inputmenu ", " +.BR menu ", " +.BR mixedform ", " +.BR mixedgauge ", " +.BR msgbox " (message), " +.BR passwordbox ", " +.BR passwordform ", " +.BR pause ", " +.BR prgbox ", " +.BR programbox ", " +.BR progressbox ", " +.BR radiolist ", " +.BR rangebox ", " +.BR tailbox ", " +.BR tailboxbg ", " +.BR textbox ", " +.BR timebox ", " +.BR treeview ", and " +.BR yesno " (yes/no)." +.ad +.RE +.PP +You can put more than one dialog box into a script: +.bP +Use the "\fB\-\-and\-widget\fP" token to force \fB\*p\fP to proceed to the next +dialog unless you have pressed ESC to cancel, or +.bP +Simply add the tokens for the next dialog box, making a chain. +\*L stops chaining when the return code from a dialog is nonzero, +e.g., Cancel or No (see DIAGNOSTICS). +.PP +Some widgets, e.g., checklist, will write text to \fB\*p\fP's output. +Normally that is the standard error, but there are options for +changing this: +\*(``\fB\-\-output\-fd\fP\*('', +\*(``\fB\-\-stderr\fP\*('' and +\*(``\fB\-\-stdout\fP\*(''. +No text is written if the Cancel button (or ESC) is pressed; +\fB\*p\fP exits immediately in that case. +. +.\" ************************************************************************ +.SH OPTIONS +All options begin with \*(``\fB\-\-\fP\*('' +(two ASCII hyphens, +for the benefit of those using systems with deranged locale support). +.PP +A \*(``\fB\-\-\fP\*('' by itself is used as an escape, +i.e., the next token on the command-line is not treated as an option. +This is different from \fBgetopt\fP(1), +which uses that token to treat the remaining tokens as \fIparameters\fP +rather than \fIoptions\fP. +.RS +.PP +.B \*p \-\-title \-\- \-\-Not an option +.br +.B \*p \-\-title This \-\- \-\-title is not an option +.RE +.PP +\fB\*L\fP +uses no \fIparameters\fP, +and uses its own \fIoptions\fP parser. +.PP +When a common (e.g., non-widget) option is repeated, +the last found is the one that is used. +Boolean options are handled specially so they can be cancelled, +by adding (or omitting) a \*(``no\*('' modifier +after the leading \*(``\fB\-\-\fP\*(''. +For instance, \fB\-\-no\-shadow\fP is documented here, +but \fB\-\-shadow\fP also is accepted. +.PP +The \*(``\fB\-\-args\fP\*('' option tells \fB\*p\fP to list the command-line +parameters to the standard error. +This is useful when debugging complex scripts using +the \*(``\fB\-\-\fP\*('' and \*(``\fB\-\-file\fP\*('', +since the command-line may be rewritten as these are expanded. +.PP +The \*(``\fB\-\-file\fP\*('' option tells \fB\*p\fP to read parameters from +the file named as its value. +.RS +.B \*p \-\-file \fIparameterfile +.RE +.PP +Blanks not within double-quotes are discarded +(use backslashes to quote single characters). +The result is inserted into the command-line, +replacing \*(``\fB\-\-file\fP\*('' and its option value. +Interpretation of the command-line resumes from that point. +If \fIparameterfile\fP begins with \*(``&\*('', \fB\*p\fP +interprets the following text as a file descriptor number +rather than a filename. +.PP +Most widgets accept \fIheight\fP and \fIwidth\fP parameters, +which can be used to automatically size the widget to accommodate +multi-line message \fIprompt\fP values: +.bP +If the parameter is negative, +\fB\*l\fP uses the screen's size. +.bP +If the parameter is zero, +\fB\*l\fP uses minimum size for the widget to display the \fIprompt\fP +and data. +.bP +Otherwise, \fB\*l\fP uses the given size for the widget. +. +.SS \fBCommon Options\fP +Most of the common options are reset before processing each widget. +. +.IP "\fB\-\-ascii\-lines" +Rather than draw graphics lines around boxes, +draw ASCII \*(``+\*('' and \*(``-\*('' in the same place. +See also \*(``\fB\-\-no\-lines\fR\*(''. +. +.IP "\fB\-\-aspect \fIratio" +This gives you some control over the box dimensions when using auto +sizing (specifying 0 for height and width). +It represents width / height. +The default is 9, which means 9 characters wide to every 1 line high. +. +.IP "\fB\-\-backtitle \fIbacktitle" +Specifies a +\fIbacktitle\fP +string to be displayed on the backdrop, at the top of the screen. +. +.IP "\fB\-\-begin \fIy x" +Specify the position of the upper left corner of a dialog box on the screen. +. +.IP "\fB\-\-cancel\-label \fIstring" +Override the label used for \*(``Cancel\*('' buttons. +. +.IP "\fB\-\-clear" +Clears the widget screen, keeping only the screen_color background. +Use this when you combine widgets +with \*(``\fB\-\-and\-widget\fR\*('' to erase the +contents of a previous widget on the screen, so it won't be seen +under the contents of a following widget. +Understand this as the complement of \*(``\fB\-\-keep\-window\fR\*(''. +To compare the effects, use these: +. +.ES +All three widgets visible, staircase effect, ordered 1,2,3: +.Ex +\*p \e + \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +Only the last widget is left visible: +.Ex +\*p \e + \-\-clear \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +All three widgets visible, staircase effect, ordered 3,2,1: +.Ex +\*p \e + \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-keep\-window \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +First and third widget visible, staircase effect, ordered 3,1: +.Ex +\*p \e + \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +.IP +Note, if you want to restore original console colors and send your +cursor home after the dialog program has exited, use the \fBclear\fR(1) +command. +Conversely, if you want to clear the screen and send your cursor to +the lower left after the \fB\*p\fP program has exited, use the +\fB\-\-erase\-on\-exit\fR\ option. +. +.IP "\fB\-\-colors" +Interpret embedded \*(``\eZ\*('' sequences in the dialog text +by the following character, +which tells \fB\*p\fP to set colors or video attributes: +.RS +.bP +0 through 7 are the ANSI color numbers used in curses: +black, +red, +green, +yellow, +blue, +magenta, +cyan and +white respectively. +.bP +Bold is set by 'b', reset by 'B'. +.bP +Reverse is set by 'r', reset by 'R'. +.bP +Underline is set by 'u', reset by 'U'. +.bP +The settings are cumulative, e.g., \*(``\eZb\eZ1\*('' makes the following text +bold (perhaps bright) red. +.bP +Restore normal settings with \*(``\eZn\*(''. +.RE +. +.IP "\fB\-\-column\-separator \fIstring" +Tell \fB\*p\fP to split data for radio/checkboxes and menus on the +occurrences of the given string, and to align the split data into columns. +. +.IP "\fB\-\-cr\-wrap" +Interpret embedded newlines in the dialog text as a newline on the screen. +Otherwise, \fB\*p\fR will only wrap lines +where needed to fit inside the text box. +.IP +Even though you can control line breaks with this, +\fB\*L\fR will still wrap any lines that are too long for the width of the box. +Without cr-wrap, the layout of your text may be formatted to look nice +in the source code of your script without affecting the way it will +look in the dialog. +.IP +The \fIcr\-wrap\fP feature is implemented subject to these conditions: +.RS +.bP +the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is +not used, or +.bP +the \fB\-\-trim\fP option is used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-create\-rc \fIfile" +When +\fB\*p\fP +supports run-time configuration, +this can be used to dump a sample configuration file to the file specified +by +.IR file "." +. +.IP "\fB\-\-cursor\-off\-label" +Place the terminal cursor at the end of a button instead of on the +first character of the button label. +This is useful to reduce visual confusion when the cursor coloration +interacts poorly with the button-label text colors. +. +.IP "\fB\-\-date\-format \fIformat" +If the host provides \fBstrftime\fP, +this option allows you to specify the format of the date printed for +the \fB\-\-calendar\fP widget. +The time of day (hour, minute, second) are the current local time. +. +.IP "\fB\-\-defaultno" +Make the default value of the +\fByes/no\fP +box a +.BR No . +Likewise, treat the default button of widgets that provide +\*(``OK\*('' and \*(``Cancel\*('' +as a \fICancel\fP. +If \*(``\fB\-\-no\-cancel\fP\*('' or \*(``\fB\-\-visit\-items\fP\*('' are given +those options overrides this, +making the default button always \*(``Yes\*('' +(internally the same as \*(``OK\*(''). +. +.IP "\fB\-\-default\-button \fIstring" +Set the default (preselected) button in a widget. +By preselecting a button, +a script makes it possible for the user to simply press \fIEnter\fP +to proceed through a dialog with minimum interaction. +.IP +The option's value is the name of the button: +.IR ok , +.IR yes , +.IR cancel , +.IR no , +.IR help "\ or" +.IR extra . +.IP +Normally the first button in each widget is the default. +The first button shown is determined by the widget +together with the \*(``\fB\-\-no\-ok\fP\*('' +and \*(``\fB\-\-no\-cancel\fP\*('' options. +If this option is not given, there is no default button assigned. +. +.IP "\fB\-\-default\-item \fIstring" +Set the default item in a checklist, form or menu box. +Normally the first item in the box is the default. +. +.IP "\fB\-\-erase\-on\-exit" +When \fB\*p\fP exits, remove the dialog widget, erasing the entire +screen to its native background color, and place the terminal cursor +at the lower left corner. +. +.IP "\fB\-\-exit\-label \fIstring" +Override the label used for \*(``EXIT\*('' buttons. +. +.IP "\fB\-\-extra\-button" +Show an extra button, between \*(``OK\*('' and \*(``Cancel\*('' buttons. +.IP +The extra button appears between \*(``Yes\*('' and \*(``No\*('' +for the \fIyesno\fP widget. +. +.IP "\fB\-\-extra\-label \fIstring" +Override the label used for \*(``Extra\*('' buttons. +Note: for inputmenu widgets, this defaults to \*(``Rename\*(''. +. +.IP "\fB\-\-help" +Prints the help message to the standard output and exits. +The help message is also printed if no options are given, +or if an unrecognized option is given. +. +.IP "\fB\-\-help\-button" +Show a help-button after \*(``OK\*('' and \*(``Cancel\*('' buttons +in boxes which have a list of tagged items +(i.e., checklist, radiolist, menu, and treeview boxes). +.IP +The help-button appears after \*(``Yes\*('' and \*(``No\*('' +for the \fIyesno\fP widget. +.IP +On exit, the return status indicates that the Help button was pressed. +\fB\*L\fP also writes a message to its output +after the token \*(``HELP\*('': +.RS +.bP +If "\fB\-\-item\-help\fR" is also given, the item-help text is written. +.bP +Otherwise, the item's tag (the first field) is written. +.RE +.IP +You can use the \fB\-\-help\-tags\fP option and/or set the DIALOG_ITEM_HELP +environment variable to modify these messages and exit-status. +.IP +This option can be applied to other widgets, +which have an \*(``OK\*('' button, +whether or not the \*(``Cancel\*('' button is used. +The return status and output are not treated specially for the other widgets; +the help-button is just an extra button. +. +.IP "\fB\-\-help\-label \fIstring" +Override the label used for \*(``Help\*('' buttons. +. +.IP "\fB\-\-help\-status" +If the help-button is selected, +writes the checklist, radiolist or form information +after the item-help \*(``HELP\*('' information. +This can be used to reconstruct the state of a checklist after processing +the help request. +. +.IP "\fB\-\-help\-tags" +Modify the messages written on exit for \fB\-\-help\-button\fP +by making them always just the item's tag. +This does not affect the exit status code. +. +.IP "\fB\-\-hfile \fIfilename" +Display the given file using a textbox when the user presses F1. +. +.IP "\fB\-\-hline \fIstring" +Display the given string centered at the bottom of the widget. +. +.IP "\fB\-\-ignore" +Ignore options that \fB\*p\fP does not recognize. +Some well-known ones such as \*(``\fB\-\-icon\fP\*('' are ignored anyway, +but this is a better choice for compatibility with other implementations. +. +.IP "\fB\-\-input\-fd \fIfd" +Read keyboard input from the given file descriptor. +Most \fB\*p\fR scripts read from the standard input, +but the gauge widget reads a pipe (which is always standard input). +Some configurations do not work properly when +\fB\*p\fP tries to reopen the terminal. +Use this option (with appropriate juggling of file-descriptors) +if your script must work in that type of environment. +. +.IP "\fB\-\-insecure" +Makes the password widget friendlier but less secure, +by echoing asterisks for each character. +. +.IP "\fB\-\-iso\-week" +Set the starting point for the week-number +shown in the \*(``\fB\-\-calendar\fP\*('' option +according to ISO-8601, which starts numbering +with the first week which includes a Thursday in January. +. +.IP "\fB\-\-item\-help" +Interpret the tags data for checklist, radiolist and menu boxes +adding a column which is displayed in the bottom line of the +screen, for the currently selected item. +. +.IP "\fB\-\-keep\-tite" +When built with \fBncurses\fP, +\fB\*p\fP normally checks to see if it is running in an \fBxterm\fP, +and in that case tries to suppress the initialization strings that +would make it switch to the alternate screen. +Switching between the normal and alternate screens +is visually distracting in a script which runs \fB\*p\fP +several times. +Use this option to allow \fB\*p\fP to use those initialization strings. +. +.IP "\fB\-\-keep\-window" +Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets +connected by \*(``\fB\-\-and\-widget\fR\*('', +it clears the old widget from the screen by painting over it. +Use this option to suppress that repainting. +.IP +At exit, \fB\*p\fR repaints all of the widgets which have been +marked with \*(``\fB\-\-keep\-window\fR\*('', +even if they are not \fBtailboxbg\fR widgets. +That causes them to be repainted in reverse order. +See the discussion of the \*(``\fB\-\-clear\fR\*('' option for examples. +. +.IP "\fB\-\-last\-key" +At exit, report the last key which the user entered. +This is the curses key code rather than a symbol or literal character, +and is only reported for keys which are bound to an action. +It can be used by scripts to distinguish between two keys which are +bound to the same action. +. +.IP "\fB\-\-max\-input \fIsize" +Limit input strings to the given size. +If not specified, the limit is 2048. +. +.IP "\fB\-\-no\-cancel" +Suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes. +A script can still test if the user pressed the ESC key to cancel to quit. +. +.IP "\fB\-\-no\-collapse" +Normally \fB\*p\fR converts tabs to spaces and reduces multiple +spaces to a single space for text which is displayed in a message boxes, etc. +Use this option to disable that feature. +Note that \fB\*p\fR will still wrap text, +subject to the \*(``\fB\-\-cr\-wrap\fR\*('' +and \*(``\fB\-\-trim\fR\*('' options. +.IP +The \fIno\-collapse\fP feature is implemented subject to these conditions: +.RS +.bP +the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is +not used, or +.bP +the \fB\-\-trim\fP option is not used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-no\-hot\-list" +Tells +\fB\*p\fP +to suppress the hotkey feature for lists, e.g., the checkbox, menus. +.IP +Normally, the first uppercase character of a list entry will be highlighted, +and typing that character will move the focus to that entry. +This option suppresses both the highlighting and the movement. +.IP +Hotkeys for buttons (\*(``OK\*('' , \*(``Cancel\*('', etc.) are unaffected. +. +.IP "\fB\-\-no\-items" +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a \*(``tag\*('' and \*(``item\*('', +i.e., \*(``description\*(''). +This option tells \fB\*p\fP to read shorter rows, +omitting the \*(``item\*('' part of the list. +This is occasionally useful, e.g., if the tags provide enough information. +.IP +See also \fB\-\-no\-tags\fP. +If both options are given, this one is ignored. +. +.IP "\fB\-\-no\-kill" +Tells +\fB\*p\fP +to put the +\fBtailboxbg\fP +box in the background, +printing its process id to \fB\*p\fP's output. +SIGHUP is disabled for the background process. +. +.IP "\fB\-\-no-label \fIstring" +Override the label used for \*(``No\*('' buttons. +. +.IP "\fB\-\-no\-lines" +Rather than draw lines around boxes, draw spaces in the same place. +See also \*(``\fB\-\-ascii\-lines\fR\*(''. +. +.IP "\fB\-\-no\-mouse" +Do not enable the mouse. +. +.IP "\fB\-\-no\-nl\-expand" +Do not convert \*(``\en\*('' substrings of the message/prompt text into +literal newlines. +.IP +The \fIno\-nl\-expand\fP feature is used only if +the string contains \*(``\en\*('' so that there is something to convert. +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-no\-ok" +Suppress the \*(``OK\*('' button, so that it is not displayed. +A script can still test if the user pressed +the \*(``Enter\*('' key to accept the data: +.RS +.bP +The \*(``Enter\*('' key is always handled as the \*(``OK\*('' button +when the \fB\-\-no\-ok\fP option is used. +That is, by default it is bound to the \fILEAVE\fP virtual key. +.IP +When \fB\-\-no\-ok\fP is not used, +you can use the the \fITab\fP key to move the cursor through the +fields and buttons on the widget. +In that case, the \*(``Enter\*('' key activates the current button +if the cursor is positioned on a button. +.bP +To provide for the case where you want to activate a button +when using \fB\-\-no\-ok\fP, +there is another virtual key \fILEAVE\fP, +which activates the current button. +By default, \fB^D\fP (EOF) is bound to that key. +.RE +. +.IP "\fB\-\-no\-shadow" +Suppress shadows that would be drawn to the right and bottom of each dialog box. +. +.IP "\fB\-\-no\-tags" +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a \*(``tag\*('' and \*(``description\*(''). +The tag is useful for scripting, but may not help the user. +The \fB\-\-no\-tags\fP option (from Xdialog) may be used to suppress the +column of tags from the display. +Unlike the \fB\-\-no\-items\fP option, +this does not affect the data which is read from the script. +.IP +Xdialog does not display the tag column for the analogous buildlist +and treeview widgets; \fB\*p\fP does the same. +.IP +Normally \fB\*p\fP allows you to quickly move to entries on the displayed list, +by matching a single character to the first character of the tag. +When the \fB\-\-no\-tags\fP option is given, \fB\*p\fP matches against +the first character of the description. +In either case, the matchable character is highlighted. +. +.IP "\fB\-\-ok\-label \fIstring" +Override the label used for \*(``OK\*('' buttons. +. +.IP "\fB\-\-output\-fd \fIfd" +Direct output to the given file descriptor. +Most \fB\*p\fR scripts write to the standard error, +but error messages may also be written there, depending on your script. +. +.IP "\fB\-\-separator \fIstring" +.IP "\fB\-\-output\-separator \fIstring" +Specify a string that will separate the output on \fB\*p\fP's output from +checklists, rather than a newline (for \fB\-\-separate\-output\fP) or a space. +This applies to other widgets such as forms and editboxes which normally +use a newline. +. +.IP "\fB\-\-print\-maxsize" +Print the maximum size of dialog boxes, i.e., the screen size, +to \fB\*p\fP's output. +This may be used alone, without other options. +. +.IP "\fB\-\-print\-size" +Prints the size of each dialog box to \fB\*p\fP's output +when the box is initialized. +. +.IP "\fB\-\-print\-text\-only \fIstring [ height [ width ] ]" +Prints the string as it would be wrapped in a message box +to \fB\*p\fP's output. +.IP +Because the optional \fIheight\fP and \fIwidth\fP default to zero, +if they are omitted, \fB\*p\fP autosizes according to the screen dimensions. +. +.IP "\fB\-\-print\-text\-size \fIstring [ height [ width ] ]" +Prints the size of the string as it would be wrapped in a message box, +to \fB\*p\fP's output, +as +.Ex +height width +.Ee +.IP +Because the optional \fIheight\fP and \fIwidth\fP parameters default to zero, +if they are omitted, \fB\*p\fP autosizes according to the screen dimensions. +. +.IP "\fB\-\-print\-version" +Prints \fB\*p\fR's version to \fB\*p\fP's output. +This may be used alone, without other options. +It does not cause \fB\*l\fP to exit by itself. +. +.IP "\fB\-\-quoted" +Normally \fB\*p\fP quotes the strings returned by checklist's +as well as the item-help text. +Use this option to quote all string results as needed +(i.e., if the string contains whitespace or a single or double-quote character). +. +.IP "\fB\-\-reorder" +By default, the buildlist widget uses the same order for the output (right) +list as for the input (left). +Use this option to tell \fB\*p\fP to use the order +in which a user adds selections to the output list. +. +.IP "\fB\-\-scrollbar" +For widgets holding a scrollable set of data, +draw a scrollbar on its right-margin. +This does not respond to the mouse. +. +.IP "\fB\-\-separate\-output" +For certain widgets (buildlist, checklist, treeview), +output result one line at a time, with no quoting. +This facilitates parsing by another program. +. +.IP "\fB\-\-separate\-widget \fIstring" +Specify a string that will separate the output on \fB\*p\fP's output from +each widget. +This is used to simplify parsing the result of a dialog with several widgets. +If this option is not given, +the default separator string is a tab character. +. +.IP "\fB\-\-single\-quoted" +Use single-quoting as needed (and no quotes if unneeded) for the +output of checklist's as well as the item-help text. +.IP +If this option is not set, \fB\*p\fP may use double quotes around each item. +In either case, +\fB\*p\fP adds backslashes to make the output useful in shell scripts. +.IP +Single quotes would be needed if +the string contains whitespace or a single or double-quote character. +. +.IP "\fB\-\-size\-err" +Check the resulting size of a dialog box before trying to use it, +printing the resulting size if it is larger than the screen. +(This option is obsolete, since all new-window calls are checked). +. +.IP "\fB\-\-sleep \fIsecs" +Sleep (delay) for the given number of seconds after processing a dialog box. +. +.IP "\fB\-\-stderr" +Direct output to the standard error. +This is the default, since curses normally writes screen updates to +the standard output. +. +.IP "\fB\-\-stdout" +Direct output to the standard output. +This option is provided for compatibility with Xdialog, +however using it in portable scripts is not recommended, +since curses normally writes its screen updates to the standard output. +If you use this option, \fB\*p\fR attempts to reopen the terminal +so it can write to the display. +Depending on the platform and your environment, that may fail. +. +.IP "\fB\-\-tab\-correct" +Convert each tab character to one or more spaces +(for the \fBtextbox\fP widget; otherwise to a single space). +Otherwise, tabs are rendered according to the curses library's interpretation. +The \fB\-\-no\-collapse\fP option disables tab expansion. +. +.IP "\fB\-\-tab\-len \fIn" +Specify the number of spaces that a tab character occupies if the +\*(``\fB\-\-tab\-correct\fP\*('' option is given. +The default is 8. +This option is only effective for the \fBtextbox\fP widget. +. +.IP "\fB\-\-time\-format \fIformat" +If the host provides \fBstrftime\fP, +this option allows you to specify the format of the time printed for +the \fB\-\-timebox\fP widget. +The day, month, year values in this case are for the current local time. +. +.IP "\fB\-\-timeout \fIsecs" +Timeout if no user response within the given number of seconds. +A timeout of zero seconds is ignored. +.IP +Normally a timeout causes an ESC character to be entered in the current widget, +cancelling it. +Other widgets may still be on the screen; +these are not cancelled. +Set the \fBDIALOG_TIMEOUT\fP environment variable to tell \fB\*l\fP to +directly exit instead, i.e., cancelling all widgets on the screen. +.IP +This option is ignored by the \*(``\fB\-\-pause\fP\*('' widget. +It is also overridden +if the background \*(``\fB\-\-tailboxbg\fP\*('' option is used +to set up multiple concurrent widgets. +. +.IP "\fB\-\-title \fItitle" +Specifies a +\fItitle\fP +string to be displayed at the top of the dialog box. +. +.IP "\fB\-\-trace \fIfilename" +logs the command-line parameters, +keystrokes and other information to the given file. +If \fB\*l\fP reads a configure file, it is logged as well. +Piped input to the \fIgauge\fP widget is logged. +Use control/T to log a picture of the current dialog window. +.IP +The \fB\*p\fR program handles some command-line parameters specially, +and removes them from the parameter list as they are processed. +For example, if the first option is \fB\-\-trace\fP, +then that is processed (and removed) before \fB\*p\fR initializes the display. +. +.IP "\fB\-\-week\-start \fIday" +sets the starting day for the week, +used in the \*(``\fB\-\-calendar\fP\*('' option. +The \fIday\fP parameter can be +.RS +.bP +a number (0 to 6, Sunday through Saturday using POSIX) or +.bP +the special value \*(``locale\*('' (this works with systems using glibc, +providing an extension to the \fBlocale\fP command, +the \fBfirst_weekday\fP value). +.bP +a string matching one of the abbreviations for the day of the week +shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''. +.RE +. +.IP "\fB\-\-trim" +eliminate leading blanks, +trim literal newlines and repeated blanks from message text. +.IP +The \fItrim\fP feature is implemented subject to these conditions: +.RS +.bP +the string does not contain \*(``\en\*('' or +.bP +the \fB\-\-no\-nl\-expand\fP option is used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP +See also the \*(``\fB\-\-cr\-wrap\fR\*('' +and \*(``\fB\-\-no\-collapse\fR\*('' options. +. +.IP "\fB\-\-version" +Prints \fB\*p\fR's version to the standard output, and exits. +See also \*(``\fB\-\-print\-version\fP\*(''. +. +.IP "\fB\-\-visit\-items" +Modify the tab-traversal of checklist, radiolist, menubox and inputmenu +to include the list of items as one of the states. +This is useful as a visual aid, +i.e., the cursor position helps some users. +.IP +When this option is given, the cursor is initially placed on the list. +Abbreviations (the first letter of the tag) apply to the list items. +If you tab to the button row, abbreviations apply to the buttons. +. +.IP "\fB\-\-yes-label \fIstring" +Override the label used for \*(``Yes\*('' buttons. +. +.\" ************************************************************************ +.SS Box Options +All dialog boxes have at least three parameters: +.TP 7 +\fItext\fP +the caption or contents of the box. +.TP 7 +\fIheight\fP +the height of the dialog box. +.TP 7 +\fIwidth\fP +the width of the dialog box. +.PP +Other parameters depend on the box type. +. +. +.IP "\fB\-\-buildlist \fItext height width list-height \fR[ \fItag item status \fR] \fI..." +A \fBbuildlist\fP dialog displays two lists, side-by-side. +The list on the left shows unselected items. +The list on the right shows selected items. +As items are selected or unselected, they move between the lists. +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the selected-window and exit. +The results are written using the order displayed in the selected-window. +.IP +The initial on/off state of each entry is specified by +.IR status "." +.IP +The dialog behaves like a \fBmenu\fP, using the \fB\-\-visit\-items\fP +to control whether the cursor is allowed to visit the lists directly. +.RS +.bP +If \fB\-\-visit\-items\fP is not given, +tab-traversal uses two states (OK/Cancel). +.bP +If \fB\-\-visit\-items\fP is given, +tab-traversal uses four states (Left/Right/OK/Cancel). +.RE +.IP +Whether or not \fB\-\-visit\-items\fP is given, +it is possible to move the highlight between the two lists using +the default \*(``^\*('' (left-column) and \*(``$\*('' (right-column) keys. +.IP +On exit, a list of the \fItag\fP +strings of those entries that are turned on +will be printed on \fB\*p\fP's output. +.IP +If the "\fB\-\-separate\-output\fP" option is not given, +the strings will be quoted as needed +to make it simple for scripts to separate them. +By default, this uses double-quotes, as needed. +See the \*(``\fB\-\-single\-quoted\fP\*('' option, +which modifies the quoting behavior. +. +.IP "\fB\-\-calendar \fItext height width day month year" +A \fBcalendar\fP box displays +month, day and year in separately adjustable windows. +If the values for day, month or year are missing or negative, +the current date's corresponding values are used. +You can increment or decrement any of those using the +left-, up-, right-, and down-arrows. +Use vi-style h, j, k and l for moving around the array of days in a month. +Use tab or backtab to move between windows. +If the year is given as zero, the current date is used as an initial value. +.IP +On exit, the date is printed in the form day/month/year. +The format can be overridden using the \fB\-\-date\-format\fP option. +. +.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..." +A \fBchecklist\fP box is similar to a \fBmenu\fP box; +there are multiple entries presented in the form of a menu. +Another difference is +that you can indicate which entry is currently selected, by setting its +.IR status " to " on "." +Instead of choosing +one entry among the entries, each entry can be turned on or off by the user. +The initial on/off state of each entry is specified by +.IR status "." +.IP +On exit, a list of the \fItag\fP +strings of those entries that are turned on +will be printed on \fB\*p\fP's output. +.IP +If the \*(``\fB\-\-separate\-output\fP\*('' option is not given, +the strings will be quoted as needed +to make it simple for scripts to separate them. +By default, this uses double-quotes (as needed). +See the \*(``\fB\-\-single\-quoted\fP\*('' option, +which modifies the quoting behavior. +. +.IP "\fB\-\-dselect \fIfilepath height width\fR" +The directory-selection dialog displays a text-entry window +in which you can type a directory, +and above that a windows with directory names. +.IP +Here +\fBfilepath\fP +can be a filepath in which case the directory window +will display the contents of the path and the text-entry window will contain +the preselected directory. +.IP +Use tab or arrow keys to move between the windows. +Within the directory window, use the up/down arrow keys +to scroll the current selection. +Use the space-bar to copy the current selection into the text-entry +window. +.IP +Typing any printable characters switches focus to the text-entry window, +entering that character as well as scrolling the directory +window to the closest match. +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the text-entry window and exit. +.IP +On exit, the contents of the text-entry window are written +to \fB\*p\fP's output. +. +.IP "\fB\-\-editbox \fIfilepath height width\fR" +The edit-box dialog displays a copy of the file. +You may edit it using +the \fIbackspace\fP, \fIdelete\fP and cursor keys +to correct typing errors. +It also recognizes pageup/pagedown. +Unlike the \fB\-\-inputbox\fP, +you must tab to the \*(``OK\*('' or \*(``Cancel\*('' buttons +to close the dialog. +Pressing the \*(``Enter\*('' key within the box will split +the corresponding line. +.IP +On exit, the contents of the edit window are written to \fB\*p\fP's output. +. +.nf +.IP "\fB\-\-form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..." +.fi +The \fBform\fP dialog displays a form consisting of labels and fields, +which are positioned on a scrollable window by coordinates given in the script. +The field length \fIflen\fR and input-length \fIilen\fR tell how long +the field can be. +The former defines the length shown for a selected field, +while the latter defines the permissible length of the data entered in the +field. +.RS +.bP +If \fIflen\fR is zero, the corresponding field cannot be altered. +and the contents of the field determine the displayed-length. +.bP +If \fIflen\fR is negative, the corresponding field cannot be altered, +and the negated value of \fIflen\fR is used as the displayed-length. +.bP +If \fIilen\fR is zero, it is set to \fIflen\fR. +.RE +.IP +Use up/down arrows (or control/N, control/P) to move between fields. +Use tab to move between windows. +.IP +On exit, the contents of the form-fields are written to \fB\*p\fP's output, +each field separated by a newline. +The text used to fill non-editable fields +(\fIflen\fR is zero or negative) +is not written out. +. +. +.IP "\fB\-\-fselect \fIfilepath height width\fR" +The \fBfselect\fP (file-selection) dialog displays a text-entry window +in which you can type a filename (or directory), +and above that two windows with directory names and filenames. +.IP +Here +\fBfilepath\fP +can be a filepath in which case the file and directory windows +will display the contents of the path and the text-entry window will contain +the preselected filename. +.IP +Use tab or arrow keys to move between the windows. +Within the directory or filename windows, use the up/down arrow keys +to scroll the current selection. +Use the space-bar to copy the current selection into the text-entry +window. +.IP +Typing any printable characters switches focus to the text-entry window, +entering that character as well as scrolling the directory and filename +windows to the closest match. +.IP +Typing the space character forces \fB\*p\fP to complete the current +name (up to the point where there may be a match against more than one +entry). +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the text-entry window and exit. +.IP +On exit, the contents of the text-entry window are written +to \fB\*p\fP's output. +. +. +.IP "\fB\-\-gauge \fItext height width [percent]\fR" +A +\fBgauge\fP +box displays a meter along the bottom of the box. +The meter indicates the percentage. +New percentages are read from +standard input, one integer per line. +The meter is updated +to reflect each new percentage. +If the standard input reads the string \*(``XXX\*('', +then the first line following is taken as an integer percentage, +then subsequent lines up to another \*(``XXX\*('' are used for a new prompt. +The gauge exits when EOF is reached on the standard input. +.IP +The \fIpercent\fR value denotes the initial percentage shown in the meter. +If not specified, it is zero. +.IP +On exit, no text is written to \fB\*p\fP's output. +The widget accepts no input, so the exit status is always OK. +. +. +.IP "\fB\-\-infobox \fItext height width" +An \fBinfo\fP box is basically a \fBmessage\fP box. +However, in this case, \fB\*p\fP +will exit immediately after displaying the message to the user. +The screen is not cleared when \fB\*p\fP +exits, so that the message will remain on the screen until the calling +shell script clears it later. +This is useful when you want to inform +the user that some operations are carrying on that may require some +time to finish. +.IP +On exit, no text is written to \fB\*p\fP's output. +An OK exit status is returned. +. +. +.IP "\fB\-\-inputbox \fItext height width [init]" +An +\fBinput\fP +box is useful when you want to ask questions that +require the user to input a string as the answer. +If init is supplied +it is used to initialize the input string. +When entering the string, +the \fIbackspace\fP, \fIdelete\fP and cursor keys +can be used to correct typing errors. +If the input string is longer than +can fit in the dialog box, the input field will be scrolled. +.IP +On exit, the input string will be printed on \fB\*p\fP's output. +. +. +.IP "\fB\-\-inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..." +An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box. +There are only a few differences between them: +.RS +.TP 4 +1. +The entries are not automatically centered but left adjusted. +.TP +2. +An extra button (called \fIRename\/\fP) is implied to rename +the current item when it is pressed. +.TP +3. +It is possible to rename the current entry by pressing the +\fIRename\fP +button. +Then \fB\*p\fP will write the following on \fB\*p\fP's output. +.IP +RENAMED +.RE +. +. +.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..." +As its name suggests, a +\fBmenu\fP +box is a dialog box that can be used to present a list of choices in +the form of a menu for the user to choose. +Choices are displayed in the order given. +Each menu entry consists of a \fItag\fP string and an \fIitem\fP string. +The \fItag\fP +gives the entry a name to distinguish it from the other entries in the +menu. +The \fIitem\fP is a short description of the option that the entry represents. +The user can move between the menu entries by pressing the +cursor keys, the first letter of the \fItag\fP +as a hot-key, or the number keys \fI1\fP through \fI9\fP. +There are \fImenu-height\fP +entries displayed in the menu at one time, but the menu will be +scrolled if there are more entries than that. +.IP +On exit the \fItag\fP +of the chosen menu entry will be printed on \fB\*p\fP's output. +If the \*(``\fB\-\-help\-button\fR\*('' option is given, the corresponding help +text will be printed if the user selects the help button. +. +.nf +.IP "\fB\-\-mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..." +.fi +The \fBmixedform\fP dialog displays a form consisting of labels and fields, +much like the \fB\-\-form\fP dialog. +It differs by adding a field-type parameter to each field's description. +Each bit in the type denotes an attribute of the field: +.RS +.TP 5 +1 +hidden, e.g., a password field. +.TP 5 +2 +readonly, e.g., a label. +.RE +. +.IP "\fB\-\-mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..." +A \fBmixedgauge\fP box displays a meter along the bottom of the box. +The meter indicates the percentage. +.IP +It also displays a list of the \fItag\/\fP- and \fIitem\/\fP-values at the +top of the box. +See \*l(3) for the tag values. +.IP +The \fItext\fP is shown as a caption between the list and meter. +The \fIpercent\fR value denotes the initial percentage shown in the meter. +.IP +No provision is made for reading data from the standard input as \fB\-\-gauge\fP +does. +.IP +On exit, no text is written to \fB\*p\fP's output. +The widget accepts no input, so the exit status is always OK. +. +.IP "\fB\-\-msgbox \fItext height width" +A \fBmessage\fP box is very similar to a \fByes/no\fP box. +The only difference between a \fBmessage\fP box and a \fByes/no\fP +box is that a \fBmessage\fP box has only a single \fBOK\fP button. +You can use this dialog box to display any message you like. +After reading the message, the user can press the \fIENTER\fP key so that +\fB\*p\fP will exit and the calling shell script can continue its operation. +.IP +If the message is too large for the space, +\fB\*p\fP may allow you to scroll it, +provided that the underlying curses implementation is capable enough. +In this case, a percentage is shown in the base of the widget. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``OK\*('' button is provided for input, +but an ESC exit status may be returned. +. +.IP "\fB\-\-pause \fItext height width seconds\fR" +A +\fBpause\fP +box displays a meter along the bottom of the box. +The meter indicates how many seconds remain until the end of the pause. +The pause exits when timeout is reached +or the user presses the OK button +(status OK) +or the user presses the CANCEL button +or Esc key. +.IP "\fB\-\-passwordbox \fItext height width [init]" +A \fBpassword\fP box is similar to an input box, +except that the text the user enters is not displayed. +This is useful when prompting for passwords or other +sensitive information. +Be aware that if anything is passed in \*(``init\*('', it +will be visible in the system's process table to casual snoopers. +Also, it +is very confusing to the user to provide them with a default password they +cannot see. +For these reasons, using \*(``init\*('' is highly discouraged. +See \*(``\fB\-\-insecure\fP\*('' if you do not care about your password. +.IP +On exit, the input string will be printed on \fB\*p\fP's output. +. +. +.nf +.IP "\fB\-\-passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..." +.fi +This is identical to \fB\-\-form\fP except that all text fields are +treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets. +. +. +.IP "\fB\-\-prgbox \fItext command height width" +.IP "\fB\-\-prgbox \fIcommand height width" +A \fBprgbox\fP is very similar to a \fBprogrambox\fP. +.IP +This dialog box is used to display the output of a command that is +specified as an argument to \fBprgbox\fP. +.IP +After the command completes, the user can press the \fIENTER\fP key so that +\fB\*l\fP will exit and the calling shell script can continue its operation. +.IP +If four parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only three parameters are given, this text is omitted. +. +. +.IP "\fB\-\-programbox \fItext height width" +.IP "\fB\-\-programbox \fIheight width" +A \fBprogrambox\fP is very similar to a \fBprogressbox\fP. +The only difference between a \fBprogram\fP box and a \fBprogress\fP +box is that a \fBprogram\fP box displays an \fBOK\fP button +(but only after the command completes). +.IP +This dialog box is used to display the piped output of a command. +After the command completes, the user can press the \fIENTER\fP key so that +\fB\*l\fP will exit and the calling shell script can continue its operation. +.IP +If three parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only two parameters are given, this text is omitted. +. +. +.IP "\fB\-\-progressbox \fItext height width" +.IP "\fB\-\-progressbox \fIheight width" +A \fBprogressbox\fP is similar to an \fBtailbox\fP, +except that +.RS +.TP 3 +a) rather than displaying the contents of a file, +it displays the piped output of a command and +.TP 3 +b) it will exit when it reaches the end of the file +(there is no \*(``OK\*('' button). +.RE +.IP +If three parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only two parameters are given, this text is omitted. +. +. +.IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..." +A \fBradiolist\fP box is similar to a \fBmenu\fP box. +The only difference is +that you can indicate which entry is currently selected, by setting its +.IR status " to " on "." +.IP +On exit, the tag of the selected item is written to \fB\*p\fP's output. +. +. +.nf +.IP "\fB\-\-rangebox \fItext height width min-value max-value default-value" +.fi +Allow the user to select from a range of values, e.g., using a slider. +The dialog shows the current value as a bar (like the gauge dialog). +Tabs or arrow keys move the cursor between the buttons and the value. +When the cursor is on the value, +you can edit it by: +.RS +.TP 5 +left/right cursor movement to select a digit to modify +.TP 5 ++/- +characters to increment/decrement the digit by one +.TP 5 +0 through 9 +to set the digit to the given value +.RE +.IP +Some keys are also recognized in all cursor positions: +.RS +.TP 5 +home/end +set the value to its maximum or minimum +.TP 5 +pageup/pagedown +increment the value so that the slider moves by one column +.RE +. +. +.IP "\fB\-\-tailbox \fIfile height width" +Display text from a file in a dialog box, +as in a \*(``tail -f\*('' command. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the scrolling. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``OK\*('' button is provided for input, +but an ESC exit status may be returned. +. +. +.IP "\fB\-\-tailboxbg \fIfile height width" +Display text from a file in a dialog box as a background task, +as in a \*(``tail -f &\*('' command. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the scrolling. +.IP +\*L treats the background task specially if there are other +widgets (\fB\-\-and\-widget\fP) on the screen concurrently. +Until those widgets are closed (e.g., an \*(``OK\*(''), +\fB\*p\fP will perform all of the tailboxbg widgets in the same process, +polling for updates. +You may use a tab to traverse between the widgets on the screen, +and close them individually, e.g., by pressing \fIENTER\fP. +Once the non-tailboxbg widgets are closed, +\fB\*p\fP forks a copy of itself into the background, +and prints its process id if the \*(``\fB\-\-no\-kill\fP\*('' option +is given. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``EXIT\*('' button is provided for input, +but an ESC exit status may be returned. +.IP +NOTE: +Older versions of \fB\*p\fP forked immediately and attempted to +update the screen individually. +Besides being bad for performance, +it was unworkable. +Some older scripts may not work properly with the polled scheme. +. +. +.IP "\fB\-\-textbox \fIfile height width" +A +\fBtext\fP +box lets you display the contents of a text file in a dialog box. +It is like a simple text file viewer. +The user can move through the file by using the +cursor, page-up, page-down +and \fIHOME/END\fR keys available on most keyboards. +If the lines are too long to be displayed in the box, +the \fILEFT/RIGHT\fP +keys can be used to scroll the text region horizontally. +You may also use vi-style keys h, j, k, and l in place of the cursor keys, +and B or N in place of the page-up and page-down keys. +Scroll up/down using vi-style 'k' and 'j', or arrow-keys. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the left/right scrolling. +For more convenience, +vi-style forward and backward searching functions are also provided. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``EXIT\*('' button is provided for input, +but an ESC exit status may be returned. +. +. +.IP "\fB\-\-timebox \fItext height [width hour minute second]" +A dialog is displayed which allows you to select hour, minute and second. +If the values for hour, minute or second are missing or negative, +the current date's corresponding values are used. +You can increment or decrement any of those using the +left-, up-, right- and down-arrows. +Use tab or backtab to move between windows. +.IP +On exit, the result is printed in the form hour:minute:second. +The format can be overridden using the \fB\-\-time\-format\fP option. +. +. +.IP "\fB\-\-treeview \fItext height width list-height \fR[ \fItag item status depth \fR] \fI..." +Display data organized as a tree. +Each group of data contains a tag, +the text to display for the item, +its status (\*(``on\*('' or \*(``off\*('') +and the depth of the item in the tree. +.IP +Only one item can be selected (like the \fBradiolist\fP). +The tag is not displayed. +.IP +On exit, the tag of the selected item is written to \fB\*p\fP's output. +. +. +.IP "\fB\-\-yesno \fItext height width" +A \fByes/no\fP dialog box of +size \fIheight\fP rows by \fIwidth\fP columns will be displayed. +The string specified by +\fItext\fP +is displayed inside the dialog box. +If this string is too long to fit +in one line, it will be automatically divided into multiple lines at +appropriate places. +The +\fItext\fP +string can also contain the sub-string +.RI """" \en """" +or newline characters +.RI ` \en ' +to control line breaking explicitly. +This dialog box is useful for +asking questions that require the user to answer either yes or no. +The dialog box has a +\fBYes\fP +button and a +\fBNo\fP +button, in which the user can switch between by pressing the +.IR TAB " key." +.IP +On exit, no text is written to \fB\*p\fP's output. +In addition to the \*(``Yes\*('' and \*(``No\*('' exit codes (see DIAGNOSTICS) +an ESC exit status may be returned. +.IP +The codes used for \*(``Yes\*('' and \*(``No\*('' +match those used for \*(``OK\*('' and \*(``Cancel\*('', +internally no distinction is made. +. +.\" ************************************************************************ +.SS "Obsolete Options" +.\" from cdialog 0.9a (Pako) +.IP "\fB\-\-beep" +This was used to tell the original cdialog that it should make a beep +when the separate processes of the tailboxbg widget would repaint the screen. +. +.\" from cdialog 0.9a (Pako) +.IP "\fB\-\-beep\-after" +Beep after a user has completed a widget by pressing one of the buttons. +. +.\" ************************************************************************ +.SS "Whitespace Options" +These options can be used to transform whitespace (space, tab, newline) +as dialog reads the script: +.RS +.BR \-\-cr\-wrap , +.BR \-\-no\-collapse , +.BR \-\-no\-nl\-expand ", and" +.B \-\-trim +.RE +.PP +The options are not independent: +.bP +\fB\*L\fP checks if the script contains at least one \*(``\en\*('' +and (unless \fB\-\-no\-nl\-expand\fP is set) will ignore the +\fB\-\-no\-collapse\fP and \fB\-\-trim\fP options. +.bP +After checking for \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option, +\fB\*l\fP handles the \fB\-\-trim\fP option. +.IP +If the \fB\-\-trim\fP option takes effect, +then \fB\*l\fP ignores \fB\-\-no\-collapse\fP. +It changes sequences of tabs, spaces +(and newlines unless \fB\-cr\-wrap\fP is set) to a single space. +.bP +If neither the \*(``\en\*('' or \fB\-\-trim\fP cases apply, +\fB\*l\fP checks \fB\-\-no\-collapse\fP to decide whether to reduce +sequences of tabs and spaces to a single space. +.IP +In this case, \fB\*l\fP ignores \fB\-\-cr\-wrap\fP and does not modify newlines. +.PP +Taking those dependencies into account, +here is a table summarizing the behavior +for the various combinations of options. +The table assumes that the script contains at least one \*(``\en\*('' +when the \fB\-\-no\-nl\-expand\fP option is not set. +.na +.RS 5 +.TS +tab(/) ; +lB lB lB lB lB +lB lB lB lB lB +_ _ _ _ _ +lw4 lw4 lw4 lw4 lw29. +cr-/no-/no-/trim/Result +wrap/collapse/nl\-expand +no/no/no/no/T{ +Convert tab to space. +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/no/no/yes/T{ +Convert tab to space. +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/no/yes/no/T{ +Convert tab to space. +Do not convert newline to space. +Convert multiple-space to single. +Show \*(``\en\*('' literally. +T} +no/no/yes/yes/T{ +Convert tab to space. +Convert multiple-space to single. +Convert newline to space. +Show \*(``\en\*('' literally. +T} +no/yes/no/no/T{ +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/yes/no/yes/T{ +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/yes/yes/no/T{ +Do not convert newline to space. +Do not reduce multiple blanks. +Show \*(``\en\*('' literally. +T} +no/yes/yes/yes/T{ +Convert multiple-space to single. +Convert newline to space. +Show \*(``\en\*('' literally. +T} +yes/no/no/no/T{ +Convert tab to space. +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/no/no/yes/T{ +Convert tab to space. +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/no/yes/no/T{ +Convert tab to space. +Do not convert newline to space. +Convert multiple-space to single. +Show \*(``\en\*('' literally. +T} +yes/no/yes/yes/T{ +Convert tab to space. +Convert multiple-space to single. +Wrap on newline. +Show \*(``\en\*('' literally. +T} +yes/yes/no/no/T{ +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/yes/no/yes/T{ +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/yes/yes/no/T{ +Do not convert newline to space. +Do not reduce multiple blanks. +Show \*(``\en\*('' literally. +T} +yes/yes/yes/yes/T{ +Convert multiple-space to single. +Wrap on newline. +Show \*(``\en\*('' literally. +T} +.TE +.RE +.ad +. +.\" ************************************************************************ +.SH "RUN-TIME CONFIGURATION" +.TP 4 +1. +Create a sample configuration file by typing: +.LP +.Ex +\*p \-\-create\-rc \fIfile\fP +.Ee +.TP 4 +2. +At start, +\fB\*p\fP +determines the settings to use as follows: +.RS +.TP 4 +a) +if environment variable +\fBDIALOGRC\fP +is set, its value determines the name of the configuration file. +.TP 4 +b) +if the file in (a) is not found, use the file +\fI$HOME/.dialogrc\fP +as the configuration file. +.TP 4 +c) +if the file in (b) is not found, try using the GLOBALRC file determined at +compile-time, i.e., \fI/etc/dialogrc\fP. +.TP 4 +d) +if the file in (c) is not found, use compiled in defaults. +.RE +.TP 4 +3. +Edit the sample configuration file and copy it to some place that +\fB\*p\fP +can find, as stated in step 2 above. +. +.\" ************************************************************************ +.SH "KEY BINDINGS" +You can override or add to key bindings in \fB\*p\fP +by adding to the configuration file. +\fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding. +.Ex +bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP +.Ee +.PP +The \fIwidget\fP name can be \*(``*\*('' (all widgets), or +specific widgets such as \fBtextbox\fP. +Specific widget bindings override the \*(``*\*('' bindings. +User-defined bindings override the built-in bindings. +.PP +The \fIcurses_key\fP can be expressed in different forms: +.bP +It may be any of the names derived from +\fBcurses.h\fP, e.g., \*(``HELP\*('' from \*(``KEY_HELP\*(''. +.bP +\fB\*L\fP also recognizes ANSI control characters +such as \*(``^A\*('', \*(``^?\*('', +as well as C1-controls such as \*(``~A\*('' and \*(``~?\*(''. +.bP +Finally, \fB\*l\fP allows backslash escapes as in C. +Those can be octal character values such as \*(``\\033\*('' +(the ASCII escape character), +or the characters listed in this table: +.RS 10 +.TS +tab(/) ; +lI lI +_ _ +l l . +Escaped/Actual +\\b/backspace +\\f/form feed +\\n/new line (line feed) +\\r/carriage return +\\s/space +\\t/tab +\\^/\*(``^\*('' (caret) +\\?/\*(``?\*('' (question mark) +\\\\/\*(``\\\*('' (backslash) +_ +.TE +.RE +.PP +\fB\*L\fP's internal keycode names correspond to the +\fBDLG_KEYS_ENUM\fP type in +\fBdlg_keys.h\fP, e.g., \*(``HELP\*('' from \*(``DLGK_HELP\*(''. +.SS Widget Names +Some widgets (such as the formbox) have an area where fields can be edited. +Those are managed in a subwindow of the widget, and +may have separate keybindings from the main widget +because the subwindows are registered using a different name. +.RS 5 +.TS +tab(/) ; +lI lI lI +_ _ _ +l l l . +Widget/Window name/Subwindow Name +calendar/calendar +checklist/checklist +editbox/editbox/editbox2 +form/formbox/formfield +fselect/fselect/fselect2 +inputbox/inputbox/inputbox2 +menu/menubox/menu +msgbox/msgbox +pause/pause +progressbox/progressbox +radiolist/radiolist +tailbox/tailbox +textbox/textbox/searchbox +timebox/timebox +yesno/yesno +_ +.TE +.RE +.PP +Some widgets are actually other widgets, +using internal settings to modify the behavior. +Those use the same widget name as the actual widget: +.RS 5 +.TS +tab(/) ; +lI lI +_ _ +l l . +Widget/Actual Widget +dselect/fselect +infobox/msgbox +inputmenu/menu +mixedform/form +passwordbox/inputbox +passwordform/form +prgbox/progressbox +programbox/progressbox +tailboxbg/tailbox +_ +.TE +.RE +.SS Built-in Bindings +This manual page does not list the key bindings for each widget, +because that detailed information can be obtained by running \fB\*p\fP. +If you have set the \fB\-\-trace\fP option, +\fB\*p\fP writes the key-binding information for each widget +as it is registered. +.PP +A few bindings are built-in, independent of particular widgets: +.TS +tab(/) ; +lI lI +_ _ +l l . +Key/Purpose +Control-I/forward tab-traversal, e.g., with \fB\-\-tailboxbg\fP. +Control-L/repaints the screen. +Control-T/writes a screen dump to the \fB\-\-trace\fP file. +Control-V/suppresses special-keys for the next input byte. +DLGK_FIELD_NEXT/forward tab-traversal, like Control-I. +DLGK_FIELD_PREV/backward tab-traversal, like back-tab. +DLGK_HELPFILE/displays the help-file specified with \fB\-\-hfile\fP. +KEY_BTAB/backward tab-traversal, e.g., with \fB\-\-tailboxbg\fP. +_ +.TE + +.SS Example +Normally \fB\*p\fP uses different keys for navigating between the buttons +and editing part of a dialog versus navigating within the editing part. +That is, tab (and back-tab) traverse buttons +(or between buttons and the editing part), +while arrow keys traverse fields within the editing part. +Tabs are also recognized as a special case for traversing between +widgets, e.g., when using multiple tailboxbg widgets. +.PP +Some users may wish to use the same key for traversing within the +editing part as for traversing between buttons. +The form widget is written to support this sort of redefinition of +the keys, by adding a special group in \fBdlgk_keys.h\fP +for \*(``form\*('' (left/right/next/prev). +Here is an example binding demonstrating how to do this: +.Ex +bindkey formfield TAB form_NEXT +bindkey formbox TAB form_NEXT +bindkey formfield BTAB form_prev +bindkey formbox BTAB form_prev +.Ee +.PP +That type of redefinition would not be useful in other widgets, +e.g., calendar, due to the potentially large number of fields to traverse. +. +.SH EXIT STATUS +Exit status is subject to being overridden by environment variables. +The default values and corresponding environment variables +that can override them are: +.TP 5 +0 +if the \fBYES\fP or \fBOK\fP button is pressed (DIALOG_OK). +.TP 5 +1 +if the +.BR No " or " Cancel +button is pressed (DIALOG_CANCEL). +.TP 5 +2 +if the +.B Help +button is pressed (DIALOG_HELP), +.br +except as noted below about DIALOG_ITEM_HELP. +.TP 5 +3 +if the +.B Extra +button is pressed (DIALOG_EXTRA). +.TP 5 +4 +if the +.B Help +button is pressed, +.br +and the \fB\-\-item\-help\fP option is set +.br +and the DIALOG_ITEM_HELP environment variable is set to 4. +.IP +While any of the exit-codes can be overridden using environment variables, +this special case was introduced in 2004 to simplify compatibility. +\fB\*L\fP uses DIALOG_ITEM_HELP (4) internally, +but unless the environment variable is also set, +it changes that to DIALOG_HELP (2) on exit. +.TP 5 +5 +if a timeout expires and the \fBDIALOG_TIMEOUT\fP variable is set to 5. +.TP 5 +\-1 +if errors occur inside \fB\*p\fP (DIALOG_ERROR) +or \fB\*p\fP exits because the \fIESC\fP key (DIALOG_ESC) was pressed. +.\" ************************************************************************ +.SH ENVIRONMENT +.TP 15 +\fBDIALOGOPTS\fP +Define this variable to apply any of the common options to each widget. +Most of the common options are reset before processing each widget. +If you set the options in this environment variable, +they are applied to \fB\*p\fP's state after the reset. +As in the \*(``\fB\-\-file\fP\*('' option, +double-quotes and backslashes are interpreted. +.IP +The \*(``\fB\-\-file\fP\*('' option is not considered a common option +(so you cannot embed it within this environment variable). +.TP 15 +\fBDIALOGRC\fP +Define this variable if you want to specify the name of the configuration file +to use. +.TP 15 +\fBDIALOG_CANCEL\fP +.TP 15 +\fBDIALOG_ERROR\fP +.TP 15 +\fBDIALOG_ESC\fP +.TP 15 +\fBDIALOG_EXTRA\fP +.TP 15 +\fBDIALOG_HELP\fP +.TP 15 +\fBDIALOG_ITEM_HELP\fP +.TP 15 +\fBDIALOG_TIMEOUT\fP +.TP 15 +\fBDIALOG_OK\fP +Define any of these variables to change the exit code on +.RS +.bP +Cancel (1), +.bP +error (\-1), +.bP +ESC (255), +.bP +Extra (3), +.bP +Help (2), +.bP +Help with \fB\-\-item\-help\fP (2), +.bP +Timeout (5), or +.bP +OK (0). +.RE +.IP +Normally shell scripts cannot distinguish between \-1 and 255. +.TP 15 +\fBDIALOG_TTY\fP +Set this variable to \*(``1\*('' to provide compatibility with older versions +of \fB\*p\fP which assumed that if the script redirects the standard output, +that the \*(``\fB\-\-stdout\fP\*('' option was given. +.\" ************************************************************************ +.SH FILES +.TP 20 +\fI$HOME/.dialogrc\fP +default configuration file +.\" ************************************************************************ +.SH PORTABILITY +\fB\*L\fP works with X/Open curses. +However, some implementations have deficiencies: +.RS 3 +.bP +HPUX curses (and perhaps others) do not open the terminal properly for +the \fInewterm\fP function. +This interferes with \fB\*p\fP's \fB\-\-input\-fd\fP option, +by preventing cursor-keys and similar escape sequences from being recognized. +.bP +NetBSD 5.1 curses has incomplete support for wide-characters. +\fB\*p\fP will build, but not all examples display properly. +.RE +.\" ************************************************************************ +.SH COMPATIBILITY +You may want to write scripts which run with +other \fB\*l\fP \*(``clones\*(''. +.SS Original Dialog +First, there is the \*(``original\*('' \fB\*p\fP program to consider +(versions 0.3 to 0.9). +It had some misspelled (or inconsistent) options. +The \fB\*p\fP program maps those deprecated options to the preferred ones. +They include: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-beep\-after\fP/ignored +\fB\-\-guage\fP/mapped to \fB\-\-gauge\fP +_ +.TE +.RE +.SS Xdialog +This is an X application, rather than a terminal program. +With some care, it is possible to write useful scripts that work +with both \fBXdialog\fP and \fB\*p\fP. +.PP +The \fB\*p\fP program ignores these options which are recognized +by \fBXdialog\fP: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-allow\-close\fP/ignored +\fB\-\-auto\-placement\fP/ignored +\fB\-\-fixed\-font\fP/ignored +\fB\-\-icon\fP/ignored +\fB\-\-keep\-colors\fP/ignored +\fB\-\-no\-close\fP/ignored +\fB\-\-no\-cr\-wrap\fP/ignored +\fB\-\-screen\-center\fP/ignored +\fB\-\-separator\fP/mapped to \fB\-\-separate\-output\fP +\fB\-\-smooth\fP/ignored +\fB\-\-under\-mouse\fP/ignored +\fB\-\-wmclass\fP/ignored +_ +.TE +.RE +.PP +\fBXdialog\fP's manpage has a section discussing its compatibility +with \fB\*p\fP. +There are some differences not shown in the manpage. +For example, the html documentation states +.RS +.PP +Note: former Xdialog releases used the \*(``\en\*('' (line feed) as a +results separator for the checklist widget; +this has been changed to \*(``/\*('' in Xdialog v1.5.0 +to make it compatible with (c)dialog. +In your old scripts using the Xdialog checklist, you +will then have to add the \fB\-\-separate\-output\fP option before the +\fB\-\-checklist\fP one. +.RE +.PP +\fB\*L\fP has not used a different separator; +the difference was likely due to confusion regarding some script. +.SS Whiptail +Then there is \fBwhiptail\fP. +For practical purposes, it is maintained by Debian +(very little work is done by its upstream developers). +Its documentation (README.whiptail) claims +.Ex +\fBwhiptail\fP(1) is a lightweight replacement for \*p(1), +to provide dialog boxes for shell scripts. +It is built on the +newt windowing library rather than the ncurses library, allowing +it to be smaller in embedded environments such as installers, +rescue disks, etc. + +whiptail is designed to be drop-in compatible with \*p, but +has less features: some dialog boxes are not implemented, such +as tailbox, timebox, calendarbox, etc. +.Ee +.PP +Comparing actual sizes (Debian testing, 2007/1/10): +The total of sizes for \fBwhiptail\fP, +the newt, popt and slang libraries is 757\ KB. +The comparable number for \fB\*p\fP (counting ncurses) is 520\ KB. +Disregard the first paragraph. +.PP +The second paragraph is misleading, since \fBwhiptail\fP +also does not work for common options of \fB\*p\fP, +such as the gauge box. +\fBwhiptail\fP is less compatible with \fB\*p\fP than the +original mid-1990s dialog 0.4 program. +.PP +\fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g., +but oddly cites only \fB\*p\fP versions up to 0.4 (1994) as a source. +That is, its manpage refers to features which +were borrowed from more recent versions of \fB\*p\fP, e.g., +.bP +\fB\-\-gauge\fP (from 0.5) +.bP +\fB\-\-passwordbox\fP (from Debian changes in 1999), +.bP +\fB\-\-default\-item\fP (from \fB\*p\fP 2000/02/22), +.bP +\fB\-\-output\-fd\fP (from \fB\*p\fP 2002/08/14). +.PP +Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation. +.PP +The \fB\*p\fP program ignores or maps these options which are recognized +by \fBwhiptail\fP: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-cancel\-button\fP/mapped to \fB\-\-cancel\-label\fP +\fB\-\-fb\fP/ignored +\fB\-\-fullbutton\fP/ignored +\fB\-\-no\-button\fP/mapped to \fB\-\-no\-label\fP +\fB\-\-nocancel\fP/mapped to \fB\-\-no\-cancel\fP +\fB\-\-noitem\fP/mapped to \fB\-\-no\-items\fP +\fB\-\-notags\fP/mapped to \fB\-\-no\-tags\fP +\fB\-\-ok\-button\fP/mapped to \fB\-\-ok\-label\fP +\fB\-\-scrolltext\fP/mapped to \fB\-\-scrollbar\fP +\fB\-\-topleft\fP/mapped to \fB\-\-begin 0 0\fP +\fB\-\-yes\-button\fP/mapped to \fB\-\-yes\-label\fP +_ +.TE +.RE +.LP +There are visual differences which are not addressed by command-line options: +.bP +\fB\*p\fP centers lists within the window. +\fBwhiptail\fP typically puts lists against the left margin. +.bP +\fBwhiptail\fP uses angle brackets (\*(``<\*('' and \*(``>\*('') +for marking buttons. +\fB\*p\fP uses square brackets. +.bP +\fBwhiptail\fP marks the limits of subtitles with vertical bars. +\fB\*p\fP does not mark the limits. +.bP +\fBwhiptail\fP attempts to mark the top/bottom cells of a scrollbar +with up/down arrows. +When it cannot do this, +it fills those cells with the background color +of the scrollbar and confusing the user. +\fB\*p\fP uses the entire scrollbar space, +thereby getting better resolution. +.\" ************************************************************************ +.SH BUGS +Perhaps. +.\" ************************************************************************ +.SH EXAMPLES +The \fB\*p\fP sources contain several samples +of how to use the different box options and how they look. +Just take a look into the directory \fBsamples/\fP of the source. +.\" ************************************************************************ +.SH AUTHORS +Thomas E.\& Dickey (updates for 0.9b and beyond) +.LP +Kiran Cherupally \(en the mixed form and mixed gauge widgets. +.LP +Tobias C.\& Rittweiler +.LP +Valery Reznic \(en the form and progressbox widgets. +.LP +Yura Kalinichenko adapted the gauge widget as \*(``pause\*(''. +.PP +This is a rewrite (except as needed to provide compatibility) +of the earlier version of \fB\*p 0.9a\fP, +which lists as authors: +.bP +Savio Lam \(en version 0.3, \*(``dialog\*('' +.bP +Stuart Herbert \(en patch for version 0.4 +.bP +Marc Ewing \(en the gauge widget. +.bP +Pasquale De Marco \*(``Pako\*('' \(en version 0.9a, \*(``cdialog\*('' diff --git a/upstream/fedora-40/man1/diff.1 b/upstream/fedora-40/man1/diff.1 new file mode 100644 index 00000000..e2e94892 --- /dev/null +++ b/upstream/fedora-40/man1/diff.1 @@ -0,0 +1,270 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.40.4. +.TH DIFF "1" "January 2024" "diffutils 3.10" "User Commands" +.SH NAME +diff \- compare files line by line +.SH SYNOPSIS +.B diff +[\fIOPTION\fR]... \fIFILES\fR +.SH DESCRIPTION +Compare FILES line by line. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-\-normal\fR +output a normal diff (the default) +.TP +\fB\-q\fR, \fB\-\-brief\fR +report only when files differ +.TP +\fB\-s\fR, \fB\-\-report\-identical\-files\fR +report when two files are the same +.TP +\fB\-c\fR, \fB\-C\fR NUM, \fB\-\-context\fR[=\fINUM\fR] +output NUM (default 3) lines of copied context +.TP +\fB\-u\fR, \fB\-U\fR NUM, \fB\-\-unified\fR[=\fINUM\fR] +output NUM (default 3) lines of unified context +.TP +\fB\-e\fR, \fB\-\-ed\fR +output an ed script +.TP +\fB\-n\fR, \fB\-\-rcs\fR +output an RCS format diff +.TP +\fB\-y\fR, \fB\-\-side\-by\-side\fR +output in two columns +.TP +\fB\-W\fR, \fB\-\-width\fR=\fINUM\fR +output at most NUM (default 130) print columns +.TP +\fB\-\-left\-column\fR +output only the left column of common lines +.TP +\fB\-\-suppress\-common\-lines\fR +do not output common lines +.TP +\fB\-p\fR, \fB\-\-show\-c\-function\fR +show which C function each change is in +.TP +\fB\-F\fR, \fB\-\-show\-function\-line\fR=\fIRE\fR +show the most recent line matching RE +.TP +\fB\-\-label\fR LABEL +use LABEL instead of file name and timestamp +(can be repeated) +.TP +\fB\-t\fR, \fB\-\-expand\-tabs\fR +expand tabs to spaces in output +.TP +\fB\-T\fR, \fB\-\-initial\-tab\fR +make tabs line up by prepending a tab +.TP +\fB\-\-tabsize\fR=\fINUM\fR +tab stops every NUM (default 8) print columns +.TP +\fB\-\-suppress\-blank\-empty\fR +suppress space or tab before empty output lines +.TP +\fB\-l\fR, \fB\-\-paginate\fR +pass output through 'pr' to paginate it +.TP +\fB\-r\fR, \fB\-\-recursive\fR +recursively compare any subdirectories found +.TP +\fB\-\-no\-dereference\fR +don't follow symbolic links +.TP +\fB\-N\fR, \fB\-\-new\-file\fR +treat absent files as empty +.TP +\fB\-\-unidirectional\-new\-file\fR +treat absent first files as empty +.TP +\fB\-\-ignore\-file\-name\-case\fR +ignore case when comparing file names +.TP +\fB\-\-no\-ignore\-file\-name\-case\fR +consider case when comparing file names +.TP +\fB\-x\fR, \fB\-\-exclude\fR=\fIPAT\fR +exclude files that match PAT +.TP +\fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR +exclude files that match any pattern in FILE +.TP +\fB\-S\fR, \fB\-\-starting\-file\fR=\fIFILE\fR +start with FILE when comparing directories +.TP +\fB\-\-from\-file\fR=\fIFILE1\fR +compare FILE1 to all operands; +FILE1 can be a directory +.TP +\fB\-\-to\-file\fR=\fIFILE2\fR +compare all operands to FILE2; +FILE2 can be a directory +.TP +\fB\-i\fR, \fB\-\-ignore\-case\fR +ignore case differences in file contents +.TP +\fB\-E\fR, \fB\-\-ignore\-tab\-expansion\fR +ignore changes due to tab expansion +.TP +\fB\-Z\fR, \fB\-\-ignore\-trailing\-space\fR +ignore white space at line end +.TP +\fB\-b\fR, \fB\-\-ignore\-space\-change\fR +ignore changes in the amount of white space +.TP +\fB\-w\fR, \fB\-\-ignore\-all\-space\fR +ignore all white space +.TP +\fB\-B\fR, \fB\-\-ignore\-blank\-lines\fR +ignore changes where lines are all blank +.TP +\fB\-I\fR, \fB\-\-ignore\-matching\-lines\fR=\fIRE\fR +ignore changes where all lines match RE +.TP +\fB\-a\fR, \fB\-\-text\fR +treat all files as text +.TP +\fB\-\-strip\-trailing\-cr\fR +strip trailing carriage return on input +.TP +\fB\-D\fR, \fB\-\-ifdef\fR=\fINAME\fR +output merged file with '#ifdef NAME' diffs +.TP +\fB\-\-GTYPE\-group\-format\fR=\fIGFMT\fR +format GTYPE input groups with GFMT +.TP +\fB\-\-line\-format\fR=\fILFMT\fR +format all input lines with LFMT +.TP +\fB\-\-LTYPE\-line\-format\fR=\fILFMT\fR +format LTYPE input lines with LFMT +.IP +These format options provide fine\-grained control over the output +.IP +of diff, generalizing \fB\-D\fR/\-\-ifdef. +.TP +LTYPE is 'old', 'new', or 'unchanged'. +GTYPE is LTYPE or 'changed'. +.IP +GFMT (only) may contain: +.TP +%< +lines from FILE1 +.TP +%> +lines from FILE2 +.TP +%= +lines common to FILE1 and FILE2 +.TP +%[\-][WIDTH][.[PREC]]{doxX}LETTER +printf\-style spec for LETTER +.IP +LETTERs are as follows for new group, lower case for old group: +.TP +F +first line number +.TP +L +last line number +.TP +N +number of lines = L\-F+1 +.TP +E +F\-1 +.TP +M +L+1 +.TP +%(A=B?T:E) +if A equals B then T else E +.IP +LFMT (only) may contain: +.TP +%L +contents of line +.TP +%l +contents of line, excluding any trailing newline +.TP +%[\-][WIDTH][.[PREC]]{doxX}n +printf\-style spec for input line number +.IP +Both GFMT and LFMT may contain: +.TP +%% +% +.TP +%c'C' +the single character C +.TP +%c'\eOOO' +the character with octal code OOO +.TP +C +the character C (other characters represent themselves) +.TP +\fB\-d\fR, \fB\-\-minimal\fR +try hard to find a smaller set of changes +.TP +\fB\-\-horizon\-lines\fR=\fINUM\fR +keep NUM lines of the common prefix and suffix +.TP +\fB\-\-speed\-large\-files\fR +assume large files and many scattered small changes +.TP +\fB\-\-color\fR[=\fIWHEN\fR] +color output; WHEN is 'never', 'always', or 'auto'; +plain \fB\-\-color\fR means \fB\-\-color=\fR'auto' +.TP +\fB\-\-palette\fR=\fIPALETTE\fR +the colors to use when \fB\-\-color\fR is active; PALETTE is +a colon\-separated list of terminfo capabilities +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +output version information and exit +.PP +FILES are 'FILE1 FILE2' or 'DIR1 DIR2' or 'DIR FILE' or 'FILE DIR'. +If \fB\-\-from\-file\fR or \fB\-\-to\-file\fR is given, there are no restrictions on FILE(s). +If a FILE is '\-', read standard input. +Exit status is 0 if inputs are the same, 1 if different, 2 if trouble. +.SH AUTHOR +Written by Paul Eggert, Mike Haertel, David Hayes, +Richard Stallman, and Len Tower. +.SH "REPORTING BUGS" +Report bugs to: bug\-diffutils@gnu.org +.br +GNU diffutils home page: +.br +General help using GNU software: +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR wdiff (1), +.BR cmp (1), +.BR diff3 (1), +.BR sdiff (1), +.BR patch (1) +.PP +The full documentation for +.B diff +is maintained as a Texinfo manual. If the +.B info +and +.B diff +programs are properly installed at your site, the command +.IP +.B info diff +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/diff3.1 b/upstream/fedora-40/man1/diff3.1 new file mode 100644 index 00000000..9bd8342a --- /dev/null +++ b/upstream/fedora-40/man1/diff3.1 @@ -0,0 +1,102 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.40.4. +.TH DIFF3 "1" "May 2023" "diffutils 3.10" "User Commands" +.SH NAME +diff3 \- compare three files line by line +.SH SYNOPSIS +.B diff3 +[\fIOPTION\fR]... \fIMYFILE OLDFILE YOURFILE\fR +.SH DESCRIPTION +Compare three files line by line. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-A\fR, \fB\-\-show\-all\fR +output all changes, bracketing conflicts +.TP +\fB\-e\fR, \fB\-\-ed\fR +output ed script incorporating changes +from OLDFILE to YOURFILE into MYFILE +.TP +\fB\-E\fR, \fB\-\-show\-overlap\fR +like \fB\-e\fR, but bracket conflicts +.TP +\fB\-3\fR, \fB\-\-easy\-only\fR +like \fB\-e\fR, but incorporate only nonoverlapping changes +.TP +\fB\-x\fR, \fB\-\-overlap\-only\fR +like \fB\-e\fR, but incorporate only overlapping changes +.TP +\fB\-X\fR +like \fB\-x\fR, but bracket conflicts +.TP +\fB\-i\fR +append 'w' and 'q' commands to ed scripts +.TP +\fB\-m\fR, \fB\-\-merge\fR +output actual merged file, according to +\fB\-A\fR if no other options are given +.TP +\fB\-a\fR, \fB\-\-text\fR +treat all files as text +.TP +\fB\-\-strip\-trailing\-cr\fR +strip trailing carriage return on input +.TP +\fB\-T\fR, \fB\-\-initial\-tab\fR +make tabs line up by prepending a tab +.TP +\fB\-\-diff\-program\fR=\fIPROGRAM\fR +use PROGRAM to compare files +.TP +\fB\-L\fR, \fB\-\-label\fR=\fILABEL\fR +use LABEL instead of file name +(can be repeated up to three times) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +output version information and exit +.PP +The default output format is a somewhat human\-readable representation of +the changes. +.PP +The \fB\-e\fR, \fB\-E\fR, \fB\-x\fR, \fB\-X\fR (and corresponding long) options cause an ed script +to be output instead of the default. +.PP +Finally, the \fB\-m\fR (\fB\-\-merge\fR) option causes diff3 to do the merge internally +and output the actual merged file. For unusual input, this is more +robust than using ed. +.PP +If a FILE is '\-', read standard input. +Exit status is 0 if successful, 1 if conflicts, 2 if trouble. +.SH AUTHOR +Written by Randy Smith. +.SH "REPORTING BUGS" +Report bugs to: bug\-diffutils@gnu.org +.br +GNU diffutils home page: +.br +General help using GNU software: +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR cmp (1), +.BR diff (1), +.BR sdiff (1) +.PP +The full documentation for +.B diff3 +is maintained as a Texinfo manual. If the +.B info +and +.B diff3 +programs are properly installed at your site, the command +.IP +.B info diff3 +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/dir.1 b/upstream/fedora-40/man1/dir.1 new file mode 100644 index 00000000..7bea68ae --- /dev/null +++ b/upstream/fedora-40/man1/dir.1 @@ -0,0 +1,265 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DIR "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +dir \- list directory contents +.SH SYNOPSIS +.B dir +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +List information about the FILEs (the current directory by default). +Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-a\fR, \fB\-\-all\fR +do not ignore entries starting with . +.TP +\fB\-A\fR, \fB\-\-almost\-all\fR +do not list implied . and .. +.TP +\fB\-\-author\fR +with \fB\-l\fR, print the author of each file +.TP +\fB\-b\fR, \fB\-\-escape\fR +print C\-style escapes for nongraphic characters +.TP +\fB\-\-block\-size\fR=\fI\,SIZE\/\fR +with \fB\-l\fR, scale sizes by SIZE when printing them; +e.g., '\-\-block\-size=M'; see SIZE format below +.TP +\fB\-B\fR, \fB\-\-ignore\-backups\fR +do not list implied entries ending with ~ +.TP +\fB\-c\fR +with \fB\-lt\fR: sort by, and show, ctime (time of last +change of file status information); +with \fB\-l\fR: show ctime and sort by name; +otherwise: sort by ctime, newest first +.TP +\fB\-C\fR +list entries by columns +.TP +\fB\-\-color\fR[=\fI\,WHEN\/\fR] +color the output WHEN; more info below +.TP +\fB\-d\fR, \fB\-\-directory\fR +list directories themselves, not their contents +.TP +\fB\-D\fR, \fB\-\-dired\fR +generate output designed for Emacs' dired mode +.TP +\fB\-f\fR +list all entries in directory order +.TP +\fB\-F\fR, \fB\-\-classify\fR[=\fI\,WHEN\/\fR] +append indicator (one of */=>@|) to entries WHEN +.TP +\fB\-\-file\-type\fR +likewise, except do not append '*' +.TP +\fB\-\-format\fR=\fI\,WORD\/\fR +across \fB\-x\fR, commas \fB\-m\fR, horizontal \fB\-x\fR, long \fB\-l\fR, +single\-column \fB\-1\fR, verbose \fB\-l\fR, vertical \fB\-C\fR +.TP +\fB\-\-full\-time\fR +like \fB\-l\fR \fB\-\-time\-style\fR=\fI\,full\-iso\/\fR +.TP +\fB\-g\fR +like \fB\-l\fR, but do not list owner +.TP +\fB\-\-group\-directories\-first\fR +group directories before files; +can be augmented with a \fB\-\-sort\fR option, but any +use of \fB\-\-sort\fR=\fI\,none\/\fR (\fB\-U\fR) disables grouping +.TP +\fB\-G\fR, \fB\-\-no\-group\fR +in a long listing, don't print group names +.TP +\fB\-h\fR, \fB\-\-human\-readable\fR +with \fB\-l\fR and \fB\-s\fR, print sizes like 1K 234M 2G etc. +.TP +\fB\-\-si\fR +likewise, but use powers of 1000 not 1024 +.TP +\fB\-H\fR, \fB\-\-dereference\-command\-line\fR +follow symbolic links listed on the command line +.TP +\fB\-\-dereference\-command\-line\-symlink\-to\-dir\fR +follow each command line symbolic link +that points to a directory +.TP +\fB\-\-hide\fR=\fI\,PATTERN\/\fR +do not list implied entries matching shell PATTERN +(overridden by \fB\-a\fR or \fB\-A\fR) +.TP +\fB\-\-hyperlink\fR[=\fI\,WHEN\/\fR] +hyperlink file names WHEN +.TP +\fB\-\-indicator\-style\fR=\fI\,WORD\/\fR +append indicator with style WORD to entry names: +none (default), slash (\fB\-p\fR), +file\-type (\fB\-\-file\-type\fR), classify (\fB\-F\fR) +.TP +\fB\-i\fR, \fB\-\-inode\fR +print the index number of each file +.TP +\fB\-I\fR, \fB\-\-ignore\fR=\fI\,PATTERN\/\fR +do not list implied entries matching shell PATTERN +.TP +\fB\-k\fR, \fB\-\-kibibytes\fR +default to 1024\-byte blocks for file system usage; +used only with \fB\-s\fR and per directory totals +.TP +\fB\-l\fR +use a long listing format +.TP +\fB\-L\fR, \fB\-\-dereference\fR +when showing file information for a symbolic +link, show information for the file the link +references rather than for the link itself +.TP +\fB\-m\fR +fill width with a comma separated list of entries +.TP +\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR +like \fB\-l\fR, but list numeric user and group IDs +.TP +\fB\-N\fR, \fB\-\-literal\fR +print entry names without quoting +.TP +\fB\-o\fR +like \fB\-l\fR, but do not list group information +.TP +\fB\-p\fR, \fB\-\-indicator\-style\fR=\fI\,slash\/\fR +append / indicator to directories +.TP +\fB\-q\fR, \fB\-\-hide\-control\-chars\fR +print ? instead of nongraphic characters +.TP +\fB\-\-show\-control\-chars\fR +show nongraphic characters as\-is (the default, +unless program is 'ls' and output is a terminal) +.TP +\fB\-Q\fR, \fB\-\-quote\-name\fR +enclose entry names in double quotes +.TP +\fB\-\-quoting\-style\fR=\fI\,WORD\/\fR +use quoting style WORD for entry names: +literal, locale, shell, shell\-always, +shell\-escape, shell\-escape\-always, c, escape +(overrides QUOTING_STYLE environment variable) +.TP +\fB\-r\fR, \fB\-\-reverse\fR +reverse order while sorting +.TP +\fB\-R\fR, \fB\-\-recursive\fR +list subdirectories recursively +.TP +\fB\-s\fR, \fB\-\-size\fR +print the allocated size of each file, in blocks +.TP +\fB\-S\fR +sort by file size, largest first +.TP +\fB\-\-sort\fR=\fI\,WORD\/\fR +sort by WORD instead of name: none (\fB\-U\fR), size (\fB\-S\fR), +time (\fB\-t\fR), version (\fB\-v\fR), extension (\fB\-X\fR), width +.TP +\fB\-\-time\fR=\fI\,WORD\/\fR +select which timestamp used to display or sort; +access time (\fB\-u\fR): atime, access, use; +metadata change time (\fB\-c\fR): ctime, status; +modified time (default): mtime, modification; +birth time: birth, creation; +.IP +with \fB\-l\fR, WORD determines which time to show; +with \fB\-\-sort\fR=\fI\,time\/\fR, sort by WORD (newest first) +.TP +\fB\-\-time\-style\fR=\fI\,TIME_STYLE\/\fR +time/date format with \fB\-l\fR; see TIME_STYLE below +.TP +\fB\-t\fR +sort by time, newest first; see \fB\-\-time\fR +.TP +\fB\-T\fR, \fB\-\-tabsize\fR=\fI\,COLS\/\fR +assume tab stops at each COLS instead of 8 +.TP +\fB\-u\fR +with \fB\-lt\fR: sort by, and show, access time; +with \fB\-l\fR: show access time and sort by name; +otherwise: sort by access time, newest first +.TP +\fB\-U\fR +do not sort; list entries in directory order +.TP +\fB\-v\fR +natural sort of (version) numbers within text +.TP +\fB\-w\fR, \fB\-\-width\fR=\fI\,COLS\/\fR +set output width to COLS. 0 means no limit +.TP +\fB\-x\fR +list entries by lines instead of by columns +.TP +\fB\-X\fR +sort alphabetically by entry extension +.TP +\fB\-Z\fR, \fB\-\-context\fR +print any security context of each file +.TP +\fB\-\-zero\fR +end each output line with NUL, not newline +.TP +\fB\-1\fR +list one file per line +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +The SIZE argument is an integer and optional unit (example: 10K is 10*1024). +Units are K,M,G,T,P,E,Z,Y,R,Q (powers of 1024) or KB,MB,... (powers of 1000). +Binary prefixes can be used, too: KiB=K, MiB=M, and so on. +.PP +The TIME_STYLE argument can be full\-iso, long\-iso, iso, locale, or +FORMAT. +FORMAT is interpreted like in \fBdate\fP(1). If FORMAT is FORMAT1FORMAT2, +then FORMAT1 applies to non\-recent files and FORMAT2 to recent files. +TIME_STYLE prefixed with 'posix\-' takes effect only outside the POSIX locale. +Also the TIME_STYLE environment variable sets the default style to use. +.PP +The WHEN argument defaults to 'always' and can also be 'auto' or 'never'. +.PP +Using color to distinguish file types is disabled both by default and +with \fB\-\-color\fR=\fI\,never\/\fR. With \fB\-\-color\fR=\fI\,auto\/\fR, ls emits color codes only when +standard output is connected to a terminal. The LS_COLORS environment +variable can change the settings. Use the \fBdircolors\fP(1) command to set it. +.SS "Exit status:" +.TP +0 +if OK, +.TP +1 +if minor problems (e.g., cannot access subdirectory), +.TP +2 +if serious trouble (e.g., cannot access command\-line argument). +.SH AUTHOR +Written by Richard M. Stallman and David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) dir invocation\(aq diff --git a/upstream/fedora-40/man1/dircolors.1 b/upstream/fedora-40/man1/dircolors.1 new file mode 100644 index 00000000..214c6490 --- /dev/null +++ b/upstream/fedora-40/man1/dircolors.1 @@ -0,0 +1,50 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DIRCOLORS "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +dircolors \- color setup for ls +.SH SYNOPSIS +.B dircolors +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Output commands to set the LS_COLORS environment variable. +.SS "Determine format of output:" +.TP +\fB\-b\fR, \fB\-\-sh\fR, \fB\-\-bourne\-shell\fR +output Bourne shell code to set LS_COLORS +.TP +\fB\-c\fR, \fB\-\-csh\fR, \fB\-\-c\-shell\fR +output C shell code to set LS_COLORS +.TP +\fB\-p\fR, \fB\-\-print\-database\fR +output defaults +.TP +\fB\-\-print\-ls\-colors\fR +output fully escaped colors for display +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +If FILE is specified, read it to determine which colors to use for which +file types and extensions. Otherwise, a precompiled database is used. +For details on the format of these files, run 'dircolors \fB\-\-print\-database\fR'. +.SH AUTHOR +Written by H. Peter Anvin. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) dircolors invocation\(aq diff --git a/upstream/fedora-40/man1/dirname.1 b/upstream/fedora-40/man1/dirname.1 new file mode 100644 index 00000000..458da15f --- /dev/null +++ b/upstream/fedora-40/man1/dirname.1 @@ -0,0 +1,50 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DIRNAME "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +dirname \- strip last component from file name +.SH SYNOPSIS +.B dirname +[\fI\,OPTION\/\fR] \fI\,NAME\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Output each NAME with its last non\-slash component and trailing slashes +removed; if NAME contains no /'s, output '.' (meaning the current directory). +.TP +\fB\-z\fR, \fB\-\-zero\fR +end each output line with NUL, not newline +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH EXAMPLES +.TP +dirname /usr/bin/ +\-> "/usr" +.TP +dirname dir1/str dir2/str +\-> "dir1" followed by "dir2" +.TP +dirname stdio.h +\-> "." +.SH AUTHOR +Written by David MacKenzie and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBbasename\fP(1), \fBreadlink\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) dirname invocation\(aq diff --git a/upstream/fedora-40/man1/dnf-utils.1 b/upstream/fedora-40/man1/dnf-utils.1 new file mode 100644 index 00000000..aa2c1467 --- /dev/null +++ b/upstream/fedora-40/man1/dnf-utils.1 @@ -0,0 +1,115 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "DNF-UTILS" "1" "Feb 08, 2024" "4.5.0" "dnf-plugins-core" +.SH NAME +dnf-utils \- classic YUM utilities implemented as CLI shims on top of DNF +.sp +The main purpose of these shims is ensuring backward compatibility with yum\-3. +.SH SHELL COMMANDS +.INDENT 0.0 +.TP +.B \fBdebuginfo\-install(1)\fP +Install the associated debuginfo packages for a given package +specification. +Maps to \fBdnf debuginfo\-install\fP\&. +.TP +.B \fBneeds\-restarting(1)\fP +Check for running processes that should be restarted. +Maps to \fBdnf needs\-restarting\fP\&. +.TP +.B \fBfind\-repos\-of\-install\fP +Report which repository the package was installed from. +Part of core DNF functionality. +Maps to \fBdnf list \-\-installed\fP\&. +See \fIList Command\fP in \fBdnf(8)\fP for details. +.TP +.B \fBpackage\-cleanup(1)\fP +Clean up locally installed, duplicate, or orphaned packages. +.TP +.B \fBrepo\-graph(1)\fP +Output a full package dependency graph in dot format. +Maps to \fBdnf repograph\fP\&. +.TP +.B \fBrepoclosure(1)\fP +Display a list of unresolved dependencies for repositories. +Maps to \fBdnf repoclosure\fP\&. +.TP +.B \fBrepodiff(1)\fP +Display a list of differences between two or more repositories. +Maps to \fBdnf repodiff\fP\&. +.TP +.B \fBrepomanage(1)\fP +Manage a directory of rpm packages. +Maps to \fBdnf repomanage\fP\&. +.TP +.B \fBrepoquery\fP +Searches the available DNF repositories for selected packages and displays +the requested information about them. +Part of core DNF functionality. +Maps to \fBdnf repoquery\fP\&. +See \fIRepoquery Command\fP in \fBdnf(8)\fP for details. +.TP +.B \fBreposync(1)\fP +Synchronize packages of a remote DNF repository to a local directory. +Maps to \fBdnf reposync\fP\&. +.TP +.B \fBrepotrack\fP +Track packages and its dependencies and download them. +Maps to \fByumdownloader \-\-resolve \-\-alldeps\fP\&. +See \fByumdownloader(1)\fP for details. +.TP +.B \fByum\-builddep(1)\fP +Install whatever is needed to build the given .src.rpm, .nosrc.rpm or .spec +file. +Maps to \fBdnf builddep\fP\&. +.TP +.B \fByum\-config\-manager(1)\fP +Manage main DNF configuration options, toggle which repositories are +enabled or disabled, and add new repositories. +Maps to \fBdnf config\-manager\fP\&. +.TP +.B \fByum\-debug\-dump(1)\fP +Writes system RPM configuration to a dump file. +Maps to \fBdnf debug\-dump\fP\&. +.TP +.B \fByum\-debug\-restore(1)\fP +Restores system RPM configuration from a dump file. +Maps to \fBdnf debug\-restore\fP\&. +.TP +.B \fByumdownloader(1)\fP +Download binary or source packages. +Maps to \fBdnf download\fP\&. +.UNINDENT +.SH AUTHOR +See AUTHORS in your Core DNF Plugins distribution +.SH COPYRIGHT +2024, Red Hat, Licensed under GPLv2+ +.\" Generated by docutils manpage writer. +. diff --git a/upstream/fedora-40/man1/du.1 b/upstream/fedora-40/man1/du.1 new file mode 100644 index 00000000..34ff3647 --- /dev/null +++ b/upstream/fedora-40/man1/du.1 @@ -0,0 +1,163 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH DU "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +du \- estimate file space usage +.SH SYNOPSIS +.B du +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.br +.B du +[\fI\,OPTION\/\fR]... \fI\,--files0-from=F\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Summarize device usage of the set of FILEs, recursively for directories. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-0\fR, \fB\-\-null\fR +end each output line with NUL, not newline +.TP +\fB\-a\fR, \fB\-\-all\fR +write counts for all files, not just directories +.TP +\fB\-\-apparent\-size\fR +print apparent sizes rather than device usage; although +the apparent size is usually smaller, it may be +larger due to holes in ('sparse') files, internal +fragmentation, indirect blocks, and the like +.TP +\fB\-B\fR, \fB\-\-block\-size\fR=\fI\,SIZE\/\fR +scale sizes by SIZE before printing them; e.g., +\&'\-BM' prints sizes in units of 1,048,576 bytes; +see SIZE format below +.TP +\fB\-b\fR, \fB\-\-bytes\fR +equivalent to '\-\-apparent\-size \fB\-\-block\-size\fR=\fI\,1\/\fR' +.TP +\fB\-c\fR, \fB\-\-total\fR +produce a grand total +.TP +\fB\-D\fR, \fB\-\-dereference\-args\fR +dereference only symlinks that are listed on the +command line +.TP +\fB\-d\fR, \fB\-\-max\-depth\fR=\fI\,N\/\fR +print the total for a directory (or file, with \fB\-\-all\fR) +only if it is N or fewer levels below the command +line argument; \fB\-\-max\-depth\fR=\fI\,0\/\fR is the same as +\fB\-\-summarize\fR +.TP +\fB\-\-files0\-from\fR=\fI\,F\/\fR +summarize device usage of the +NUL\-terminated file names specified in file F; +if F is \-, then read names from standard input +.TP +\fB\-H\fR +equivalent to \fB\-\-dereference\-args\fR (\fB\-D\fR) +.TP +\fB\-h\fR, \fB\-\-human\-readable\fR +print sizes in human readable format (e.g., 1K 234M 2G) +.TP +\fB\-\-inodes\fR +list inode usage information instead of block usage +.TP +\fB\-k\fR +like \fB\-\-block\-size\fR=\fI\,1K\/\fR +.TP +\fB\-L\fR, \fB\-\-dereference\fR +dereference all symbolic links +.TP +\fB\-l\fR, \fB\-\-count\-links\fR +count sizes many times if hard linked +.TP +\fB\-m\fR +like \fB\-\-block\-size\fR=\fI\,1M\/\fR +.TP +\fB\-P\fR, \fB\-\-no\-dereference\fR +don't follow any symbolic links (this is the default) +.TP +\fB\-S\fR, \fB\-\-separate\-dirs\fR +for directories do not include size of subdirectories +.TP +\fB\-\-si\fR +like \fB\-h\fR, but use powers of 1000 not 1024 +.TP +\fB\-s\fR, \fB\-\-summarize\fR +display only a total for each argument +.TP +\fB\-t\fR, \fB\-\-threshold\fR=\fI\,SIZE\/\fR +exclude entries smaller than SIZE if positive, +or entries greater than SIZE if negative +.TP +\fB\-\-time\fR +show time of the last modification of any file in the +directory, or any of its subdirectories +.TP +\fB\-\-time\fR=\fI\,WORD\/\fR +show time as WORD instead of modification time: +atime, access, use, ctime or status +.TP +\fB\-\-time\-style\fR=\fI\,STYLE\/\fR +show times using STYLE, which can be: +full\-iso, long\-iso, iso, or +FORMAT; +FORMAT is interpreted like in 'date' +.TP +\fB\-X\fR, \fB\-\-exclude\-from\fR=\fI\,FILE\/\fR +exclude files that match any pattern in FILE +.TP +\fB\-\-exclude\fR=\fI\,PATTERN\/\fR +exclude files that match PATTERN +.TP +\fB\-x\fR, \fB\-\-one\-file\-system\fR +skip directories on different file systems +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Display values are in units of the first available SIZE from \fB\-\-block\-size\fR, +and the DU_BLOCK_SIZE, BLOCK_SIZE and BLOCKSIZE environment variables. +Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set). +.PP +The SIZE argument is an integer and optional unit (example: 10K is 10*1024). +Units are K,M,G,T,P,E,Z,Y,R,Q (powers of 1024) or KB,MB,... (powers of 1000). +Binary prefixes can be used, too: KiB=K, MiB=M, and so on. +.SH PATTERNS +PATTERN is a shell pattern (not a regular expression). The pattern +.B ?\& +matches any one character, whereas +.B * +matches any string (composed of zero, one or multiple characters). For +example, +.B *.o +will match any files whose names end in +.BR .o . +Therefore, the command +.IP +.B du \-\-exclude=\(aq*.o\(aq +.PP +will skip all files and subdirectories ending in +.B .o +(including the file +.B .o +itself). +.SH AUTHOR +Written by Torbjorn Granlund, David MacKenzie, Paul Eggert, +and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) du invocation\(aq diff --git a/upstream/fedora-40/man1/dumpkeys.1 b/upstream/fedora-40/man1/dumpkeys.1 new file mode 100644 index 00000000..8a8f77b8 --- /dev/null +++ b/upstream/fedora-40/man1/dumpkeys.1 @@ -0,0 +1,251 @@ +.\" @(#)loadkeys.1 1.0 93/09/1 RK +.TH DUMPKEYS 1 "1 Sep 1993" "kbd" +.SH NAME +dumpkeys \- dump keyboard translation tables +.SH SYNOPSIS +.B dumpkeys +[OPTIONS] +.SH DESCRIPTION +.IX "dumpkeys command" "" "\fLdumpkeys\fR command" +.LP +.B dumpkeys +writes, to the standard output, the current contents of the keyboard +driver's translation tables, in the format specified by +.BR keymaps (5). +.LP +Using the various options, the format of the output can be controlled +and also other information from the kernel and the programs +.BR dumpkeys (1) +and +.BR loadkeys (1) +can be obtained. +.SH OPTIONS +.TP +.B \-h \-\-help +Prints the program's version number and a short usage message to the +program's standard error output and exits. +.TP +.B \-i \-\-short-info +Prints some characteristics of the kernel's keyboard driver. The items +shown are: +.LP +.RS +Keycode range supported by the kernel +.LP +.RS +This tells what values can be used after the +.B keycode +keyword in keytable files. See +.BR keymaps (5) +for more information and the syntax of these files. +.RE +.LP +Number of actions bindable to a key +.LP +.RS +This tells how many different actions a single key can output using +various modifier keys. If the value is 16 for example, you can define up +to 16 different actions to a key combined with modifiers. When the value +is 16, the kernel probably knows about four modifier keys, which you can +press in different combinations with the key to access all the bound +actions. +.RE +.LP +Ranges of action codes supported by the kernel +.LP +.RS +This item contains a list of action code ranges in hexadecimal notation. +These are the values that can be used in the right hand side of a key +definition, ie. the +.IR vv 's +in a line +.LP +.RS +.B keycode +.I xx += +.I vv vv vv vv +.RE +.LP +(see +.BR keymaps (5) +for more information about the format of key definition lines). +.BR dumpkeys (1) +and +.BR loadkeys (1) +support a symbolic notation, which is preferable to the numeric one, as +the action codes may vary from kernel to kernel while the symbolic names +usually remain the same. However, the list of action code ranges can be +used to determine, if the kernel actually supports all the symbols +.BR loadkeys (1) +knows, or are there maybe some actions supported by the kernel that +have no symbolic name in your +.BR loadkeys (1) +program. To see this, you compare the range list with the action symbol +list, see option +.B --long-info +below. +.RE +.LP +Number of function keys supported by kernel +.LP +.RS +This tells the number of action codes that can be used to output +strings of characters. These action codes are traditionally bound to +the various function and editing keys of the keyboard and are defined +to send standard escape sequences. However, you can redefine these to +send common command lines, email addresses or whatever you like. +Especially if the number of this item is greater than the number of +function and editing keys in your keyboard, you may have some "spare" +action codes that you can bind to AltGr-letter combinations, for example, +to send some useful strings. See +.BR loadkeys (1) +for more details. +.RE +.LP +Function strings +.LP +.RS +You can see you current function key definitions with the command +.LP +.RS +.B dumpkeys --funcs-only +.RE +.LP +.RE +.RE +.LP +.TP +.B \-l \-s \-\-long-info +This option instructs +.B dumpkeys +to print a long information listing. The output is the same as with the +.B --short-info +appended with the list of action symbols supported by +.BR loadkeys (1) +and +.BR dumpkeys (1), +along with the symbols' numeric values. +.LP +.TP +.B \-n \-\-numeric +This option causes +.B dumpkeys +to by-pass the conversion of action code values to symbolic notation and +to print the in hexadecimal format instead. +.LP +.TP +.B \-f \-\-full-table +This makes +.B dumpkeys +skip all the short-hand heuristics (see +.BR keymaps (5)) +and output the key bindings in the canonical form. First a keymaps +line describing the currently defined modifier combinations +is printed. Then for each key a row with a column for each +modifier combination is printed. For +example, if the current keymap in use uses seven modifiers, +every row will have seven action code columns. This format +can be useful for example to programs that post-process the +output of +.BR dumpkeys . +.LP +.TP +.BI \-S shape " " " " \-\-shape= shape +Available shapes: +.LP +.RS +.B 2 +default output. +.RE +.LP +.RS +.B 4 +one line for each keycode. +.RE +.LP +.RS +.B 8 +one line for each (modifier,keycode) pair. +.RE +.LP +.RS +.B 16 +one line for each keycode until 1st hole. +.RE +.LP +.TP +.B \-1 \-\-separate-lines +This forces +.B dumpkeys +to write one line per (modifier,keycode) pair. It prefixes the word +.I plain +for plain keycodes. +.LP +.TP +.B \-t \-\-funcs-only +When this option is given, +.B dumpkeys +prints only the function key string definitions. Normally +.B dumpkeys +prints both the key bindings and the string definitions. +.LP +.TP +.B \-k \-\-keys-only +When this option is given, +.B dumpkeys +prints only the key bindings. Normally +.B dumpkeys +prints both the key bindings and the string definitions. +.LP +.TP +.B \-d \-\-compose-only +When this option is given, +.B dumpkeys +prints only the compose key combinations. +This option is available only if your kernel has compose key support. +.LP +.TP +.BI \-c charset " " " " \-\-charset= charset +This instructs +.B dumpkeys +to interpret character code values according to the specified character +set. This affects only the translation of character code values to +symbolic names. Valid values for +.I charset +currently are +.BR iso-8859-X , +Where X is a digit in 1-9. If no +.I charset +is specified, +.B iso-8859-1 +is used as a default. +This option produces an output line `charset "iso-8859-X"', telling +loadkeys how to interpret the keymap. (For example, "division" is +0xf7 in iso-8859-1 but 0xba in iso-8859-8.) +.LP +.TP +.BI \-C dev " " " " \-\-console= dev +The affected console device can be specified using the +.I -C +(or +.I --console +) option. This option supports exactly one device name. +.LP +.TP +.B \-v \-\-verbose +Turn on verbose output. +.LP +.TP +.B \-V \-\-version +Prints version number and exits. +.LP +.SH FILES +.TP +.I /usr/lib/kbd/keymaps +The recommended directory for keytable files. +.LP +.SH "SEE ALSO" +.BR loadkeys (1), +.BR keymaps (5) + diff --git a/upstream/fedora-40/man1/echo.1 b/upstream/fedora-40/man1/echo.1 new file mode 100644 index 00000000..d4a06725 --- /dev/null +++ b/upstream/fedora-40/man1/echo.1 @@ -0,0 +1,93 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH ECHO "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +echo \- display a line of text +.SH SYNOPSIS +.B echo +[\fI\,SHORT-OPTION\/\fR]... [\fI\,STRING\/\fR]... +.br +.B echo +\fI\,LONG-OPTION\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Echo the STRING(s) to standard output. +.TP +\fB\-n\fR +do not output the trailing newline +.TP +\fB\-e\fR +enable interpretation of backslash escapes +.TP +\fB\-E\fR +disable interpretation of backslash escapes (default) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +If \fB\-e\fR is in effect, the following sequences are recognized: +.TP +\e\e +backslash +.TP +\ea +alert (BEL) +.TP +\eb +backspace +.TP +\ec +produce no further output +.TP +\ee +escape +.TP +\ef +form feed +.TP +\en +new line +.TP +\er +carriage return +.TP +\et +horizontal tab +.TP +\ev +vertical tab +.TP +\e0NNN +byte with octal value NNN (1 to 3 digits) +.TP +\exHH +byte with hexadecimal value HH (1 to 2 digits) +.PP +NOTE: your shell may have its own version of echo, which usually supersedes +the version described here. Please refer to your shell's documentation +for details about the options it supports. +.PP +NOTE: \fBprintf\fP(1) is a preferred alternative, +which does not have issues outputting option\-like strings. +.SH AUTHOR +Written by Brian Fox and Chet Ramey. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBprintf\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) echo invocation\(aq diff --git a/upstream/fedora-40/man1/ed.1 b/upstream/fedora-40/man1/ed.1 new file mode 100644 index 00000000..dcff01ce --- /dev/null +++ b/upstream/fedora-40/man1/ed.1 @@ -0,0 +1,91 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.2. +.TH ED "1" "February 2024" "GNU ed 1.20.1" "User Commands" +.SH NAME +ed \- line-oriented text editor +.SH SYNOPSIS +.B ed +[\fI\,options\/\fR] [[\fI\,+line\/\fR] \fI\,file\/\fR] +.SH DESCRIPTION +GNU ed is a line\-oriented text editor. It is used to create, display, +modify and otherwise manipulate text files, both interactively and via +shell scripts. A restricted version of ed, red, can only edit files in +the current directory and cannot execute shell commands. Ed is the +\&'standard' text editor in the sense that it is the original editor for +Unix, and thus widely available. For most purposes, however, it is +superseded by full\-screen editors such as GNU Emacs or GNU Moe. +.PP +The file name may be preceded by '+line', '+/RE', or '+?RE' to set the +current line to the line number specified or to the first or last line +matching the regular expression 'RE'. +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help and exit +.TP +\fB\-V\fR, \fB\-\-version\fR +output version information and exit +.TP +\fB\-E\fR, \fB\-\-extended\-regexp\fR +use extended regular expressions +.TP +\fB\-G\fR, \fB\-\-traditional\fR +run in compatibility mode +.TP +\fB\-l\fR, \fB\-\-loose\-exit\-status\fR +exit with 0 status even if a command fails +.TP +\fB\-p\fR, \fB\-\-prompt\fR=\fI\,STRING\/\fR +use STRING as an interactive prompt +.TP +\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR +suppress diagnostics written to stderr +.TP +\fB\-r\fR, \fB\-\-restricted\fR +run in restricted mode +.TP +\fB\-s\fR, \fB\-\-script\fR +suppress byte counts and '!' prompt +.TP +\fB\-v\fR, \fB\-\-verbose\fR +be verbose; equivalent to the 'H' command +.TP +\fB\-\-strip\-trailing\-cr\fR +strip carriage returns at end of text lines +.TP +\fB\-\-unsafe\-names\fR +allow control characters 1\-31 in file names +.PP +Start edit by reading in 'file' if given. +If 'file' begins with a '!', read output of shell command. +.PP +Exit status: 0 for a normal exit, 1 for environmental problems +(invalid command\-line options, memory exhausted, command failed, etc), +2 for problems with the input file (file not found, buffer modified, +I/O errors), 3 for an internal consistency error (e.g., bug) which caused +ed to panic. +.SH "REPORTING BUGS" +Report bugs to bug\-ed@gnu.org +.br +Ed home page: http://www.gnu.org/software/ed/ed.html +.br +General help using GNU software: http://www.gnu.org/gethelp +.SH COPYRIGHT +Copyright \(co 1994 Andrew L. Moore. +.br +Copyright \(co 2024 Antonio Diaz Diaz. +License GPLv2+: GNU GPL version 2 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B ed +is maintained as a Texinfo manual. If the +.B info +and +.B ed +programs are properly installed at your site, the command +.IP +.B info ed +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/elfedit.1 b/upstream/fedora-40/man1/elfedit.1 new file mode 100644 index 00000000..daf85008 --- /dev/null +++ b/upstream/fedora-40/man1/elfedit.1 @@ -0,0 +1,195 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ELFEDIT 1" +.TH ELFEDIT 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +elfedit \- update ELF header and program property of ELF files +.SH SYNOPSIS +.IX Header "SYNOPSIS" +elfedit [\fB\-\-input\-mach=\fR\fImachine\fR] + [\fB\-\-input\-type=\fR\fItype\fR] + [\fB\-\-input\-osabi=\fR\fIosabi\fR] + [\fB\-\-input\-abiversion=\fR\fIversion\fR] + \fB\-\-output\-mach=\fR\fImachine\fR + \fB\-\-output\-type=\fR\fItype\fR + \fB\-\-output\-osabi=\fR\fIosabi\fR + \fB\-\-output\-abiversion=\fR\fIversion\fR + \fB\-\-enable\-x86\-feature=\fR\fIfeature\fR + \fB\-\-disable\-x86\-feature=\fR\fIfeature\fR + [\fB\-v\fR|\fB\-\-version\fR] + [\fB\-h\fR|\fB\-\-help\fR] + \fIelffile\fR... +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBelfedit\fR updates the ELF header and program property of ELF +files which have the matching ELF machine and file types. The options +control how and which fields in the ELF header and program property +should be updated. +.PP +\&\fIelffile\fR... are the ELF files to be updated. 32\-bit and +64\-bit ELF files are supported, as are archives containing ELF files. +.SH OPTIONS +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. At least one of the \fB\-\-output\-mach\fR, +\&\fB\-\-output\-type\fR, \fB\-\-output\-osabi\fR, +\&\fB\-\-output\-abiversion\fR, +\&\fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR +options must be given. +.IP \fB\-\-input\-mach=\fR\fImachine\fR 4 +.IX Item "--input-mach=machine" +Set the matching input ELF machine type to \fImachine\fR. If +\&\fB\-\-input\-mach\fR isn't specified, it will match any ELF +machine types. +.Sp +The supported ELF machine types are, \fIi386\fR, \fIIAMCU\fR, \fIL1OM\fR, +\&\fIK1OM\fR and \fIx86\-64\fR. +.IP \fB\-\-output\-mach=\fR\fImachine\fR 4 +.IX Item "--output-mach=machine" +Change the ELF machine type in the ELF header to \fImachine\fR. The +supported ELF machine types are the same as \fB\-\-input\-mach\fR. +.IP \fB\-\-input\-type=\fR\fItype\fR 4 +.IX Item "--input-type=type" +Set the matching input ELF file type to \fItype\fR. If +\&\fB\-\-input\-type\fR isn't specified, it will match any ELF file types. +.Sp +The supported ELF file types are, \fIrel\fR, \fIexec\fR and \fIdyn\fR. +.IP \fB\-\-output\-type=\fR\fItype\fR 4 +.IX Item "--output-type=type" +Change the ELF file type in the ELF header to \fItype\fR. The +supported ELF types are the same as \fB\-\-input\-type\fR. +.IP \fB\-\-input\-osabi=\fR\fIosabi\fR 4 +.IX Item "--input-osabi=osabi" +Set the matching input ELF file OSABI to \fIosabi\fR. If +\&\fB\-\-input\-osabi\fR isn't specified, it will match any ELF OSABIs. +.Sp +The supported ELF OSABIs are, \fInone\fR, \fIHPUX\fR, \fINetBSD\fR, +\&\fIGNU\fR, \fILinux\fR (alias for \fIGNU\fR), +\&\fISolaris\fR, \fIAIX\fR, \fIIrix\fR, +\&\fIFreeBSD\fR, \fITRU64\fR, \fIModesto\fR, \fIOpenBSD\fR, \fIOpenVMS\fR, +\&\fINSK\fR, \fIAROS\fR and \fIFenixOS\fR. +.IP \fB\-\-output\-osabi=\fR\fIosabi\fR 4 +.IX Item "--output-osabi=osabi" +Change the ELF OSABI in the ELF header to \fIosabi\fR. The +supported ELF OSABI are the same as \fB\-\-input\-osabi\fR. +.IP \fB\-\-input\-abiversion=\fR\fIversion\fR 4 +.IX Item "--input-abiversion=version" +Set the matching input ELF file ABIVERSION to \fIversion\fR. +\&\fIversion\fR must be between 0 and 255. If \fB\-\-input\-abiversion\fR +isn't specified, it will match any ELF ABIVERSIONs. +.IP \fB\-\-output\-abiversion=\fR\fIversion\fR 4 +.IX Item "--output-abiversion=version" +Change the ELF ABIVERSION in the ELF header to \fIversion\fR. +\&\fIversion\fR must be between 0 and 255. +.IP \fB\-\-enable\-x86\-feature=\fR\fIfeature\fR 4 +.IX Item "--enable-x86-feature=feature" +Set the \fIfeature\fR bit in program property in \fIexec\fR or \fIdyn\fR +ELF files with machine types of \fIi386\fR or \fIx86\-64\fR. The +supported features are, \fIibt\fR, \fIshstk\fR, \fIlam_u48\fR and +\&\fIlam_u57\fR. +.IP \fB\-\-disable\-x86\-feature=\fR\fIfeature\fR 4 +.IX Item "--disable-x86-feature=feature" +Clear the \fIfeature\fR bit in program property in \fIexec\fR or +\&\fIdyn\fR ELF files with machine types of \fIi386\fR or \fIx86\-64\fR. +The supported features are the same as \fB\-\-enable\-x86\-feature\fR. +.Sp +Note: \fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR +are available only on hosts with \fBmmap\fR support. +.IP \fB\-v\fR 4 +.IX Item "-v" +.PD 0 +.IP \fB\-\-version\fR 4 +.IX Item "--version" +.PD +Display the version number of \fBelfedit\fR. +.IP \fB\-h\fR 4 +.IX Item "-h" +.PD 0 +.IP \fB\-\-help\fR 4 +.IX Item "--help" +.PD +Display the command-line options understood by \fBelfedit\fR. +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/env.1 b/upstream/fedora-40/man1/env.1 new file mode 100644 index 00000000..eb6f3194 --- /dev/null +++ b/upstream/fedora-40/man1/env.1 @@ -0,0 +1,142 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH ENV "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +env \- run a program in a modified environment +.SH SYNOPSIS +.B env +[\fI\,OPTION\/\fR]... [\fI\,-\/\fR] [\fI\,NAME=VALUE\/\fR]... [\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Set each NAME to VALUE in the environment and run COMMAND. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-i\fR, \fB\-\-ignore\-environment\fR +start with an empty environment +.TP +\fB\-0\fR, \fB\-\-null\fR +end each output line with NUL, not newline +.TP +\fB\-u\fR, \fB\-\-unset\fR=\fI\,NAME\/\fR +remove variable from the environment +.TP +\fB\-C\fR, \fB\-\-chdir\fR=\fI\,DIR\/\fR +change working directory to DIR +.TP +\fB\-S\fR, \fB\-\-split\-string\fR=\fI\,S\/\fR +process and split S into separate arguments; +used to pass multiple arguments on shebang lines +.TP +\fB\-\-block\-signal\fR[=\fI\,SIG\/\fR] +block delivery of SIG signal(s) to COMMAND +.TP +\fB\-\-default\-signal\fR[=\fI\,SIG\/\fR] +reset handling of SIG signal(s) to the default +.TP +\fB\-\-ignore\-signal\fR[=\fI\,SIG\/\fR] +set handling of SIG signal(s) to do nothing +.TP +\fB\-\-list\-signal\-handling\fR +list non default signal handling to stderr +.TP +\fB\-v\fR, \fB\-\-debug\fR +print verbose information for each processing step +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +A mere \- implies \fB\-i\fR. If no COMMAND, print the resulting environment. +.PP +SIG may be a signal name like 'PIPE', or a signal number like '13'. +Without SIG, all known signals are included. Multiple signals can be +comma\-separated. An empty SIG argument is a no\-op. +.SS "Exit status:" +.TP +125 +if the env command itself fails +.TP +126 +if COMMAND is found but cannot be invoked +.TP +127 +if COMMAND cannot be found +.TP +\- +the exit status of COMMAND otherwise +.SH OPTIONS +.SS "\-S/\-\-split\-string usage in scripts" +The +.B \-S +option allows specifying multiple parameters in a script. +Running a script named +.B 1.pl +containing the following first line: +.PP +.RS +.nf +#!/usr/bin/env \-S perl \-w \-T +\&... +.fi +.RE +.PP +Will execute +.B "perl \-w \-T 1.pl". +.PP +Without the +.B '\-S' +parameter the script will likely fail with: +.PP +.RS +.nf +/usr/bin/env: 'perl \-w \-T': No such file or directory +.fi +.RE +.PP +See the full documentation for more details. +.PP +.SS "\-\-default-signal[=SIG]" usage +This option allows setting a signal handler to its default +action, which is not possible using the traditional shell +trap command. The following example ensures that seq +will be terminated by SIGPIPE no matter how this signal +is being handled in the process invoking the command. + +.PP +.RS +.nf +sh \-c 'env \-\-default-signal=PIPE seq inf | head \-n1' +.fi +.RE +.PP +.SH NOTES +POSIX's \fBexec\fP(3p) pages says: +.RS +"many existing applications wrongly assume that they start with certain +signals set to the default action and/or unblocked.... Therefore, it is best +not to block or ignore signals across execs without explicit reason to do so, +and especially not to block signals across execs of arbitrary (not closely +cooperating) programs." +.RE +.SH AUTHOR +Written by Richard Mlynarik, David MacKenzie, and Assaf Gordon. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBsigaction\fP(2), \fBsigprocmask\fP(2), \fBsignal\fP(7) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) env invocation\(aq diff --git a/upstream/fedora-40/man1/epsffit.1 b/upstream/fedora-40/man1/epsffit.1 new file mode 100644 index 00000000..6ad046e1 --- /dev/null +++ b/upstream/fedora-40/man1/epsffit.1 @@ -0,0 +1,63 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.1. +.TH EPSFFIT "1" "February 2023" "epsffit 2.10" "User Commands" +.SH NAME +epsffit - fit an Encapsulated PostScript file to a given bounding box +.SH SYNOPSIS +.B epsffit +[\fI\,OPTION\/\fR...] \fI\,LLX LLY URX URY \/\fR[\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]] +.SH DESCRIPTION +Fit an Encapsulated PostScript file to a given bounding box. +.TP +\fB\-c\fR, \fB\-\-center\fR +center the image in the given bounding box +.TP +\fB\-r\fR, \fB\-\-rotate\fR +rotate the image by 90 degrees counter\-clockwise +.TP +\fB\-a\fR, \fB\-\-aspect\fR +adjust the aspect ratio to fit the bounding box +.TP +\fB\-m\fR, \fB\-\-maximize\fR +rotate the image to fill more of the page if possible +.TP +\fB\-s\fR, \fB\-\-showpage\fR +append a \fI\,/showpage\/\fP to the file to force printing +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +display version information and exit +.PP +(LLX, LLY) are the coordinates of the lower left corner of the box, and +(URX, URY) the upper right. +.PP +If OUTFILE is not specified, writes to standard output. +If INFILE is not specified, reads from standard input. +.PP +See +.BR psutils (1) +for the available units. +.SS "Exit status:" +.TP +0 +if OK, +.TP +1 +if arguments or options are incorrect, or there is some other problem +starting up, +.TP +2 +if there is some problem during processing, typically an error reading or +writing an input or output file. +.SH AUTHOR +Written by Angus J. C. Duggan and Reuben Thomas. +.SH COPYRIGHT +Copyright \(co Reuben Thomas 2016\-2022. +Released under the GPL version 3, or (at your option) any later version. +.SH TRADEMARKS +.B PostScript +is a trademark of Adobe Systems Incorporated. +.SH "SEE ALSO" +.BR psutils (1), +.BR paper (1) diff --git a/upstream/fedora-40/man1/eqn.1 b/upstream/fedora-40/man1/eqn.1 new file mode 100644 index 00000000..0f3d47ba --- /dev/null +++ b/upstream/fedora-40/man1/eqn.1 @@ -0,0 +1,2240 @@ +'\" et +.TH \%eqn 1 "24 January 2024" "groff 1.23.0" +.SH Name +\%eqn \- format mathematics (equations) for +.I groff +or MathML +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_eqn_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.ie \n(.V<\n(.v \ +. ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el \ +. ds tx TeX +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY \%eqn +.RB [ \-CNrR ] +.RB [ \- d +.IR xy ] +.RB [ \-f +.IR F ] +.RB [ \-m +.IR n ] +.RB [ \-M +.IR dir ] +.RB [ \-p +.IR n ] +.RB [ \-s +.IR n ] +.RB [ \-T +.IR dev ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY \%eqn +.B \-\-help +.YS +. +. +.SY \%eqn +.B \-v +. +.SY \%eqn +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU implementation of +.I eqn \" GNU +is part of the +.MR groff 7 +document formatting system. +. +.I \%eqn +is a +.MR \%troff 1 +preprocessor that translates expressions in its own language, +embedded in +.MR roff 7 +input files, +into mathematical notation typeset by +.MR \%troff 1 . +. +It copies each +.IR file 's +contents to the standard output stream, +translating each +.I equation +between lines starting with +.B .EQ +and +.BR .EN , +or within a pair of user-specified delimiters. +. +Normally, +.I \%eqn +is not executed directly by the user, +but invoked by specifying the +.B \-e +option to +.MR groff 1 . +. +While GNU +.IR eqn 's \" GNU +input syntax is highly compatible with AT&T +.IR eqn , \" AT&T +the output +.I \%eqn +produces cannot be processed by AT&T +.IR troff ; \" AT&T +GNU +.I troff \" GNU +(or a +.I troff \" generic +implementing relevant GNU extensions) +must be used. +. +If no +.I file +operands are given on the command line, +or if +.I file +is +.RB \[lq] \- \[rq], +.I \%eqn +reads the standard input stream. +. +. +.P +Unless the +.B \-R +option is used, +.I \%eqn +searches for the file +.I eqnrc +in the directories given with the +.B \-M +option first, +then in +.if !'no'no' .IR /etc/\:\%groff/\:\%site\-tmac , +.IR /etc/\:\%groff/\:\%site\-tmac , +and finally in the standard macro directory +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac . +. +If it exists and is readable, +.I \%eqn +processes it before any input files. +. +. +.P +This man page primarily discusses the differences between GNU +.I eqn \" GNU +and AT&T +.IR eqn .\" AT&T +. +Most of the new features of the GNU +.I eqn \" GNU +input language are based on \*[tx]. +. +There are some references to the differences between \*[tx] and GNU +.I eqn \" GNU +below; +these may safely be ignored if you do not know \*[tx]. +. +. +.P +Three points are worth special note. \" good, bad, and different +. +. +.IP \[bu] 2n +GNU +.I eqn \" GNU +emits Presentation MathML output when invoked with the +.RB \[lq] "\-T\~MathML" \[rq] +option. +. +. +.IP \[bu] +GNU +.I eqn \" GNU +does not support terminal devices well, +though it may suffice for simple inputs. +. +. +.IP \[bu] +GNU +.I eqn +sets the input token +.RB \[lq] .\|.\|.\& \[rq] +as an ellipsis on the text baseline, +not the three centered dots of AT&T +.IR eqn . \" AT&T +. +Set an ellipsis on the math axis with the GNU extension macro +.BR cdots . +. +. +.\" ==================================================================== +.SS "Anatomy of an equation" +.\" ==================================================================== +. +.I eqn +input consists of tokens. +. +Consider a form of Newton's second law of motion. +. +The input +. +. +.P +.RS +.EX +\&.EQ +F = +m a +\&.EN +.EE +.RE +. +. +.P +becomes +.EQ +F = +m a. +.EN +. +Each of +.BR F , +.BR = , +.BR m , +and +.B a +is a token. +. +. +Spaces and newlines are interchangeable; +they separate tokens but do not break lines or produce space in +the output. +. +. +.P +The following input characters not only separate tokens, +but manage their grouping and spacing as well. +. +. +.TP +.B "{ }" +Braces perform grouping. +. +Whereas +.RB \[lq] "e sup a b" \[rq] +expresses +.ie n .RI \[lq]( e "\~to the\~" a )\~times\~ b \[rq], +.el \{\ +.EQ +e sup a b , +.EN +.\} +.RB \[lq] "e sup { a b }" \[rq] +means +.ie n .RI \[lq] e "\~to the\~(" a \~times\~ b )\[rq]. +.el \{\ +.EQ +e sup { a b } . +.EN +.\} +. +When immediately preceded by a +.RB \[lq] left \[rq] +or +.RB \[lq] right \[rq] +primitive, +a brace loses its special meaning. +. +. +.TP +.B "\[ha] \[ti] +are the +.I "half space" +and +.I "full space," +respectively. +. +Use them to tune the appearance of the output. +. +. +.P +Tab and leader characters separate tokens as well as advancing the +drawing position to the next tab stop, +but are seldom used in +.I eqn +input. +. +When they occur, +they must appear at the outermost lexical scope. +. +This roughly means that they can't appear within braces that are +necessary to disambiguate the input; +.I \%eqn +will diagnose an error in this event. +. +(See subsection \[lq]Macros\[rq] below for additional token separation +rules.) +. +. +.P +Other tokens are primitives, +macros, +an argument to either of the foregoing, +or components of an equation. +. +. +.br +.ne 4v +.P +.I Primitives +are fundamental keywords of the +.I eqn +language. +. +They can configure an aspect of the preprocessor's state, +as when setting a \[lq]global\[rq] font selection or type size +.RB ( gfont +and +.BR gsize ), +or declaring or deleting macros +.RB \%(\[lq] define \[rq] +and +.BR undef ); +these are termed +.I commands. +. +Other primitives perform formatting operations on the tokens after them +(as with +.BR fat , +.BR over , +.BR sqrt , +or +.BR up ). +. +. +.P +Equation +.I components +include mathematical variables, +constants, +numeric literals, +and operators. +. +.I \%eqn +remaps some input character sequences to +.I groff +special character escape sequences for economy in equation entry and to +ensure that glyphs from an unstyled font are used; +see +.MR groff_char 7 . +. +. +.P +.RS +.TS +tab(@); +Lf(CR) Lf(CR) Lw(1i) Lf(CR) Lf(CR). ++@\[rs][pl]@\&@\[aq]@\[rs][fm] +-@\[rs][mi]@\&@<=@\[rs][<=] +\&=@\[rs][eq]@\&@>=@\[rs][>=] +.TE +.RE +. +. +.P +.I Macros +permit primitives, +components, +and other macros to be collected and referred to by a single token. +. +Predefined macros make convenient the preparation of +.I eqn +input in a form resembling its spoken expression; +for example, +consider +.BR cos , +.BR hat , +.BR inf , +and +.BR lim . +. +. +.\" ==================================================================== +.SS "Spacing and typeface" +.\" ==================================================================== +. +GNU +.I eqn +imputes types to the components of an equation, +adjusting the spacing between them accordingly. +. +Recognized types are as follows; +most affect spacing only, +whereas the +.RB \%\[lq] letter \[rq] +subtype of +.RB \%\[lq] ordinary \[rq] +also assigns a style. +. +. +.RS 2n \" we need quite a bit of horizontal space for this table +.P +.TS +Lf(CR) Lx +Af(CR) Lx +Af(CR) Lx +Lf(CR) Lx. +ordinary T{ +character such as \[lq]1\[rq], +\[lq]a\[rq], +or +\[lq]!\&\[rq] +T} +letter character to be italicized by default +digit \f[I]n/a\f[] +operator T{ +large operator such as +.ds Su \[lq]\s+5\[*S]\s0\[rq] +.if \n(.g .if !c\[*S] .ds Su the summation operator +\*[Su] +.rm Su +T} +binary binary operator such as \[lq]\[pl]\[rq] +relation relational operator such as \[lq]=\[rq] +opening opening bracket such as \[lq](\[rq] +closing closing bracket such as \[lq])\[rq] +punctuation punctuation character such as \[lq],\[rq] +inner sub-formula contained within brackets +suppress component to which automatic spacing is not applied +.TE +.RE +. +. +.P +Two primitives apply types to equation components. +. +. +.TP +.BI type\~ "t e" +Apply +.RI type\~ t +to +.RI expression\~ e . +. +. +.TP +.BI chartype\~ "t text" +Assign each character in (unquoted) +.I text +.RI type\~ t , +persistently. +. +. +.P +.I \%eqn \" GNU +sets up spacings and styles as if by the following commands. +. +.P +.RS +.TS +tab(@); +Lf(CR)1 Lf(CR). +chartype \[dq]letter\[dq]@abcdefghiklmnopqrstuvwxyz +chartype \[dq]letter\[dq]@ABCDEFGHIKLMNOPQRSTUVWXYZ +chartype \[dq]letter\[dq]@\[rs][*a]\[rs][*b]\[rs][*g]\[rs][*d]\[rs][*e]\ +\[rs][*z] +chartype \[dq]letter\[dq]@\[rs][*y]\[rs][*h]\[rs][*i]\[rs][*k]\[rs][*l]\ +\[rs][*m] +chartype \[dq]letter\[dq]@\[rs][*n]\[rs][*c]\[rs][*o]\[rs][*p]\[rs][*r]\ +\[rs][*s] +chartype \[dq]letter\[dq]@\[rs][*t]\[rs][*u]\[rs][*f]\[rs][*x]\[rs][*q]\ +\[rs][*w] +chartype \[dq]binary\[dq]@*\[rs][pl]\[rs][mi] +chartype \[dq]relation\[dq]@<>\[rs][eq]\[rs][<=]\[rs][>=] +chartype \[dq]opening\[dq]@{([ +chartype \[dq]closing\[dq]@})] +chartype \[dq]punctuation\[dq]@,;:. +chartype \[dq]suppress\[dq]@\[ha]\[ti] +.TE +.RE +. +. +.P +.I \%eqn +assigns all other ordinary and special +.I roff +characters, +including numerals 0\[en]9, +the +.RB \%\[lq] ordinary \[rq] +type. +. +(The +.RB \[lq] digit \[rq] +type is not used, +but is available for customization.) +.\" XXX: How would you actually customize it, though? There doesn't +.\" seem to be a means of replacing the font associated with a type. +.\" Is the "digit" type just cruft? +. +In keeping with common practice in mathematical typesetting, +lowercase, +but not uppercase, +Greek letters are assigned the +.RB \%\[lq] letter \[rq] +type to style them in italics. +. +The macros for producing ellipses, +.RB \[lq] .\|.\|. \[rq], +.BR cdots , +and +.BR ldots , +use the +.RB \%\[lq] inner \[rq] +type. +. +. +.\" ==================================================================== +.SS Primitives +.\" ==================================================================== +. +.I \%eqn +supports without alteration the AT&T +.I eqn \" AT&T +primitives +.BR above , +.BR back , +.BR bar , +.BR bold , +.BR \%define , +.BR down , +.BR fat , +.BR font , +.BR from , +.BR fwd , +.BR gfont , +.BR gsize , +.BR italic , +.BR left , +.BR lineup , +.BR mark , +.BR \%matrix , +.BR \%ndefine , +.BR over , +.BR right , +.BR roman , +.BR size , +.BR sqrt , +.BR sub , +.BR sup , +.BR \%tdefine , +.BR to , +.BR \%under , +and +.BR up . +. +. +.\" ==================================================================== +.SS "New primitives" +.\" ==================================================================== +. +The GNU extension primitives +.RB \[lq] type \[rq] +and +.B \%chartype +are discussed in subsection \[lq]Spacing and typeface\[rq] above; +.RB \[lq] set \[rq] +in subsection \[lq]Customization\[rq] below; +and +.B grfont +and +.B gbfont +in subsection \[lq]Fonts\[rq] below. +. +In the following synopses, +.I X +can be any character not appearing in the parameter thus bracketed. +. +. +.TP +.IB e1 \~accent\~ e2 +Set +.I e2 +as an accent over +.IR e1 . +. +.I e2 +is assumed to be at the appropriate height for a lowercase letter +without an ascender; +.I \% eqn +vertically shifts it depending on +.IR e1 's +height. +. +For example, +.B hat +is defined as follows. +. +. +.RS +.IP +.EX +accent { "\[ha]" } +.EE +.RE +. +. +.IP +.BR dotdot , +.BR dot , +.BR tilde , +.BR vec , +and +.B dyad +are also defined using the +.B \%accent +primitive. +. +. +.TP +.BI big\~ e +Enlarge the expression +.IR e ; +semantics like those of CSS \[lq]large\[rq] are intended. +. +In +.I \%troff +output, +the type size is increased by\~5 scaled points. +. +MathML output emits the following. +. +. +.RS +.IP +.EX + +.EE +.RE +. +. +.TP +.BI copy\~ file +.TQ +.BI include\~ file +Interpolate the contents of +.IR file , +omitting lines +beginning with +.B .EQ +or +.BR .EN . +. +If a relative path name, +.I file +is sought relative to the current working directory. +. +. +.TP +.BI ifdef\~ "name X anything X" +If +.I name +is defined as a primitive or macro, +interpret +.IR anything . +. +. +.TP +.BI nosplit\~ text +As +.RI \[dq] text \[dq], +but since +.I text +is not quoted it is subject to macro expansion; +it is not split up and the spacing between characters not adjusted per +subsection \[lq]Spacing and typeface\[rq] above. +. +. +.TP +.IB e\~ opprime +As +.BR prime , +but set the prime symbol as an operator +.RI on\~ e . +. +In the input +.RB \[lq] "A opprime sub 1" \[rq], +the\~\[lq]1\[rq] is tucked under the prime as a subscript to +the\~\[lq]A\[rq] +(as is conventional in mathematical typesetting), +whereas when +.B prime +is used, +the\~\[lq]1\[rq] is a subscript to the prime character. +. +The precedence of +.B \%opprime +is the same as that of +.B bar +and +.RB \%\[lq] under \[rq], +and higher than that of other primitives except +.B \%accent +and +.BR uaccent . +. +In unquoted text, +a neutral apostrophe +.RB ( \[aq] ) +that is not the first character on the input line is treated like +.BR \%opprime . +. +. +.TP +.BI sdefine\~ "name X anything X" +As +.RB \%\[lq] define \[rq], +but +.I name +is not recognized as a macro if called with arguments. +. +. +.TP +.IB e1 \~smallover\~ e2 +As +.BR over , +but reduces the type size of +.I e1 +and +.IR e2 , +and puts less vertical space between +.I e1 +and +.I e2 +and the fraction bar. +. +The +.B over +primitive corresponds to the \*[tx] +.B \[rs]over +primitive in displayed equation styles; +.B smallover +corresponds to +.B \[rs]over +in non-display (\[lq]inline\[rq]) styles. +. +. +.br +.ne 5v +.TP +.BI space\~ n +Set extra vertical spacing around the equation, +replacing the default values, +where +.IR n \~is +an integer in hundredths of an em. +. +If positive, +.IR n \~increases +vertical spacing before the equation; +if negative, +it does so after the equation. +. +This primitive provides an interface to +.IR groff 's +.B \[rs]x +escape sequence, +but with the opposite sign convention. +. +It has no effect if the equation is part of a +.MR \%pic 1 +picture. +. +. +.TP +.BI special\~ "troff-macro e" +Construct an object by calling +.I troff-macro +.RI on\~ e . +. +The +.I troff \" generic +string +.B 0s +contains the +.I eqn \" generic +output +.RI for\~ e , +and the registers +.BR 0w , +.BR 0h , +.BR 0d , +.BR 0skern , +and +.B 0skew +the width, +height, +depth, +subscript kern, +and skew +.RI of\~ e , +respectively. +. +(The +.I subscript kern +of an object indicates how much a subscript on that object should be +\[lq]tucked in\[rq], +or placed to the left relative to a non-subscripted glyph of the same +size. +. +The +.I skew +of an object is how far to the right of the center of the object an +accent over it should be placed.) +. +The macro must modify +.B 0s +so that it outputs the desired result, +returns the drawing position to the text baseline at the beginning of +.IR e , +and updates the foregoing registers to correspond to the new dimensions +of the result. +. +. +.IP +Suppose you want a construct that \[lq]cancels\[rq] an expression by +drawing a diagonal line through it. +. +. +.br +.ne 11v +.RS +.IP +.EX +\&.de Ca +\&. ds 0s \[rs] +\[rs]Z\[aq]\[rs]\[rs]*(0s\[aq]\[rs] +\[rs]v\[aq]\[rs]\[rs]n(0du\[aq]\[rs] +\[rs]D\[aq]l \[rs]\[rs]n(0wu \-\[rs]\[rs]n(0hu\-\[rs]\ +\[rs]n(0du\[aq]\[rs] +\[rs]v\[aq]\[rs]\[rs]n(0hu\[aq] +\&.. +\&.EQ +special Ca "x \[rs][mi] 3 \[rs][pl] x" \[ti] 3 +\&.EN +.EE +.RE +. +. +.IP +We use the +.B \[rs][mi] +and +.B \[rs][pl] +special characters instead of + and \- +because they are part of the argument to a +.I \%troff +macro, +so +.I \%eqn +does not transform them to mathematical glyphs for us. +. +Here's a more complicated construct that draws a box around an +expression; +the bottom of the box rests on the text baseline. +. +We define the +.I eqn \" generic +macro +.B box +to wrap the call of the +.I \%troff +macro +.BR Bx . +. +. +.br +.ne 17v +.RS +.IP +.EX +\&.de Bx +\&.ds 0s \[rs] +\[rs]Z\[aq]\[rs]\[rs]h\[aq]1n\[aq]\[rs]\[rs]*[0s]\[aq]\[rs] +\[rs]v\[aq]\[rs]\[rs]n(0du+1n\[aq]\[rs] +\[rs]D\[aq]l \[rs]\[rs]n(0wu+2n 0\[aq]\[rs] +\[rs]D\[aq]l 0 \-\[rs]\[rs]n(0hu\-\[rs]\[rs]n(0du\-2n\[aq]\[rs] +\[rs]D\[aq]l \-\[rs]\[rs]n(0wu\-2n 0\[aq]\[rs] +\[rs]D\[aq]l 0 \[rs]\[rs]n(0hu+\[rs]\[rs]n(0du+2n\[aq]\[rs] +\[rs]h\[aq]\[rs]\[rs]n(0wu+2n\[aq] +\&.nr 0w +2n +\&.nr 0d +1n +\&.nr 0h +1n +\&.. +\&.EQ +define box \[aq] special Bx $1 \[aq] +box(foo) \[ti] "bar" +\&.EN +.EE +.RE +. +. +.TP +.BI "split \[dq]" text \[dq] +As +.IR text , +but since +.I text +is quoted, +it is not subject to macro expansion; +it is split up and the spacing between characters adjusted per +subsection \[lq]Spacing and typeface\[rq] above. +. +. +.TP +.IB e1 \~uaccent\~ e2 +Set +.I e2 +as an accent under +.IR e1 . +. +.I e2 +is assumed to be at the appropriate height for a letter without a +descender; +.I \% eqn +vertically shifts it depending on whether +.I e1 +has a descender. +. +.B utilde +is predefined using +.B uaccent +as a tilde accent below the baseline. +. +. +.TP +.BI undef\~ name +Remove definition of macro or primitive +.IR name , +making it undefined. +. +. +.TP +.BI vcenter\~ e +Vertically center +.I e +about the +.IR "math axis" , +a horizontal line upon which fraction bars and characters such as +\[lq]\[pl]\[rq] and \[lq]\[mi]\[rq] are aligned. +. +MathML already behaves this way, +so +.I \%eqn +ignores this primitive when producing that output format. +. +The built-in +.B sum +macro is defined as if by the following. +. +.RS +.IP +.EX +define sum ! { type "operator" vcenter size +5 \[rs](*S } ! +.EE +.RE +. +. +.br +.ne 8v +.\" ==================================================================== +.SS "Extended primitives" +.\" ==================================================================== +. +GNU +.I eqn \" GNU +extends the syntax of some AT&T +.I eqn \" AT&T +primitives, +introducing one deliberate incompatibility. +. +. +.TP +.B "delim on" +.I \%eqn +recognizes an +.RB \[lq] on \[rq] +argument to the +.B \%delim +primitive specially, +restoring any delimiters previously disabled with +.RB \%\[lq] "delim off" \[rq]. +. +If delimiters haven't been specified, +neither command has effect. +. +Few +.I eqn \" generic +documents are expected to use \[lq]o\[rq] and \[lq]n\[rq] as left and +right delimiters, +respectively. +. +If yours does, +consider swapping them, +or select others. +. +. +.TP +.BI col\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI ccol\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI lcol\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI rcol\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI pile\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI cpile\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI lpile\~ n\~\c +.BR {\~ .\|.\|.\& \~} +.TQ +.BI rpile\~ n\~\c +.BR {\~ .\|.\|.\& \~} +The integer +.RI value\~ n +(in hundredths of an em) +increases the vertical spacing between rows, +using +.IR groff 's +.B \[rs]x +escape sequence +(the value has no effect in MathML mode). +. +Negative values are accepted but have no effect. +. +If more than one +.I n +occurs in a matrix or pile, +the largest is used. +. +. +.\" ==================================================================== +.SS Customization +.\" ==================================================================== +. +When +.I \%eqn +generates +.I \%troff +input, +the appearance of equations is controlled by a large number of +parameters. +. +They have no effect when generating MathML, +which delegates typesetting to a MathML rendering engine. +. +Configure these parameters with the +.B set +primitive. +. +. +.TP +.BI set\~ "p n" +assigns +.RI parameter\~ p +the integer +.RI value\~ n ; +.IR n \~is +interpreted in units of hundredths of an em unless otherwise stated. +. +For example, +. +. +.RS +.IP +.EX +set x_height 45 +.EE +.RE +. +. +.IP +says that +.I \%eqn +should assume that the font's x-height is 0.45\~ems. +. +. +.RS +.P +Available parameters are as follows; +defaults are shown in parentheses. +. +We intend these descriptions to be expository rather than rigorous. +. +. +.TP 17n +.B minimum_size +sets a floor for the type size +(in scaled points) +at which equations are set +.RB ( 5 ). +. +. +.TP +.B fat_offset +The +.B fat +primitive emboldens an equation by overprinting two copies of the +equation horizontally offset by this amount +.RB ( 4 ). +. +In MathML mode, +components to which +.B \%fat_offset +applies instead use the following. +. +.RS +.RS +.EX + +.EE +.RE +.RE +. +. +.TP +.B over_hang +A fraction bar is longer by twice this amount than +the maximum of the widths of the numerator and denominator; +in other words, +it overhangs the numerator and denominator by at least this amount +.RB ( 0 ). +. +. +.TP +.B accent_width +When +.B bar +or +.B \%under +is applied to a single character, +the line is this long +.RB ( 31 ). +. +Normally, +.B bar +or +.B \%under +produces a line whose length is the width of the object to which it +applies; +in the case of a single character, +this tends to produce a line that looks too long. +. +. +.TP +.B delimiter_factor +Extensible delimiters produced with the +.B left +and +.B right +primitives have a combined height and depth of at least this many +thousandths of twice the maximum amount by which the sub-equation that +the delimiters enclose extends away from the axis +.RB ( 900 ). +. +. +.TP +.B delimiter_shortfall +Extensible delimiters produced with the +.B left +and +.B right +primitives have a combined height and depth not less than the +difference of twice the maximum amount by which the sub-equation that +the delimiters enclose extends away from the axis and this amount +.RB ( 50 ). +. +. +.TP +.B null_delimiter_space +This much horizontal space is inserted on each side of a fraction +.RB ( 12 ). +. +. +.TP +.B script_space +The width of subscripts and superscripts is increased by this amount +.RB ( 5 ). +. +. +.TP +.B thin_space +This amount of space is automatically inserted after punctuation +characters. +. +It also configures the width of the space produced by the +.B \[ha] +token +.RB ( 17 ). +. +. +.TP +.B medium_space +This amount of space is automatically inserted on either side of +binary operators +.RB ( 22 ). +. +. +.TP +.B thick_space +This amount of space is automatically inserted on either side of +relations. +. +It also configures the width of the space produced by the +.B \[ti] +token +.RB ( 28 ). +. +. +.TP +.B x_height +The height of lowercase letters without ascenders such as \[lq]x\[rq] +.RB ( 45 ). +. +. +.TP +.B axis_height +The height above the baseline of the center of characters such as +\[lq]\[pl]\[rq] and \[lq]\[mi]\[rq] +.RB ( 26 ). +. +It is important that this value is correct for the font +you are using. +. +. +.TP +.B default_rule_thickness +This should be set to the thickness of the +.B \[rs][ru] +character, +or the thickness of horizontal lines produced with the +.B \[rs]D +escape sequence +.RB ( 4 ). +. +. +.TP +.B num1 +The +.B over +primitive shifts up the numerator by at least this amount +.RB ( 70 ). +. +. +.TP +.B num2 +The +.B smallover +primitive shifts up the numerator by at least this amount +.RB ( 36 ). +. +. +.TP +.B denom1 +The +.B over +primitive shifts down the denominator by at least this amount +.RB ( 70 ). +. +. +.TP +.B denom2 +The +.B smallover +primitive shifts down the denominator by at least this amount +.RB ( 36 ). +. +. +.TP +.B sup1 +Normally superscripts are shifted up by at least this amount +.RB ( 42 ). +. +. +.TP +.B sup2 +Superscripts within superscripts or upper limits +or numerators of +.B smallover +fractions are shifted up by at least this amount +.RB ( 37 ). +. +Conventionally, +this is less than +.BR sup1 . +. +. +.TP +.B sup3 +Superscripts within denominators or square roots +or subscripts or lower limits are shifted up by at least +this amount +.RB ( 28 ). +. +Conventionally, +this is less than +.BR sup2 . +. +. +.TP +.B sub1 +Subscripts are normally shifted down by at least this amount +.RB ( 20 ). +. +. +.TP +.B sub2 +When there is both a subscript and a superscript, +the subscript is shifted down by at least this amount +.RB ( 23 ). +. +. +.TP +.B sup_drop +The baseline of a superscript is no more than this much below the top of +the object on which the superscript is set +.RB ( 38 ). +. +. +.TP +.B sub_drop +The baseline of a subscript is at least this much below the bottom of +the object on which the subscript is set +.RB ( 5 ). +. +. +.TP +.B big_op_spacing1 +The baseline of an upper limit is at least this much above the top of +the object on which the limit is set +.RB ( 11 ). +. +. +.TP +.B big_op_spacing2 +The baseline of a lower limit is at least this much below the bottom +of the object on which the limit is set +.RB ( 17 ). +. +. +.TP +.B big_op_spacing3 +The bottom of an upper limit is at least this much above the top of +the object on which the limit is set +.RB ( 20 ). +. +. +.TP +.B big_op_spacing4 +The top of a lower limit is at least this much below the bottom of the +object on which the limit is set +.RB ( 60 ). +. +. +.TP +.B big_op_spacing5 +This much vertical space is added above and below limits +.RB ( 10 ). +. +. +.TP +.B baseline_sep +The baselines of the rows in a pile or matrix are normally this far +apart +.RB ( 140 ). +. +Usually equal to the sum of +.B num1 +and +.BR denom1 . +. +. +.TP +.B shift_down +The midpoint between the top baseline and the bottom baseline in a +matrix or pile is shifted down by this much from the axis +.RB ( 26 ). +. +Usually equal to +.BR axis_height . +. +. +.TP +.B column_sep +This much space is added between columns in a matrix +.RB ( 100 ). +. +. +.TP +.B matrix_side_sep +This much space is added at each side of a matrix +.RB ( 17 ). +. +. +.br +.ne 4v +.TP +.B draw_lines +If non-zero, +.I \%eqn +draws lines using the +.I troff \" generic +.B \[rs]D +escape sequence, +rather than the +.B \[rs]l +escape sequence and the +.B \[rs][ru] +special character. +. +The +.I eqnrc +file sets the default: +.BR 1 \~on +.BR ps , +.BR html , +and the X11 devices, +.RB otherwise\~ 0 . +. +. +.TP +.B body_height +is the presumed height of an equation above the text baseline; +.I \%eqn +adds any excess as extra pre-vertical line spacing with +.IR troff 's\" generic +.B \[rs]x +escape sequence +.RB ( 85 ). +. +. +.TP +.B body_depth +is the presumed depth of an equation below the text baseline; +.I \%eqn +adds any excess as extra post-vertical line spacing with +.IR troff 's\" generic +.B \[rs]x +escape sequence +.RB ( 35 ). +. +. +.TP +.B nroff +If non-zero, +then +.B \%ndefine +behaves like +.B \%define +and +.B \%tdefine +is ignored, +otherwise +.B \%tdefine +behaves like +.B \%define +and +.B \%ndefine +is ignored. +. +The +.I eqnrc +file sets the default: +.BR 1 \~on +.BR ascii , +.BR latin1 , +.BR utf8 , +and +.B cp1047 +devices, +.RB otherwise\~ 0 . +.RE +. +. +.\" ==================================================================== +.SS Macros +.\" ==================================================================== +. +In GNU +.IR eqn , \" GNU +macros can take arguments. +. +A word defined by any of the +.BR \%define , +.BR \%ndefine , +or +.B \%tdefine +primitives followed immediately by a left parenthesis is treated as a +.I "parameterized macro call:" +subsequent tokens up to a matching right parenthesis are treated as +comma-separated arguments. +. +In this context only, +commas and parentheses also serve as token separators. +. +A macro argument is not terminated by a comma inside parentheses nested +within it. +. +In a macro definition, +.BI $ n\c +, +where +.I n +is between 1 and\~9 inclusive, +is replaced by the +.IR n th +argument; +if there are fewer than +.IR n \~arguments, +it is replaced by nothing. +. +. +.\" ==================================================================== +.SS "Predefined macros" +.\" ==================================================================== +. +GNU +.I eqn \" GNU +supports the predefined macros offered by AT&T +.IR eqn : \" AT&T +.BR and , +.BR \%approx , +.BR arc , +.BR cos , +.BR cosh , +.BR del , +.BR det , +.BR dot , +.BR \%dotdot , +.BR dyad , +.BR exp , +.BR for , +.BR grad , +.BR half , +.BR hat , +.BR if , +.BR \%inter , +.BR Im , +.BR inf , +.BR int , +.BR lim , +.BR ln , +.BR log , +.BR max , +.BR min , +.BR \%nothing , +.BR \%partial , +.BR prime , +.BR prod , +.BR Re , +.BR sin , +.BR sinh , +.BR sum , +.BR tan , +.BR tanh , +.BR tilde , +.BR times , +.BR union , +.BR vec , +.BR == , +.BR != , +.BR += , +.BR \-> , +.BR <\- , +.BR << , +.BR >> , +and +.RB \[lq] .\|.\|. \[rq]. +. +The lowercase classical Greek letters are available as +.BR \%alpha , +.BR beta , +.BR chi , +.BR delta , +.BR \%epsilon , +.BR eta , +.BR gamma , +.BR iota , +.BR kappa , +.BR lambda , +.BR mu , +.BR nu , +.BR omega , +.BR \%omicron , +.BR phi , +.BR pi , +.BR psi , +.BR rho , +.BR sigma , +.BR tau , +.BR theta , +.BR \%upsilon , +.BR xi , +and +.BR zeta . +. +Spell them with an initial capital letter +.RB \%( Alpha ) +or in full capitals +.RB \%( ALPHA ) +to obtain uppercase forms. +. +. +.P +GNU +.I eqn \" GNU +further defines the macros +.BR cdot , +.BR cdots , +and +.B utilde +(all discussed above), +.BR \%dollar , +which sets a dollar sign, +and +.BR ldots , +which sets an ellipsis on the text baseline. +. +. +.\" ==================================================================== +.SS Fonts +.\" ==================================================================== +. +.I \%eqn +uses up to three typefaces to set an equation: +italic (oblique), +roman (upright), +and bold. +. +Assign each a +.I groff +typeface with the primitives +.BR gfont , +.BR \%grfont , +and +.B \%gbfont. +. +The defaults are the styles +.BR I , +.BR R , +and +.B B +(applied to the current font family). +. +The +.B \%chartype +primitive +(see above) +sets a character's type, +which determines the face used to set it. +. +The +.RB \%\[lq] letter \[rq] +type is set in italics; +others are set in roman. +. +Use the +.B bold +primitive to select an (upright) bold style. +. +. +.TP +.BI gbfont\~ f +.RI Select\~ f +as the bold font. +. +This is a GNU extension. +. +. +.TP +.BI gfont\~ f +.RI Select\~ f +as the italic font. +. +. +.TP +.BI grfont\~ f +.RI Select\~ f +as the roman font. +. +This is a GNU extension. +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-C +Recognize +.B .EQ +and +.B .EN +even when followed by a character other than space or newline. +. +. +.TP +.BI \-d\~ xy +Specify delimiters +.I x +for left +.RI and\~ y +for right ends +of equations not bracketed by +.BR .EQ / .EN . +. +.I x +and +.I y +need not be distinct. +. +Any +.RB \%\[lq] delim +.IR xy \[rq] +statements in the source file override this option. +. +. +.TP +.BI \-f\~ F +is equivalent to +.RB \[lq] gfont +.IR F \[rq]. +. +. +.TP +.BI \-m\~ n +is equivalent to +.RB \[lq] "set \%minimum_size" +.IR n \[rq]. +. +. +.TP +.BI \-M\~ dir +Search +.I dir +for +.I eqnrc +before those listed in section \[lq]Description\[rq] above. +. +. +.TP +.B \-N +Prohibit newlines within delimiters. +. +This option allows +.I \%eqn +to recover better from missing closing delimiters. +. +. +.TP +.BI \-p\~ n +Set sub- and superscripts +.IR n \~points +smaller than the surrounding text. +. +This option is deprecated. +. +.I \%eqn +normally sets sub- and superscripts at 70% of the type size of the +surrounding text. +. +. +.TP +.B \-r +Reduce the type size of subscripts at most once relative to the base +type size for the equation. +. +. +.TP +.B \-R +Don't load +.IR eqnrc . +. +. +.TP +.BI \-s\~ n +is equivalent to +.RB \[lq] gsize +.IR n \[rq]. +. +This option is deprecated. +. +. +.TP +.BI \-T\~ dev +Prepare output for the device +.IR dev . +. +In most cases, +the effect of this is to define a macro +.I dev +with a value +.RB of\~ 1 ; +.I eqnrc +uses this to provide definitions appropriate for the device. +. +However, +if the specified driver is \[lq]MathML\[rq], +the output is MathML markup rather than +.I \%troff +input, +and +.I eqnrc +is not loaded at all. +. +The default output device is +.BR \%ps . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%eqnrc +Initialization file. +. +. +.\" ==================================================================== +.SH "MathML mode limitations" +.\" ==================================================================== +. +MathML is designed on the assumption that it cannot know the exact +physical characteristics of the media and devices on which it will +be rendered. +. +It does not support control of motions and sizes to the same +degree +.I \%troff +does. +. +. +.IP \[bu] 2n +.I \%eqn +customization parameters have no effect on generated MathML. +. +. +.IP \[bu] +The +.BR \%special , +.BR up , +.BR down , +.BR fwd , +and +.B back +primitives cannot be implemented, +and yield a MathML \%\[lq]\[rq] message instead. +. +. +.IP \[bu] +The +.B vcenter +primitive is silently ignored, +as centering on the math axis is the MathML default. +. +. +.IP \[bu] +Characters that +.I \%eqn +sets extra large in +.I troff \" mode +mode\[em]notably the integral sign\[em]may appear too small and need to +have their \[lq]\[rq] wrappers adjusted by hand. +. +. +.P +As in its +.I troff \" mode +mode, +.I \%eqn +in MathML mode leaves the +.B .EQ +and +.B .EN +tokens in place, +but emits nothing corresponding to +.B \%delim +delimiters. +. +They can, +however, +be recognized as character sequences that begin with \[lq]\[rq], +end with \[lq]\[rq], +and do not cross line boundaries. +. +. +.\" ==================================================================== +.SH Caveats +.\" ==================================================================== +. +Tokens must be double-quoted in +.I eqn \" generic +input if they are not to be recognized as names of macros or primitives, +or if they are to be interpreted by +.IR troff . \" generic +. +In particular, +short ones, +like +.RB \[lq] pi \[rq] +and +.RB \[lq] PI \[rq], +can collide with +.I troff \" generic +identifiers. +. +For instance, +the +.I eqn \" generic +command +.RB \%\[lq]\^ "gfont PI" \^\[rq] +does not select +.IR groff 's +Palatino italic font for the global italic face; +you must use +.RB \%\[lq]\^ "gfont \[dq]PI\[dq]" \^\[rq] +instead. +. +. +.P +Delimited equations are set at the type size current at the beginning of +the input line, +not necessarily that immediately preceding the opening delimiter. +. +. +.P +Unlike \*[tx], +.I eqn \" generic +does not inherently distinguish displayed and inline equation styles; +see the +.B smallover +primitive above. +. +However, +macro packages frequently define +.B EQ +and +.B EN +macros such that the equation within is displayed. +. +These macros may accept arguments permitting the equation to be labeled +or captioned; +see the package's documentation. +. +. +.\" ==================================================================== +.SH Bugs +.\" ==================================================================== +. +.I eqn \" generic +abuses terminology\[em]its +\[lq]equations\[rq] +can be inequalities, +bare expressions, +or unintelligible gibberish. +. +But there's no changing it now. +. +. +.P +In +.I nroff \" mode +mode, +lowercase Greek letters are rendered in roman instead of italic style. +. +. +.P +In MathML mode, +the +.B mark +and +.B lineup +features don't work. +. +These could, +in theory, +be implemented with \%\[lq]\[rq] elements. +. +. +.P +In MathML mode, +each digit of a numeric literal gets a separate \[lq]\:\[rq] +pair, +and decimal points are tagged with \[lq]\:\[rq]. +. +This is allowed by the specification, +but inefficient. +. +. +.\" ==================================================================== +.SH Examples +.\" ==================================================================== +. +We first illustrate +.I \%eqn +usage with a trigonometric identity. +. +. +.RS +.P +.EX +\&.EQ +sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta +\&.EN +.EE +.if t \{\ +. +. +.P +.RS +.EQ +sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta +.EN +.RE +.\} +.RE +. +. +.P +It can be convenient to set up delimiters if mathematical content will +appear frequently in running text. +. +. +.RS +.P +.EX +\&.EQ +delim $$ +\&.EN +. +Having cached a table of logarithms, +the property $ln ( x y ) = ln x + ln y$ sped calculations. +.EE +.if t \{\ +. +. +.P +.RS +.EQ +delim $$ +.EN +. +Having cached a table of logarithms, +the property $ln ( x y ) = ln x + ln y$ sped calculations. +. +.\" We _must_ shut delimiters back off when serially processing man +.\" pages, or subsequent documents cannot safely use those characters. +.EQ +delim off +.EN +.RE +.\} +.RE +. +. +.P +The quadratic formula illustrates use of fractions and radicals, +and affords an opportunity to use the full space token +.BR \[ti] . +. +. +.RS +.P +.EX +\&.EQ +x = { \- b \[ti] \[rs][+\-] \[ti] sqrt { b sup 2 \- 4 a c } } \ +over { 2 a } +\&.EN +.EE +.if t \{\ +. +. +.P +.RS +.EQ +x = { - b ~ \[+-] ~ sqrt { b sup 2 - 4 a c } } over { 2 a } +.EN +.RE +.\} +.RE +. +. +.P +Alternatively, +we could define the plus-minus sign as a binary operator. +. +Automatic spacing puts 0.06\~em less space on either side of the +plus-minus than \[ti] does, +this being the difference between the widths of the +.B medium_space +parameter used by binary operators and that of the full space. +. +Independently, +we can define a macro \[lq]frac\[rq] for setting fractions. +. +. +.RS +.P +.EX +\&.EQ +chartype "binary" \[rs][+\-] +define frac ! { $1 } over { $2 } ! +x = frac(\- b \[rs][+\-] sqrt { b sup 2 \- 4 a c }, 2 a) +\&.EN +.EE +.if t \{\ +. +. +.P +.RS +.EQ +chartype "binary" \[+-] +define frac ! { $1 } over { $2 } ! +x = frac(- b \[+-] sqrt { b sup 2 - 4 a c }, 2 a) +.EN +.RE +.\} +.RE +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +\[lq]Typesetting Mathematics\[em]User's Guide\[rq] +(2nd edition), +by Brian W.\& Kernighan +and Lorinda L.\& Cherry, +1978, +AT&T Bell Laboratories Computing Science Technical Report No.\& 17. +. +. +.P +.IR The\~\*[tx]book , +by Donald E.\& Knuth, +1984, +Addison-Wesley Professional. +. +Appendix\~G +discusses many of the parameters from section \[lq]Customization\[rq] +above in greater detail. +. +. +.P +.MR groff_char 7 , +particularly subsections \[lq]Logical symbols\[rq], +\[lq]Mathematical symbols\[rq], +and \[lq]Greek glyphs\[rq], +documents a variety of special character escape sequences useful in +mathematical typesetting. +. +. +.P +.MR groff 1 , +.MR \%troff 1 , +.MR \%pic 1 , +.MR groff_font 5 +. +. +.\" Clean up. +.rm tx +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_eqn_1_man_C] +.do rr *groff_eqn_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" tab-width: 12 +.\" End: +.\" vim: set filetype=groff tabstop=12 textwidth=72: diff --git a/upstream/fedora-40/man1/eqn2graph.1 b/upstream/fedora-40/man1/eqn2graph.1 new file mode 100644 index 00000000..fd24128d --- /dev/null +++ b/upstream/fedora-40/man1/eqn2graph.1 @@ -0,0 +1,188 @@ +.TH eqn2graph 1 "24 January 2024" "groff 1.23.0" +.SH Name +eqn2graph \- convert an +.I eqn \" generic +equation into a cropped image +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" This documentation is released to the public domain. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_eqn2graph_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY eqn2graph +.RB [ \-format\~\c +.IR output-format ] +.RI [ convert-argument \~.\|.\|.] +.YS +. +. +.SY eqn2graph +.B \-\-help +.YS +. +. +.SY eqn2graph +.B \-v +. +.SY eqn2graph +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I eqn2graph +reads a one-line +.MR \%eqn 1 +equation from the standard input and writes an image file, +by default in Portable Network Graphics (PNG) format, +to the standard output. +. +. +.PP +The input EQN code should +.I not +be preceded by the +.B .EQ +macro that normally precedes it within +.MR groff 1 +macros; +nor do you need to have dollar-sign or other delimiters around the +equation. +. +. +.\" FIXME: How old? This text hasn't been touched since 2008 at latest. +.\" Older versions of +.\" .I \%convert +.\" will produce a black-on-white graphic; newer ones may produce a +.\" black-on-transparent graphic. +. +.PP +Arguments not recognized by +.I eqn2graph +are passed to the ImageMagick or GraphicsMagick program +.MR convert 1 . +. +. +By specifying these, you can give your image a border, +.\" Transparent backgrounds are the default in 2018. +.\" force the background transparent, +set the image's pixel density, +or perform other useful transformations. +. +. +.PP +The output image is clipped using +.IR \%convert 's +.B \-trim +option to the smallest possible bounding box that contains all the black +pixels. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-format\~ output-format +Write the image in +.IR output-format , +which must be understood by +.IR \%convert ; +the default is PNG. +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I \%GROFF_TMPDIR +.TQ +.I \%TMPDIR +.TQ +.I TMP +.TQ +.I TEMP +These environment variables are searched in the given order to determine +the directory where temporary files will be created. +. +If none are set, +.I /tmp +is used. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +.I eqn2graph +was written by +.MT esr@\:thyrsus\:.com +Eric S.\& Raymond +.ME , +based on a recipe for +.MR pic2graph 1 , +by W.\& Richard Stevens. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR pic2graph 1 , +.MR grap2graph 1 , +.MR \%eqn 1 , +.MR groff 1 , +.MR convert 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_eqn2graph_1_man_C] +.do rr *groff_eqn2graph_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/escp2topbm.1 b/upstream/fedora-40/man1/escp2topbm.1 new file mode 100644 index 00000000..926edaf7 --- /dev/null +++ b/upstream/fedora-40/man1/escp2topbm.1 @@ -0,0 +1,96 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Escp2topbm User Manual" 0 "14 July 2015" "netpbm documentation" + +.SH NAME + +escp2topbm - convert an ESC/P2 printer file to a PBM image + +.UN synopsis +.SH SYNOPSIS + +\fBescp2topbm\fP +[\fIprintfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBescp2topbm\fP reads an ESC/P2 printer control stream as input. +It produces a PBM image as output. +.PP +\fBescp2topbm\fP filters the raster graphic content from an Epson +ESC/P2 printer control stream and writes the image it would print as a +standard (raw) PBM image. +.PP +The input is from the file named by the \fIprintfile\fP argument, or +from Standard Input if you don't specify \fIprintfile\fP. The output is +to Standard Output. +.PP +\fBescp2topbm\fP understands compression modes 0 (uncompressed) +and 1 (RLE compressed) in the Epson input stream. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBescp2topbm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) +.PP +Before Netpbm 10.72 (September 2015), the Netpbm common option +\fB-plain\fP has no effect on \fBescp2topbm\fP . + +.UN hints +.SH HINTS +.PP +As \fBescp2topbm\fP is a simple program, created mainly to test +\fBpbmtoescp2\fP, there are some restrictions: + + +.IP \(bu +\fBescp2topbm\fP looks only at "ESC." sequences and ignores +all data outside these Escape sequences. + +.IP \(bu +\fBescp2topbm\fP assumes that only one raster graphic is in the +printer stream. If this isn't true, the result is garbage. + +.IP \(bu +\fBescp2topbm\fP assumes that all "ESC." sequences use the same +width value. If this isn't true, the result is garbage. + + +.UN seealso +.SH SEE ALSO +.BR "pbmtoescp2" (1)\c +\&, +.BR "pbm" (1)\c +\& + +.UN author +.SH AUTHOR +.PP +Copyright (C) 2003 by Ulrich Walcher +(\fIu.walcher@gmx.de\fP). + +.UN history +.SH HISTORY +.PP +\fBescp2topbm\fP was added to Netpbm in Release 10.18 (August 2003); +it was created around the same time. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/escp2topbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/exif.1 b/upstream/fedora-40/man1/exif.1 new file mode 100644 index 00000000..9029211a --- /dev/null +++ b/upstream/fedora-40/man1/exif.1 @@ -0,0 +1,237 @@ +.\" Copyright © 2002-2012 by Thomas Pircher (tehpeh at gmx dot net), +.\" Dan Fandrich et. al. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.TH exif 1 "2012-07-13" "exif 0.6.21.1" "command line front-end to libexif" +.SH "NAME" +exif \- shows EXIF information in JPEG files +.SH "SYNOPSIS" +.BI "exif [ " "OPTION" " ] [ " "file..." " ]" +.SH DESCRIPTION +.B "exif" +is a small command-line utility to show and change EXIF information in JPEG +files. +.PP +Most digital cameras produce EXIF files, which are JPEG files with extra tags +that contain information about the image. The +.B "exif" +command-line utility allows you to read EXIF information from and write EXIF +information to those files. +.B "exif" +internally uses the +.B "libexif" +library. +.PP +Each input file given on the command line is acted upon in turn, using +all the options given. Execution will be aborted immediately if one +file is not readable or does not contain EXIF tags. +.PP +As EXIF tags are read, any unknown ones are discarded and known ones are +automatically converted into the correct format, if they aren't already. +Corrupted MakerNote tags are also removed, but no format changes are made. +.SH "OPTIONS" +.TP +.BI "\-v, \-\-version" +Display the +.B exif +version number. +.TP +.BI "\-i, \-\-ids" +Show ID numbers instead of tag names. +.TP +.BI "\-t, \-\-tag=" "TAG" +Select only this +.IR "TAG" . +.I "TAG" +is the tag title, the short tag name, or the tag number +(hexadecimal numbers are prefixed with 0x), from the IFD specified +with \-\-ifd. The tag title is dependent on the current locale, whereas +name and number are locale-independent. +.TP +.BI "\-\-ifd=" "IFD" +Select a tag or tags from this +.IR "IFD" . +Valid IFDs are "0", "1", "EXIF", "GPS", and "Interoperability". +Defaults to "0". +.TP +.BI "\-l, \-\-list\-tags" +List all known EXIF tags and IFDs. A JPEG image must be provided, and +those tags which appear in the file are shown with an asterisk in the +corresponding position in the list. +.TP +.BI "\-|, \-\-show\-mnote" +Show the contents of the MakerNote tag. The contents of this tag are nonstandard +(and often undocumented) and may therefore not be recognized, or if they are +recognized they may not necessarily be interpreted correctly. +.TP +.BI "\-\-remove" +Remove the tag or (if no tag is specified) the entire IFD. +.TP +.BI "\-s, \-\-show\-description" +Show description of tag. The \-\-tag option must also be given. +.TP +.BI "\-e, \-\-extract\-thumbnail" +Extract the thumbnail, writing the thumbnail image to the file specified +with \-\-output. +.TP +.BI "\-r, \-\-remove\-thumbnail" +Remove the thumbnail from the image, writing the new image to the file specified +with \-\-output. +.TP +.BI "-n, \-\-insert\-thumbnail=" "FILE" +Insert +.I "FILE" +as thumbnail. No attempt is made to ensure that the contents of +.I "FILE" +are in a valid thumbnail format. +.TP +.BI "\-\-no-fixup" +Do not attempt to fix EXIF specification violations when reading tags. +When used in conjunction with \-\-create-exif, this option inhibits the +creation of the mandatory tags. +.B exif +will otherwise remove illegal or unknown tags, add some mandatory tags using +default values, and change the data type of some tags to match that required +by the specification. +.TP +.BI "\-o, \-\-output=" "FILE" +Write output image to +.IR "FILE" . +If this option is not given and an image file must be written, the +name used is the same as the input file with the suffix ".modified.jpeg". +.TP +.BI "\-\-set\-value=" "VALUE" +Set the data for the tag specified with \-\-tag and \-\-ifd to +.IR "VALUE" . +Compound values consisting of multiple components are separated with +spaces. +.TP +.BI "\-c, \-\-create-exif" +Create EXIF data if it does not exist. Mandatory tags are created with +default values unless the \-\-no-fixup option is given. +This option can be used instead of specifying an input file name in most +cases, to operate on the default values of the mandatory set of EXIF tags. +In this case, the \-\-output option has no effect and no file is written. +.TP +.BI "\-m, \-\-machine\-readable" +Produce output in a machine-readable (tab-delimited) format. +The \-\-xml-output and \-\-machine\-readable options are mutually exclusive. +.TP +.BI "\-w, \-\-width=" "N" +Set the maximum width of the output to N characters (default 80). This does +not apply to some output formats (e.g. XML). +.TP +.BI "\-x, \-\-xml-output" +Produce output in an XML format (when possible). +The \-\-xml-output and \-\-machine\-readable options are mutually exclusive. +Note that the XML schema changes with the locale, and it sometimes produces +invalid XML. This option is not recommended. +.TP +.BI "\-d, \-\-debug" +Show debugging messages. Also, when processing a file that contains corrupted +data, this option causes +.B exif +to attempt to continue processing. Normally, +corrupted data causes an abort. +.SS "Help options" +.TP +.BI "\-?, \-\-help" +Show help message. +.TP +.BI "\-\-usage" +Display brief usage message. +.SH "EXAMPLES" +Display all recognized EXIF tags in an image and the tag contents, with bad +tags fixed: +.LP +.RS +exif image.jpg +.RE +.LP +Display a table listing all known EXIF tags and whether each one exists in the +given image: +.LP +.RS +exif \-\-list-tags \-\-no-fixup image.jpg +.RE +.LP +Display details on all XResolution tags found in the given image: +.LP +.RS +exif \-\-tag=XResolution \-\-no-fixup image.jpg +.RE +.LP +Display the raw contents of the "Model" tag in the given image (with a newline +character appended): +.LP +.RS +exif \-\-ifd=0 \-\-tag=Model \-\-machine-readable image.jpg +.RE +.LP +Extract the thumbnail into the file thumbnail.jpg: +.LP +.RS +exif \-\-extract-thumbnail \-\-output=thumbnail.jpg image.jpg +.RE +.LP +Display a list of the numeric values of only the EXIF tags in the thumbnail IFD +(IFD 1) and the tag values: +.LP +.RS +exif \-\-ids \-\-ifd=1 \-\-no-fixup image.jpg +.RE +.LP +Display the meaning of tag 0x9209 in the "EXIF" IFD according to the EXIF +specification: +.LP +.RS +exif \-\-show-description \-\-ifd=EXIF \-\-tag=0x9209 +.RE +.LP +Add an Orientation tag with value "Bottom-left" (4) to an existing image, +leaving the existing tags untouched: +.LP +.RS +exif \-\-output=new.jpg \-\-ifd=0 \-\-tag=0x0112 \-\-set-value=4 \-\-no-fixup image.jpg +.RE +.LP +Add a YCbCr Sub-Sampling tag with value 2,1 (a.k.a YCbCr 4:2:2) to an +existing image and fix the existing tags, if necessary: +.LP +.RS +exif \-\-output=new.jpg \-\-tag=YCbCrSubSampling \-\-ifd=0 \-\-set-value='2 1' image.jpg +.RE +.LP +Remove the "User Comment" tag from an image: +.LP +.RS +exif \-\-output=new.jpg \-\-remove \-\-tag="User Comment" \-\-ifd=EXIF image.jpg +.RE +.LP +Display a table with all known EXIF tags, highlighting mandatory ones: +.LP +.RS +exif \-cl +.RE +.LP +.SH "AUTHOR" +.B exif +was written by Lutz Mueller +and numerous contributors. +This man page is Copyright \(co 2002-2012 Thomas Pircher, +Dan Fandrich and others. +.SH "SEE ALSO" +.UR "https://libexif.github.io/" +.BR "https://libexif.github.io/" diff --git a/upstream/fedora-40/man1/expand.1 b/upstream/fedora-40/man1/expand.1 new file mode 100644 index 00000000..09ab207c --- /dev/null +++ b/upstream/fedora-40/man1/expand.1 @@ -0,0 +1,54 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH EXPAND "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +expand \- convert tabs to spaces +.SH SYNOPSIS +.B expand +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Convert tabs in each FILE to spaces, writing to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-i\fR, \fB\-\-initial\fR +do not convert tabs after non blanks +.TP +\fB\-t\fR, \fB\-\-tabs\fR=\fI\,N\/\fR +have tabs N characters apart, not 8 +.TP +\fB\-t\fR, \fB\-\-tabs\fR=\fI\,LIST\/\fR +use comma separated list of tab positions. +The last specified position can be prefixed with '/' +to specify a tab size to use after the last +explicitly specified tab stop. Also a prefix of '+' +can be used to align remaining tab stops relative to +the last specified tab stop instead of the first column +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBunexpand\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) expand invocation\(aq diff --git a/upstream/fedora-40/man1/expr.1 b/upstream/fedora-40/man1/expr.1 new file mode 100644 index 00000000..81acdfc1 --- /dev/null +++ b/upstream/fedora-40/man1/expr.1 @@ -0,0 +1,107 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH EXPR "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +expr \- evaluate expressions +.SH SYNOPSIS +.B expr +\fI\,EXPRESSION\/\fR +.br +.B expr +\fI\,OPTION\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Print the value of EXPRESSION to standard output. A blank line below +separates increasing precedence groups. EXPRESSION may be: +.TP +ARG1 | ARG2 +ARG1 if it is neither null nor 0, otherwise ARG2 +.TP +ARG1 & ARG2 +ARG1 if neither argument is null or 0, otherwise 0 +.TP +ARG1 < ARG2 +ARG1 is less than ARG2 +.TP +ARG1 <= ARG2 +ARG1 is less than or equal to ARG2 +.TP +ARG1 = ARG2 +ARG1 is equal to ARG2 +.TP +ARG1 != ARG2 +ARG1 is unequal to ARG2 +.TP +ARG1 >= ARG2 +ARG1 is greater than or equal to ARG2 +.TP +ARG1 > ARG2 +ARG1 is greater than ARG2 +.TP +ARG1 + ARG2 +arithmetic sum of ARG1 and ARG2 +.TP +ARG1 \- ARG2 +arithmetic difference of ARG1 and ARG2 +.TP +ARG1 * ARG2 +arithmetic product of ARG1 and ARG2 +.TP +ARG1 / ARG2 +arithmetic quotient of ARG1 divided by ARG2 +.TP +ARG1 % ARG2 +arithmetic remainder of ARG1 divided by ARG2 +.TP +STRING : REGEXP +anchored pattern match of REGEXP in STRING +.TP +match STRING REGEXP +same as STRING : REGEXP +.TP +substr STRING POS LENGTH +substring of STRING, POS counted from 1 +.TP +index STRING CHARS +index in STRING where any CHARS is found, or 0 +.TP +length STRING +length of STRING +.TP ++ TOKEN +interpret TOKEN as a string, even if it is a +.IP +keyword like 'match' or an operator like '/' +.TP +( EXPRESSION ) +value of EXPRESSION +.PP +Beware that many operators need to be escaped or quoted for shells. +Comparisons are arithmetic if both ARGs are numbers, else lexicographical. +Pattern matches return the string matched between \e( and \e) or null; if +\e( and \e) are not used, they return the number of characters matched or 0. +.PP +Exit status is 0 if EXPRESSION is neither null nor 0, 1 if EXPRESSION is null +or 0, 2 if EXPRESSION is syntactically invalid, and 3 if an error occurred. +.SH AUTHOR +Written by Mike Parker, James Youngman, and Paul Eggert. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) expr invocation\(aq diff --git a/upstream/fedora-40/man1/extractres.1 b/upstream/fedora-40/man1/extractres.1 new file mode 100644 index 00000000..51f9330a --- /dev/null +++ b/upstream/fedora-40/man1/extractres.1 @@ -0,0 +1,70 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.1. +.TH EXTRACTRES "1" "February 2023" "extractres 2.10" "User Commands" +.SH NAME +extractres - extract resources from a PostScript document +.SH SYNOPSIS +.B extractres +[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]] +.SH DESCRIPTION +Extract resources from a PostScript document. +.TP +\fB\-m\fR, \fB\-\-merge\fR +merge resources of the same name into one file +(needed e.g. for fonts output in multiple blocks) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +display version information and exit +.PP +.B extractres +extracts resources (fonts, procsets, patterns, files, etc) appearing in a +PostScript document, and puts appropriate +.B %%IncludeResource +comments in the document prologue. +The extracted resources are written to files with the same name as the +resource, and an appropriate extension. +The pipeline +.sp +.RS +extractres file.ps | includeres >out.ps +.RE +.sp +will move all resources appearing in a document to the document prologue, +removing redundant copies. +The output file can then be put through page re-arrangement filters such as +.B psnup +or +.B pstops +safely. + +.SS "Exit status:" +.TP +0 +if OK, +.TP +1 +if arguments or options are incorrect, or there is some other problem +starting up, +.TP +2 +if there is some problem during processing, typically an error reading or +writing an input or output file. +.SH AUTHOR +Written by Angus J. C. Duggan and Reuben Thomas. +.SH BUGS +.B extractres +does not alter the +.B %%DocumentSuppliedResources +comments. +.SH COPYRIGHT +Copyright \(co Reuben Thomas 2012\-2022. +.br +Copyright \(co Angus J. C. Duggan 1991\-1997. +.SH TRADEMARKS +.B PostScript +is a trademark of Adobe Systems Incorporated. +.SH "SEE ALSO" +.BR psutils (1), +.BR paper (1) diff --git a/upstream/fedora-40/man1/eyuvtoppm.1 b/upstream/fedora-40/man1/eyuvtoppm.1 new file mode 100644 index 00000000..0e400b86 --- /dev/null +++ b/upstream/fedora-40/man1/eyuvtoppm.1 @@ -0,0 +1,74 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Eyuvtoppm User Manual" 0 "22 April 2001" "netpbm documentation" + +.SH NAME +eyuvtoppm - convert a Berkeley YUV file to a PPM file + +.UN synopsis +.SH SYNOPSIS + +\fBeyuvtoppm\fP +[\fB--width\fP +\fIwidth\fP] +[\fB--height\fP +\fIheight\fP] +[\fIeyuvfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBeyuvtoppm\fP reads a Berkeley Encoder YUV (not the same as +Abekas YUV) file as input and produces a PPM image on Standard Output. +.PP +With no filename argument takes input from Standard Input. +Otherwise, \fIeyuvfile \fP is the file specification of the input +file. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBeyuvtoppm\fP recognizes the following +command line options: + + + +.TP +\fB--width\fP \fIwidth\fP +Width of the image, in pixels. Must be an even number. + +.TP +\fB--height\fP \fIheight\fP +Height of the image, in pixels. Must be an even number. + + +.PP +These options are mandatory. + + +.UN seealso +.SH SEE ALSO +.BR "ppmtoeyuv" (1)\c +\&, +.BR "yuvtoppm" (1)\c +\&, +.BR "ppm" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/eyuvtoppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/factor.1 b/upstream/fedora-40/man1/factor.1 new file mode 100644 index 00000000..8269dd99 --- /dev/null +++ b/upstream/fedora-40/man1/factor.1 @@ -0,0 +1,37 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH FACTOR "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +factor \- factor numbers +.SH SYNOPSIS +.B factor +[\fI\,OPTION\/\fR] [\fI\,NUMBER\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print the prime factors of each specified integer NUMBER. If none +are specified on the command line, read them from standard input. +.TP +\fB\-h\fR, \fB\-\-exponents\fR +print repeated factors in form p^e unless e is 1 +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by Paul Rubin, Torbjorn Granlund, and Niels Moller. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) factor invocation\(aq diff --git a/upstream/fedora-40/man1/false.1 b/upstream/fedora-40/man1/false.1 new file mode 100644 index 00000000..86e83d05 --- /dev/null +++ b/upstream/fedora-40/man1/false.1 @@ -0,0 +1,40 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH FALSE "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +false \- do nothing, unsuccessfully +.SH SYNOPSIS +.B false +[\fI\,ignored command line arguments\/\fR] +.br +.B false +\fI\,OPTION\/\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Exit with a status code indicating failure. +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +NOTE: your shell may have its own version of false, which usually supersedes +the version described here. Please refer to your shell's documentation +for details about the options it supports. +.SH AUTHOR +Written by Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) false invocation\(aq diff --git a/upstream/fedora-40/man1/faxformat.1 b/upstream/fedora-40/man1/faxformat.1 new file mode 100644 index 00000000..3749d8d7 --- /dev/null +++ b/upstream/fedora-40/man1/faxformat.1 @@ -0,0 +1,105 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Fax Formats" 1 "03 December 2008" "netpbm documentation" + +.SH SYNOPSIS +.PP +This page, part of the +.BR "Netpbm user's guide" (1)\c +\&, +describes FAX formats in relation to Netpbm facilities. + +.SH DESCRIPTION +.PP +The ITU (formerly CCITT) publishes standards for operation of fax machines +(the idea is to provide a way to be sure that a fax machine is able to receive +a fax sent by another). These standards incidentally specify graphics file +formats -- a protocol for representing a visual image in sequences of bits. +.PP +The two relevant standards are called Group 3 (G3) and Group 4 (G4) (Groups +1 and 2 are analog standards no longer in use). Virtually every fax machine +in existence conforms at least generally to at least one of these standards. +.PP +The standard for Group 3 fax is defined in ITU Recommendation T.4. In the +U.S., that is implemented by EIA standards EIA-465 and EIA-466. These +standards cover more than the file format as well, including how to transmit +bits over a telephone line and procedures for handling document transmissions. +.PP +G3 faxes are 204 dots per inch (dpi) horizontally and 98 dpi (196 +dpi optionally, in fine-detail mode) vertically. +.PP +The standards specify three file formats (also called coding methods and +compression schemes -- remember the standard doesn't mention computer files; +it talks about the format of a stream of bits travelling over a telephone +line): + + + +.TP +MH +This compresses in one dimension: it compresses individual raster lines +but makes no attempt to compress redundancy between lines. +.sp +One dimensional compression is traditionally the best a fax machine could +handle because G3 neither assumes error free transmission not retransmits when +errors occur, and receiving fax machines traditionally could not afford to +buffer much of a page. It's important that when there is an error in a raster +line, its impact not spread to many lines after it. +.sp +All Group 3 and Group 4 fax machines must be able to send and receive MH. +.sp +MH is sometimes called "G3," but that is a poor name because +while the Group 3 standard does specify MH, it has always specified other +formats too. +.sp +MH is sometimes called "T4" based on the name of the +document that specifies it, ITU T.4. But this is a poor name because +T.4 also specifies MR. + + +.TP +MR +This compresses in two dimensions, horizontally and vertically. +.sp +MR has always been part of the Group 3 standard, but is optional +(a Group 3 fax machine may or may not be able to send and receive it). + +.TP +MMR +This is a more advanced format than the others. It is even more +two-dimensional than MR. It is optional in the Group 3 standard, and didn't +even exist in earlier versions of it. It was developed specifically for the +Group 4 standard, but then added to an extended Group 3 standard as well. +.sp +MMR is sometimes called Group 4, but that is a poor name because of +the fact that it is also part of the current Group 3 standard. +.sp +MMR is sometimes called "T6" based on the name of the document + that specifies it, ITU T.6. + + +.PP +\fBg3topbm\fP converts the MH format to PBM. \fBpbmtog3\fP converts +PBM to MH. +.PP +There is no Netpbm program to convert to or from other fax formats. + +.SH TIFF +.PP +The TIFF format is flexible enough to allow lots of different coding +methods, within it. There are TIFF subformats for MH, MR, and MMR, among +others. These are particularly useful when you receive a fax as a TIFF file. +.PP +\fBtifftopnm\fP recognizes and can convert from any of these. +.PP +\fBpamtotiff\fP can convert to any of these; you use command options +to choose which. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/faxformat.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/fgconsole.1 b/upstream/fedora-40/man1/fgconsole.1 new file mode 100644 index 00000000..12965a57 --- /dev/null +++ b/upstream/fedora-40/man1/fgconsole.1 @@ -0,0 +1,50 @@ +.TH FGCONSOLE 1 "14 February 2002" "kbd" + +.SH NAME +fgconsole \- print the number of the active VT. + +.SH SYNOPSIS +.B fgconsole +[ +.B \-h \-\-help +| +.B \-V \-\-version +| +.B \-n \-\-next-available +] +.SH DESCRIPTION +If the active Virtual Terminal is +.IR /dev/ttyN , +then prints +.I N +on standard output. + +If the console is a serial console, then +"serial" +is printed instead. +.TP +.I \-h \-\-help +Prints short usage message and exits. +.TP +.I \-V \-\-version +Prints version number and exits. +.TP +.I \-\-next\-available +Will show the next unallocated virtual terminal. Normally 6 virtual +terminals are allocated, with number 7 used for X; this will return +"8" in this case. + +.SH NOTES +Under +.IR devfs , +the consoles are in +.IR /dev/vc/N . +.I devfsd +may maintain symlinks for compatibility. +.SH "SEE ALSO" +.BR chvt (1). +.\" .SH "AUTHORS" +.\" Andries Brouwer +.\" .br +.\" Manpage by Alastair McKinstry + diff --git a/upstream/fedora-40/man1/fiascotopnm.1 b/upstream/fedora-40/man1/fiascotopnm.1 new file mode 100644 index 00000000..e57945c6 --- /dev/null +++ b/upstream/fedora-40/man1/fiascotopnm.1 @@ -0,0 +1,231 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Fiascotopnm User Manual" 0 "12 July 2000" "netpbm documentation" + +.SH NAME +fiascotopnm - Convert compressed FIASCO image to PGM, or PPM + +.UN synopsis +.SH SYNOPSIS + +\fBfiascotopnm \fP +[\fIoption\fP]... +[\fIfilename\fP]... +.PP +All option names may be abbreviated; for example, --output may be +written --outp or --ou. For all options an one letter short option +is provided. Mandatory or optional arguments to long options are +mandatory or optional for short options, too. Both short and long +options are case sensitive. + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBfiascotopnm\fP decompresses the named FIASCO files, or the +Standard Input if no file is named, and writes the images as PGM, or +PPM files, depending on whether the FIASCO image is black and white or +color. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBfiascotopnm\fP recognizes the following +command line options: + + +.TP +\fB-o\fP[\fIname\fP], \fB--output=\fP[\fIname\fP] + Write decompressed image to the file \fIname\fP.ppm (if PPM) or +\fIname\fP.pgm (if PGM). If \fIname\fP is \fB-\fP, then produce +the image file on the standard output. The optional argument +\fIname\fP can be omitted, then the input filename is used as +basename with the suffix .ppm or .pgm. In case of video streams, the +frames are stored in the files \fIname\fP.\fBN\fP.ppm where \fBN\fP +is the frame number (of the form 00..0 - 99..9); output on the +standard output is not possible with video streams. +.sp + If \fIname\fP is a relative path and the environment variable +\fBFIASCO_IMAGES\fP is a (colon-separated) list of directories, then +the output file(s) are written to the first (writable) directory of +this list. Otherwise, the current directory is used to store the +output file(s). + +.TP +\fB-r\fP, \fB--fast\fP +Decompress images in the 4:2:0 format; i.e., each chroma channel is +decompressed to an image of halved width and height. Use this option +on slow machines when the desired frame rate is not achieved; the +output quality is only slightly decreased. + +.TP +\fB-d\fP, \fB--double\fP +Double the size of the X11 window both in width and height; no pixel +interpolation is used, each pixel is just replaced by four identical +pixels. + +.TP +\fB-p\fP, \fB--panel\fP +Show a panel with play, stop, pause, record and exit buttons to +control the display of videos. When pressing the record button, all +frames are decompressed and stored in memory. The other buttons work +in the usual way. + +.TP +\fB-m\fP \fIN\fP, \fB--magnify=\fP\fIN\fP +Set magnification of the decompressed image. Positive values enlarge +and negative values reduce the image width and height by a factor of +2^|\fIN\fP|. + +.TP +\fB-s\fP \fIN\fP, \fB--smoothing=\fP\fIN\fP +Smooth decompressed image(s) along the partitioning borders by the +given amount \fIN\fP. \fIN\fP is 1 (minimum) to 100 (maximum); default +is 70. When \fIN\fP=0, then the smoothing amount specified in the +FIASCO file is used (defined by the FIASCO coder). + +.TP +\fB-F\fP \fIN\fP, \fB--framerate=\fP\fIN\fP +Set number of frames per second to \fIN\fP. When using this option, +the frame rate specified in the FIASCO file is overridden. + +.TP +\fB--verbose=\fP\fIN\fP +Set verbose of \fBfiascotopnm\fP to \fIN\fP. + +.TP +\fB-v\fP, \fB--version\fP +Print \fBfiascotopnm\fP version number, then exit. + +.TP +\fB-f\fP \fIname\fP, \fB--config=\fP\fIname\fP +Load parameter file \fIname\fP to initialize the options of +\fBfiascotopnm\fP. See file \fBsystem.fiascorc\fP for an example of +the syntax. Options of \fBfiascotopnm \fP are set by any of the +following methods (in the specified order): + + +.IP \(bu +Global ressource file \fB/etc/system.fiascorc\fP + +.IP \(bu +$HOME\fB/.fiascorc\fP + +.IP \(bu +command line + +.IP \(bu +--config=\fIname\fP + + +.TP +\fB-h\fP, \fB--help\fP +Print help, then exit. + + + + +.UN examples +.SH EXAMPLES + +.nf +fiascotopnm foo.wfa >foo.ppm + +.fi +.PP +Decompress the FIASCO file "foo.wfa" and store it as +"foo.ppm". + +.nf +fiascotopnm -o foo1.wfa foo2.wfa + +.fi +.PP +Decompress the FIASCO files "foo1.wfa" and +"foo2.wfa" and write the frames to the image files +"foo1.wfa.ppm" and "foo2.wfa.ppm". + +.nf +fiascotopnm -oimage foo1.wfa + +.fi +.PP +Decompress the FIASCO file "foo1.wfa" and write all 15 +frames to the image files "image.00.ppm", ... , +"image.14.ppm". + +.nf +fiascotopnm --fast --magnify=-1 --double video.wfa >stream.ppm + +.fi +.PP +Decompress the FIASCO file "video.wfa". The +decompression speed is as fast as possible: the image is decompressed +(in 4:2:0 format) at a quarter of its original size; then the image is +enlarged again by pixel doubling. + +.UN files +.SH FILES + + +.TP +\fB/etc/system.fiascorc\fP +The systemwide initialization file. + +.TP +$HOME\fB/.fiascorc\fP +The personal initialization file. + + + +.UN environment +.SH ENVIRONMENT + + +.TP +\fBFIASCO_IMAGES\fP +Save path for image files. Default is "./". + +.TP +\fBFIASCO_DATA\fP +Search path for FIASCO files. Default is "./". + + + + +.UN seealso +.SH SEE ALSO +.BR "pnmtofiasco" (1)\c +\&, +.BR "pnm" (1)\c +\& +.PP +Ullrich Hafner, Juergen Albert, Stefan Frank, and Michael Unger. +\fBWeighted Finite Automata for Video Compression\fP, IEEE Journal on +Selected Areas In Communications, January 1998 +Ullrich Hafner. \fBLow Bit-Rate Image and Video Coding with Weighted +Finite Automata\fP, Ph.D. thesis, Mensch & Buch Verlag, ISBN +3-89820-002-7, October 1999. + +.UN author +.SH AUTHOR + +Ullrich Hafner <\fIhafner@bigfoot.de\fP> +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/fiascotopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/file.1 b/upstream/fedora-40/man1/file.1 new file mode 100644 index 00000000..0af0b893 --- /dev/null +++ b/upstream/fedora-40/man1/file.1 @@ -0,0 +1,743 @@ +.\" $File: file.man,v 1.150 2023/05/21 17:08:34 christos Exp $ +.Dd May 21, 2023 +.Dt FILE 1 +.Os +.Sh NAME +.Nm file +.Nd determine file type +.Sh SYNOPSIS +.Nm +.Bk -words +.Op Fl bcdEhiklLNnprsSvzZ0 +.Op Fl Fl apple +.Op Fl Fl exclude-quiet +.Op Fl Fl extension +.Op Fl Fl mime-encoding +.Op Fl Fl mime-type +.Op Fl e Ar testname +.Op Fl F Ar separator +.Op Fl f Ar namefile +.Op Fl m Ar magicfiles +.Op Fl P Ar name=value +.Ar +.Ek +.Nm +.Fl C +.Op Fl m Ar magicfiles +.Nm +.Op Fl Fl help +.Sh DESCRIPTION +This manual page documents version 5.45 of the +.Nm +command. +.Pp +.Nm +tests each argument in an attempt to classify it. +There are three sets of tests, performed in this order: +filesystem tests, magic tests, and language tests. +The +.Em first +test that succeeds causes the file type to be printed. +.Pp +The type printed will usually contain one of the words +.Em text +(the file contains only +printing characters and a few common control +characters and is probably safe to read on an +.Dv ASCII +terminal), +.Em executable +(the file contains the result of compiling a program +in a form understandable to some +.Tn UNIX +kernel or another), +or +.Em data +meaning anything else (data is usually +.Dq binary +or non-printable). +Exceptions are well-known file formats (core files, tar archives) +that are known to contain binary data. +When modifying magic files or the program itself, make sure to +.Em preserve these keywords . +Users depend on knowing that all the readable files in a directory +have the word +.Dq text +printed. +Don't do as Berkeley did and change +.Dq shell commands text +to +.Dq shell script . +.Pp +The filesystem tests are based on examining the return from a +.Xr stat 2 +system call. +The program checks to see if the file is empty, +or if it's some sort of special file. +Any known file types appropriate to the system you are running on +(sockets, symbolic links, or named pipes (FIFOs) on those systems that +implement them) +are intuited if they are defined in the system header file +.In sys/stat.h . +.Pp +The magic tests are used to check for files with data in +particular fixed formats. +The canonical example of this is a binary executable (compiled program) +.Dv a.out +file, whose format is defined in +.In elf.h , +.In a.out.h +and possibly +.In exec.h +in the standard include directory. +These files have a +.Dq magic number +stored in a particular place +near the beginning of the file that tells the +.Tn UNIX +operating system +that the file is a binary executable, and which of several types thereof. +The concept of a +.Dq magic number +has been applied by extension to data files. +Any file with some invariant identifier at a small fixed +offset into the file can usually be described in this way. +The information identifying these files is read from the compiled +magic file +.Pa /usr/share/misc/magic.mgc , +or the files in the directory +.Pa /usr/share/misc/magic +if the compiled file does not exist. +In addition, if +.Pa $HOME/.magic.mgc +or +.Pa $HOME/.magic +exists, it will be used in preference to the system magic files. +.Pp +If a file does not match any of the entries in the magic file, +it is examined to see if it seems to be a text file. +ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets +(such as those used on Macintosh and IBM PC systems), +UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC +character sets can be distinguished by the different +ranges and sequences of bytes that constitute printable text +in each set. +If a file passes any of these tests, its character set is reported. +ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified +as +.Dq text +because they will be mostly readable on nearly any terminal; +UTF-16 and EBCDIC are only +.Dq character data +because, while +they contain text, it is text that will require translation +before it can be read. +In addition, +.Nm +will attempt to determine other characteristics of text-type files. +If the lines of a file are terminated by CR, CRLF, or NEL, instead +of the Unix-standard LF, this will be reported. +Files that contain embedded escape sequences or overstriking +will also be identified. +.Pp +Once +.Nm +has determined the character set used in a text-type file, +it will +attempt to determine in what language the file is written. +The language tests look for particular strings (cf. +.In names.h ) +that can appear anywhere in the first few blocks of a file. +For example, the keyword +.Em .br +indicates that the file is most likely a +.Xr troff 1 +input file, just as the keyword +.Em struct +indicates a C program. +These tests are less reliable than the previous +two groups, so they are performed last. +The language test routines also test for some miscellany +(such as +.Xr tar 1 +archives, JSON files). +.Pp +Any file that cannot be identified as having been written +in any of the character sets listed above is simply said to be +.Dq data . +.Sh OPTIONS +.Bl -tag -width indent +.It Fl Fl apple +Causes the +.Nm +command to output the file type and creator code as +used by older MacOS versions. +The code consists of eight letters, +the first describing the file type, the latter the creator. +This option works properly only for file formats that have the +apple-style output defined. +.It Fl b , Fl Fl brief +Do not prepend filenames to output lines (brief mode). +.It Fl C , Fl Fl compile +Write a +.Pa magic.mgc +output file that contains a pre-parsed version of the magic file or directory. +.It Fl c , Fl Fl checking-printout +Cause a checking printout of the parsed form of the magic file. +This is usually used in conjunction with the +.Fl m +option to debug a new magic file before installing it. +.It Fl d +Prints internal debugging information to stderr. +.It Fl E +On filesystem errors (file not found etc), instead of handling the error +as regular output as POSIX mandates and keep going, issue an error message +and exit. +.It Fl e , Fl Fl exclude Ar testname +Exclude the test named in +.Ar testname +from the list of tests made to determine the file type. +Valid test names are: +.Bl -tag -width compress +.It apptype +.Dv EMX +application type (only on EMX). +.It ascii +Various types of text files (this test will try to guess the text +encoding, irrespective of the setting of the +.Sq encoding +option). +.It encoding +Different text encodings for soft magic tests. +.It tokens +Ignored for backwards compatibility. +.It cdf +Prints details of Compound Document Files. +.It compress +Checks for, and looks inside, compressed files. +.It csv +Checks Comma Separated Value files. +.It elf +Prints ELF file details, provided soft magic tests are enabled and the +elf magic is found. +.It json +Examines JSON (RFC-7159) files by parsing them for compliance. +.It soft +Consults magic files. +.It simh +Examines SIMH tape files. +.It tar +Examines tar files by verifying the checksum of the 512 byte tar header. +Excluding this test can provide more detailed content description by using +the soft magic method. +.It text +A synonym for +.Sq ascii . +.El +.It Fl Fl exclude-quiet +Like +.Fl Fl exclude +but ignore tests that +.Nm +does not know about. +This is intended for compatibility with older versions of +.Nm . +.It Fl Fl extension +Print a slash-separated list of valid extensions for the file type found. +.It Fl F , Fl Fl separator Ar separator +Use the specified string as the separator between the filename and the +file result returned. +Defaults to +.Sq \&: . +.It Fl f , Fl Fl files-from Ar namefile +Read the names of the files to be examined from +.Ar namefile +(one per line) +before the argument list. +Either +.Ar namefile +or at least one filename argument must be present; +to test the standard input, use +.Sq - +as a filename argument. +Please note that +.Ar namefile +is unwrapped and the enclosed filenames are processed when this option is +encountered and before any further options processing is done. +This allows one to process multiple lists of files with different command line +arguments on the same +.Nm +invocation. +Thus if you want to set the delimiter, you need to do it before you specify +the list of files, like: +.Dq Fl F Ar @ Fl f Ar namefile , +instead of: +.Dq Fl f Ar namefile Fl F Ar @ . +.It Fl h , Fl Fl no-dereference +This option causes symlinks not to be followed +(on systems that support symbolic links). +This is the default if the environment variable +.Dv POSIXLY_CORRECT +is not defined. +.It Fl i , Fl Fl mime +Causes the +.Nm +command to output mime type strings rather than the more +traditional human readable ones. +Thus it may say +.Sq text/plain; charset=us-ascii +rather than +.Dq ASCII text . +.It Fl Fl mime-type , Fl Fl mime-encoding +Like +.Fl i , +but print only the specified element(s). +.It Fl k , Fl Fl keep-going +Don't stop at the first match, keep going. +Subsequent matches will be +have the string +.Sq "\[rs]012\- " +prepended. +(If you want a newline, see the +.Fl r +option.) +The magic pattern with the highest strength (see the +.Fl l +option) comes first. +.It Fl l , Fl Fl list +Shows a list of patterns and their strength sorted descending by +.Xr magic 5 +strength +which is used for the matching (see also the +.Fl k +option). +.It Fl L , Fl Fl dereference +This option causes symlinks to be followed, as the like-named option in +.Xr ls 1 +(on systems that support symbolic links). +This is the default if the environment variable +.Ev POSIXLY_CORRECT +is defined. +.It Fl m , Fl Fl magic-file Ar magicfiles +Specify an alternate list of files and directories containing magic. +This can be a single item, or a colon-separated list. +If a compiled magic file is found alongside a file or directory, +it will be used instead. +.It Fl N , Fl Fl no-pad +Don't pad filenames so that they align in the output. +.It Fl n , Fl Fl no-buffer +Force stdout to be flushed after checking each file. +This is only useful if checking a list of files. +It is intended to be used by programs that want filetype output from a pipe. +.It Fl p , Fl Fl preserve-date +On systems that support +.Xr utime 3 +or +.Xr utimes 2 , +attempt to preserve the access time of files analyzed, to pretend that +.Nm +never read them. +.It Fl P , Fl Fl parameter Ar name=value +Set various parameter limits. +.Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" +.Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent +.It Sy "Name" Ta Sy "Default" Ta Sy "Explanation" +.It Li bytes Ta 1M Ta max number of bytes to read from file +.It Li elf_notes Ta 256 Ta max ELF notes processed +.It Li elf_phnum Ta 2K Ta max ELF program sections processed +.It Li elf_shnum Ta 32K Ta max ELF sections processed +.It Li encoding Ta 65K Ta max number of bytes to determine encoding +.It Li indir Ta 50 Ta recursion limit for indirect magic +.It Li name Ta 50 Ta use count limit for name/use magic +.It Li regex Ta 8K Ta length limit for regex searches +.El +.It Fl r , Fl Fl raw +Don't translate unprintable characters to \eooo. +Normally +.Nm +translates unprintable characters to their octal representation. +.It Fl s , Fl Fl special-files +Normally, +.Nm +only attempts to read and determine the type of argument files which +.Xr stat 2 +reports are ordinary files. +This prevents problems, because reading special files may have peculiar +consequences. +Specifying the +.Fl s +option causes +.Nm +to also read argument files which are block or character special files. +This is useful for determining the filesystem types of the data in raw +disk partitions, which are block special files. +This option also causes +.Nm +to disregard the file size as reported by +.Xr stat 2 +since on some systems it reports a zero size for raw disk partitions. +.It Fl S , Fl Fl no-sandbox +On systems where libseccomp +.Pa ( https://github.com/seccomp/libseccomp ) +is available, the +.Fl S +option disables sandboxing which is enabled by default. +This option is needed for +.Nm +to execute external decompressing programs, +i.e. when the +.Fl z +option is specified and the built-in decompressors are not available. +On systems where sandboxing is not available, this option has no effect. +.It Fl v , Fl Fl version +Print the version of the program and exit. +.It Fl z , Fl Fl uncompress +Try to look inside compressed files. +.It Fl Z , Fl Fl uncompress-noreport +Try to look inside compressed files, but report information about the contents +only not the compression. +.It Fl 0 , Fl Fl print0 +Output a null character +.Sq \e0 +after the end of the filename. +Nice to +.Xr cut 1 +the output. +This does not affect the separator, which is still printed. +.Pp +If this option is repeated more than once, then +.Nm +prints just the filename followed by a NUL followed by the description +(or ERROR: text) followed by a second NUL for each entry. +.It Fl -help +Print a help message and exit. +.El +.Sh ENVIRONMENT +The environment variable +.Ev MAGIC +can be used to set the default magic file name. +If that variable is set, then +.Nm +will not attempt to open +.Pa $HOME/.magic . +.Nm +adds +.Dq Pa .mgc +to the value of this variable as appropriate. +The environment variable +.Ev POSIXLY_CORRECT +controls (on systems that support symbolic links), whether +.Nm +will attempt to follow symlinks or not. +If set, then +.Nm +follows symlink, otherwise it does not. +This is also controlled by the +.Fl L +and +.Fl h +options. +.Sh FILES +.Bl -tag -width /usr/share/misc/magic.mgc -compact +.It Pa /usr/share/misc/magic.mgc +Default compiled list of magic. +.It Pa /usr/share/misc/magic +Directory containing default magic files. +.El +.Sh EXIT STATUS +.Nm +will exit with +.Dv 0 +if the operation was successful or +.Dv >0 +if an error was encountered. +The following errors cause diagnostic messages, but don't affect the program +exit code (as POSIX requires), unless +.Fl E +is specified: +.Bl -bullet -compact -offset indent +.It +A file cannot be found +.It +There is no permission to read a file +.It +The file type cannot be determined +.El +.Sh EXAMPLES +.Bd -literal -offset indent +$ file file.c file /dev/{wd0a,hda} +file.c: C program text +file: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), + dynamically linked (uses shared libs), stripped +/dev/wd0a: block special (0/0) +/dev/hda: block special (3/0) + +$ file -s /dev/wd0{b,d} +/dev/wd0b: data +/dev/wd0d: x86 boot sector + +$ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10} +/dev/hda: x86 boot sector +/dev/hda1: Linux/i386 ext2 filesystem +/dev/hda2: x86 boot sector +/dev/hda3: x86 boot sector, extended partition table +/dev/hda4: Linux/i386 ext2 filesystem +/dev/hda5: Linux/i386 swap file +/dev/hda6: Linux/i386 swap file +/dev/hda7: Linux/i386 swap file +/dev/hda8: Linux/i386 swap file +/dev/hda9: empty +/dev/hda10: empty + +$ file -i file.c file /dev/{wd0a,hda} +file.c: text/x-c +file: application/x-executable +/dev/hda: application/x-not-regular-file +/dev/wd0a: application/x-not-regular-file + +.Ed +.Sh SEE ALSO +.Xr hexdump 1 , +.Xr od 1 , +.Xr strings 1 , +.Xr magic 5 +.Sh STANDARDS CONFORMANCE +This program is believed to exceed the System V Interface Definition +of FILE(CMD), as near as one can determine from the vague language +contained therein. +Its behavior is mostly compatible with the System V program of the same name. +This version knows more magic, however, so it will produce +different (albeit more accurate) output in many cases. +.\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html +.Pp +The one significant difference +between this version and System V +is that this version treats any white space +as a delimiter, so that spaces in pattern strings must be escaped. +For example, +.Bd -literal -offset indent +\*[Gt]10 string language impress\ (imPRESS data) +.Ed +.Pp +in an existing magic file would have to be changed to +.Bd -literal -offset indent +\*[Gt]10 string language\e impress (imPRESS data) +.Ed +.Pp +In addition, in this version, if a pattern string contains a backslash, +it must be escaped. +For example +.Bd -literal -offset indent +0 string \ebegindata Andrew Toolkit document +.Ed +.Pp +in an existing magic file would have to be changed to +.Bd -literal -offset indent +0 string \e\ebegindata Andrew Toolkit document +.Ed +.Pp +SunOS releases 3.2 and later from Sun Microsystems include a +.Nm +command derived from the System V one, but with some extensions. +This version differs from Sun's only in minor ways. +It includes the extension of the +.Sq \*[Am] +operator, used as, +for example, +.Bd -literal -offset indent +\*[Gt]16 long\*[Am]0x7fffffff \*[Gt]0 not stripped +.Ed +.Sh SECURITY +On systems where libseccomp +.Pa ( https://github.com/seccomp/libseccomp ) +is available, +.Nm +is enforces limiting system calls to only the ones necessary for the +operation of the program. +This enforcement does not provide any security benefit when +.Nm +is asked to decompress input files running external programs with +the +.Fl z +option. +To enable execution of external decompressors, one needs to disable +sandboxing using the +.Fl S +option. +.Sh MAGIC DIRECTORY +The magic file entries have been collected from various sources, +mainly USENET, and contributed by various authors. +Christos Zoulas (address below) will collect additional +or corrected magic file entries. +A consolidation of magic file entries +will be distributed periodically. +.Pp +The order of entries in the magic file is significant. +Depending on what system you are using, the order that +they are put together may be incorrect. +If your old +.Nm +command uses a magic file, +keep the old magic file around for comparison purposes +(rename it to +.Pa /usr/share/misc/magic.orig ) . +.Sh HISTORY +There has been a +.Nm +command in every +.Dv UNIX since at least Research Version 4 +(man page dated November, 1973). +The System V version introduced one significant major change: +the external list of magic types. +This slowed the program down slightly but made it a lot more flexible. +.Pp +This program, based on the System V version, +was written by Ian Darwin +.Aq ian@darwinsys.com +without looking at anybody else's source code. +.Pp +John Gilmore revised the code extensively, making it better than +the first version. +Geoff Collyer found several inadequacies +and provided some magic file entries. +Contributions of the +.Sq \*[Am] +operator by Rob McMahon, +.Aq cudcv@warwick.ac.uk , +1989. +.Pp +Guy Harris, +.Aq guy@netapp.com , +made many changes from 1993 to the present. +.Pp +Primary development and maintenance from 1990 to the present by +Christos Zoulas +.Aq christos@astron.com . +.Pp +Altered by Chris Lowth +.Aq chris@lowth.com , +2000: handle the +.Fl i +option to output mime type strings, using an alternative +magic file and internal logic. +.Pp +Altered by Eric Fischer +.Aq enf@pobox.com , +July, 2000, +to identify character codes and attempt to identify the languages +of non-ASCII files. +.Pp +Altered by Reuben Thomas +.Aq rrt@sc3d.org , +2007-2011, to improve MIME support, merge MIME and non-MIME magic, +support directories as well as files of magic, apply many bug fixes, +update and fix a lot of magic, improve the build system, improve the +documentation, and rewrite the Python bindings in pure Python. +.Pp +The list of contributors to the +.Sq magic +directory (magic files) +is too long to include here. +You know who you are; thank you. +Many contributors are listed in the source files. +.Sh LEGAL NOTICE +Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999. +Covered by the standard Berkeley Software Distribution copyright; see the file +COPYING in the source distribution. +.Pp +The files +.Pa tar.h +and +.Pa is_tar.c +were written by John Gilmore from his public-domain +.Xr tar 1 +program, and are not covered by the above license. +.Sh BUGS +Please report bugs and send patches to the bug tracker at +.Pa https://bugs.astron.com/ +or the mailing list at +.Aq file@astron.com +(visit +.Pa https://mailman.astron.com/mailman/listinfo/file +first to subscribe). +.Sh TODO +Fix output so that tests for MIME and APPLE flags are not needed all +over the place, and actual output is only done in one place. +This needs a design. +Suggestion: push possible outputs on to a list, then pick the +last-pushed (most specific, one hopes) value at the end, or +use a default if the list is empty. +This should not slow down evaluation. +.Pp +The handling of +.Dv MAGIC_CONTINUE +and printing \e012- between entries is clumsy and complicated; refactor +and centralize. +.Pp +Some of the encoding logic is hard-coded in encoding.c and can be moved +to the magic files if we had a !:charset annotation. +.Pp +Continue to squash all magic bugs. +See Debian BTS for a good source. +.Pp +Store arbitrarily long strings, for example for %s patterns, so that +they can be printed out. +Fixes Debian bug #271672. +This can be done by allocating strings in a string pool, storing the +string pool at the end of the magic file and converting all the string +pointers to relative offsets from the string pool. +.Pp +Add syntax for relative offsets after current level (Debian bug #466037). +.Pp +Make file -ki work, i.e. give multiple MIME types. +.Pp +Add a zip library so we can peek inside Office2007 documents to +print more details about their contents. +.Pp +Add an option to print URLs for the sources of the file descriptions. +.Pp +Combine script searches and add a way to map executable names to MIME +types (e.g. have a magic value for !:mime which causes the resulting +string to be looked up in a table). +This would avoid adding the same magic repeatedly for each new +hash-bang interpreter. +.Pp +When a file descriptor is available, we can skip and adjust the buffer +instead of the hacky buffer management we do now. +.Pp +Fix +.Dq name +and +.Dq use +to check for consistency at compile time (duplicate +.Dq name , +.Dq use +pointing to undefined +.Dq name +). +Make +.Dq name +/ +.Dq use +more efficient by keeping a sorted list of names. +Special-case ^ to flip endianness in the parser so that it does not +have to be escaped, and document it. +.Pp +If the offsets specified internally in the file exceed the buffer size +( +.Dv HOWMANY +variable in file.h), then we don't seek to that offset, but we give up. +It would be better if buffer managements was done when the file descriptor +is available so we can seek around the file. +One must be careful though because this has performance and thus security +considerations, because one can slow down things by repeatedly seeking. +.Pp +There is support now for keeping separate buffers and having offsets from +the end of the file, but the internal buffer management still needs an +overhaul. +.Sh AVAILABILITY +You can obtain the original author's latest version by anonymous FTP +on +.Pa ftp.astron.com +in the directory +.Pa /pub/file/file-X.YZ.tar.gz . diff --git a/upstream/fedora-40/man1/find.1 b/upstream/fedora-40/man1/find.1 new file mode 100644 index 00000000..478f7162 --- /dev/null +++ b/upstream/fedora-40/man1/find.1 @@ -0,0 +1,2777 @@ +'\" t +.TH FIND 1 \" -*- nroff -*- +.SH NAME +find \- search for files in a directory hierarchy +.SH SYNOPSIS +.B find +[\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [starting-point...\&] [expression] +. +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR find . +GNU +.B find +searches the directory tree rooted at each given starting-point by +evaluating the given expression from left to right, according to the +rules of precedence (see section OPERATORS), until the outcome is +known (the left hand side is false for \fIand\fR operations, true for +.IR or ), +at which point +.B find +moves on to the next file name. If no starting-point is specified, +`.\&' is assumed. +.PP +If you are using +.B find +in an environment where security is important (for example if you are +using it to search directories that are writable by other users), you +should read the `Security Considerations' chapter of the findutils +documentation, which is called \fBFinding Files\fP and comes with +findutils. +That document also includes a lot more detail +and discussion than this manual page, so you may find it a more useful +source of information. +. +.SH OPTIONS +The +.BR \-H , +.B \-L +and +.B \-P +options control the treatment of symbolic +links. Command-line arguments following these are taken to be names +of files or directories to be examined, up to the first argument that +begins with `\-', or the argument `(' or `!'. That argument and any +following arguments are taken to be the expression describing what is +to be searched for. If no paths are given, the current directory is +used. If no expression is given, the expression +.B \-print +is used +(but you should probably consider using +.B \-print0 +instead, anyway). +.PP +This manual page talks about `options' within the expression list. +These options control the behaviour of +.B find +but are specified immediately after the last path name. The five +`real' options +.BR \-H , +.BR \-L , +.BR \-P , +.B \-D +and +.B \-O +must appear before +the first path name, if at all. A double dash +.B \-\- +could theoretically be used to signal that any remaining arguments +are not options, but this does not really work due to the way +.B find +determines the end of the following path arguments: it does that by reading +until an expression argument comes (which also starts with a `-'). +Now, if a path argument would start with a `-', then +.B find +would treat it as expression argument instead. +Thus, to ensure that all start points are taken as such, and especially to +prevent that wildcard patterns expanded by the calling shell are not mistakenly +treated as expression arguments, it is generally safer to prefix wildcards or +dubious path names with either `./' or to use absolute path names starting +with '/'. +Alternatively, it is generally safe though non-portable to use the GNU option +.B \-files0\-from +to pass arbitrary starting points to +.BR find . + +.IP \-P +Never follow symbolic links. This is the default behaviour. When +.B find +examines or prints information about files, and the file is a symbolic +link, the information used shall be taken from the properties of the +symbolic link itself. + +.IP \-L +Follow symbolic links. When +.B find +examines or prints information about files, the information used shall +be taken from the properties of the file to which the link points, not +from the link itself (unless it is a broken symbolic link or +.B find +is unable to examine the file to which the link points). Use of this +option implies +.BR \-noleaf . +If you later use the +.B \-P +option, +.B \-noleaf +will still be in effect. If +.B \-L +is in effect and +.B find +discovers a symbolic link to a subdirectory during its search, +the subdirectory pointed to by the symbolic link will be searched. +.IP +When the +.B \-L +option is in effect, the +.B \-type +predicate will always +match against the type of the file that a symbolic link points to +rather than the link itself (unless the symbolic link is broken). +Actions that can cause symbolic links to become broken while +.B find +is executing (for example +.BR \-delete ) +can give rise to confusing behaviour. +Using +.B \-L +causes the +.B \-lname +and +.B \-ilname +predicates always to return +false. + +.IP \-H +Do not follow symbolic links, except while processing the command +line arguments. When +.B find +examines or prints information about files, the information used +shall be taken from the properties of the symbolic link itself. +The only exception to this behaviour is when a file specified on the +command line is a symbolic link, +and the link can be resolved. +For that situation, the information used is taken from whatever the +link points to +(that is, the link is followed). +The information about the link itself is used as a fallback if the +file pointed to by the symbolic link cannot be examined. +If +.B \-H +is in effect and one of the +paths specified on the command line is a symbolic link to a directory, +the contents of that directory will be examined (though of course +.B \-maxdepth\ 0 +would prevent this). +.P +If more than one of +.BR \-H , +.B \-L +and +.B \-P +is specified, each overrides the +others; the last one appearing on the command line takes effect. +Since it is the default, the +.B \-P +option should be considered to be in +effect unless either +.B \-H +or +.B \-L +is specified. + +GNU +.B find +frequently stats files during the processing of the command line +itself, before any searching has begun. These options also affect how +those arguments are processed. Specifically, there are a number of +tests that compare files listed on the command line against a file we +are currently considering. In each case, the file specified on the +command line will have been examined and some of its properties will +have been saved. If the named file is in fact a symbolic link, and +the +.B \-P +option is in effect (or if neither +.B \-H +nor +.B \-L +were specified), the information used for the comparison will be taken from +the properties of the symbolic link. Otherwise, it will be taken from +the properties of the file the link points to. If +.B find +cannot follow the link (for example because it has insufficient +privileges or the link points to a nonexistent file) the properties of +the link itself will be used. +.P +When the +.B \-H +or +.B \-L +options are in effect, any symbolic links listed as the argument of +.B \-newer +will be dereferenced, and the timestamp +will be taken from the file to which the symbolic link points. The +same consideration applies to +.BR \-newerXY , +.B \-anewer +and +.BR \-cnewer . + +The +.B \-follow +option has a similar effect to +.BR \-L , +though it takes +effect at the point where it appears (that is, if +.B \-L +is not used but +.B \-follow +is, any symbolic links appearing after +.B \-follow +on the +command line will be dereferenced, and those before it will not). + +.IP "\-D debugopts" +Print diagnostic information; this can be helpful to diagnose problems +with why +.B find +is not doing what you want. The list of debug options should be comma +separated. Compatibility of the debug options is not guaranteed +between releases of findutils. For a complete list of valid debug +options, see the output of +.BR "find \-D\ help" . +Valid debug options include +.RS +.IP exec +Show diagnostic information relating to \-exec, \-execdir, \-ok and \-okdir +.IP opt +Prints diagnostic information relating to the optimisation of the +expression tree; see the \-O option. +.IP rates +Prints a summary indicating how often each predicate succeeded or +failed. +.IP search +Navigate the directory tree verbosely. +.IP stat +Print messages as files are examined with the +.B stat +and +.B lstat +system calls. The +.B find +program tries to minimise such calls. +.IP tree +Show the expression tree in its original and optimised form. +.IP all +Enable all of the other debug options (but +.BR help ). +.IP help +Explain the debugging options. +.RE +.IP \-Olevel +Enables query optimisation. +The +.B find +program reorders tests to speed up execution while preserving the +overall effect; that is, predicates with side effects are not +reordered relative to each other. The optimisations performed at each +optimisation level are as follows. +.RS +.IP 0 +Equivalent to optimisation level 1. +.IP 1 +This is the default optimisation level and corresponds to the +traditional behaviour. Expressions are reordered so that tests based +only on the names of files (for example +.B \-name +and +.BR \-regex ) +are performed first. +.IP 2 +Any +.B \-type +or +.B \-xtype +tests are performed after any tests based only on the names of files, +but before any tests that require information from the inode. On many +modern versions of Unix, file types are returned by +.B readdir() +and so these predicates are faster to evaluate than predicates which +need to stat the file first. +If you use the +.B "\-fstype\ \fIFOO\fR" +predicate and specify a filesystem type +.I FOO +which is not known (that is, present in `/etc/mtab') at the time +.B find +starts, that predicate is equivalent to +.BR \-false . +.IP 3 +At this optimisation level, the full cost-based query optimiser is +enabled. The order of tests is modified so that cheap (i.e.\& fast) +tests are performed first and more expensive ones are performed later, +if necessary. Within each cost band, predicates are evaluated earlier +or later according to whether they are likely to succeed or not. For +.BR \-o , +predicates which are likely to succeed are evaluated earlier, and for +.BR \-a , +predicates which are likely to fail are evaluated earlier. +.RE +.IP +The cost-based optimiser has a fixed idea of how likely any given test +is to succeed. In some cases the probability takes account of the +specific nature of the test (for example, +.B \-type\ f +is assumed to be more likely to succeed than +.BR "\-type\ c" ). +The cost-based optimiser is currently being evaluated. +If it does not actually improve the performance of +.BR find , +it will be removed again. Conversely, optimisations that prove to be +reliable, robust and effective may be enabled at lower optimisation +levels over time. However, the default behaviour (i.e.\& optimisation +level 1) will not be changed in the 4.3.x release series. The +findutils test suite runs all the tests on +.B find +at each optimisation level and ensures that the result is the same. +. +.SH EXPRESSION +The part of the command line after the list of starting points is the +.IR expression . +This is a kind of query specification describing how we match files +and what we do with the files that were matched. +An expression is composed of a sequence of things: + +.IP Tests +Tests return a true or false value, usually on the basis of some +property of a file we are considering. The +.B \-empty +test for example is true only when the current file is empty. + +.IP Actions +Actions have side effects (such as printing something on the standard +output) and return either true or false, usually based on whether or +not they are successful. The +.B \-print +action for example prints the name of the current file on the standard +output. + +.IP "Global options" +Global options affect the operation of tests and actions specified on +any part of the command line. Global options always return true. The +.B \-depth +option for example makes +.B find +traverse the file system in a depth-first order. + +.IP "Positional options" +Positional options affect only tests or actions which follow them. +Positional options always return true. The +.B \-regextype +option for example is positional, specifying the regular expression +dialect for regular expressions occurring later on the command line. + +.IP Operators +Operators join together the other items within the expression. They +include for example +.B \-o +(meaning logical OR) and +.B \-a +(meaning logical AND). Where an operator is missing, +.B \-a +is assumed. + +.P +The +.B \-print +action is performed on all files for which the whole expression is +true, unless it contains an action other than +.B \-prune +or +.BR \-quit . +Actions which inhibit the default +.B \-print +are +.BR \-delete , +.BR \-exec , +.BR \-execdir , +.BR \-ok , +.BR \-okdir , +.BR \-fls , +.BR \-fprint , +.BR \-fprintf , +.BR \-ls , +.B \-print +and +.BR \-printf . + + +The +.B \-delete +action also acts like an option (since it implies +.BR \-depth ). + +.SS POSITIONAL OPTIONS +Positional options always return true. They affect only tests occurring +later on the command line. + +.IP \-daystart +Measure times (for +.BR \-amin , +.BR \-atime , +.BR \-cmin , +.BR \-ctime , +.BR \-mmin , +and +.BR \-mtime ) +from the beginning of today rather than from 24 hours ago. This +option only affects tests which appear later on the command line. + +.IP \-follow +Deprecated; use the +.B \-L +option instead. Dereference symbolic links. +Implies +.BR \-noleaf . +The +.B \-follow +option affects only those tests which +appear after it on the command line. Unless the +.B \-H +or +.B \-L +option has +been specified, the position of the +.B \-follow +option changes the behaviour of the +.B \-newer +predicate; any files listed as the argument +of +.B \-newer +will be dereferenced if they are symbolic links. The same +consideration applies to +.BR \-newerXY , +.B \-anewer +and +.BR \-cnewer . +Similarly, the +.B \-type +predicate will always match against the type of the file +that a symbolic link points to rather than the link itself. Using +.B \-follow +causes the +.B \-lname and +.B \-ilname +predicates always to return false. + +.IP "\-regextype \fItype\fR" +Changes the regular expression syntax understood by +.B \-regex +and +.B \-iregex +tests which occur later on the command line. To see which regular +expression types are known, use +.BR "\-regextype\ help" . +The Texinfo documentation (see +.B SEE +.BR ALSO ) +explains the meaning of and +differences between the various types of regular expression. + +.IP "\-warn, \-nowarn" +Turn warning messages on or off. These warnings apply only to the +command line usage, not to any conditions that +.B find +might encounter when it searches directories. The default behaviour +corresponds to +.B \-warn +if standard input is a tty, and to +.B \-nowarn +otherwise. If a warning message relating to command-line usage is +produced, the exit status of +.B find +is not affected. If the +.B POSIXLY_CORRECT +environment variable is set, and +.B \-warn +is also used, it is not specified which, if any, warnings will be active. + +.SS GLOBAL OPTIONS +Global options always return true. +Global options take effect even for tests which occur earlier on the +command line. To prevent confusion, global options should specified +on the command-line after the list of start points, just before the +first test, positional option or action. +If you specify a global option in some other place, +.B find +will issue a warning message explaining that this can be confusing. + +The global options occur after the list of start points, and so are +not the same kind of option as +.BR \-L , +for example. + +.IP \-d +A synonym for \-depth, for compatibility with FreeBSD, NetBSD, \ +MacOS X and OpenBSD. + +.IP \-depth +Process each directory's contents before the directory itself. The +\-delete action also implies +.BR \-depth . + +.IP "\-files0\-from \fIfile\fR" +Read the starting points from \fIfile\fR instead of getting them on the +command line. +In contrast to the known limitations of passing starting points via arguments +on the command line, namely the limitation of the amount of file names, +and the inherent ambiguity of file names clashing with option names, +using this option allows to safely pass an arbitrary number of starting points +to \fBfind\fR. + +Using this option and passing starting points on the command line is mutually +exclusive, and is therefore not allowed at the same time. + +The \fIfile\fR argument is mandatory. +One can use +.B \-files0\-from\ \- +to read the list of starting points from the \fIstandard input\fR stream, +and e.g. from a pipe. +In this case, the actions +.B \-ok +and +.B \-okdir +are not allowed, because they would obviously interfere with reading from +\fIstandard input\fR in order to get a user confirmation. + +The starting points in \fIfile\fR have to be separated by ASCII NUL characters. +Two consecutive NUL characters, i.e., a starting point with a Zero-length +file name is not allowed and will lead to an error diagnostic followed by +a non-Zero exit code later. + +In the case the given \fIfile\fR is empty, \fBfind\fR does not process any +starting point and therefore will exit immediately after parsing the program +arguments. +This is unlike the standard invocation where \fBfind\fR assumes the current +directory as starting point if no path argument is passed. + +The processing of the starting points is otherwise as usual, e.g. +.B find +will recurse into subdirectories unless otherwise prevented. +To process only the starting points, one can additionally pass +.BR \-maxdepth\ 0 . + +Further notes: +if a file is listed more than once in the input file, it is unspecified +whether it is visited more than once. +If the \fIfile\fR is mutated during the operation of +.BR find , +the result is unspecified as well. +Finally, the seek position within the named \fIfile\fR at the time +.B find +exits, be it with +.B \-quit +or in any other way, is also unspecified. +By "unspecified" here is meant that it may or may not work or do any specific +thing, and that the behavior may change from platform to platform, or from +.B findutils +release to release. + +.IP "\-help, \-\-help" +Print a summary of the command-line usage of +.B find +and exit. + +.IP \-ignore_readdir_race +Normally, \fBfind\fR will emit an error message when it fails to stat a file. +If you give this option and a file is deleted between the time \fBfind\fR +reads the name of the file from the directory and the time it tries to stat +the file, no error message will be issued. +This also applies to files or directories whose names are given on the +command line. +This option takes effect at the time the command line is read, +which means that you cannot search one part of the filesystem with +this option on and part of it with this option off +(if you need to do that, you will need to issue two \fBfind\fR commands +instead, one with the option and one without it). + +Furthermore, +.B find +with the +.B \-ignore_readdir_race +option will ignore errors of the +.B \-delete +action in the case the file has disappeared since the parent directory was read: +it will not output an error diagnostic, and the return code of the +.B \-delete +action will be true. + +.IP "\-maxdepth \fIlevels\fR" +Descend at most \fIlevels\fR (a non-negative integer) levels of +directories below the starting-points. Using +.B \-maxdepth\ 0 +means only apply the tests and actions to the starting-points themselves. + +.IP "\-mindepth \fIlevels\fR" +Do not apply any tests or actions at levels less than \fIlevels\fR (a +non-negative integer). Using +.B \-mindepth\ 1 +means process all files except the starting-points. + +.IP \-mount +Don't descend directories on other filesystems. An alternate name for +.BR \-xdev , +for compatibility with some other versions of +.BR find . + +.IP \-noignore_readdir_race +Turns off the effect of +.BR \-ignore_readdir_race . + +.IP "\-noleaf" +Do not optimize by assuming that directories contain 2 fewer +subdirectories than their hard link count. This option is needed when +searching filesystems that do not follow the Unix directory-link +convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount +points. Each directory on a normal Unix filesystem has at least 2 +hard links: its name and its `.\&' entry. Additionally, its +subdirectories (if any) each have a `..\&' entry linked to that +directory. When +.B find +is examining a directory, after it has statted 2 fewer subdirectories +than the directory's link count, it knows that the rest of the entries +in the directory are non-directories (`leaf' files in the directory +tree). If only the files' names need to be examined, there is no need +to stat them; this gives a significant increase in search speed. + +.IP "\-version, \-\-version" +Print the \fBfind\fR version number and exit. + +.IP \-xautofs +Don't descend directories on autofs filesystems. + +.IP \-xdev +Don't descend directories on other filesystems. + +.SS TESTS +Some tests, for example +.B \-newerXY +and +.BR \-samefile , +allow comparison between the file currently being examined and some +reference file specified on the command line. When these tests are +used, the interpretation of the reference file is determined by the +options +.BR \-H , +.B \-L +and +.B \-P +and any previous +.BR \-follow , +but the reference file is only examined once, at the time the command +line is parsed. If the reference file cannot be examined (for +example, the +.BR stat (2) +system call fails for it), an error message is issued, and +.B find +exits with a nonzero status. +.P +A numeric argument \fIn\fR can be specified to tests (like +.BR \-amin , +.BR \-mtime , +.BR \-gid , +.BR \-inum , +.BR \-links , +.BR \-size , +.BR \-uid +and +.BR \-used ) +as +.IP \fI+n\fP +for greater than +.IR n , +.IP \fI\-n\fP +for less than +.IR n , +.IP \fIn\fP +for exactly +.IR n . +. +.P +Supported tests: + +.IP "\-amin \fIn\fR" +File was last accessed less than, more than or exactly \fIn\fR minutes ago. + +.IP "\-anewer \fIreference\fR" +Time of the last access of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-atime \fIn\fR" +File was last accessed less than, more than or exactly +.IR n *24 +hours ago. +When find figures out how many 24-hour periods ago the file +was last accessed, any fractional part is ignored, so to match +.BR "\-atime\ +1" , +a file has to have been accessed at least +.I two +days ago. + +.IP "\-cmin \fIn\fR" +File's status was last changed less than, more than or exactly \fIn\fR minutes +ago. + +.IP "\-cnewer \fIreference\fR" +Time of the last status change of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-ctime \fIn\fR" +File's status was last changed less than, more than or exactly +.IR n *24 +hours ago. +See the comments for +.B \-atime +to understand how rounding affects the interpretation of file status +change times. + +.IP \-empty +File is empty and is either a regular file or a directory. + +.IP \-executable +Matches files which are executable and directories which are +searchable (in a file name resolution sense) by the current user. +This takes into account access control lists and other permissions +artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. Because this test is based only on +the result of the +.BR access (2) +system call, there is no guarantee that a file for which this test +succeeds can actually be executed. + +.IP \-false +Always false. + +.IP "\-fstype \fItype\fR" +File is on a filesystem of type +.IR type . +The valid filesystem types vary among different versions of Unix; +an incomplete list of +filesystem types that are accepted on some version of Unix or another +is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use +.B \-printf +with the %F directive to see the types of your filesystems. + +.IP "\-gid \fIn\fR" +File's numeric group ID is less than, more than or exactly +.IR n . + +.IP "\-group \fIgname\fR" +File belongs to group \fIgname\fR (numeric group ID allowed). + +.IP "\-ilname \fIpattern\fR" +Like +.BR \-lname , +but the match is case insensitive. +If the +.B \-L +option or the +.B \-follow +option is in effect, this test returns false unless the symbolic link +is broken. + + +.IP "\-iname \fIpattern\fR" +Like +.BR \-name , +but the match is case insensitive. For example, the +patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo', +`fOo', etc. +The pattern `*foo*` will also match a file called '.foobar'. + +.IP "\-inum \fIn\fR" +File has inode number smaller than, greater than or exactly +.IR n . +It is normally easier to use the +.B \-samefile +test instead. + +.IP "\-ipath \fIpattern\fR" +Like +.BR \-path . +but the match is case insensitive. + +.IP "\-iregex \fIpattern\fR" +Like +.BR \-regex , +but the match is case insensitive. + +.IP "\-iwholename \fIpattern\fR" +See \-ipath. This alternative is less portable than +.BR \-ipath . + +.IP "\-links \fIn\fR" +File has less than, more than or exactly \fIn\fR hard links. + +.IP "\-lname \fIpattern\fR" +File is a symbolic link whose contents match shell pattern +.IR pattern . +The metacharacters do not treat `/' or `.\&' specially. +If the +.B \-L +option or the +.B \-follow +option is in effect, this test returns false unless the symbolic link +is broken. + +.IP "\-mmin \fIn\fR" +File's data was last modified less than, more than or exactly \fIn\fR minutes +ago. + +.IP "\-mtime \fIn\fR" +File's data was last modified less than, more than or exactly +.IR n *24 +hours ago. +See the comments for +.B \-atime +to understand how rounding affects the interpretation of file +modification times. + +.IP "\-name \fIpattern\fR" +Base of file name (the path with the leading directories removed) +matches shell pattern +.IR pattern . +Because the leading directories are removed, +the file names considered for a match with +.B \-name +will never include a slash, so `\-name a/b' will never match anything +(you probably need to use +.B \-path +instead). +A warning is issued if you try to do this, +unless the environment variable +.B POSIXLY_CORRECT +is set. +The metacharacters (`*', `?', +and `[]') match a `.\&' at the start of the base name (this is a change +in findutils-4.2.2; see section STANDARDS CONFORMANCE below). To ignore a +directory and the files under it, use +.B \-prune +rather than checking every file in the tree; +see an example in the description of that action. +Braces are not recognised as being +special, despite the fact that some shells including Bash imbue braces +with a special meaning in shell patterns. The filename matching is +performed with the use of the +.BR fnmatch (3) +library function. +Don't forget to enclose the pattern in quotes in order to protect it +from expansion by the shell. + +.IP "\-newer \fIreference\fR" +Time of the last data modification of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-newerXY \fIreference\fR" +Succeeds if timestamp \fIX\fR of the file being considered is newer +than timestamp \fIY\fR of the file +.IR reference . +The letters \fIX\fR and \fIY\fR can be any of the following letters: + +.TS +ll +ll +ll +ll +llw(2i). +a The access time of the file \fIreference\fR +B The birth time of the file \fIreference\fR +c The inode status change time of \fIreference\fR +m The modification time of the file \fIreference\fR +t \fIreference\fR is interpreted directly as a time +.TE + +Some combinations are invalid; for example, it is invalid for +.I X +to be +.IR t . +Some combinations are not implemented on all systems; for example +.I B +is not supported on all systems. If an invalid or unsupported +combination of +.I XY +is specified, a fatal error results. Time specifications are +interpreted as for the argument to the +.B \-d +option of GNU +.BR date . +If you try to use the birth time of a reference file, and the birth +time cannot be determined, a fatal error message results. If you +specify a test which refers to the birth time of files being examined, +this test will fail for any files where the birth time is unknown. + +.IP \-nogroup +No group corresponds to file's numeric group ID. + +.IP \-nouser +No user corresponds to file's numeric user ID. + +.IP "\-path \fIpattern\fR" +File name matches shell pattern +.IR pattern . +The metacharacters do not treat `/' or `.\&' specially; +so, for example, +.in +4m +.nf +find . \-path \(dq./sr*sc\(dq +.fi +.in +will print an entry for a directory called +.I ./src/misc +(if one exists). To ignore a whole directory tree, use +.B \-prune +rather than +checking every file in the tree. +Note that the pattern match test applies to the whole file name, +starting from one of the start points named on the command line. It +would only make sense to use an absolute path name here if the +relevant start point is also an absolute path. This means that this +command will never match anything: +.br +.in +4m +.nf +find bar \-path /foo/bar/myfile \-print +.fi +.in +Find compares the +.B \-path +argument with the concatenation of a directory name and the base name +of the file it's examining. Since the concatenation will never end +with a slash, +.B \-path +arguments ending in a slash will match nothing (except perhaps a start +point specified on the command line). +The predicate +.B \-path +is also supported by HP-UX +.B find +and is part of the POSIX 2008 standard. + +.IP "\-perm \fImode\fR" +File's permission bits are exactly \fImode\fR (octal or symbolic). +Since an exact match is required, if you want to use this form for +symbolic modes, you may have to specify a rather complex mode string. +For example `\-perm g=w' will only match files which have mode 0020 +(that is, ones for which group write permission is the only permission +set). It is more likely that you will want to use the `/' or `\-' +forms, for example `\-perm \-g=w', which matches any file with group +write permission. See the +.B EXAMPLES +section for some illustrative examples. + +.IP "\-perm \-\fImode\fR" +All of the permission bits \fImode\fR are set for the file. +Symbolic modes are accepted in this form, and this is usually the way +in which you would want to use them. You must specify `u', `g' or `o' if +you use a symbolic mode. +See the +.B EXAMPLES +section for some illustrative examples. + +.IP "\-perm /\fImode\fR" +Any of the permission bits \fImode\fR are set for the file. Symbolic +modes are accepted in this form. You must specify `u', `g' or `o' if +you use a symbolic mode. See the +.B EXAMPLES +section for some illustrative examples. If no permission bits in +.I mode +are set, this test matches any file (the idea here is to be consistent +with the behaviour of +.BR "\-perm\ \-000" ). + +.IP "\-perm +\fImode\fR" +This is no longer supported (and has been deprecated since 2005). Use +.B "\-perm /\fImode\fR" +instead. + +.IP \-readable +Matches files which are readable by the current user. This takes into +account access control lists and other permissions artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. + +.IP "\-regex \fIpattern\fR" +File name matches regular expression +.IR pattern . +This is a match on the whole path, not a search. +For example, to match a file named +.IR ./fubar3, +you can use the regular expression `.*bar.\&' or `.*b.*3', +but not `f.*r3'. +The regular expressions understood by +.B find +are by default Emacs Regular Expressions (except that `.' matches +newline), but this can be changed with the +.B \-regextype +option. + +.IP "\-samefile \fIname\fR" +File refers to the same inode as +.IR name . +When +.B \-L +is in effect, this can include symbolic links. + +.IP "\-size \fIn\fR[cwbkMG]" +File uses less than, more than or exactly \fIn\fP units of space, rounding up. +The following suffixes can be used: +.RS +.IP `b' +for 512-byte blocks (this is the default if no suffix is used) +.IP `c' +for bytes +.IP `w' +for two-byte words +.IP `k' +for kibibytes (KiB, units of 1024 bytes) +.IP `M' +for mebibytes (MiB, units of 1024 * 1024 = 1\|048\|576 bytes) +.IP `G' +for gibibytes (GiB, units of 1024 * 1024 * 1024 = 1\|073\|741\|824 bytes) +.RE +.IP +The size is simply the st_size member of the struct stat populated by +the lstat (or stat) system call, rounded up as shown above. +In other words, it's consistent with the result you get for +.BR "ls\ \-l" . +Bear in +mind that the `%k' and `%b' format specifiers of +.B \-printf +handle sparse files +differently. The `b' suffix always denotes 512-byte blocks and never +1024-byte blocks, which is different to the behaviour of +.BR \-ls . +.IP +The + and - prefixes signify greater than and less than, as usual; +i.e., an exact size of \fIn\fR units does not match. +Bear in mind that the size is rounded up to the next unit. +Therefore +.B \-size\ \-1M +is not equivalent to +.BR "\-size\ \-1\|048\|576c" . +The former only matches empty files, the latter matches files from 0 to +1,048,575 bytes. +.IP \-true +Always true. + +.IP "\-type \fIc\fR" +File is of type +.IR c : +.RS +.IP b +block (buffered) special +.IP c +character (unbuffered) special +.IP d +directory +.IP p +named pipe (FIFO) +.IP f +regular file +.IP l +symbolic link; this is never true if the +.B \-L +option or the +.B \-follow +option is in effect, unless the symbolic link is broken. If you want +to search for symbolic links when +.B \-L +is in effect, use +.BR \-xtype . +.IP s +socket +.IP D +door (Solaris) +.RE +.IP +To search for more than one type at once, you can supply the combined list of +type letters separated by a comma `,' (GNU extension). +.IP "\-uid \fIn\fR" +File's numeric user ID is less than, more than or exactly +.IR n . + +.IP "\-used \fIn\fR" +File was last accessed less than, more than or exactly \fIn\fR days after its +status was last changed. + +.IP "\-user \fIuname\fR" +File is owned by user \fIuname\fR (numeric user ID allowed). + +.IP "\-wholename \fIpattern\fR" +See \-path. This alternative is less portable than +.BR \-path . + +.IP "\-writable" +Matches files which are writable by the current user. This takes into +account access control lists and other permissions artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. + +.IP "\-xtype \fIc\fR" +The same as +.B \-type +unless the file is a symbolic link. For symbolic +links: if the +.B \-H +or +.B \-P +option was specified, true if the file is a +link to a file of type +.IR c ; +if the +.B \-L +option has been given, true +if \fIc\fR is `l'. In other words, for symbolic links, +.B \-xtype +checks the type of the file that +.B \-type +does not check. +.IP "\-context \fIpattern\fR" +(SELinux only) Security context of the file matches glob +.IR pattern . + +.SS ACTIONS +.IP "\-delete\fR" +Delete files or directories; true if removal succeeded. +If the removal failed, an error message is issued and +.BR find 's +exit status will be nonzero (when it eventually exits). + +.BR Warning : +Don't forget that +.B find +evaluates the command line as an +expression, so putting +.B \-delete +first will make +.B find +try to delete everything below the starting points you specified. + +The use of the +.B \-delete +action on the command line automatically turns on the +.B \-depth +option. +As in turn +.B \-depth +makes +.B \-prune +ineffective, the +.B \-delete +action cannot usefully be combined with +.BR \-prune . + +Often, the user might want to test a find command line with +.B \-print +prior to adding +.B \-delete +for the actual removal run. +To avoid surprising results, it is usually best to remember to use +.B \-depth +explicitly during those earlier test runs. + +The +.B \-delete +action will fail to remove a directory unless it is empty. + +Together with the +.B \-ignore_readdir_race +option, +.B find +will ignore errors of the +.B \-delete +action in the case the file has disappeared since the parent directory was +read: it will not output an error diagnostic, not change the exit code to +nonzero, and the return code of the +.B \-delete +action will be true. + + +.IP "\-exec \fIcommand\fR ;" +Execute +.IR command ; +true if 0 status is returned. All following +arguments to +.B find +are taken to be arguments to the command until an argument consisting +of `;' is encountered. The string `{}' is replaced by the current +file name being processed everywhere it occurs in the arguments to the +command, not just in arguments where it is alone, as in some versions +of +.BR find . +Both of these constructions might need to be escaped (with a `\e') or +quoted to protect them from expansion by the shell. See the +.B EXAMPLES +section for examples of the use of the +.B \-exec +option. The specified +command is run once for each matched file. +The command is executed in the starting directory. +There are unavoidable security problems surrounding use of the +.B \-exec +action; +you should use the +.B \-execdir +option instead. + +.IP "\-exec \fIcommand\fR {} +" +This variant of the +.B \-exec +action runs the specified command on the +selected files, but the command line is built by appending each +selected file name at the end; the total number of invocations of the +command will be much less than the number of matched files. The +command line is built in much the same way that +.B xargs +builds its command lines. Only one instance of `{}' is allowed within +the command, and it must appear at the end, immediately before the `+'; +it needs to be escaped (with a `\e') or quoted to protect it from +interpretation by the shell. +The command is executed in the starting directory. If any invocation +with the `+' form returns a non-zero value as exit status, then +.B find +returns a non-zero exit status. If +.B find +encounters an error, this can sometimes cause an +immediate exit, so some pending commands may not be run +at all. For this reason +.B \-exec\ \fImy-command\fP\ ...\ {}\ +\ \-quit +may not result in +.I my-command +actually being run. This variant of +.B \-exec +always returns true. + +.IP "\-execdir \fIcommand\fR ;" +.IP "\-execdir \fIcommand\fR {} +" +Like +.BR \-exec , +but the specified command is run from the subdirectory +containing the matched file, which is not normally the directory in +which you started +.BR find . +As with \-exec, the {} should be quoted if find is being invoked from +a shell. +This a much more secure method for invoking commands, as it avoids +race conditions during resolution of the paths to the matched files. +As with the +.B \-exec +action, the `+' form of +.B \-execdir +will build a +command line to process more than one matched file, but any given +invocation of +.I command +will only list files that exist in the same subdirectory. If you use +this option, you must ensure that your +.B PATH +environment variable does not reference `.'; +otherwise, an attacker can run any commands they like by leaving an +appropriately-named file in a directory in which you will run +.BR \-execdir . +The same applies to having entries in +.B PATH +which are empty or which are not absolute directory names. If +any invocation with the `+' form returns a non-zero value as exit status, +then +.B find +returns a non-zero exit status. If +.B find +encounters an error, this can sometimes cause an +immediate exit, so some pending commands may not be run +at all. +The result of the action depends on whether the +.B + +or the +.B ; +variant is being used; +.B \-execdir\ \fIcommand\fP\ {}\ + +always returns true, while +.B \-execdir\ \fIcommand\fP\ {}\ ; +returns true only if +.I command +returns 0. + + +.IP "\-fls \fIfile\fR" +True; like +.B \-ls +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never +matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprint \fIfile\fR" +True; print the full file name into file +.IR file . +If \fIfile\fR +does not exist when \fBfind\fR is run, it is created; if it does +exist, it is truncated. The file names +.I /dev/stdout +and +.I /dev/stderr +are handled specially; they refer to the standard +output and standard error output, respectively. +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprint0 \fIfile\fR" +True; like +.B \-print0 +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprintf \fIfile\fR \fIformat\fR" +True; like +.B \-printf +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP \-ls +True; list current file in +.B ls \-dils +format on standard output. +The block counts are of 1\ KB blocks, unless the environment variable +.B POSIXLY_CORRECT +is set, in which case 512-byte blocks are used. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-ok \fIcommand\fR ;" +Like +.B \-exec +but ask the user first. If the user agrees, run the command. Otherwise +just return false. If the command is run, its standard input is redirected +from +.IR /dev/null . +This action may not be specified together with the +.B \-files0\-from +option. + +.IP +The response to the prompt is matched against a pair of regular +expressions to determine if it is an affirmative or negative +response. This regular expression is obtained from the system if the +.B POSIXLY_CORRECT +environment variable is set, or otherwise from +.BR find 's +message translations. If the system has no suitable +definition, +.BR find 's +own definition will be used. +In either case, the interpretation of the regular expression itself +will be affected by the environment variables +.B LC_CTYPE +(character classes) and +.B LC_COLLATE +(character ranges and equivalence classes). + + + +.IP "\-okdir \fIcommand\fR ;" +Like +.B \-execdir +but ask the user first in the same way as for +.BR \-ok . +If the user does not agree, just return false. +If the command is run, its standard input is redirected from +.IR /dev/null . +This action may not be specified together with the +.B \-files0\-from +option. + + +.IP \-print +True; print the full file name on the standard output, followed by a +newline. +If you are piping the output of +.B find +into another program and there is the faintest possibility that the files +which you are searching for might contain a newline, then you should +seriously consider using the +.B \-print0 +option instead of +.BR \-print . +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP \-print0 +True; print the full file name on the standard output, followed by a +null character (instead of the newline character that +.B \-print +uses). +This allows file names that contain newlines or other types of white +space to be correctly interpreted by programs that process the +\fBfind\fR output. This option corresponds to the +.B \-0 +option of +.BR xargs . + +.IP "\-printf \fIformat\fR" +True; print \fIformat\fR on the standard output, interpreting `\e' +escapes and `%' directives. Field widths and precisions can be +specified as with the +.BR printf (3) +C function. Please note that many of +the fields are printed as %s rather than %d, and this may mean that +flags don't work as you might expect. This also means that the `\-' +flag does work (it forces fields to be left-aligned). Unlike +.BR \-print , +.B \-printf +does not add a newline at the end of the string. The escapes +and directives are: +.RS +.IP \ea +Alarm bell. +.IP \eb +Backspace. +.IP \ec +Stop printing from this format immediately and flush the output. +.IP \ef +Form feed. +.IP \en +Newline. +.IP \er +Carriage return. +.IP \et +Horizontal tab. +.IP \ev +Vertical tab. +.IP \e0 +ASCII NUL. +.IP \e\e +A literal backslash (`\e'). +.IP \eNNN +The character whose ASCII code is NNN (octal). +.PP +A `\e' character followed by any other character is treated as an +ordinary character, so they both are printed. +.IP %% +A literal percent sign. +.IP %a +File's last access time in the format returned by the C +.BR ctime (3) +function. +.IP %A\fIk\fP +File's last access time in the format specified by +.IR k , +which is either `@' or a directive for the C +.BR strftime (3) +function. +The following shows an incomplete list of possible values for \fIk\fR. +Please refer to the documentation of +.BR strftime (3) +for the full list. +Some of the conversion specification characters might not be available on all systems, +due to differences in the implementation of the +.BR strftime (3) +library function. +.RS +.IP @ +seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part. +.PP +Time fields: +.IP H +hour (00..23) +.IP I +hour (01..12) +.IP k +hour ( 0..23) +.IP l +hour ( 1..12) +.IP M +minute (00..59) +.IP p +locale's AM or PM +.IP r +time, 12-hour (hh:mm:ss [AP]M) +.IP S +Second (00.00 \&..\& 61.00). There is a fractional part. +.IP T +time, 24-hour (hh:mm:ss.xxxxxxxxxx) +.IP + +Date and time, separated by `+', for example +`2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is +given in the current timezone (which may be affected by setting the +.B TZ +environment variable). The seconds field includes a fractional part. +.IP X +locale's time representation (H:M:S). The seconds field includes a +fractional part. +.IP Z +time zone (e.g., EDT), or nothing if no time zone is determinable +.PP +Date fields: +.IP a +locale's abbreviated weekday name (Sun..Sat) +.IP A +locale's full weekday name, variable length (Sunday..Saturday) +.IP b +locale's abbreviated month name (Jan..Dec) +.IP B +locale's full month name, variable length (January..December) +.IP c +locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is +the same as for +.BR ctime (3) +and so to preserve compatibility with that format, there is no fractional part +in the seconds field. +.IP d +day of month (01..31) +.IP D +date (mm/dd/yy) +.IP F +date (yyyy-mm-dd) +.IP h +same as b +.IP j +day of year (001..366) +.IP m +month (01..12) +.IP U +week number of year with Sunday as first day of week (00..53) +.IP w +day of week (0..6) +.IP W +week number of year with Monday as first day of week (00..53) +.IP x +locale's date representation (mm/dd/yy) +.IP y +last two digits of year (00..99) +.IP Y +year (1970...\&) +.RE +.IP %b +The amount of disk space used for this file in 512-byte blocks. Since disk +space is allocated in multiples of the filesystem block size this is usually +greater than %s/512, but it can also be smaller if the file is a sparse file. + +.IP %B\fIk\fP +File's birth time, i.e., its creation time, in the format specified by +.IR k , +which is the same as for %A. +This directive produces an empty string if the underlying operating system or +filesystem does not support birth times. + +.IP %c +File's last status change time in the format returned by the C +.BR ctime (3) +function. +.IP %C\fIk\fP +File's last status change time in the format specified by +.IR k , +which is the same as for %A. +.IP %d +File's depth in the directory tree; 0 means the file is a starting-point. +.IP %D +The device number on which the file exists (the st_dev field of struct +stat), in decimal. +.IP %f +Print the basename; the file's name with any leading directories +removed (only the last element). For +.BR / , +the result is `/'. +See the +.B EXAMPLES +section for an example. + +.IP %F +Type of the filesystem the file is on; this value can be used for +\-fstype. +.IP %g +File's group name, or numeric group ID if the group has no name. +.IP %G +File's numeric group ID. +.IP %h +Dirname; the Leading directories of the file's name (all but the last +element). If the file name contains no slashes (since it is in the +current directory) the %h specifier expands to `.'. For files which +are themselves directories and contain a slash (including +.BR / ), +%h expands to the empty string. See the +.B EXAMPLES +section for an example. +.IP %H +Starting-point under which file was found. +.IP %i +File's inode number (in decimal). +.IP %k +The amount of disk space used for this file in 1\ KB blocks. +Since disk space is allocated in multiples of the filesystem block +size this is usually greater than %s/1024, +but it can also be smaller if the file is a sparse file. +.IP %l +Object of symbolic link (empty string if file is not a symbolic link). +.IP %m +File's permission bits (in octal). This option uses the `traditional' +numbers which most Unix implementations use, but if your particular +implementation uses an unusual ordering of octal permissions bits, you +will see a difference between the actual value of the file's mode and +the output of %m. +Normally you will want to have a leading zero on this number, +and to do this, you should use the +.B # +flag (as in, for example, `%#m'). +.IP %M +File's permissions (in symbolic form, as for +.BR ls ). +This directive is supported in findutils 4.2.5 and later. +.IP %n +Number of hard links to file. +.IP %p +File's name. +.IP %P +File's name with the name of the starting-point under which +it was found removed. +.IP %s +File's size in bytes. +.IP %S +File's sparseness. This is calculated as (BLOCKSIZE*st_blocks / +st_size). The exact value you will get for an ordinary file of a +certain length is system-dependent. However, normally sparse files +will have values less than 1.0, and files which use indirect blocks +may have a value which is greater than 1.0. In general the number of +blocks used by a file is file system dependent. +The value used for BLOCKSIZE is system-dependent, but is usually 512 +bytes. +If the file size is zero, the value printed is undefined. +On systems which lack support for st_blocks, +a file's sparseness is assumed to be 1.0. +.IP %t +File's last modification time in the format returned by the C +.BR ctime (3) +function. +.IP %T\fIk\fP +File's last modification time in the format specified by +.IR k , +which is the same as for %A. +.IP %u +File's user name, or numeric user ID if the user has no name. +.IP %U +File's numeric user ID. +.IP %y +File's type (like in +.BR "ls \-l" ), +U=unknown type (shouldn't happen) +.IP %Y +File's type (like %y), plus follow symbolic links: `L'=loop, `N'=nonexistent, +`?' for any other error when determining the type of the target of a symbolic +link. +.IP %Z +(SELinux only) file's security context. +.IP "%{ %[ %(" +Reserved for future use. +.PP +A `%' character followed by any other character is discarded, but the +other character is printed (don't rely on this, as further format +characters may be introduced). A `%' at the end of the format +argument causes undefined behaviour since there is no following +character. In some locales, it may hide your door keys, while in +others it may remove the final page from the novel you are reading. + +The %m and %d directives support the +.BR # , +.B 0 +and +.B + +flags, but the other directives do not, even if they +print numbers. Numeric directives that do not support these flags +include +.BR G , +.BR U , +.BR b , +.BR D , +.B k +and +.BR n . +The `\-' format flag is supported and changes the alignment of a field +from right-justified (which is the default) to left-justified. +.PP +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + + +.RE +.IP \-prune +True; if the file is a directory, do not descend into it. If +.B \-depth +is given, then +.B \-prune +has no effect. Because +.B \-delete +implies +.BR \-depth , +you cannot usefully use +.B \-prune +and +.B \-delete +together. +For example, to skip the directory +.I src/emacs +and all files and directories under it, and print the names of the other files +found, do something like this: +.in +4m +.nf +find . \-path ./src/emacs \-prune \-o \-print +.fi +.in + + +.IP "\-quit" +Exit immediately (with return value zero if no errors have occurred). +This is different to +.B \-prune +because +.B \-prune +only applies to the contents of pruned directories, while +.B \-quit +simply makes +.B find +stop immediately. No child processes will be left +running. Any command lines which have been built by +.B \-exec\ ...\ + +or +.B \-execdir\ ...\ + +are invoked before the program is +exited. After +.B \-quit +is executed, no more files specified on the command line will be +processed. For example, +.RB ` "find\ \fI/tmp/foo\fP\ \fI/tmp/bar\fP\ \-print\ \-quit" ` +will print only `/tmp/foo`. +.br +One common use of +.B \-quit +is to stop searching the file system once we have +found what we want. For example, if we want to find just a single +file we can do this: +.in +4m +.nf +find / -name needle -print -quit +.fi +.in + +.SS OPERATORS +Listed in order of decreasing precedence: + +.IP "( \fIexpr\fR )" +Force precedence. Since parentheses are special to the shell, you +will normally need to quote them. Many of the examples in this manual +page use backslashes for this purpose: `\e(...\e)' instead of `(...)'. + +.IP "! \fIexpr\fR" +True if \fIexpr\fR is false. This character will also usually need +protection from interpretation by the shell. + +.IP "\-not \fIexpr\fR" +Same as !\& +.IR expr , +but not POSIX compliant. + +.IP "\fIexpr1 expr2\fR" +Two expressions in a row are taken to be joined with an +implied +.BR \-a ; +\fIexpr2\fR is not evaluated if \fIexpr1\fR is false. + +.IP "\fIexpr1\fR \-a \fIexpr2\fR" +Same as +.IR "expr1 expr2" . + +.IP "\fIexpr1\fR \-and \fIexpr2\fR" +Same as +.IR "expr1 expr2" , +but not POSIX compliant. + +.IP "\fIexpr1\fR \-o \fIexpr2\fR" +Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true. + +.IP "\fIexpr1\fR \-or \fIexpr2\fR" +Same as \fIexpr1\fR +.B \-o +.IR expr2 , +but not POSIX compliant. + +.IP "\fIexpr1\fR , \fIexpr2\fR" +List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated. The +value of \fIexpr1\fR is discarded; the value of the list is the value +of +.IR expr2 . +The comma operator can be useful for searching for +several different types of thing, but traversing the filesystem +hierarchy only once. The +.B \-fprintf +action can be used to list the various matched items into several +different output files. +.P +Please note that +.B \-a +when specified implicitly (for example by two tests appearing without +an explicit operator between them) or explicitly has higher precedence +than +.BR \-o . +This means that +.B find . \-name afile \-o \-name bfile \-print +will never print +.IR afile . +. +.SH UNUSUAL FILENAMES +Many of the actions of +.B find +result in the printing of data which is under the control of other +users. This includes file names, sizes, modification times and so +forth. File names are a potential problem since they can contain any +character except `\e0' and `/'. Unusual characters in file names can +do unexpected and often undesirable things to your terminal (for +example, changing the settings of your function keys on some +terminals). Unusual characters are handled differently by various +actions, as described below. + +.IP "\-print0, \-fprint0" +Always print the exact filename, unchanged, even if the output is +going to a terminal. + +.IP "\-ls, \-fls" +Unusual characters are always escaped. White space, backslash, and +double quote characters are printed using C-style escaping (for +example `\ef', `\e\(dq'). Other unusual characters are printed using an +octal escape. Other printable characters (for +.B \-ls +and +.B \-fls +these are the characters between octal 041 and 0176) are printed as-is. + +.IP "\-printf, \-fprintf" +If the output is not going to a terminal, it is printed as-is. +Otherwise, the result depends on which directive is in use. The +directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are +not under control of files' owners, and so are printed as-is. The +directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have +values which are under the control of files' owners but which cannot +be used to send arbitrary data to the terminal, and so these are +printed as-is. The directives %f, %h, %l, %p and %P are quoted. This +quoting is performed in the same way as for GNU +.BR ls . +This is not the same quoting mechanism as the one used for +.B \-ls +and +.BR \-fls . +If you are able to decide what format to use for the output of +.B find +then it is normally better to use `\e0' as a terminator +than to use newline, as file names can contain white space and newline +characters. The setting of the +.B LC_CTYPE +environment variable is used to determine which characters need to be quoted. + +.IP "\-print, \-fprint" +Quoting is handled in the same way as for +.B \-printf +and +.BR \-fprintf . +If you are using +.B find +in a script or in a situation where the matched files might have +arbitrary names, you should consider using +.B \-print0 +instead of +.BR \-print . +.P +The +.B \-ok +and +.B \-okdir +actions print the current filename as-is. This may change in a future release. +. +.SH "STANDARDS CONFORMANCE" +For closest compliance to the POSIX standard, you should set the +.B POSIXLY_CORRECT +environment variable. +The following options are specified in the POSIX standard +(IEEE Std 1003.1-2008, 2016 Edition): + +.IP \fB\-H\fR +This option is supported. + +.IP \fB\-L\fR +This option is supported. + +.IP \fB\-name\fR +This option is supported, but POSIX conformance depends on the +POSIX conformance of the system's +.BR fnmatch (3) +library function. As of findutils-4.2.2, shell metacharacters +(`*', `?' or `[]' for example) match a leading `.', because +IEEE PASC interpretation 126 requires this. +This is a change from previous versions of findutils. + +.IP \fB\-type\fR +Supported. +POSIX specifies `b', `c', `d', `l', `p', `f' and `s'. +GNU find also supports `D', representing a Door, where the OS provides these. +Furthermore, GNU find allows multiple types to be specified at once in a +comma-separated list. + +.IP \fB\-ok\fR +Supported. +Interpretation of the response is according to the `yes' and `no' +patterns selected by setting the +.B LC_MESSAGES +environment variable. +When the +.B POSIXLY_CORRECT +environment variable is set, these patterns are taken system's definition +of a positive (yes) or negative (no) response. +See the system's documentation for +.BR nl_langinfo (3), +in particular YESEXPR and NOEXPR. +When +.B POSIXLY_CORRECT +is not set, the patterns are instead taken from +.BR find 's +own message catalogue. + +.IP \fB\-newer\fR +Supported. If the file specified is a symbolic link, it is always +dereferenced. This is a change from previous behaviour, which used to +take the relevant time from the symbolic link; see the HISTORY section +below. + +.IP \fB\-perm\fR +Supported. If the +.B POSIXLY_CORRECT +environment variable is not set, +some mode arguments (for example +a+x) which are not valid in POSIX +are supported for backward-compatibility. + +.IP "Other primaries" +The primaries +.BR \-atime , +.BR \-ctime , +.BR \-depth , +.BR \-exec , +.BR \-group , +.BR \-links , +.BR \-mtime , +.BR \-nogroup , +.BR \-nouser , +.BR \-ok , +.BR \-path , +.BR \-print , +.BR \-prune , +.BR \-size , +.B \-user +and +.B \-xdev +are all supported. + +.P +The POSIX standard specifies parentheses `(', `)', negation `!' and the +logical AND/OR operators +.B \-a +and +.BR \-o . +.P +All other options, predicates, expressions and so forth are extensions +beyond the POSIX standard. Many of these extensions are not unique to +GNU find, however. +.P +The POSIX standard requires that +.B find +detects loops: +.IP +The +.B find +utility shall detect infinite loops; that is, entering a +previously visited directory that is an ancestor of the last file +encountered. When it detects an infinite loop, find shall write a +diagnostic message to standard error and shall either recover its +position in the hierarchy or terminate. +.P +GNU +.B find +complies with these requirements. The link count of +directories which contain entries which are hard links to an ancestor +will often be lower than they otherwise should be. This can mean that +GNU find will sometimes optimise away the visiting of a subdirectory +which is actually a link to an ancestor. Since +.B find +does not actually enter such a subdirectory, it is allowed to avoid +emitting a diagnostic message. Although this behaviour may be +somewhat confusing, it is unlikely that anybody actually depends on +this behaviour. If the leaf optimisation has been turned off with +.BR \-noleaf , +the directory entry will always be examined and the diagnostic message +will be issued where it is appropriate. Symbolic links cannot be used +to create filesystem cycles as such, but if the +.B \-L +option or the +.B \-follow +option is in use, a diagnostic message is issued when +.B find +encounters a loop of symbolic links. As with loops containing hard +links, the leaf optimisation will often mean that +.B find +knows that it doesn't need to call +.I stat() +or +.I chdir() +on the symbolic link, so this diagnostic is frequently not necessary. +.P +The +.B \-d +option is supported for compatibility with various BSD systems, +but you should use the POSIX-compliant option +.B \-depth +instead. +.P +The +.B POSIXLY_CORRECT +environment variable does not affect the behaviour of the +.B \-regex +or +.B \-iregex +tests because those tests aren't specified in the POSIX standard. +. +.SH "ENVIRONMENT VARIABLES" + +.IP LANG +Provides a default value for the internationalization variables that +are unset or null. + +.IP LC_ALL +If set to a non-empty string value, override the values of all the +other internationalization variables. + +.IP LC_COLLATE +The POSIX standard specifies that this variable affects the pattern +matching to be used for the +.B \-name +option. +GNU find uses the +.BR fnmatch (3) +library function, and so support for +.B LC_COLLATE +depends on the system library. +This variable also affects the interpretation of the response to +.BR \-ok ; +while the +.B LC_MESSAGES +variable selects the actual pattern used to interpret the response to +.BR \-ok , +the interpretation of any bracket expressions in the pattern will be +affected by +.BR LC_COLLATE . + +.IP LC_CTYPE +This variable affects the treatment of character classes used in +regular expressions and also with +the +.B \-name +test, if the system's +.BR fnmatch (3) +library function supports this. This variable also affects the +interpretation of any character classes in the regular expressions +used to interpret the response to the prompt issued by +.BR \-ok . +The +.B LC_CTYPE +environment variable will also affect which characters are considered +to be unprintable when filenames are printed; +see the section UNUSUAL FILENAMES. + +.IP LC_MESSAGES +Determines the locale to be used for internationalised messages. If the +.B POSIXLY_CORRECT +environment variable is set, this also determines the interpretation of +the response to the prompt made by the +.B \-ok +action. + +.IP NLSPATH +Determines the location of the internationalisation message catalogues. + +.IP PATH +Affects the directories which are searched to find the executables +invoked by +.BR \-exec , +.BR \-execdir , +.B \-ok +and +.BR \-okdir . + +.IP POSIXLY_CORRECT +Determines the block size used by +.B \-ls +and +.BR \-fls . +If +.B POSIXLY_CORRECT +is set, blocks are units of 512 bytes. Otherwise they are units of 1024 bytes. +.IP +Setting this variable also turns off +warning messages (that is, implies +.BR \-nowarn ) +by default, because POSIX requires that apart from +the output for +.BR \-ok , +all messages printed on stderr are diagnostics and must result in a +non-zero exit status. +.IP +When +.B POSIXLY_CORRECT +is not set, +.B "\-perm \fI+zzz\fR" +is treated just like +.B "\-perm \fI/zzz\fR" +if +\fI+zzz\fR is not a valid symbolic mode. When +.B POSIXLY_CORRECT +is set, such +constructs are treated as an error. +.IP +When +.B POSIXLY_CORRECT +is set, the response to the prompt made by the +.B \-ok +action is interpreted according to the system's message catalogue, as +opposed to according to +.BR find 's +own message translations. + +.IP TZ +Affects the time zone used for some of the time-related format +directives of +.B \-printf +and +.BR \-fprintf . +. +.SH "EXAMPLES" +.\" A bulleted \[bu] list of examples. +.SS Simple `find|xargs` approach +.IP \[bu] +Find files named +.I core +in or below the directory +.I /tmp +and delete them. +.nf +\& +.in +4m +.B $ find /tmp \-name core \-type f \-print | xargs /bin/rm \-f +.in +\& +.fi +Note that this will work incorrectly if there are +any filenames containing newlines, single or double quotes, or spaces. +. +.SS Safer `find -print0 | xargs -0` approach +.IP \[bu] +Find files named \fIcore\fP in or below the directory \fI/tmp\fP +and delete them, processing filenames in such a way that file or +directory names containing single or double quotes, spaces or newlines +are correctly handled. +.nf +\& +.in +4m +.B $ find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f +.in +\& +.fi +The +.B \-name +test comes before the +.B \-type +test in order to avoid having to call +.BR stat (2) +on every file. +.PP +Note that there is still a race between the time +.B find +traverses the hierarchy printing the matching filenames, and the time the +process executed by +.B xargs +works with that file. +. +.SS Processing arbitrary starting points +.IP \[bu] +Given that another program \fIproggy\fR pre-filters and creates a huge +NUL-separated list of files, process those as starting points, and find +all regular, empty files among them: +.nf +\& +.in +4m +.B $ proggy | find \-files0\-from \- \-maxdepth 0 \-type f \-empty +.in +\& +.fi +The use of +.B `\-files0\-from\ \-` +means to read the names of the starting points from \fIstandard input\fR, +i.e., from the pipe; and +.B \-maxdepth\ 0 +ensures that only explicitly those entries are examined without recursing +into directories (in the case one of the starting points is one). +. +.SS +Executing a command for each file +.IP \[bu] +Run +.I file +on every file in or below the current directory. +.nf +\& +.in +4m +.B $ find . \-type f \-exec file \(aq{}\(aq \e; +.in +\& +.fi +Notice that the braces are enclosed in single quote marks to protect them +from interpretation as shell script punctuation. The semicolon is +similarly protected by the use of a backslash, though single quotes +could have been used in that case also. +.PP +In many cases, one might prefer the +.B `\-exec\ \&...\&\ +` +or better the +.B `\-execdir\ \&...\&\ +` +syntax for performance and security reasons. +. +.SS Traversing the filesystem just once - for 2 different actions +.IP \[bu] +Traverse the filesystem just once, listing set-user-ID files and +directories into +.I /root/suid.txt +and large files into +.IR /root/big.txt . +.nf +\& +.in +4m +.B $ find / \e +.in +4m +.B \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e +.br +.B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e) +.in -4m +.in -4m +\& +.fi +This example uses the line-continuation character \(aq\e\(aq on the first two +lines to instruct the shell to continue reading the command on the next line. +. +.SS +Searching files by age +.IP \[bu] +Search for files in your home directory which have been modified in +the last twenty-four hours. +.nf +\& +.in +4m +.B $ find $HOME \-mtime 0 +.in +\& +.fi +This command works this way because the +time since each file was last modified is divided by 24 hours and any +remainder is discarded. That means that to match +.B \-mtime +.BR 0 , +a file will have to have a modification in the past which is less than +24 hours ago. +. +.SS +Searching files by permissions +.IP \[bu] +Search for files which are executable but not readable. +.nf +\& +.in +4m +.B $ find /sbin /usr/sbin \-executable \e! \-readable \-print +.in +\& +.fi +. +.IP \[bu] +Search for files which have read and write permission for their owner, +and group, but which other users can read but not write to. +.nf +\& +.in +4m +.B $ find . \-perm 664 +.in +\& +.fi +Files which meet these criteria but have other permissions bits set +(for example if someone can execute the file) will not be matched. +. +.IP \[bu] +Search for files which have read and write permission for their owner +and group, and which other users can read, without regard to the +presence of any extra permission bits (for example the executable +bit). +.nf +\& +.in +4m +.B $ find . \-perm \-664 +.in +\& +.fi +This will match a file which has mode +.IR 0777 , +for example. +. +.IP \[bu] +Search for files which are writable by somebody (their owner, or +their group, or anybody else). +.nf +\& +.in +4m +.B $ find . \-perm /222 +.in +\& +.fi +. +.IP \[bu] +Search for files which are writable by either their owner or their group. +.nf +\& +.in +4m +.B $ find . \-perm /220 +.B $ find . \-perm /u+w,g+w +.B $ find . \-perm /u=w,g=w +.in +\& +.fi +All three of these commands do the same thing, but the first one uses +the octal representation of the file mode, and the other two use the +symbolic form. +The files don't have to be writable by both the owner and group to be matched; +either will do. +. +.IP \[bu] +Search for files which are writable by both their owner and their group. +.nf +\& +.in +4m +.B $ find . \-perm \-220 +.B $ find . \-perm \-g+w,u+w +.in +\& +.fi +Both these commands do the same thing. +. +.IP \[bu] +A more elaborate search on permissions. +.nf +\& +.in +4m +.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111 +.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x +.in +\& +.fi +These two commands both search for files that are readable for everybody +.RB ( "\-perm \-444" +or +.BR "\-perm \-a+r" ), +have at least one write bit +set +.RB ( "\-perm /222" +or +.BR "\-perm /a+w" ) +but are not executable for anybody +.RB ( "! \-perm /111" +or +.B ! \-perm /a+x +respectively). +. +.SS +Pruning - omitting files and subdirectories +.IP \[bu] +Copy the contents of +.I /source-dir +to +.IR /dest-dir , +but omit files and directories named +.I .snapshot +(and anything in them). It also omits files or directories whose name ends in +`\(ti', but not their contents. +.nf +\& +.in +4m +.B $ cd /source-dir +.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e +.br +.in +4m +.B | cpio \-pmd0 /dest-dir +.in -4m +.in -4m +\& +.fi +The construct +.B \-prune\ \-o\ \e(\ \&...\&\ \-print0\ \e) +is quite common. The idea here is that the expression before +.B \-prune +matches things which are to be pruned. However, the +.B \-prune +action itself returns true, so the following +.B \-o +ensures that the right hand side is evaluated only for those +directories which didn't get pruned (the contents of the pruned +directories are not even visited, so their contents are irrelevant). +The expression on the right hand side of the +.B \-o +is in parentheses only for clarity. It emphasises that the +.B \-print0 +action takes place only for things that didn't have +.B \-prune +applied to them. Because the default `and' condition between tests +binds more tightly than +.BR \-o , +this is the default anyway, but the parentheses help to show +what is going on. +. +.IP \[bu] +Given the following directory of projects and their associated SCM +administrative directories, perform an efficient search for the +projects' roots: +.nf +\& +.in +4m +.B $ find repo/ \e +.in +4m +.B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e +.B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e +.B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e +.B \e) \-print \-prune +.in -4m +.in -4m +\& +.fi +Sample output: +.nf +\& +.in +4m +.B repo/project1/CVS +.B repo/gnu/project2/.svn +.B repo/gnu/project3/.svn +.B repo/gnu/project3/src/.svn +.B repo/project4/.git +.in +\& +.fi +In this example, +.B \-prune +prevents unnecessary descent into directories that have already been +discovered (for example we do not search +.I project3/src +because we already found +.IR project3/.svn ), +but ensures sibling directories +.RI ( project2 +and +.IR project3 ) +are found. +. +.SS +Other useful examples +.IP \[bu] +Search for several file types. +.nf +\& +.in +4m +.B $ find /tmp \-type f,d,l +.in +\& +.fi +Search for files, directories, and symbolic links in the directory +.I /tmp +passing these types as a comma-separated list (GNU extension), +which is otherwise equivalent to the longer, yet more portable: +.nf +\& +.in +4m +.B $ find /tmp \e( \-type f \-o \-type d \-o \-type l \e) +.in +\& +.fi +. +.IP \[bu] +Search for files with the particular name +.I needle +and stop immediately when we find the first one. +.nf +\& +.in +4m +.B $ find / -name needle -print -quit +.in +\& +.fi +. +.IP \[bu] +Demonstrate the interpretation of the +.B %f +and +.B %h +format directives of the +.B \-printf +action for some corner-cases. +Here is an example including some output. +.nf +\& +.in +4m +.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en' +.B [.][.] +.B [.][..] +.B [][/] +.B [][tmp] +.B [/tmp][TRACE] +.B [.][compile] +.B [compile/64/tests][find] +.in +\& +.fi +. +.SH EXIT STATUS +.B find +exits with status 0 if all files are processed successfully, greater +than 0 if errors occur. +This is deliberately a very broad description, +but if the return value is non-zero, +you should not rely on the correctness of the results of +.BR find . + +When some error occurs, +.B find +may stop immediately, without completing all the actions specified. +For example, some starting points may not have been examined or some +pending program invocations for +.B \-exec\ \&...\&\ {}\ + +or +.B "\-execdir\ \&...\&\ {}\ + +may not have been performed. +. +.SH "HISTORY" +As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for +example) used in filename patterns match a leading `.', because +IEEE POSIX interpretation 126 requires this. +.P +As of findutils-4.3.3, +.B \-perm\ /000 +now matches all files instead of none. +.P +Nanosecond-resolution +timestamps were implemented in findutils-4.3.3. +.P +As of findutils-4.3.11, the +.B \-delete +action sets +.BR find 's +exit status to a nonzero value when it fails. +However, +.B find +will not exit immediately. Previously, +.BR find 's +exit status was unaffected by the failure of +.BR \-delete . +.TS +l l l . +Feature Added in Also occurs in +\-files0\-from 4.9.0 +\-newerXY 4.3.3 BSD +\-D 4.3.1 +\-O 4.3.1 +\-readable 4.3.0 +\-writable 4.3.0 +\-executable 4.3.0 +\-regextype 4.2.24 +\-exec ... + 4.2.12 POSIX +\-execdir 4.2.12 BSD +\-okdir 4.2.12 +\-samefile 4.2.11 +\-H 4.2.5 POSIX +\-L 4.2.5 POSIX +\-P 4.2.5 BSD +\-delete 4.2.3 +\-quit 4.2.3 +\-d 4.2.3 BSD +\-wholename 4.2.0 +\-iwholename 4.2.0 +\-ignore_readdir_race 4.2.0 +\-fls 4.0 +\-ilname 3.8 +\-iname 3.8 +\-ipath 3.8 +\-iregex 3.8 +.TE +.P +The syntax +\.B \-perm +MODE +was removed in findutils-4.5.12, in favour of +\.B \-perm +.BR /MODE . +The +.B +MODE +syntax had been deprecated since findutils-4.2.21 +which was released in 2005. +. +.SH "NON-BUGS" +.SS Operator precedence surprises +The command +.B find . \-name afile \-o \-name bfile \-print +will never print +.I afile +because this is actually equivalent to +.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" . +Remember that the precedence of +.B \-a +is higher than that of +.B \-o +and when there is no operator specified between tests, +.B \-a +is assumed. +.SS \(lqpaths must precede expression\(rq error message +.nf +.B $ find . \-name *.c \-print +find: paths must precede expression +find: possible unquoted pattern after predicate `-name'? +.fi +.P +This happens when the shell could expand the pattern +.I *.c +to more than one file name existing in the current directory, +and passing the resulting file names in the command line to +.B find +like this: +.nf +. +.B find . \-name frcode.c locate.c word_io.c \-print +. +.fi +That command is of course not going to work, because the +.B \-name +predicate allows exactly only one pattern as argument. Instead of doing things +this way, you should enclose the pattern in quotes or escape the wildcard, thus +allowing +.B find +to use the pattern with the wildcard during the search for file name matching +instead of file names expanded by the parent shell: +.nf +.B $ find . \-name \(aq*.c\(aq \-print +.B $ find . \-name \e*.c \-print +.fi +. +.SH "BUGS" +There are security problems inherent in the behaviour that the POSIX +standard specifies for +.BR find , +which therefore cannot be fixed. For example, the +.B \-exec +action is +inherently insecure, and +.B \-execdir +should be used instead. +. +.P +The environment variable +.B LC_COLLATE +has no effect on the +.B \-ok +action. +. +.SH "REPORTING BUGS" +GNU findutils online help: +.br +Report any translation bugs to +.PP +Report any other issue via the form at the GNU Savannah bug tracker: +.RS + +.RE +General topics about the GNU findutils package are discussed at the +.I bug\-findutils +mailing list: +.RS + +.RE +. +.SH COPYRIGHT +Copyright \(co 1990-2022 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +. +.SH "SEE ALSO" +.BR chmod (1), +.BR locate (1), +.BR ls (1), +.BR updatedb (1), +.BR xargs (1), +.BR lstat (2), +.BR stat (2), +.BR ctime (3) +.BR fnmatch (3), +.BR printf (3), +.BR strftime (3), +.BR locatedb (5), +.BR regex (7) +.PP +Full documentation +.br +or available locally via: +.B info find diff --git a/upstream/fedora-40/man1/finger.1 b/upstream/fedora-40/man1/finger.1 new file mode 100644 index 00000000..91fed19b --- /dev/null +++ b/upstream/fedora-40/man1/finger.1 @@ -0,0 +1,194 @@ +.\" Copyright (c) 1989, 1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)finger.1 6.14 (Berkeley) 7/27/91 +.\" $Id: finger.1,v 1.1.1.1 2000/11/03 19:18:15 mk Exp $ +.\" +.Dd August 15, 1999 +.Dt FINGER 1 +.Os "Linux NetKit (0.17)" +.Sh NAME +.Nm finger +.Nd user information lookup program +.Sh SYNOPSIS +.Nm finger +.Op Fl lmsp +.Op Ar user ... +.Op Ar user@host ... +.Sh DESCRIPTION +The +.Nm finger +displays information about the system users. +.Pp +Options are: +.Bl -tag -width flag +.It Fl s +.Nm Finger +displays the user's login name, real name, terminal name and write +status (as a ``*'' after the terminal name if write permission is +denied), idle time, login time, office location and office phone +number. +.Pp +Login time is displayed as month, day, hours and minutes, unless +more than six months ago, in which case the year is displayed rather +than the hours and minutes. +.Pp +Unknown devices as well as nonexistent idle and login times are +displayed as single asterisks. +.Pp +.It Fl l +Produces a multi-line format displaying all of the information +described for the +.Fl s +option as well as the user's home directory, home phone number, login +shell, mail status, and the contents of the files +.Dq Pa .plan , +.Dq Pa .project , +.Dq Pa .pgpkey +and +.Dq Pa .forward +from the user's home directory. +.Pp +Phone numbers specified as eleven digits are printed as ``+N-NNN-NNN-NNNN''. +Numbers specified as ten or seven digits are printed as the appropriate +subset of that string. +Numbers specified as five digits are printed as ``xN-NNNN''. +Numbers specified as four digits are printed as ``xNNNN''. +.Pp +If write permission is denied to the device, the phrase ``(messages off)'' +is appended to the line containing the device name. +One entry per user is displayed with the +.Fl l +option; if a user is logged on multiple times, terminal information +is repeated once per login. +.Pp +Mail status is shown as ``No Mail.'' if there is no mail at all, +``Mail last read DDD MMM ## HH:MM YYYY (TZ)'' if the person has looked +at their mailbox since new mail arriving, or ``New mail received ...'', +`` Unread since ...'' if they have new mail. +.Pp +.It Fl p +Prevents +the +.Fl l +option of +.Nm finger +from displaying the contents of the +.Dq Pa .plan , +.Dq Pa .project +and +.Dq Pa .pgpkey +files. +.It Fl m +Prevent matching of +.Ar user +names. +.Ar User +is usually a login name; however, matching will also be done on the +users' real names, unless the +.Fl m +option is supplied. +All name matching performed by +.Nm finger +is case insensitive. +.El +.Pp +If no options are specified, +.Nm finger +defaults to the +.Fl l +style output if operands are provided, otherwise to the +.Fl s +style. +Note that some fields may be missing, in either format, if information +is not available for them. +.Pp +If no arguments are specified, +.Nm finger +will print an entry for each user currently logged into the system. +.Pp +.Nm Finger +may be used to look up users on a remote machine. +The format is to specify a +.Ar user +as +.Dq Li user@host , +or +.Dq Li @host , +where the default output +format for the former is the +.Fl l +style, and the default output format for the latter is the +.Fl s +style. +The +.Fl l +option is the only option that may be passed to a remote machine. +.Pp +If standard output is a socket, +.Nm finger +will emit a carriage return (^M) before every linefeed (^J). This is +for processing remote finger requests when invoked by +.Xr fingerd 8 . +.Sh FILES +.Bl -tag -width mmmmmmmmmmmmmmm +.It Pa ~/.nofinger +If finger finds this file in a user's home directory, it will, for +finger requests originating outside the local host, firmly deny the +existence of that user. For this to work, the finger program, as +started by +.Xr fingerd 8 , +must be able to see the +.Pa .nofinger +file. This generally means that the home directory containing the file +must have the other-users-execute bit set (o+x). See +.Xr chmod 1 . +If you use this feature for privacy, please test it with ``finger +@localhost'' before relying on it, just in case. +.It ~/.plan +.It ~/.project +.It ~/.pgpkey +These files are printed as part of a long-format request. The +.Pa .project +file is limited to one line; the +.Pa .plan +file may be arbitrarily long. +.El +.Sh SEE ALSO +.Xr chfn 1 , +.Xr passwd 1 , +.Xr w 1 , +.Xr who 1 +.Sh HISTORY +The +.Nm finger +command appeared in +.Bx 3.0 . diff --git a/upstream/fedora-40/man1/fitstopnm.1 b/upstream/fedora-40/man1/fitstopnm.1 new file mode 100644 index 00000000..c0f44dd7 --- /dev/null +++ b/upstream/fedora-40/man1/fitstopnm.1 @@ -0,0 +1,157 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Fitstopnm User Manual" 0 "02 August 2015" "netpbm documentation" + +.SH NAME +fitstopnm - convert a FITS file into a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBfitstopnm\fP +[\fB-image=\fP\fIN\fP] +[\fB-scanmax\fP] +[\fB-printmax\fP] +[\fB-min=\fP\fIf\fP] +[\fB-max=\fP\fIf\fP] +[\fB-omaxval=\fP\fIN\fP +[\fIFITSfile\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBfitstopnm\fP reads a FITS (Flexible Image Transport System) file as +input and produces a PPM image if the FITS file consists of 3 image planes +(NAXIS = 3 and NAXIS3 = 3), or a PGM image if the FITS file consists of 2 +image planes (NAXIS = 2), or if you specify the \fB-image\fP option. +.PP +Note that the PPM image is highly unlikely to be a true PPM image, as it is +not normal for a FITS image to use the third axis as R, G, and B components of +the pixels. The most common interpretation when there are 3 axes is that the +third one is time. So the image is instead a pseudo-PPM in which the three +sample values of a pixel represent something other than color components, for +example gray levels at three instants (this variation on PPM is common in +programs such as \fBfitstopnm\fP that predate the PAM format). +.PP +If you work with FITS images with 3 axes, you should probably always use +the \fB-image\fP option to avoid getting an unwanted pseudo-PPM image. +.PP +The program tells you what kind of PNM image it is writing. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBfitstopnm\fP recognizes the following +command line options: + + + +.TP +\fB-image=\fP\fIN\fP +This is for FITS files with three axes. This option says that the third +axis is for multiple images, and the option value \fIN\fP tells which one you +want. + +.TP +\fB-omaxval=\fP\fIN\fP +.sp +This is the maxval that the output PNM image is to have. +.sp +By default, the maxval is the least possible to retain all the +precision of the FITS input. That means the difference between the +highest and lowest sample value in the input. If the values range +from -5 to 100, for example, the default maxval would be 106 and each +PNM sample value would correspond to one FITS sample value. +.sp +For a FITS input with floating point sample values, the precision is +essentially unlimited, so this is not possible. In that case, the default +maxval is simply 255. +.sp +This option was new in Netpbm 10.39 (June 2007). Before that, the +output maxval is always the default. + +.TP +\fB-min=\fP\fIfloat\fP +.TP +\fB-max=\fP\fIfloat\fP +.sp +You can use these options to override the min and max values as +read from the FITS header or the image data if the header has no +DATAMIN and DATAMAX keywords. + +.TP +\fB-scanmax\fP +Use this option to force the program to scan the data even when the +header has DATAMIN and DATAMAX. + +.TP +\fB-printmax\fP +With this option, the program just prints the min and max values +and quits without doing its normal job. +.sp +This is for use in shell programs. Example: + +.nf +\f(CW + eval 'fitstopnm -printmax $filename | \e + awk {min = $1; max = $2} \e + END {print "min=" min; " max=" max}' +\fP + +.fi + + + +.UN notes +.SH NOTES + +.UN pixelorder +.SS Pixel Order +.PP +You may need to pass the output of \fBfitstopnm\fP through \fBpamflip +-topbottom\fP. See +.UR pamtofits.html#pixelorder +\fBpamtofits\fP +.UE +\& + + +.UN seealso +.SH SEE ALSO +.BR "pamtofits" (1)\c +\&, +.BR "pamflip" (1)\c +\&, +.BR "pgm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1989 by Jef Poskanzer, with modifications by Daniel +Briggs (\fIdbriggs@nrao.edu\fP) and +Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP). +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/fitstopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/flex.1 b/upstream/fedora-40/man1/flex.1 new file mode 100644 index 00000000..e0c96a0c --- /dev/null +++ b/upstream/fedora-40/man1/flex.1 @@ -0,0 +1,163 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH FLEX "1" "January 2024" "The Flex Project" "Programming" +.SH NAME +flex \- the fast lexical analyser generator +.SH SYNOPSIS +.B flex +[\fI\,OPTIONS\/\fR] [\fI\,FILE\/\fR]... +.SH DESCRIPTION +Generates programs that perform pattern\-matching on text. +.SS "Table Compression:" +.TP +\fB\-Ca\fR, \fB\-\-align\fR +trade off larger tables for better memory alignment +.TP +\fB\-Ce\fR, \fB\-\-ecs\fR +construct equivalence classes +.TP +\fB\-Cf\fR +do not compress tables; use \fB\-f\fR representation +.TP +\fB\-CF\fR +do not compress tables; use \fB\-F\fR representation +.TP +\fB\-Cm\fR, \fB\-\-meta\-ecs\fR +construct meta\-equivalence classes +.TP +\fB\-Cr\fR, \fB\-\-read\fR +use read() instead of stdio for scanner input +.TP +\fB\-f\fR, \fB\-\-full\fR +generate fast, large scanner. Same as \fB\-Cfr\fR +.TP +\fB\-F\fR, \fB\-\-fast\fR +use alternate table representation. Same as \fB\-CFr\fR +.TP +\fB\-Cem\fR +default compression (same as \fB\-\-ecs\fR \fB\-\-meta\-ecs\fR) +.SS "Debugging:" +.TP +\fB\-d\fR, \fB\-\-debug\fR +enable debug mode in scanner +.TP +\fB\-b\fR, \fB\-\-backup\fR +write backing\-up information to lex.backup +.TP +\fB\-p\fR, \fB\-\-perf\-report\fR +write performance report to stderr +.TP +\fB\-s\fR, \fB\-\-nodefault\fR +suppress default rule to ECHO unmatched text +.TP +\fB\-T\fR, \fB\-\-trace\fR +flex should run in trace mode +.TP +\fB\-w\fR, \fB\-\-nowarn\fR +do not generate warnings +.TP +\fB\-v\fR, \fB\-\-verbose\fR +write summary of scanner statistics to stdout +.TP +\fB\-\-hex\fR +use hexadecimal numbers instead of octal in debug outputs +.SH FILES +.TP +\fB\-o\fR, \fB\-\-outfile\fR=\fI\,FILE\/\fR +specify output filename +.TP +\fB\-S\fR, \fB\-\-skel\fR=\fI\,FILE\/\fR +specify skeleton file +.TP +\fB\-t\fR, \fB\-\-stdout\fR +write scanner on stdout instead of lex.yy.c +.TP +\fB\-\-yyclass\fR=\fI\,NAME\/\fR +name of C++ class +.TP +\fB\-\-header\-file\fR=\fI\,FILE\/\fR +create a C header file in addition to the scanner +.HP +\fB\-\-tables\-file\fR[=\fI\,FILE\/\fR] write tables to FILE +.SS "Scanner behavior:" +.TP +\fB\-7\fR, \fB\-\-7bit\fR +generate 7\-bit scanner +.TP +\fB\-8\fR, \fB\-\-8bit\fR +generate 8\-bit scanner +.TP +\fB\-B\fR, \fB\-\-batch\fR +generate batch scanner (opposite of \fB\-I\fR) +.TP +\fB\-i\fR, \fB\-\-case\-insensitive\fR +ignore case in patterns +.TP +\fB\-l\fR, \fB\-\-lex\-compat\fR +maximal compatibility with original lex +.TP +\fB\-X\fR, \fB\-\-posix\-compat\fR +maximal compatibility with POSIX lex +.TP +\fB\-I\fR, \fB\-\-interactive\fR +generate interactive scanner (opposite of \fB\-B\fR) +.TP +\fB\-\-yylineno\fR +track line count in yylineno +.SS "Generated code:" +.TP +\-+, \fB\-\-c\fR++ +generate C++ scanner class +.TP +\fB\-Dmacro\fR[=\fI\,defn\/\fR] +#define macro defn (default defn is '1') +.TP +\fB\-L\fR, \fB\-\-noline\fR +suppress #line directives in scanner +.TP +\fB\-P\fR, \fB\-\-prefix\fR=\fI\,STRING\/\fR +use STRING as prefix instead of "yy" +.TP +\fB\-R\fR, \fB\-\-reentrant\fR +generate a reentrant C scanner +.TP +\fB\-\-bison\-bridge\fR +scanner for bison pure parser. +.TP +\fB\-\-bison\-locations\fR +include yylloc support. +.TP +\fB\-\-stdinit\fR +initialize yyin/yyout to stdin/stdout +.TP +\fB\-\-nounistd\fR +do not include +.TP +\fB\-\-noFUNCTION\fR +do not generate a particular FUNCTION +.SS "Miscellaneous:" +.TP +\fB\-c\fR +do\-nothing POSIX option +.TP +\fB\-n\fR +do\-nothing POSIX option +.HP +\-? +.TP +\fB\-h\fR, \fB\-\-help\fR +produce this help message +.TP +\fB\-V\fR, \fB\-\-version\fR +report flex version +.SH "SEE ALSO" +The full documentation for +.B flex +is maintained as a Texinfo manual. If the +.B info +and +.B flex +programs are properly installed at your site, the command +.IP +.B info flex +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/fmt.1 b/upstream/fedora-40/man1/fmt.1 new file mode 100644 index 00000000..b17df353 --- /dev/null +++ b/upstream/fedora-40/man1/fmt.1 @@ -0,0 +1,60 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH FMT "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +fmt \- simple optimal text formatter +.SH SYNOPSIS +.B fmt +[\fI\,-WIDTH\/\fR] [\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Reformat each paragraph in the FILE(s), writing to standard output. +The option \fB\-WIDTH\fR is an abbreviated form of \fB\-\-width\fR=\fI\,DIGITS\/\fR. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-c\fR, \fB\-\-crown\-margin\fR +preserve indentation of first two lines +.TP +\fB\-p\fR, \fB\-\-prefix\fR=\fI\,STRING\/\fR +reformat only lines beginning with STRING, +reattaching the prefix to reformatted lines +.TP +\fB\-s\fR, \fB\-\-split\-only\fR +split long lines, but do not refill +.TP +\fB\-t\fR, \fB\-\-tagged\-paragraph\fR +indentation of first line different from second +.TP +\fB\-u\fR, \fB\-\-uniform\-spacing\fR +one space between words, two after sentences +.TP +\fB\-w\fR, \fB\-\-width\fR=\fI\,WIDTH\/\fR +maximum line width (default of 75 columns) +.TP +\fB\-g\fR, \fB\-\-goal\fR=\fI\,WIDTH\/\fR +goal width (default of 93% of width) +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by Ross Paterson. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) fmt invocation\(aq diff --git a/upstream/fedora-40/man1/fold.1 b/upstream/fedora-40/man1/fold.1 new file mode 100644 index 00000000..43b52612 --- /dev/null +++ b/upstream/fedora-40/man1/fold.1 @@ -0,0 +1,52 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH FOLD "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +fold \- wrap each input line to fit in specified width +.SH SYNOPSIS +.B fold +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Wrap input lines in each FILE, writing to standard output. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-b\fR, \fB\-\-bytes\fR +count bytes rather than columns +.TP +\fB\-c\fR, \fB\-\-characters\fR +count characters rather than columns +.TP +\fB\-s\fR, \fB\-\-spaces\fR +break at spaces +.TP +\fB\-w\fR, \fB\-\-width\fR=\fI\,WIDTH\/\fR +use WIDTH columns instead of 80 +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBfmt\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) fold invocation\(aq diff --git a/upstream/fedora-40/man1/formail.1 b/upstream/fedora-40/man1/formail.1 new file mode 100644 index 00000000..92c861ec --- /dev/null +++ b/upstream/fedora-40/man1/formail.1 @@ -0,0 +1,558 @@ +.\"if n .pl +(135i-\n(.pu) +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.Id $Id$ +.TH FORMAIL 1 \*(Dt BuGless +.rn SH Sh +.de SH +.br +.ne 11 +.Sh "\\$1" +.. +.rn SS Ss +.de SS +.br +.ne 10 +.Ss "\\$1" +.. +.rn TP Tp +.de TP +.br +.ne 9 +.Tp \\$1 +.. +.rn RS Rs +.de RS +.na +.nf +.Rs +.. +.rn RE Re +.de RE +.Re +.fi +.ad +.. +.de Sx +.PP +.ne \\$1 +.RS +.. +.de Ex +.RE +.PP +.. +.SH NAME +formail \- mail (re)formatter +.SH SYNOPSIS +.na +.B formail +.RI [ "\fB\+\fPskip" ] +.RI [ "\fB\-\fPtotal" ] +.RB [ \-bczfrktedqBY ] +.RB [ \-p +.IR prefix ] +.if n .ti +0.5i +.RB [ \-D +.IR "maxlen idcache" ] +.if n .ti +0.5i +.RB [ \-l +.IR folder ] +.if n .ti +0.5i +.RB [ \-x +.IR headerfield ] +.RB [ \-X +.IR headerfield ] +.if n .ti +0.5i +.RB [ \-a +.IR headerfield ] +.RB [ \-A +.IR headerfield ] +.if n .ti +0.5i +.RB [ \-i +.IR headerfield ] +.RB [ \-I +.IR headerfield ] +.if n .ti +0.5i +.RB [ \-u +.IR headerfield ] +.RB [ \-U +.IR headerfield ] +.if n .ti +0.5i +.RB [ \-R +.I oldfield +.IR newfield ] +.if n .ti +0.5i +.RB [ \-n +.RI [ maxprocs +]] +.RB [ \-m +.IR minfields ] +.RB [ \-s +.RI [ command +.RI [ arg +\&.\|.\|.\|]]] +.br +.B formail +.B \-v +.ad +.SH DESCRIPTION +.B formail +is a filter that can be used to force mail into mailbox format, perform +`From ' escaping, generate auto-replying headers, do simple +header munging/extracting or split up a +mailbox/digest/articles file. The mail/mailbox/article contents will be +expected on stdin. +.PP +If formail is supposed to determine the sender of the mail, but is unable +to find any, it will substitute `foo@bar'. +.PP +If formail is started without any command line options, it will force any +mail coming from stdin into mailbox format and will escape +.B all +bogus `From ' lines with a `>'. +.SH OPTIONS +.TP 0.5i +.B \-v +Formail will print its version number and exit. +.TP +.B \-b +Don't escape any bogus mailbox headers (i.e., lines starting with `From '). +.TP +.I "\fB\-p\fP prefix" +Define a different quotation prefix. If unspecified it defaults to `>'. +.TP +.B \-Y +Assume traditional Berkeley mailbox format, ignoring any +.B Content-Length: +fields. +.TP +.B \-c +Concatenate continued fields in the header. Might be convenient when +postprocessing mail with standard (line oriented) text utilities. +.TP +.B \-z +Ensure a whitespace exists between field name and content. +Zap fields which contain only a single whitespace character. +Zap leading and trailing whitespace on fields extracted with +.BR \-x . +.TP +.B \-f +Force formail to simply pass along any non-mailbox format (i.e., don't +generate a `From ' line as the first line). +.TP +.B \-r +Generate an auto-reply header. This will normally throw away all the existing +fields (except X-Loop:) in the original message, fields you wish to preserve +need to be named using the +.B \-i +option. If you use this option in conjunction with +.BR \-k , +you can prevent the body from being `escaped' by also specifying +.BR \-b . +.TP +.B \-k +When generating the auto-reply header or when extracting fields, keep +the body as well. +.TP +.B \-t +Trust the sender to have used a valid return address in his header. This +causes formail to select the +.I header sender +instead of the +.I envelope sender +for the reply. This option should be used when generating auto-reply +headers from news articles or when the sender of the message is +expecting a reply. +.TP +.B \-s +The input will be split up into separate mail messages, and piped into +a program one by one (a new program is started for every part). +.B \-s +has to be the last option specified, the first argument following it is +expected to be the name of a program, any other arguments will be +passed along to it. If you omit the program, then formail will simply +concatenate the split mails on stdout again. See +.BR FILENO . +.TP +.I "\fB\-n\fP [maxprocs]" +Tell formail not to wait for every program to finish before starting +the next (causes splits to be processed in parallel). +.I Maxprocs +optionally specifies an upper limit on the number of concurrently +running processes. +.TP +.B \-e +Do not require empty lines to be preceding the header of a new message +(i.e., the messages could start on every line). +.TP +.B \-d +Tell formail that the messages it is supposed to split need not be in +strict mailbox format (i.e., allows you to split digests/articles or +non-standard mailbox formats). This disables recognition of the +.B Content-Length: +field. +.TP +.B \-l folder +Generate a log summary in the same style as procmail. This includes +the entire "From " line, the Subject: header field, the folder, and +the size of the message in bytes. The mailstat command can be used +to summarize logs in this format. +.TP +.B \-B +Makes formail assume that it is splitting up a BABYL rmail file. +.TP +.I "\fB\-m\fP minfields" +Allows you to specify the number of consecutive headerfields formail +needs to find before it decides it found the start of a new message, it +defaults to 2. +.TP +.B \-q +Tells formail to (still detect but) be quiet about write errors, +duplicate messages and mismatched +.B Content-Length: +fields. This option is on by default, to make it display the messages +use +.BR \-q\- . +.TP +.I "\fB\-D\fP maxlen idcache" +Formail will detect if the Message-ID of the current message has +already been seen using an +.I idcache +file of approximately +.I maxlen +size. If not splitting, it will return success if a duplicate has been +found. If splitting, it will not output duplicate messages. If used +in conjunction with +.BR \-r , +formail will look at the +.I mail address +of the envelope sender +.I instead +at the Message-ID. +.TP +.I "\fB\-x\fP headerfield" +Extract the contents of this +.I headerfield +from the header. Line continuations will be left intact; if you +want the value on a single line then you'll also need the +.B \-c +option. +.TP +.I "\fB\-X\fP headerfield" +Same as +.BR \-x , +but also preserves/includes the field name. +.TP +.I "\fB\-a\fP headerfield" +Append a custom +.I headerfield +onto the header; but only if a similar field does not exist yet. If +you specify either one of the field names +.B Message-ID: +or +.B Resent-Message-ID: +with no field contents, then formail will generate a unique message-ID +for you. +.TP +.I "\fB\-A\fP headerfield" +Append a custom +.I headerfield +onto the header in any case. +.TP +.I "\fB\-i\fP headerfield" +Same as +.BR \-A , +except that any existing similar fields are renamed by prepending an +``Old-'' prefix. If +.I headerfield +consists only of a field-name, it will not be appended. +.TP +.I "\fB\-I\fP headerfield" +Same as +.BR \-i , +except that any existing similar fields are simply removed. If +.I headerfield +consists only of a field-name, it effectively deletes the field. +.TP +.I "\fB\-u\fP headerfield" +Make the first occurrence of this field unique, and thus delete all +subsequent occurrences of it. +.TP +.I "\fB\-U\fP headerfield" +Make the last occurrence of this field unique, and thus delete all +preceding occurrences of it. +.TP +.I "\fB\-R\fP oldfield newfield" +Renames all occurrences of the fieldname +.I oldfield +into +.IR newfield . +.TP +.I "\fB\+\fPskip" +Skip the first +.I skip +messages while splitting. +.TP +.I "\fB\-\fPtotal" +Output at most +.I total +messages while splitting. +.SH NOTES +When renaming, removing, or extracting fields, partial fieldnames may +be used to specify all fields that start with the specified value. +.PP +By default, when generating an auto-reply header formail selects the +envelope sender from the input message. This is correct for vacation +messages and other automatic replies regarding the routing or delivery +of the original message. If the sender is expecting a reply or the +reply is being generated in response to the contents of the original +message then the \-t option should be used. +.PP +.BR RFC822 , +the original standard governing the format of Internet mail +messages, did not specify whether Resent header fields (those that +begin with `Resent\-', such as `Resent\-From:') should be considered +when generating a reply. Since then, the recommended usage of the +Resent headers has evolved to consider them as purely informational and +not for use when generating a reply. This has been codified in +.BR RFC2822 , +the new Internet Message Format standard, which states in part: +.IP +Resent fields are used to identify a message as having been +reintroduced into the transport system by a user. The purpose of +using resent fields is to have the message appear to the final +recipient as if it were sent directly by the original sender, with +all of the original fields remaining the same.\|\|.\|.\|.\|\|They +MUST NOT be used in the normal processing of replies or other such +automatic actions on messages. +.PP +While formail now +ignores Resent headers when generating header replies, versions of +formail prior to 3.14 gave such headers a high precedence. If the old +behavior is needed for established applications it can be specified by +calling formail with the option `-a Resent-' in addition +to the \-r and \-t options. This usage is deprecated +and should not be used in new applications. +.SH ENVIRONMENT +.TP .5i +.B FILENO +While splitting, formail assigns the message number currently being output to +this variable. By presetting FILENO, you can change the initial message +number being used and the width of the zero-padded output. If FILENO is +unset it will default to 000. If FILENO is non-empty and +does not contain a number, FILENO generation is disabled. +.SH EXAMPLES +To split up a digest one usually uses: +.RS +formail +1 \-ds >>the_mailbox_of_your_choice +.RE +or +.RS +formail +1 \-ds procmail +.RE +.PP +To remove all Received: fields from the header: +.RS +formail \-I Received: +.RE +.PP +To remove all fields except From: and Subject: from the header: +.RS +formail \-k \-X From: \-X Subject: +.RE +.PP +To supersede the Reply-To: field in a header you could use: +.RS +formail \-i "Reply-To: foo@bar" +.RE +.PP +To convert a non-standard mailbox file into a standard mailbox file you can +use: +.RS +formail \-ds >new_mailbox +.RE +.PP +Or, if you have a very tolerant mailer: +.RS +formail \-a Date: \-ds >new_mailbox +.RE +.PP +To extract the header from a message: +.RS +formail \-X "" +.RE +or +.RS +sed \-e '/^$/ q' +.RE +.PP +To extract the body from a message: +.RS +formail \-I "" +.RE +or +.RS +sed \-e '1,/^$/ d' +.RE +.SH "SEE ALSO" +.na +.nh +.BR mail (1), +.BR sendmail (8), +.BR procmail (1), +.BR sed (1), +.BR sh (1), +.BR RFC822 , +.BR RFC2822 , +.B RFC1123 +.hy +.ad +.SH DIAGNOSTICS +.TP 2.3i +Can't fork +Too many processes on this machine. +.TP +Content-Length: field exceeds actual length by nnn bytes +The Content-Length: field in the header specified a length that was longer +than the actual body. This causes this message to absorb a number of +subsequent messages following it in the same mailbox. +.TP +Couldn't write to stdout +The program that formail was trying to pipe into didn't accept all the data +formail sent to it; this diagnostic can be suppressed by the +.B \-q +option. +.TP +Duplicate key found: x +The Message-ID or sender x in this message was found in the idcache; this +diagnostic can be suppressed by the +.B \-q +option. +.TP +Failed to execute "x" +Program not in path, or not executable. +.TP +File table full +Too many open files on this machine. +.TP +Invalid field-name: "x" +The specified field-name "x" contains control characters, or cannot be a +partial field-name for this option. +.SH WARNINGS +You can save yourself and others a lot of grief if you try to avoid using +this autoreply feature on mails coming through mailinglists. Depending +on the format of the incoming mail (which in turn depends on both the +original sender's mail agent and the mailinglist setup) formail could +decide to generate an autoreply header that replies to the list. +.PP +In the tradition of UN*X utilities, formail will do exactly what +you ask it to, even if it results in a +.RB non- RFC822 +compliant message. In particular, formail will let you generate +header fields whose name ends in a space instead of a colon. While +this is correct for the leading `From ' line, that line is not a +header field so much as the message separator for the mbox mailbox +format. Multiple occurrences of such a line or any other colonless +header field will be considered by many mail programs, including +formail itself, as the beginning of a new message. Others will +consider the message to be corrupt. Because of this, you should +not use the +.B \-i +option with the `From ' line as the resulting renamed line, +`Old-From ', will probably not do what you want it to. If +you want to save the original `From ' line, rename it with the +.B \-R +option to a legal header field such as `X-From_:'. +.SH BUGS +When formail has to generate a leading `From ' line it normally will contain +the current date. If formail is given the option `\-a Date:', +it will use the date from the `Date:' field in the header (if present). +However, since formail copies it verbatim, the format will differ from that +expected by most mail readers. +.PP +If formail is instructed to delete or rename the leading `From ' line, it +will not automatically regenerate it as usual. To force formail to regenerate +it in this case, include \fB\-a 'From '\fP. +.PP +If formail is not called as the first program in a pipe and it is told to +split up the input in several messages, then formail will not terminate until +the program it receives the input from closes its output or terminates itself. +.PP +If formail is instructed to generate an autoreply mail, it will +.B never +put more than one address in the `To:' field. +.SH MISCELLANEOUS +Formail is eight-bit clean. +.PP +When formail has to determine the sender's address, every +.B RFC822 +conforming +mail address is allowed. Formail will always strip down the address to +its minimal form (deleting excessive comments and whitespace). +.PP +The regular expression that is used to find `real' postmarks is: +.RS +"\en\enFrom [\et ]*[^\et\en ]+[\et ]+[^\en\et ]" +.RE +.PP +If a +.B Content-Length: +field is found in a header, formail will copy the number of specified bytes in +the body verbatim before resuming the regular scanning for message boundaries +(except when splitting digests or Berkeley mailbox format is assumed). +.PP +Any header lines immediately following the leading `From ' line +that start with `>From ' are considered to be a continuation +of the `From ' line. If instructed to rename the `From ' line, +formail will change each leading `>' into a space, thereby +transforming those lines into normal +.B RFC822 +continuations. +.SH NOTES +Calling up formail with the \-h or \-? options will cause +it to display a command-line help page. +.Sh SOURCE +This program is part of the +.I procmail mail-processing-package +(v3.24) available at http://www.procmail.org/ or +ftp.procmail.org in +.BR pub/procmail/ . +.Sh MAILINGLIST +There exists a mailinglist for questions relating to any program in the +procmail package: +.RS + +.RS +for submitting questions/answers. +.RE + +.RS +for subscription requests. +.RE +.PP +.RE +If you would like to stay informed about new versions and official patches send +a subscription request to +.RS +procmail-announce-request@procmail.org +.RE +(this is a readonly list). +.SH AUTHORS +Stephen R. van den Berg +.RS + +.RE +.\".if n .pl -(\n(.tu-1i) +.rm SH +.rn Sh SH +.rm SS +.rn Ss SS +.rm TP +.rn Tp TP +.rm RS +.rn Rs RS +.rm RE +.rn Re RE diff --git a/upstream/fedora-40/man1/fstopgm.1 b/upstream/fedora-40/man1/fstopgm.1 new file mode 100644 index 00000000..7316b3b2 --- /dev/null +++ b/upstream/fedora-40/man1/fstopgm.1 @@ -0,0 +1,98 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Fstopgm User Manual" 0 "06 April 89" "netpbm documentation" + +.SH NAME +fstopgm - convert a Usenix FaceSaver(tm) file into a PGM image + + +.UN synopsis +.SH SYNOPSIS + +\fBfstopgm\fP +[\fIfsfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBfstopgm\fP reads a Usenix FaceSaver(tm) file as input and +produces a PGM image as output. +.PP +FaceSaver(tm) files sometimes have rectangular pixels. While +\fBfstopgm\fP won't re-scale them into square pixels for you, it will +give you the precise \fBpamscale\fP command that will do the job. +Because of this, reading a FaceSaver(tm) image is a two-step process. +First you do: + +.nf + fstopgm > /dev/null + +.fi + +This will tell you whether you need to use \fBpamscale.\fP + +Then use one of the following pipelines: +.nf + fstopgm | pnmnorm + fstopgm | pamscale -whatever | pnmnorm + +.fi + +To go to PBM, you want something more like one of these: +.nf + fstopgm | pamenlarge 3 | pnmnorm | pamditherbw + fstopgm | pamenlarge 3 | pamscale | pnmnorm | pamditherbw + +.fi + +You want to enlarge when going to a bitmap because otherwise you lose +information; but enlarging by more than 3 does not look good. +.PP +FaceSaver is a registered trademark of Metron Computerware Ltd. of +Oakland, CA. + + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBfstopgm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "pgmtofs" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "pnmnorm" (1)\c +\&, +.BR "pamenlarge" (1)\c +\&, +.BR "pamscale" (1)\c +\&, +.BR "pamditherbw" (1)\c +\& + + +.UN author +.SH AUTHOR + +Copyright (C) 1989 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/fstopgm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/funzip.1 b/upstream/fedora-40/man1/funzip.1 new file mode 100644 index 00000000..30206e4b --- /dev/null +++ b/upstream/fedora-40/man1/funzip.1 @@ -0,0 +1,127 @@ +.\" Copyright (c) 1990-2009 Info-ZIP. All rights reserved. +.\" +.\" See the accompanying file LICENSE, version 2009-Jan-02 or later +.\" (the contents of which are also included in unzip.h) for terms of use. +.\" If, for some reason, all these files are missing, the Info-ZIP license +.\" also may be found at: ftp://ftp.info-zip.org/pub/infozip/license.html +.\" +.\" funzip.1 by Greg Roelofs and others. +.\" +.\" ========================================================================= +.\" define .EX/.EE (for multiline user-command examples; normal Courier font) +.de EX +.in +4n +.nf +.ft CW +.. +.de EE +.ft R +.fi +.in -4n +.. +.\" ========================================================================= +.TH FUNZIP 1L "20 April 2009 (v3.95)" "Info-ZIP" +.SH NAME +funzip \- filter for extracting from a ZIP archive in a pipe +.PD +.SH SYNOPSIS +\fBfunzip\fP [\fB\-password\fP] [\fIinput[.zip|.gz]\fP] +.\" ========================================================================= +.SH ARGUMENTS +.IP [\fI\-password\fP] +Optional password to be used if ZIP archive is encrypted. Decryption +may not be supported at some sites. See DESCRIPTION for more details. +.IP [\fIinput[.zip|.gz]\fP] +Optional input archive file specification. See DESCRIPTION for details. +.PD +.\" ========================================================================= +.SH DESCRIPTION +.I funzip +without a file argument acts as a filter; that is, it assumes that a +ZIP archive (or a \fIgzip\fP'd(1) file) is being piped into +standard input, and it extracts the first member from the archive to stdout. +When stdin comes from a tty device, +.I funzip +assumes that this cannot be a stream of (binary) compressed data and +shows a short help text, instead. +If there is a file argument, then input is read from the specified file +instead of from stdin. +.PP +A password for encrypted zip files can be specified +on the command line (preceding the file name, if any) by prefixing the +password with a dash. Note that this constitutes a security risk on many +systems; currently running processes are often visible via simple commands +(e.g., \fIps\fP(1) under Unix), and command-line histories can be read. +If the first entry of the zip file is encrypted and +no password is specified on the command line, then the user is prompted for +a password and the password is not echoed on the console. +.PP +Given the limitation on single-member extraction, \fIfunzip\fP is most +useful in conjunction with a secondary archiver program such as \fItar\fP(1). +The following section includes an example illustrating this usage in the +case of disk backups to tape. +.PD +.\" ========================================================================= +.SH EXAMPLES +To use \fIfunzip\fP to extract the first member file of the archive test.zip +and to pipe it into \fImore\fP(1): +.PP +.EX +funzip test.zip | more +.EE +.PP +To use \fIfunzip\fP to test the first member file of test.zip (any errors +will be reported on standard error): +.PP +.EX +funzip test.zip > /dev/null +.EE +.PP +To use \fIzip\fP and \fIfunzip\fP in place of \fIcompress\fP(1) and +\fIzcat\fP(1) (or \fIgzip\fP(1L) and \fIgzcat\fP(1L)) for tape backups: +.PP +.EX +tar cf \- . | zip \-7 | dd of=/dev/nrst0 obs=8k +dd if=/dev/nrst0 ibs=8k | funzip | tar xf \- +.EE +.PP +(where, for example, nrst0 is a SCSI tape drive). +.PD +.\" ========================================================================= +.SH BUGS +When piping an encrypted file into \fImore\fP and allowing \fIfunzip\fP +to prompt for password, the terminal may sometimes be reset to a non-echo +mode. This is apparently due to a race condition between the two programs; +\fIfunzip\fP changes the terminal mode to non-echo before \fImore\fP reads +its state, and \fImore\fP then ``restores'' the terminal to this mode before +exiting. To recover, run \fIfunzip\fP on the same file but redirect to +/dev/null rather than piping into more; after prompting again for the +password, \fIfunzip\fP will reset the terminal properly. +.PP +There is presently no way to extract any member but the first from a ZIP +archive. This would be useful in the case where a ZIP archive is included +within another archive. In the case where the first member is a directory, +\fIfunzip\fP simply creates the directory and exits. +.PP +The functionality of \fIfunzip\fP should be incorporated into \fIunzip\fP +itself (future release). +.PD +.\" ========================================================================= +.SH "SEE ALSO" +\fIgzip\fP(1L), \fIunzip\fP(1L), \fIunzipsfx\fP(1L), \fIzip\fP(1L), +\fIzipcloak\fP(1L), \fIzipinfo\fP(1L), \fIzipnote\fP(1L), \fIzipsplit\fP(1L) +.PD +.\" ========================================================================= +.SH URL +The Info-ZIP home page is currently at +.EX +\fChttp://www.info-zip.org/pub/infozip/\fR +.EE +or +.EX +\fCftp://ftp.info-zip.org/pub/infozip/\fR . +.EE +.PD +.\" ========================================================================= +.SH AUTHOR +Mark Adler (Info-ZIP) diff --git a/upstream/fedora-40/man1/fuse2fs.1 b/upstream/fedora-40/man1/fuse2fs.1 new file mode 100644 index 00000000..6b1f2136 --- /dev/null +++ b/upstream/fedora-40/man1/fuse2fs.1 @@ -0,0 +1,79 @@ +.\" -*- nroff -*- +.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH FUSE2FS 1 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +fuse2fs \- FUSE file system client for ext2/ext3/ext4 file systems +.SH SYNOPSIS +.B fuse2fs +[ +.B device/image +] +[ +.B mountpoint +] +[ +.I options +] +.SH DESCRIPTION +.B fuse2fs +is a FUSE file system client that supports reading and writing from +devices or image files containing ext2, ext3, and ext4 file systems. +.SH OPTIONS +.SS "general options:" +.TP +\fB\-o\fR opt,[opt...] +mount options +.TP +\fB\-h\fR \fB\-\-help\fR +print help +.TP +\fB\-V\fR \fB\-\-version\fR +print version +.SS "fuse2fs options:" +.TP +\fB-o\fR ro +read-only mount +.TP +\fB-o\fR errors=panic +dump core on error +.TP +\fB-o\fR minixdf +minix-style df +.TP +\fB-o\fR fakeroot +pretend to be root for permission checks +.TP +\fB-o\fR no_default_opts +do not include default fuse options +.TP +\fB-o\fR norecovery +do not replay the journal and mount the file system read-only +.TP +\fB-o\fR fuse2fs_debug +enable fuse2fs debugging +.SS "FUSE options:" +.TP +\fB-d -o\fR debug +enable debug output (implies -f) +.TP +\fB-f\fR +foreground operation +.TP +\fB-s\fR +disable multi-threaded operation +.P +For other FUSE options please see +.BR mount.fuse (8) +or see the output of +.I fuse2fs \-\-helpfull +.SH AVAILABILITY +.B fuse2fs +is part of the e2fsprogs package and is available from +http://e2fsprogs.sourceforge.net. +.SH SEE ALSO +.BR ext4 (5) +.BR e2fsck (8), +.BR mount.fuse (8) + diff --git a/upstream/fedora-40/man1/g3topbm.1 b/upstream/fedora-40/man1/g3topbm.1 new file mode 100644 index 00000000..e13eae9b --- /dev/null +++ b/upstream/fedora-40/man1/g3topbm.1 @@ -0,0 +1,154 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "G3topbm User Manual" 0 "03 December 2008" "netpbm documentation" + +.SH NAME +g3topbm - convert a Group 3 fax file into a PBM image + +.UN synopsis +.SH SYNOPSIS + +\fBg3topbm\fP +[\fB-kludge\fP] +[\fB-reversebits\fP] +[\fB-stretch\fP] +[\fB-width=\fP\fIpixels\fP | paper_size={A3|A4|A5|A6|B4}] +[\fB-stop_error\fP] +[\fIg3file\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBg3topbm\fP reads a Group 3 fax file with MH (Modified Huffman) +compression as input and produces a PBM image as output. +.PP +\fBg3topbm\fP tolerates various deviations from the standard, +so as to recover some of the image if there was a transmission error. +One thing it tolerates is lines of varying length. The standard requires +all the lines to be the same length; \fBg3topbm\fP makes the output +image as wide as the longest line in the input and pads the others on +the right. It warns you when it does this. +.PP +You can use the \fBstop_error\fP option to make \fBg3topbm\fP +insist on valid input. +.PP +There is no Netpbm program that understands the other G3 fax +compression methods: MR (Modified Read) and MMR (Modified Modified Read). +.PP +Note that the Group 3 fax file format does not include any kind of a +signature so that \fBg3topbm\fP might verify it's actually looking at a G3 +file or that the compression method is MH. The program will interpret any +sequence of bytes you give it as if it is G3 and, while typically issuing a +lot of error messages about the file not conforming to the G3 MH format, will +produce output (unless you use +\fB-stoperror\fP). In particular, if you feed \fBg3topbm\fP an MR or MMR +file, it will not tell you of your mistake. +.PP +There are subformats of TIFF that use the Group 3 fax encodings +inside. See \fBtifftopnm\fP. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBg3topbm\fP recognizes the following +command line options: + + +.TP +\fB-kludge\fP +Tells \fBg3topbm\fP to ignore the first few lines of the file; +sometimes fax files have some junk at the beginning. + +.TP +\fB-reversebits\fP +Tells \fBg3topbm\fP to interpret bits least-significant first, +instead of the default most-significant first. Apparently some fax +modems do it one way and others do it the other way. If you get a +whole bunch of "bad code word" messages, try using this +option. + +.TP +\fB-stretch\fP +This option tells \fBg3topbm\fP to stretch the image vertically by +duplicating each row. This is for the low-quality transmission mode. + +.TP +\fB-width=\fP\fIpixels\fP +This option tells \fBg3topbm\fP that the image is supposed to be +\fIpixels\fP pixels wide. If any line in it is not that size, \fBg3topbm\fP +issues a warning or fails, depending on whether you specify +\fB-stop_error\fP. +.sp +You cannot specify both \fB-width\fP and \fB-paper_size\fP. +.sp +This option was new in Netpbm 10.33 (March 2006). + +.TP +\fB-paper_size=\fP{\fBA3\fP,\fBA4\fP,\fBA5\fP,\fBA6\fP,\fBB4\fP} +This option tells \fBg3topbm\fP for what size paper this image is +supposed to be formatted. \fBg3topbm\fP uses the width of the paper +the same way as with the \fB-width\fP option. \fBg3topbm\fP +does not use the height of the paper for anything. +.sp +You cannot specify both \fB-width\fP and \fB-paper_size\fP. +.sp +This option was new in Netpbm 10.33 (March 2006). + +.TP +\fB-stop_error\fP +This option tells \fBg3topbm\fP to fail when it finds a problem +in the input. "Fail" means it terminates with a nonzero +status code with the contents of the output file undefined. +.sp +If you don't specify this option, \fBg3topbm\fP does its best to +work around input errors and salvage as much of the image as possible +in the output image. It first tries to resynchronize to a later line +by searching for the next End Of Line marker, skipping any lines or +partial lines in between. It saves the beginning of the line in which +it encountered the problem. If the input file ends prematurely, +\fBg3topbm\fP produces output containing the lines up to where it +encountered the problem. +.sp +\fBg3topbm\fP issues warning messages when it continues in spite of +input errors. +.sp +This option was new in Netpbm 10.24 (August 2004). Before that, +\fBg3topbm\fP always failed when it encountered premature EOF and +never failed when it encountered other problems. + + + + +.UN seealso +.SH SEE ALSO +.BR "pbmtog3" (1)\c +\&, +.BR "tifftopnm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "fax formats" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/g3topbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/gawk.1 b/upstream/fedora-40/man1/gawk.1 new file mode 100644 index 00000000..8bdda3b0 --- /dev/null +++ b/upstream/fedora-40/man1/gawk.1 @@ -0,0 +1,2513 @@ +.ds PX \s-1POSIX\s+1 +.ds UX \s-1UNIX\s+1 +.ds GN \s-1GNU\s+1 +.ds AK \s-1AWK\s+1 +.ds EP \fIGAWK: Effective AWK Programming\fP +.if !\n(.g \{\ +. if !\w|\*(lq| \{\ +. ds lq `` +. if \w'\(lq' .ds lq "\(lq +. \} +. if !\w|\*(rq| \{\ +. ds rq '' +. if \w'\(rq' .ds rq "\(rq +. \} +.\} +.TH GAWK 1 "Nov 02 2023" "Free Software Foundation" "Utility Commands" +.SH NAME +gawk \- pattern scanning and processing language +.SH SYNOPSIS +.B gawk +[ \*(PX or \*(GN style options ] +.B \-f +.I program-file +[ +.B \-\^\- +] file .\|.\|. +.br +.B gawk +[ \*(PX or \*(GN style options ] +[ +.B \-\^\- +] +.I program-text +file .\|.\|. +.SH DESCRIPTION +.I Gawk +is the \*(GN Project's implementation of the \*(AK programming language. +It conforms to the definition of the language in +the \*(PX 1003.1 standard. +This version in turn is based on the description in +.IR "The AWK Programming Language" , +by Aho, Kernighan, and Weinberger. +.I Gawk +provides the additional features found in the current version +of Brian Kernighan's +.I awk +and numerous \*(GN-specific extensions. +.PP +The command line consists of options to +.I gawk +itself, the \*(AK program text (if not supplied via the +.B \-f +or +.B \-\^\-include +options), and values to be made +available in the +.B ARGC +and +.B ARGV +pre-defined \*(AK variables. +.SH PREFACE +This manual page is intentionally as terse as possible. +Full details are provided in \*(EP, and you should look +there for the full story on any specific feature. +Where possible, links to the online version of the manual +are provided. +.SH OPTION FORMAT +.I Gawk +options may be either traditional \*(PX-style one letter options, +or \*(GN-style long options. \*(PX options start with a single \*(lq\-\*(rq, +while long options start with \*(lq\-\^\-\*(rq. +Long options are provided for both \*(GN-specific features and +for \*(PX-mandated features. +.PP +.IR Gawk -specific +options are typically used in long-option form. +Arguments to long options are either joined with the option +by an +.B = +sign, with no intervening spaces, or they may be provided in the +next command line argument. +Long options may be abbreviated, as long as the abbreviation +remains unique. +.PP +Additionally, every long option has a corresponding short +option, so that the option's functionality may be used from +within +.B #! +executable scripts. +.SH OPTIONS +.I Gawk +accepts the following options. +Standard options are listed first, followed by options for +.I gawk +extensions, listed alphabetically by short option. +.TP +.BI \-f " program-file\fR,\fP " \-\^\-file " program-file" +Read the \*(AK program source from the file +.IR program-file , +instead of from the first command line argument. +Multiple +.B \-f +options may be used. +Files read with +.B \-f +are treated as if they begin with an implicit \fB@namespace "awk"\fR statement. +.TP +.BI \-F " fs\fR, \fP" \-\^\-field-separator " fs" +Use +.I fs +for the input field separator (the value of the +.B FS +predefined +variable). +.TP +\fB\-v\fI var\fB\^=\^\fIval\fR, \fB\-\^\-assign \fIvar\fB\^=\^\fIval\fR +Assign the value +.I val +to the variable +.IR var , +before execution of the program begins. +Such variable values are available to the +.B BEGIN +rule of an \*(AK program. +.TP +.BR \-b ", " \-\^\-characters\-as\-bytes +Treat all input data as single-byte characters. +The +.B \-\^\-posix +option overrides this one. +.TP +.BR \-c ", " \-\^\-traditional +Run in +.I compatibility +mode. In compatibility mode, +.I gawk +behaves identically to Brian Kernighan's +.IR awk ; +none of the \*(GN-specific extensions are recognized. +.TP +.BR \-C ", " \-\^\-copyright +Print the short version of the \*(GN copyright information message on +the standard output and exit successfully. +.TP +\fB\-d\fR[\fIfile\fR], \fB\-\^\-dump-variables\fR[\fB=\fIfile\fR] +Print a sorted list of global variables, their types and final values to +.IR file . +The default file is +.B awkvars.out +in the current directory. +.TP +\fB\-D\fR[\fIfile\fR], \fB\-\^\-debug\fR[\fB=\fIfile\fR] +Enable debugging of \*(AK programs. +By default, the debugger reads commands interactively from the keyboard +(standard input). +The optional +.I file +argument specifies a file with a list +of commands for the debugger to execute non-interactively. +.sp .5 +In this mode of execution, +.I gawk +loads the +AWK source code and then prompts for debugging commands. +.I Gawk +can only debug AWK program source provided with the +.B \-f +and +.B \-\^\-include +options. +The debugger is documented in \*(EP; see +.IR https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger . +.TP +.BI \-e " program-text\fR, \fP" \-\^\-source " program-text" +Use +.I program-text +as \*(AK program source code. +Each argument supplied via +.B \-e +is treated as if it begins with an implicit \fB@namespace "awk"\fR statement. +.TP +\fB\-E \fIfile\fR, \fB\-\^\-exec \fIfile\fR +Similar to +.BR \-f , +however, this option is the last one processed. +This should be used with +.B #! +scripts, particularly for CGI applications, to avoid +passing in options or source code (!) on the command line +from a URL. +This option disables command-line variable assignments. +.TP +.BR \-g ", " \-\^\-gen\-pot +Scan and parse the \*(AK program, and generate a \*(GN +.B \&.pot +(Portable Object Template) +format file on standard output with entries for all localizable +strings in the program. The program itself is not executed. +.TP +.BR \-h ", " \-\^\-help +Print a relatively short summary of the available options on +the standard output. +Per the +.IR "GNU Coding Standards" , +these options cause an immediate, successful exit. +.TP +\fB\-i \fIinclude-file\fR, \fB\-\^\-include \fIinclude-file\fR +Load an awk source library. +This searches for the library using the +.B AWKPATH +environment variable. If the initial search fails, another attempt will +be made after appending the +.B \&.awk +suffix. The file will be loaded only +once (i.e., duplicates are eliminated), and the code does not constitute +the main program source. +Files read with +.B \-\^\-include +are treated as if they begin with an implicit \fB@namespace "awk"\fR statement. +.TP +.BR \-I ", " \-\^\-trace +Print the internal byte code names as they are executed when running +the program. The trace is printed to standard error. Each ``op code'' +is preceded by a +.B + +sign in the output. +.TP +\fB\-k\fR, \fB\-\^\-csv\fR +Enable CSV special processing. +See +.BR "Comma Separated Values" , +below, for more detail. +.TP +.BI \-l " lib\fR, " \-\^\-load " lib" +Load a +.I gawk +extension from the shared library +.IR lib . +This searches for the library using the +.B AWKLIBPATH +environment variable. If the initial search fails, another attempt will +be made after appending the default shared library suffix for the platform. +The library initialization routine is expected to be named +.BR dl_load() . +.TP +\fB\-L \fR[\fIvalue\fR], \fB\-\^\-lint\fR[\fB=\fIvalue\fR] +Provide warnings about constructs that are +dubious or non-portable to other \*(AK implementations. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options +for the list of possible values for +.IR value . +.TP +.BR \-M ", " \-\^\-bignum +Force arbitrary precision arithmetic on numbers. This option has +no effect if +.I gawk +is not compiled to use the GNU MPFR and GMP libraries. +(In such a case, +.I gawk +issues a warning.) +.sp +.B NOTE: +This feature is +.IR "on parole" . +The primary +.I gawk +maintainer is no longer supporting it, although there is +a member of the development team who is. If this situation +changes, the feature +will be removed from +.IR gawk . +.ig +Set +.B GAWK_NO_MPFR_WARN +in the environment to silence the warning. +.. +.TP +.BR \-n ", " \-\^\-non\-decimal\-data +Recognize octal and hexadecimal values in input data. +.I "Use this option with great caution!" +.TP +.BR \-N ", " \-\^\-use\-lc\-numeric +Force +.I gawk +to use the locale's decimal point character when parsing input data. +.ig +.\" This option is left undocumented, on purpose. +.TP +.BR "\-W nostalgia" ", " \-\^\-nostalgia +Provide a moment of nostalgia for long time +.I awk +users. +.. +.TP +\fB\-o\fR[\fIfile\fR], \fB\-\^\-pretty-print\fR[\fB=\fIfile\fR] +Output a pretty printed version of the program to +.IR file . +The default file is +.B awkprof.out +in the current directory. +This option implies +.BR \-\^\-no\-optimize . +.TP +.BR \-O ", " \-\^\-optimize +Enable +.IR gawk 's +default optimizations upon the internal representation of the program. +This option is on by default. +.TP +\fB\-p\fR[\fIprof-file\fR], \fB\-\^\-profile\fR[\fB=\fIprof-file\fR] +Start a profiling session, and send the profiling data to +.IR prof-file . +The default is +.B awkprof.out +in the current directory. +The profile contains execution counts of each statement in the program +in the left margin and function call counts for each user-defined function. +.I Gawk +runs more slowly in this mode. +This option implies +.BR \-\^\-no\-optimize . +.TP +.BR \-P ", " \-\^\-posix +This turns on +.I compatibility +mode, and disables a number of common extensions. +.TP +.BR \-r ", " \-\^\-re\-interval +Enable the use of +.I "interval expressions" +in regular expression matching. +Interval expressions +are enabled by default, but this option remains for backwards compatibility. +.TP +.BR \-s ", " \-\^\-no\-optimize +Disable +.IR gawk 's +default optimizations upon the internal representation of the program. +.TP +.BR \-S ", " \-\^\-sandbox +Run +.I gawk +in sandbox mode, disabling the +.B system() +function, input redirection with +.BR getline , +output redirection with +.BR print " and " printf , +and loading dynamic extensions. +Command execution (through pipelines) is also disabled. +.TP +.BR \-t ", " \-\^\-lint\-old +Provide warnings about constructs that are +not portable to the original version of \*(UX +.IR awk . +.TP +.BR \-V ", " \-\^\-version +Print version information for this particular copy of +.I gawk +on the standard output. +This is useful when reporting bugs. +Per the +.IR "GNU Coding Standards" , +these options cause an immediate, successful exit. +.TP +.B \-\^\- +Signal the end of options. This is useful to allow further arguments to the +\*(AK program itself to start with a \*(lq\-\*(rq. +.PP +In compatibility mode, +any other options are flagged as invalid, but are otherwise ignored. +In normal operation, as long as program text has been supplied, unknown +options are passed on to the \*(AK program in the +.B ARGV +array for processing. +.PP +For \*(PX compatibility, the +.B \-W +option may be used, followed by the name of a long option. +.SH AWK PROGRAM EXECUTION +An \*(AK program consists of a sequence of +optional directives, +pattern-action statements, +and optional function definitions. +.RS +.PP +\fB@include "\fIfilename\^\fB" +.br +\fB@load "\fIfilename\^\fB" +.br +\fB@namespace "\fIname\^\fB" +.br +\fIpattern\fB { \fIaction statements\fB }\fR +.br +\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR +.RE +.PP +.I Gawk +first reads the program source from the +.IR program-file (s) +if specified, +from arguments to +.BR \-\^\-source , +or from the first non-option argument on the command line. +The +.B \-f +and +.B \-\^\-source +options may be used multiple times on the command line. +.I Gawk +reads the program text as if all the +.IR program-file s +and command line source texts +had been concatenated together. +.PP +In addition, lines beginning with +.B @include +may be used to include other source files into your program. +This is equivalent +to using the +.B \-\^\-include +option. +.PP +Lines beginning with +.B @load +may be used to load extension functions into your program. This is equivalent +to using the +.B \-\^\-load +option. +.PP +The environment variable +.B AWKPATH +specifies a search path to use when finding source files named with +the +.B \-f +and +.B \-\^\-include +options. If this variable does not exist, the default path is +\fB".:/usr/local/share/awk"\fR. +(The actual directory may vary, depending upon how +.I gawk +was built and installed.) +If a file name given to the +.B \-f +option contains a \*(lq/\*(rq character, no path search is performed. +.PP +The environment variable +.B AWKLIBPATH +specifies a search path to use when finding source files named with +the +.B \-\^\-load +option. If this variable does not exist, the default path is +\fB"/usr/local/lib/gawk"\fR. +(The actual directory may vary, depending upon how +.I gawk +was built and installed.) +.PP +.I Gawk +executes \*(AK programs in the following order. +First, +all variable assignments specified via the +.B \-v +option are performed. +Next, +.I gawk +compiles the program into an internal form. +Then, +.I gawk +executes the code in the +.B BEGIN +rule(s) (if any), +and then proceeds to read +each file named in the +.B ARGV +array (up to +.BR ARGV[ARGC\-1] ). +If there are no files named on the command line, +.I gawk +reads the standard input. +.PP +If a filename on the command line has the form +.IB var = val +it is treated as a variable assignment. The variable +.I var +will be assigned the value +.IR val . +(This happens after any +.B BEGIN +rule(s) have been run.) +.PP +If the value of a particular element of +.B ARGV +is empty (\fB""\fR), +.I gawk +skips over it. +.PP +For each input file, +if a +.B BEGINFILE +rule exists, +.I gawk +executes the associated code +before processing the contents of the file. Similarly, +.I gawk +executes +the code associated with +.B ENDFILE +rules +after processing the file. +.PP +For each record in the input, +.I gawk +tests to see if it matches any +.I pattern +in the \*(AK program. +For each pattern that the record matches, +.I gawk +executes the associated +.IR action . +The patterns are tested in the order they occur in the program. +.PP +Finally, after all the input is exhausted, +.I gawk +executes the code in the +.B END +rule(s) (if any). +.SS Command Line Directories +According to POSIX, files named on the +.I awk +command line must be +text files. The behavior is ``undefined'' if they are not. Most versions +of +.I awk +treat a directory on the command line as a fatal error. +.PP +For +.IR gawk , +a directory on the command line +produces a warning, but is otherwise skipped. If either of the +.B \-\^\-posix +or +.B \-\^\-traditional +options is given, then +.I gawk +reverts to +treating directories on the command line as a fatal error. +.SH VARIABLES, RECORDS AND FIELDS +\*(AK variables are dynamic; they come into existence when they are +first used. Their values are either floating-point numbers or strings, +or both, +depending upon how they are used. +Additionally, +.I gawk +allows variables to have regular-expression type. +\*(AK also has one dimensional +arrays; arrays with multiple dimensions may be simulated. +However, +.I gawk +provides true arrays of arrays. +Several pre-defined variables are set as a program +runs; these are described as needed and summarized below. +.SS Records +Normally, records are separated by newline characters. You can control how +records are separated by assigning values to the built-in variable +.BR RS . +See +.I https://www.gnu.org/software/gawk/manual/html_node/Records.html +for the details. +.SS Fields +As each input record is read, +.I gawk +splits the record into +.IR fields , +using the value of the +.B FS +variable as the field separator. +Additionally, +.B FIELDWIDTHS +and +.B FPAT +may be used to control input field splitting. +See the details, starting at +.IR https://www.gnu.org/software/gawk/manual/html_node/Fields.html . +.PP +Each field in the input record may be referenced by its position: +.BR $1 , +.BR $2 , +and so on. +.B $0 +is the whole record, +including leading and trailing whitespace. +.PP +The variable +.B NF +is set to the total number of fields in the input record. +.PP +References to non-existent fields (i.e., fields after +.BR $NF ) +produce the null string. However, assigning to a non-existent field +(e.g., +.BR "$(NF+2) = 5" ) +increases the value of +.BR NF , +creates any intervening fields with the null string as their values, and +causes the value of +.B $0 +to be recomputed, with the fields being separated by the value of +.BR OFS . +References to negative numbered fields cause a fatal error. +Decrementing +.B NF +causes the values of fields past the new value to be lost, and the value of +.B $0 +to be recomputed, with the fields being separated by the value of +.BR OFS . +.PP +Assigning a value to an existing field +causes the whole record to be rebuilt when +.B $0 +is referenced. +Similarly, assigning a value to +.B $0 +causes the record to be resplit, creating new +values for the fields. +.SS Comma Separated Values +When invoked with ether the +.B \-k +or the +.B \-\^\-csv +option, +.I gawk +does not use regular record determination and field splitting +as described above. +Instead, records are terminated by unquoted newlines, and +fields are separated by commas. +Double-quotes may be used to enclose fields containing +commas, newlines, or doubled double-quotes. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html +for more details. +.SS Built-in Variables +.IR Gawk\^ "'s" +built-in variables are listed below. +This list is purposely terse. For details, see +.IR https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables . +.TP "\w'\fBFIELDWIDTHS\fR'u+1n" +.B ARGC +The number of command line arguments. +.TP +.B ARGIND +The index in +.B ARGV +of the current file being processed. +.TP +.B ARGV +Array of command line arguments. The array is indexed from +0 to +.B ARGC +\- 1. +.TP +.B BINMODE +On non-POSIX systems, specifies use of \*(lqbinary\*(rq mode for all file I/O. +See +.I https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html +for the details. +.TP +.B CONVFMT +The conversion format for numbers, \fB"%.6g"\fR, by default. +.TP +.B ENVIRON +An array containing the values of the current environment. +The array is indexed by the environment variables, each element being +the value of that variable. +.TP +.B ERRNO +If a system error occurs either doing a redirection for +.BR getline , +during a read for +.BR getline , +or during a +.BR close() , +then +.B ERRNO +is set to +a string describing the error. +The value is subject to translation in non-English locales. +.TP +.B FIELDWIDTHS +A whitespace-separated list of field widths. When set, +.I gawk +parses the input into fields of fixed width, instead of using the +value of the +.B FS +variable as the field separator. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. +.TP +.B FILENAME +The name of the current input file. +If no files are specified on the command line, the value of +.B FILENAME +is \*(lq\-\*(rq. +However, +.B FILENAME +is undefined inside the +.B BEGIN +rule +(unless set by +.BR getline ). +.TP +.B FNR +The input record number in the current input file. +.TP +.B FPAT +A regular expression describing the contents of the +fields in a record. +When set, +.I gawk +parses the input into fields, where the fields match the +regular expression, instead of using the +value of +.B FS +as the field separator. +.TP +.B FS +The input field separator, a space by default. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html +for the details. +.TP +.B FUNCTAB +An array whose indices and corresponding values +are the names of all the user-defined +or extension functions in the program. +.BR NOTE : +You may not use the +.B delete +statement with the +.B FUNCTAB +array. +.TP +.B IGNORECASE +Controls the case-sensitivity of all regular expression +and string operations. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html +for details. +.TP +.B LINT +Provides dynamic control of the +.B \-\^\-lint +option from within an \*(AK program. +.TP +.B NF +The number of fields in the current input record. +.TP +.B NR +The total number of input records seen so far. +.TP +.B OFMT +The output format for numbers, \fB"%.6g"\fR, by default. +.TP +.B OFS +The output field separator, a space by default. +.TP +.B ORS +The output record separator, by default a newline. +.TP +.B PREC +The working precision of arbitrary precision floating-point +numbers, 53 by default. +.TP +.B PROCINFO +The elements of this array provide access to information about the +running \*(AK program. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset +for the details. +.TP +.B ROUNDMODE +The rounding mode to use for arbitrary precision arithmetic on +numbers, by default \fB"N"\fR (IEEE-754 roundTiesToEven mode). +See +.I https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode +for the details. +.TP +.B RS +The input record separator, by default a newline. +.TP +.B RT +The record terminator. +.I Gawk +sets +.B RT +to the input text that matched the character or regular expression +specified by +.BR RS . +.TP +.B RSTART +The index of the first character matched by +.BR match() ; +0 if no match. +.TP +.B RLENGTH +The length of the string matched by +.BR match() ; +\-1 if no match. +.TP +.B SUBSEP +The string used to separate multiple subscripts in array +elements, by default \fB"\e034"\fR. +.TP +.B SYMTAB +An array whose indices are the names of all currently defined +global variables and arrays in the program. +You may not use the +.B delete +statement with the +.B SYMTAB +array, nor assign to elements with an index that is +not a variable name. +.TP +.B TEXTDOMAIN +The text domain of the \*(AK program; used to find the localized +translations for the program's strings. +.SS Arrays +Arrays are subscripted with an expression between square brackets +.RB ( [ " and " ] ). +If the expression is an expression list +.RI ( expr ", " expr " .\|.\|.)" +then the array subscript is a string consisting of the +concatenation of the (string) value of each expression, +separated by the value of the +.B SUBSEP +variable. +This facility is used to simulate multiply dimensioned +arrays. For example: +.PP +.RS +.ft B +i = "A";\^ j = "B";\^ k = "C" +.br +x[i, j, k] = "hello, world\en" +.ft R +.RE +.PP +assigns the string \fB"hello,\ world\en"\fR to the element of the array +.B x +which is indexed by the string \fB"A\e034B\e034C"\fR. All arrays in \*(AK +are associative, i.e., indexed by string values. +.PP +The special operator +.B in +may be used to test if an array has an index consisting of a particular +value: +.PP +.RS +.ft B +.nf +if (val in array) + print array[val] +.fi +.ft +.RE +.PP +If the array has multiple subscripts, use +.BR "(i, j) in array" . +.PP +The +.B in +construct may also be used in a +.B for +loop to iterate over all the elements of an array. +However, the +.B "(i, j) in array" +construct only works in tests, not in +.B for +loops. +.PP +An element may be deleted from an array using the +.B delete +statement. +The +.B delete +statement may also be used to delete the entire contents of an array, +just by specifying the array name without a subscript. +.PP +.I gawk +supports true multidimensional arrays. It does not require that +such arrays be ``rectangular'' as in C or C++. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Arrays +for details. +.SS Namespaces +.I Gawk +provides a simple +.I namespace +facility to help work around the fact that all variables in +AWK are global. +.PP +A +.I "qualified name" +consists of a two simple identifiers joined by a double colon +.RB ( :: ). +The left-hand identifier represents the namespace and the right-hand +identifier is the variable within it. +All simple (non-qualified) names are considered to be in the +``current'' namespace; the default namespace is +.BR awk . +However, simple identifiers consisting solely of uppercase +letters are forced into the +.B awk +namespace, even if the current namespace is different. +.PP +You change the current namespace with an +\fB@namespace "\fIname\^\fB"\fR +directive. +.PP +The standard predefined builtin function names may not be used as +namespace names. The names of additional functions provided by +.I gawk +may be used as namespace names or as simple identifiers in other +namespaces. +For more details, see +.IR https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces . +.SS Variable Typing And Conversion +Variables and fields +may be (floating point) numbers, or strings, or both. +They may also be regular expressions. How the +value of a variable is interpreted depends upon its context. If used in +a numeric expression, it will be treated as a number; if used as a string +it will be treated as a string. +.PP +To force a variable to be treated as a number, add zero to it; to force it +to be treated as a string, concatenate it with the null string. +.PP +Uninitialized variables have the numeric value zero and the string value "" +(the null, or empty, string). +.PP +When a string must be converted to a number, the conversion is accomplished +using +.IR strtod (3). +A number is converted to a string by using the value of +.B CONVFMT +as a format string for +.IR sprintf (3), +with the numeric value of the variable as the argument. +However, even though all numbers in \*(AK are floating-point, +integral values are +.I always +converted as integers. +.PP +.I Gawk +performs comparisons as follows: +If two variables are numeric, they are compared numerically. +If one value is numeric and the other has a string value that is a +\*(lqnumeric string,\*(rq then comparisons are also done numerically. +Otherwise, the numeric value is converted to a string and a string +comparison is performed. +Two strings are compared, of course, as strings. +.PP +Note that string constants, such as \fB"57"\fP, are +.I not +numeric strings, they are string constants. +The idea of \*(lqnumeric string\*(rq +only applies to fields, +.B getline +input, +.BR FILENAME , +.B ARGV +elements, +.B ENVIRON +elements and the elements of an array created by +.B split() +or +.B patsplit() +that are numeric strings. +The basic idea is that +.IR "user input" , +and only user input, that looks numeric, +should be treated that way. +.SS Octal and Hexadecimal Constants +You may use C-style octal and hexadecimal constants in your AWK +program source code. +For example, the octal value +.B 011 +is equal to decimal +.BR 9 , +and the hexadecimal value +.B 0x11 +is equal to decimal 17. +.SS String Constants +String constants in \*(AK are sequences of characters enclosed +between double quotes (like \fB"value"\fR). Within strings, certain +.I "escape sequences" +are recognized, as in C. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences +for the details. +.SS Regexp Constants +A regular expression constant is a sequence of characters enclosed +between forward slashes (like +.BR /value/ ). +.PP +The escape sequences described in the manual may also be used inside +constant regular expressions +(e.g., +.B "/[\ \et\ef\en\er\ev]/" +matches whitespace characters). +.PP +.I Gawk +provides +.I "strongly typed" +regular expression constants. These are written with a leading +.B @ +symbol (like so: +.BR @/value/ ). +Such constants may be assigned to scalars (variables, array elements) +and passed to user-defined functions. Variables that have been so +assigned have regular expression type. +.SH PATTERNS AND ACTIONS +\*(AK is a line-oriented language. The pattern comes first, and then the +action. Action statements are enclosed in +.B { +and +.BR } . +Either the pattern may be missing, or the action may be missing, but, +of course, not both. If the pattern is missing, the action +executes for every single record of input. +A missing action is equivalent to +.RS +.PP +.B "{ print }" +.RE +.PP +which prints the entire record. +.PP +Comments begin with the +.B # +character, and continue until the +end of the line. +Empty lines may be used to separate statements. +Normally, a statement ends with a newline, however, this is not the +case for lines ending in +a comma, +.BR { , +.BR ? , +.BR : , +.BR && , +or +.BR || . +Lines ending in +.B do +or +.B else +also have their statements automatically continued on the following line. +In other cases, a line can be continued by ending it with a \*(lq\e\*(rq, +in which case the newline is ignored. However, a \*(lq\e\*(rq after a +.B # +is not special. +.PP +Multiple statements may +be put on one line by separating them with a \*(lq;\*(rq. +This applies to both the statements within the action part of a +pattern-action pair (the usual case), +and to the pattern-action statements themselves. +.SS Patterns +\*(AK patterns may be one of the following: +.PP +.RS +.nf +.B BEGIN +.B END +.B BEGINFILE +.B ENDFILE +.BI / "regular expression" / +.I "relational expression" +.IB pattern " && " pattern +.IB pattern " || " pattern +.IB pattern " ? " pattern " : " pattern +.BI ( pattern ) +.BI ! " pattern" +.IB pattern1 ", " pattern2 +.fi +.RE +.PP +.B BEGIN +and +.B END +are two special kinds of patterns which are not tested against +the input. +The action parts of all +.B BEGIN +patterns are merged as if all the statements had +been written in a single +.B BEGIN +rule. They are executed before any +of the input is read. Similarly, all the +.B END +rules are merged, +and executed when all the input is exhausted (or when an +.B exit +statement is executed). +.B BEGIN +and +.B END +patterns cannot be combined with other patterns in pattern expressions. +.B BEGIN +and +.B END +patterns cannot have missing action parts. +.PP +.B BEGINFILE +and +.B ENDFILE +are additional special patterns whose actions are executed +before reading the first record of each command-line input file +and after reading the last record of each file. +Inside the +.B BEGINFILE +rule, the value of +.B ERRNO +is the empty string if the file was opened successfully. +Otherwise, there is some problem with the file and the code should +use +.B nextfile +to skip it. If that is not done, +.I gawk +produces its usual fatal error for files that cannot be opened. +.PP +For +.BI / "regular expression" / +patterns, the associated statement is executed for each input record that matches +the regular expression. +Regular expressions are essentially the same as those in +.IR egrep (1). +See +.I https://www.gnu.org/software/gawk/manual/html_node/Regexp.html +for the details on regular expressions. +.PP +A +.I "relational expression" +may use any of the operators defined below in the section on actions. +These generally test whether certain fields match certain regular expressions. +.PP +The +.BR && , +.BR || , +and +.B ! +operators are logical AND, logical OR, and logical NOT, respectively, as in C. +They do short-circuit evaluation, also as in C, and are used for combining +more primitive pattern expressions. As in most languages, parentheses +may be used to change the order of evaluation. +.PP +The +.B ?\^: +operator is like the same operator in C. If the first pattern is true +then the pattern used for testing is the second pattern, otherwise it is +the third. Only one of the second and third patterns is evaluated. +.PP +The +.IB pattern1 ", " pattern2 +form of an expression is called a +.IR "range pattern" . +It matches all input records starting with a record that matches +.IR pattern1 , +and continuing until a record that matches +.IR pattern2 , +inclusive. It does not combine with any other sort of pattern expression. +.SS Actions +Action statements are enclosed in braces, +.B { +and +.BR } . +Action statements consist of the usual assignment, conditional, and looping +statements found in most languages. The operators, control statements, +and input/output statements +available are patterned after those in C. +.SS Operators +The operators in \*(AK, in order of decreasing precedence, are: +.TP "\w'\fB*= /= %= ^=\fR'u+1n" +.BR ( \&.\|.\|. ) +Grouping +.TP +.B $ +Field reference. +.TP +.B "++ \-\^\-" +Increment and decrement, both prefix and postfix. +.TP +.B ^ +Exponentiation. +.TP +.B "+ \- !" +Unary plus, unary minus, and logical negation. +.TP +.B "* / %" +Multiplication, division, and modulus. +.TP +.B "+ \-" +Addition and subtraction. +.TP +.I space +String concatenation. +.TP +.B "| |&" +Piped I/O for +.BR getline , +.BR print , +and +.BR printf . +.TP +.B "< > <= >= == !=" +The regular relational operators. +.TP +.B "~ !~" +Regular expression match, negated match. +.TP +.B in +Array membership. +.TP +.B && +Logical AND. +.TP +.B || +Logical OR. +.TP +.B ?: +The C conditional expression. This has the form +.IB expr1 " ? " expr2 " : " expr3\/\fR. +If +.I expr1 +is true, the value of the expression is +.IR expr2 , +otherwise it is +.IR expr3 . +Only one of +.I expr2 +and +.I expr3 +is evaluated. +.TP +.B "= += \-= *= /= %= ^=" +Assignment. Both absolute assignment +.BI ( var " = " value ) +and operator-assignment (the other forms) are supported. +.SS Control Statements +The control statements are +as follows: +.PP +.RS +.nf +\fBif (\fIcondition\fB) \fIstatement\fR [ \fBelse\fI statement \fR] +\fBwhile (\fIcondition\fB) \fIstatement\fR +\fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR +\fBfor (\fIexpr1\fB; \fIexpr2\fB; \fIexpr3\fB) \fIstatement\fR +\fBfor (\fIvar \fBin\fI array\fB) \fIstatement\fR +\fBbreak\fR +\fBcontinue\fR +\fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR +\fBdelete \fIarray\^\fR +\fBexit\fR [ \fIexpression\fR ] +\fB{ \fIstatements \fB}\fR +\fBswitch (\fIexpression\fB) { +\fBcase \fIvalue\fB|\fIregex\fB : \fIstatement +\&.\^.\^. +\fR[ \fBdefault: \fIstatement \fR] +\fB}\fR +.fi +.RE +.SS "I/O Statements" +The input/output statements are as follows: +.TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n" +\fBclose(\fIfile \fR[\fB, \fIhow\fR]\fB)\fR +Close an open file, pipe or coprocess. +The optional +.I how +should only be used when closing one end of a +two-way pipe to a coprocess. +It must be a string value, either +\fB"to"\fR or \fB"from"\fR. +.TP +.B getline +Set +.B $0 +from the next input record; set +.BR NF , +.BR NR , +.BR FNR , +.BR RT . +.TP +.BI "getline <" file +Set +.B $0 +from the next record of +.IR file ; +set +.BR NF , +.BR RT . +.TP +.BI getline " var" +Set +.I var +from the next input record; set +.BR NR , +.BR FNR , +.BR RT . +.TP +.BI getline " var" " <" file +Set +.I var +from the next record of +.IR file ; +set +.BR RT . +.TP +\fIcommand\fB | getline \fR[\fIvar\fR] +Run +.IR command , +piping the output either into +.B $0 +or +.IR var , +as above, and +.BR RT . +.TP +\fIcommand\fB |& getline \fR[\fIvar\fR] +Run +.I command +as a coprocess +piping the output either into +.B $0 +or +.IR var , +as above, and +.BR RT . +.RI "(The " command +can also be a socket. See the subsection +.BR "Special File Names" , +below.) +.TP +\&\fBfflush(\fR[\fIfile\^\fR]\fB)\fR +Flush any buffers associated with the open output file or pipe +.IR file . +If +.I file +is missing or if it +is the null string, +then flush all open output files and pipes. +.TP +.B next +Stop processing the current input record. +Read the next input record +and start processing over with the first pattern in the +\*(AK program. +Upon reaching the end of the input data, +execute any +.B END +rule(s). +.TP +.B nextfile +Stop processing the current input file. The next input record read +comes from the next input file. +Update +.B FILENAME +and +.BR ARGIND , +reset +.B FNR +to 1, and start processing over with the first pattern in the +\*(AK program. +Upon reaching the end of the input data, +execute any +.B ENDFILE +and +.B END +rule(s). +.TP +.B print +Print the current record. +The output record is terminated with the value of +.BR ORS . +.TP +.BI print " expr-list" +Print expressions. +Each expression is separated by the value of +.BR OFS . +The output record is terminated with the value of +.BR ORS . +.TP +.BI print " expr-list" " >" file +Print expressions on +.IR file . +Each expression is separated by the value of +.BR OFS . +The output record is terminated with the value of +.BR ORS . +.TP +.BI printf " fmt, expr-list" +Format and print. +.TP +.BI printf " fmt, expr-list" " >" file +Format and print on +.IR file . +.TP +.BI system( cmd-line ) +Execute the command +.IR cmd-line , +and return the exit status. +(This may not be available on non-\*(PX systems.) +See +.I https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions +for the full details on the exit status. +.PP +Additional output redirections are allowed for +.B print +and +.BR printf . +.TP +.BI "print .\|.\|.\& >>" " file" +Append output to the +.IR file . +.TP +.BI "print .\|.\|.\& |" " command" +Write on a pipe. +.TP +.BI "print .\|.\|.\& |&" " command" +Send data to a coprocess or socket. +(See also the subsection +.BR "Special File Names" , +below.) +.PP +The +.B getline +command returns 1 on success, zero on end of file, and \-1 on an error. +If the +.IR errno (3) +value indicates that the I/O operation may be retried, +and \fBPROCINFO["\fIinput\^\fP", "RETRY"]\fR +is set, then \-2 is returned instead of \-1, and further calls to +.B getline +may be attempted. +Upon an error, +.B ERRNO +is set to a string describing the problem. +.PP +.BR NOTE : +Failure in opening a two-way socket results in a non-fatal error being +returned to the calling function. If using a pipe, coprocess, or socket to +.BR getline , +or from +.B print +or +.B printf +within a loop, you +.I must +use +.B close() +to create new instances of the command or socket. +\*(AK does not automatically close pipes, sockets, or coprocesses when +they return EOF. +.PP +The \*(AK versions of the +.B printf +statement and +.B sprintf() +function +are similar to those of C. For details, see +.IR https://www.gnu.org/software/gawk/manual/html_node/Printf.html . +.SS Special File Names +When doing I/O redirection from either +.B print +or +.B printf +into a file, +or via +.B getline +from a file, +.I gawk +recognizes certain special filenames internally. These filenames +allow access to open file descriptors inherited from +.IR gawk\^ "'s" +parent process (usually the shell). +These file names may also be used on the command line to name data files. +The filenames are: +.TP "\w'\fB/dev/stdout\fR'u+1n" +.B \- +The standard input. +.TP +.B /dev/stdin +The standard input. +.TP +.B /dev/stdout +The standard output. +.TP +.B /dev/stderr +The standard error output. +.TP +.BI /dev/fd/\^ n +The file associated with the open file descriptor +.IR n . +.PP +The following special filenames may be used with the +.B |& +coprocess operator for creating TCP/IP network connections: +.TP +.PD 0 +.BI /inet/tcp/ lport / rhost / rport +.TP +.PD 0 +.BI /inet4/tcp/ lport / rhost / rport +.TP +.PD +.BI /inet6/tcp/ lport / rhost / rport +Files for a TCP/IP connection on local port +.I lport +to +remote host +.I rhost +on remote port +.IR rport . +Use a port of +.B 0 +to have the system pick a port. +Use +.B /inet4 +to force an IPv4 connection, +and +.B /inet6 +to force an IPv6 connection. +Plain +.B /inet +uses the system default (most likely IPv4). +Usable only with the +.B |& +two-way I/O operator. +.TP +.PD 0 +.BI /inet/udp/ lport / rhost / rport +.TP +.PD 0 +.BI /inet4/udp/ lport / rhost / rport +.TP +.PD +.BI /inet6/udp/ lport / rhost / rport +Similar, but use UDP/IP instead of TCP/IP. +.SS Numeric Functions +\*(AK has the following built-in arithmetic functions: +.TP "\w'\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR'u+1n" +.BI atan2( y , " x" ) +Return the arctangent of +.I y/x +in radians. +.TP +.BI cos( expr ) +Return the cosine of +.IR expr , +which is in radians. +.TP +.BI exp( expr ) +The exponential function. +.TP +.BI int( expr ) +Truncate to integer. +.ig +.TP +.BI intdiv( num ", " denom ", " result ) +Truncate +.I num +and +.I denom +to integers. Return the quotient of +.I num +divided by +.I denom +in \fIresult\fB["quotient"]\fR +and the remainder in +\fIresult\fB["remainder"]\fR. +This is a +.I gawk +extension, primarily of value when working with +arbitrarily large integers. +.. +.TP +.BI log( expr ) +The natural logarithm function. +.TP +.B rand() +Return a random number +.IR N , +between zero and one, +such that 0 \(<= \fIN\fP < 1. +.TP +.BI sin( expr ) +Return the sine of +.IR expr , +which is in radians. +.TP +.BI sqrt( expr ) +Return the square root of +.IR expr . +.TP +\&\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR +Use +.I expr +as the new seed for the random number generator. If no +.I expr +is provided, use the time of day. +Return the previous seed for the random +number generator. +.SS String Functions +.I Gawk +has the following built-in string functions; details are provided in +.IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions . +.TP "\w'\fBsprintf(\fIfmt\^\fB, \fIexpr-list\^\fB)\fR'u+1n" +\fBasort(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR +Return the number of elements in the source +array +.IR s . +Sort +the contents of +.I s +using +.IR gawk\^ "'s" +normal rules for +comparing values, and replace the indices of the +sorted values +.I s +with sequential +integers starting with 1. If the optional +destination array +.I d +is specified, +first duplicate +.I s +into +.IR d , +and then sort +.IR d , +leaving the indices of the +source array +.I s +unchanged. The optional string +.I how +controls the direction and the comparison mode. +Valid values for +.I how +are +described in +.IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions . +.IR s " and " d +are allowed to be the same array; this only makes sense when +supplying the third argument as well. +.TP +\fBasorti(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR +Return the number of elements in the source +array +.IR s . +The behavior is the same as that of +.BR asort() , +except that the array +.I indices +are used for sorting, not the array values. +When done, the array is indexed numerically, and +the values are those of the original indices. +The original values are lost; thus provide +a second array if you wish to preserve the original. +The purpose of the optional string +.I how +is the same as for +.BR asort() . +Here too, +.IR s " and " d +are allowed to be the same array; this only makes sense when +supplying the third argument as well. +.TP +\fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR +Search the target string +.I t +for matches of the regular expression +.IR r . +If +.I h +is a string beginning with +.B g +or +.BR G , +then replace all matches of +.I r +with +.IR s . +Otherwise, +.I h +is a number indicating which match of +.I r +to replace. +If +.I t +is not supplied, use +.B $0 +instead. +Within the replacement text +.IR s , +the sequence +.BI \e n\fR, +where +.I n +is a digit from 1 to 9, may be used to indicate just the text that +matched the +.IR n 'th +parenthesized subexpression. The sequence +.B \e0 +represents the entire matched text, as does the character +.BR & . +Unlike +.B sub() +and +.BR gsub() , +the modified string is returned as the result of the function, +and the original target string is +.I not +changed. +.TP +\fBgsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR +For each substring matching the regular expression +.I r +in the string +.IR t , +substitute the string +.IR s , +and return the number of substitutions. +If +.I t +is not supplied, use +.BR $0 . +An +.B & +in the replacement text is replaced with the text that was actually matched. +Use +.B \e& +to get a literal +.BR & . +(This must be typed as \fB"\e\e&"\fP; see +.I https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details +for a fuller discussion of the rules for ampersands +and backslashes in the replacement text of +.BR sub() , +.BR gsub() , +and +.BR gensub() .) +.TP +.BI index( s , " t" ) +Return the index of the string +.I t +in the string +.IR s , +or zero if +.I t +is not present. +(This implies that character indices start at one.) +.TP +\fBlength(\fR[\fIs\fR]\fB) +Return the length of the string +.IR s , +or the length of +.B $0 +if +.I s +is not supplied. +With an array argument, +.B length() +returns the number of elements in the array. +.TP +\fBmatch(\fIs\fB, \fIr \fR[\fB, \fIa\fR]\fB)\fR +Return the position in +.I s +where the regular expression +.I r +occurs, or zero if +.I r +is not present, and set the values of +.B RSTART +and +.BR RLENGTH . +Note that the argument order is the same as for the +.B ~ +operator: +.IB str " ~" +.IR re . +.ft R +See +.I https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions +for a description of how the array +.I a +is filled if it is provided. +.TP +\fBpatsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR +Split the string +.I s +into the array +.I a +and the separators array +.I seps +on the regular expression +.IR r , +and return the number of fields. +Element values are the portions of +.I s +that matched +.IR r . +The value of +.BI seps[ i ] +is the possibly null separator that appeared after +.BI a[ i ]\fR. +The value of +.B seps[0] +is the possibly null leading separator. +If +.I r +is omitted, +.B FPAT +is used instead. +The arrays +.I a +and +.I seps +are cleared first. +Splitting behaves identically to field splitting with +.BR FPAT . +.TP +\fBsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR +Split the string +.I s +into the array +.I a +and the separators array +.I seps +on the regular expression +.IR r , +and return the number of fields. If +.I r +is omitted, +.B FS +is used instead. +The arrays +.I a +and +.I seps +are cleared first. +.BI seps[ i ] +is the field separator matched by +.I r +between +.BI a[ i ] +and +.BI a[ i +1]\fR. +Splitting behaves identically to field splitting. +.TP +.BI sprintf( fmt\^ , " expr-list\^" ) +Print +.I expr-list +according to +.IR fmt , +and return the resulting string. +.TP +.BI strtonum( str ) +Examine +.IR str , +and return its numeric value. +If +.I str +begins +with a leading +.BR 0 , +treat it +as an octal number. +If +.I str +begins +with a leading +.B 0x +or +.BR 0X , +treat it +as a hexadecimal number. +Otherwise, assume it is a decimal number. +.TP +\fBsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR +Just like +.BR gsub() , +but replace only the first matching substring. +Return either zero or one. +.TP +\fBsubstr(\fIs\fB, \fIi \fR[\fB, \fIn\fR]\fB)\fR +Return the at most +.IR n -character +substring of +.I s +starting at +.IR i . +If +.I n +is omitted, use the rest of +.IR s . +.TP +.BI tolower( str ) +Return a copy of the string +.IR str , +with all the uppercase characters in +.I str +translated to their corresponding lowercase counterparts. +Non-alphabetic characters are left unchanged. +.TP +.BI toupper( str ) +Return a copy of the string +.IR str , +with all the lowercase characters in +.I str +translated to their corresponding uppercase counterparts. +Non-alphabetic characters are left unchanged. +.PP +.I Gawk +is multibyte aware. This means that +.BR index() , +.BR length() , +.B substr() +and +.B match() +all work in terms of characters, not bytes. +.SS Time Functions +.I Gawk +provides the following functions for obtaining time stamps and +formatting them. Details are provided in +.IR https://www.gnu.org/software/gawk/manual/html_node/Time-Functions . +.TP "\w'\fBsystime()\fR'u+1n" +\fBmktime(\fIdatespec\fR [\fB, \fIutc-flag\fR]\fB)\fR +Turn +.I datespec +into a time stamp of the same form as returned by +.BR systime() , +and return the result. +If +.I utc-flag +is present and is non-zero or non-null, the time is assumed to be in +the UTC time zone; otherwise, the +time is assumed to be in the local time zone. +If +.I datespec +does not contain enough elements or if the resulting time +is out of range, +.B mktime() +returns \-1. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions +for the details of +.IR datespec . +.TP +\fBstrftime(\fR[\fIformat \fR[\fB, \fItimestamp\fR[\fB, \fIutc-flag\fR]]]\fB)\fR +Format +.I timestamp +according to the specification in +.IR format . +If +.I utc-flag +is present and is non-zero or non-null, the result +is in UTC, otherwise the result is in local time. +The +.I timestamp +should be of the same form as returned by +.BR systime() . +If +.I timestamp +is missing, the current time of day is used. +If +.I format +is missing, a default format equivalent to the output of +.IR date (1) +is used. +The default format is available in +.BR PROCINFO["strftime"] . +See the specification for the +.B strftime() +function in ISO C for the format conversions that are +guaranteed to be available. +.TP +.B systime() +Return the current time of day as the number of seconds since the Epoch +(1970-01-01 00:00:00 UTC on \*(PX systems). +.SS Bit Manipulations Functions +.I Gawk +supplies the following bit manipulation functions. +They work by converting double-precision floating point +values to +.B uintmax_t +integers, doing the operation, and then converting the +result back to floating point. +Passing negative operands to any of these functions causes +a fatal error. +.PP +The functions are: +.TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n" +\fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise AND of the values provided in the argument list. +There must be at least two. +.TP +\fBcompl(\fIval\fB)\fR +Return the bitwise complement of +.IR val . +.TP +\fBlshift(\fIval\fB, \fIcount\fB)\fR +Return the value of +.IR val , +shifted left by +.I count +bits. +.TP +\fBor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise OR of the values provided in the argument list. +There must be at least two. +.TP +\fBrshift(\fIval\fB, \fIcount\fB)\fR +Return the value of +.IR val , +shifted right by +.I count +bits. +.TP +\fBxor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise XOR of the values provided in the argument list. +There must be at least two. +.SS Type Functions +The following functions provide type related information about +their arguments. +.TP \w'\fBisarray(\fIx\fB)\fR'u+1n +\fBisarray(\fIx\fB)\fR +Return true if +.I x +is an array, false otherwise. +.TP +\fBtypeof(\fIx\fB)\fR +Return a string indicating the type of +.IR x . +The string will be one of +\fB"array"\fP, +\fB"number"\fP, +\fB"regexp"\fP, +\fB"string"\fP, +\fB"strnum"\fP, +\fB"unassigned"\fP, +or +\fB"undefined"\fP. +.SS Internationalization Functions +The following functions may be used from within your AWK program for +translating strings at run-time. +For full details, see +.IR https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions . +.TP +\fBbindtextdomain(\fIdirectory \fR[\fB, \fIdomain\fR]\fB)\fR +Specify the directory where +.I gawk +looks for the +.B \&.gmo +files, in case they +will not or cannot be placed in the ``standard'' locations. +It returns the directory where +.I domain +is ``bound.'' +.sp .5 +The default +.I domain +is the value of +.BR TEXTDOMAIN . +If +.I directory +is the null string (\fB""\fR), then +.B bindtextdomain() +returns the current binding for the +given +.IR domain . +.TP +\fBdcgettext(\fIstring \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR +Return the translation of +.I string +in text domain +.I domain +for locale category +.IR category . +The default value for +.I domain +is the current value of +.BR TEXTDOMAIN . +The default value for +.I category +is \fB"LC_MESSAGES"\fR. +.TP +\fBdcngettext(\fIstring1\fB, \fIstring2\fB, \fInumber \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR +Return the plural form used for +.I number +of the translation of +.I string1 +and +.I string2 +in +text domain +.I domain +for locale category +.IR category . +The default value for +.I domain +is the current value of +.BR TEXTDOMAIN . +The default value for +.I category +is \fB"LC_MESSAGES"\fR. +.SS Boolean Valued Functions +You can create special Boolean-typed values; see the manual for how +they work and why they exist. +.TP +.BI mkbool( expression\^ ) +Based on the boolean value of +.I expression +return either a true value or a false value. +True values have numeric value one. +False values have numeric value zero. +.SH USER-DEFINED FUNCTIONS +Functions in \*(AK are defined as follows: +.PP +.RS +\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR +.RE +.PP +Functions execute when they are called from within expressions +in either patterns or actions. Actual parameters supplied in the function +call are used to instantiate the formal parameters declared in the function. +Arrays are passed by reference, other variables are passed by value. +.PP +Local variables are declared as extra parameters +in the parameter list. The convention is to separate local variables from +real parameters by extra spaces in the parameter list. For example: +.PP +.RS +.ft B +.nf +function f(p, q, a, b) # a and b are local +{ + \&.\|.\|. +} + +/abc/ { .\|.\|.\& ; f(1, 2) ; .\|.\|.\& } +.fi +.ft R +.RE +.PP +The left parenthesis in a function call is required +to immediately follow the function name, +without any intervening whitespace. +This restriction does not apply to the built-in functions listed above. +.PP +Functions may call each other and may be recursive. +Function parameters used as local variables are initialized +to the null string and the number zero upon function invocation. +.PP +Use +.BI return " expr" +to return a value from a function. The return value is undefined if no +value is provided, or if the function returns by \*(lqfalling off\*(rq the +end. +.PP +Functions may be called indirectly. To do this, assign +the name of the function to be called, as a string, to a variable. +Then use the variable as if it were the name of a function, prefixed with an +.B @ +sign, like so: +.RS +.ft B +.nf +function myfunc() +{ + print "myfunc called" + \&.\|.\|. +} + +{ .\|.\|. + the_func = "myfunc" + @the_func() # call through the_func to myfunc + .\|.\|. +} +.fi +.ft R +.RE +.PP +If +.B \-\^\-lint +has been provided, +.I gawk +warns about calls to undefined functions at parse time, +instead of at run time. +Calling an undefined function at run time is a fatal error. +.SH DYNAMICALLY LOADING NEW FUNCTIONS +You can dynamically add new functions written in C or C++ to the running +.I gawk +interpreter with the +.B @load +statement. +The full details are beyond the scope of this manual page; +see +.IR https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions . +.SH SIGNALS +The +.I gawk +profiler accepts two signals. +.B SIGUSR1 +causes it to dump a profile and function call stack to the +profile file, which is either +.BR awkprof.out , +or whatever file was named with the +.B \-\^\-profile +option. It then continues to run. +.B SIGHUP +causes +.I gawk +to dump the profile and function call stack and then exit. +.SH INTERNATIONALIZATION +String constants are sequences of characters enclosed in double +quotes. In non-English speaking environments, it is possible to mark +strings in the \*(AK program as requiring translation to the local +natural language. Such strings are marked in the \*(AK program with +a leading underscore (\*(lq_\*(rq). For example, +.sp +.RS +.ft B +gawk 'BEGIN { print "hello, world" }' +.RE +.sp +.ft R +always prints +.BR "hello, world" . +But, +.sp +.RS +.ft B +gawk 'BEGIN { print _"hello, world" }' +.RE +.sp +.ft R +might print +.B "bonjour, monde" +in France. +See +.I https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization +for the steps involved in producing and running a localizable +\*(AK program. +.SH GNU EXTENSIONS +.I Gawk +has a too-large number of extensions to \*(PX +.IR awk . +They are described in +.IR https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html . +All the extensions +can be disabled by +invoking +.I gawk +with the +.B \-\^\-traditional +or +.B \-\^\-posix +options. +.SH ENVIRONMENT VARIABLES +The +.B AWKPATH +environment variable can be used to provide a list of directories that +.I gawk +searches when looking for files named via the +.BR \-f , +.BR \-\^\-file , +.B \-i +and +.B \-\^\-include +options, and the +.B @include +directive. If the initial search fails, the path is searched again after +appending +.B \&.awk +to the filename. +.PP +The +.B AWKLIBPATH +environment variable can be used to provide a list of directories that +.I gawk +searches when looking for files named via the +.B \-l +and +.B \-\^\-load +options. +.PP +The +.B GAWK_PERSIST_FILE +environment variable, if present, specifies a file to use as +the backing store for persistent memory. +.IR "This is an experimental feature" . +See \*(EP for the details. +.PP +The +.B GAWK_READ_TIMEOUT +environment variable can be used to specify a timeout +in milliseconds for reading input from a terminal, pipe +or two-way communication including sockets. +.PP +For connection to a remote host via socket, +.B GAWK_SOCK_RETRIES +controls the number of retries, and +.B GAWK_MSEC_SLEEP +the interval between retries. +The interval is in milliseconds. On systems that do not support +.IR usleep (3), +the value is rounded up to an integral number of seconds. +.PP +If +.B POSIXLY_CORRECT +exists in the environment, then +.I gawk +behaves exactly as if +.B \-\^\-posix +had been specified on the command line. +If +.B \-\^\-lint +has been specified, +.I gawk +issues a warning message to this effect. +.ig +.PP +Set +.B GAWK_NO_MPFR_WARN +in the environment to silence the warning about MPFR mode +being deprecated. +.. +.SH EXIT STATUS +If the +.B exit +statement is used with a value, +then +.I gawk +exits with +the numeric value given to it. +.PP +Otherwise, if there were no problems during execution, +.I gawk +exits with the value of the C constant +.BR EXIT_SUCCESS . +This is usually zero. +.PP +If an error occurs, +.I gawk +exits with the value of +the C constant +.BR EXIT_FAILURE . +This is usually one. +.PP +If +.I gawk +exits because of a fatal error, the exit +status is 2. On non-POSIX systems, this value may be mapped to +.BR EXIT_FAILURE . +.SH VERSION INFORMATION +This man page documents +.IR gawk , +version 5.3. +.SH AUTHORS +The original version of \*(UX +.I awk +was designed and implemented by Alfred Aho, +Peter Weinberger, and Brian Kernighan of Bell Laboratories. +Ozan Yigit is the the current maintainer. +Brian Kernighan occasionally dabbles in its development. +.PP +Paul Rubin and Jay Fenlason, +of the Free Software Foundation, wrote +.IR gawk , +to be compatible with the original version of +.I awk +distributed in Seventh Edition \*(UX. +John Woods contributed a number of bug fixes. +David Trueman, with contributions +from Arnold Robbins, made +.I gawk +compatible with the new version of \*(UX +.IR awk . +Arnold Robbins is the current maintainer. +.PP +See \*(EP for a full list of the contributors to +.I gawk +and its documentation. +.PP +See the +.B README +file in the +.I gawk +distribution for up-to-date information about maintainers +and which ports are currently supported. +.SH BUG REPORTS +If you find a bug in +.IR gawk , +please use the +.IR gawkbug (1) +program to report it. +.PP +Full instructions for reporting a bug are provided in +.IR https://www.gnu.org/software/gawk/manual/html_node/Bugs.html . +.I Please +carefully read and follow the instructions given there. +This will make bug reporting and resolution much easier for everyone involved. +Really. +.SH BUGS +The +.B \-F +option is not necessary given the command line variable assignment feature; +it remains only for backwards compatibility. +.PP +This manual page is too long; +.I gawk +has too many features. +.SH SEE ALSO +.IR egrep (1), +.IR sed (1), +.IR gawkbug (1), +.IR printf (3), +and +.IR strftime (3). +.PP +.IR "The AWK Programming Language" , +Alfred V.\& Aho, Brian W.\& Kernighan, Peter J.\& Weinberger, +Addison-Wesley, 1988. ISBN 0-201-07981-X. +.PP +\*(EP, +Edition 5.2, shipped with the +.I gawk +source. +The current version of this document is available online at +.IR https://www.gnu.org/software/gawk/manual . +.PP +The GNU +.B gettext +documentation, available online at +.IR https://www.gnu.org/software/gettext . +.SH EXAMPLES +.nf +Print and sort the login names of all users: + +.ft B + BEGIN { FS = ":" } + { print $1 | "sort" } + +.ft R +Count lines in a file: + +.ft B + { nlines++ } + END { print nlines } + +.ft R +Precede each line by its number in the file: + +.ft B + { print FNR, $0 } + +.ft R +Concatenate and line number (a variation on a theme): + +.ft B + { print NR, $0 } + +.ft R +Run an external command for particular lines of data: + +.ft B + tail \-f access_log | + awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }' +.ft R +.fi +.ig +.SH ACKNOWLEDGEMENTS +Brian Kernighan +provided valuable assistance during testing and debugging. +We thank him. +.. +.SH COPYING PERMISSIONS +Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009, +2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, +2020, 2021, 2022, 2023 +Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. diff --git a/upstream/fedora-40/man1/gawkbug.1 b/upstream/fedora-40/man1/gawkbug.1 new file mode 100644 index 00000000..35524769 --- /dev/null +++ b/upstream/fedora-40/man1/gawkbug.1 @@ -0,0 +1,73 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Arnold Robbins +.\" bug-gawk@gnu.org +.\" +.TH GAWKBUG 1 "2023 October 18" "GNU Awk 5.3" +.SH NAME +gawkbug \- report a bug in gawk +.SH SYNOPSIS +\fBgawkbug\fP [\fI\-\^\-version\fP] [\fI\-\^\-help\fP] [\fIemail-address\fP] +.SH DESCRIPTION +.B gawkbug +is a shell script to help the user compose and mail bug reports +concerning +.B gawk +in a standard format. +.B gawkbug +invokes the editor specified by the environment variable +.SM +.B EDITOR +on a temporary copy of the bug report format outline. The user must +fill in the appropriate fields and exit the editor. +.B gawkbug +then mails the completed report to \fIbug-gawk@gnu.org\fP, or +\fIemail-address\fP. If the report cannot be mailed, it is saved in the +file \fIdead.gawkbug\fP in the invoking user's home directory. +.PP +The bug report format outline consists of several sections. The first +section provides information about the machine, operating system, the +.B gawk +version, and the compilation environment. The second section +should be filled in with a description of the bug. The third section +should be a description of how to reproduce the bug. The optional +fourth section is for a proposed fix. Fixes are encouraged. +.SH ENVIRONMENT +.B gawkbug +will utilize the following environment variables if they exist: +.TP +.B EDITOR +Specifies the preferred editor. If +.SM +.B EDITOR +is not set, +.B gawkbug +attempts to locate a number of alternative editors, including +.BR vim , +and if it must, +.BR emacs . +If +.B gawkbug +cannot locate any of the alternative editors, it attempts to execute \fBvi\fP. +.TP +.B HOME +Directory in which the failed bug report is saved if the mail fails. +.TP +.B TMPDIR +Directory in which to create temporary files and directories. +.SH "SEE ALSO" +.TP +\fIgawk\fP(1) +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet@po.cwru.edu +.PP +Arnold Robbins +.br +bug-gawk@gnu.org diff --git a/upstream/fedora-40/man1/gcore.1 b/upstream/fedora-40/man1/gcore.1 new file mode 100644 index 00000000..7310f3ac --- /dev/null +++ b/upstream/fedora-40/man1/gcore.1 @@ -0,0 +1,118 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "GCORE 1" +.TH GCORE 1 2024-01-29 gdb-14.1-8.fc40 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +gcore \- Generate a core file of a running program +.SH SYNOPSIS +.IX Header "SYNOPSIS" +gcore [\-a] [\-o \fIprefix\fR] \fIpid1\fR [\fIpid2\fR...\fIpidN\fR] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Generate core dumps of one or more running programs with process IDs +\&\fIpid1\fR, \fIpid2\fR, etc. A core file produced by \fBgcore\fR +is equivalent to one produced by the kernel when the process crashes +(and when \f(CW\*(C`ulimit \-c\*(C'\fR was used to set up an appropriate core dump +limit). However, unlike after a crash, after \fBgcore\fR finishes +its job the program remains running without any change. +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB\-a\fR 4 +.IX Item "-a" +Dump all memory mappings. The actual effect of this option depends on +the Operating System. On GNU/Linux, it will disable +\&\f(CW\*(C`use\-coredump\-filter\*(C'\fR and +enable \f(CW\*(C`dump\-excluded\-mappings\*(C'\fR. +.IP "\fB\-o\fR \fIprefix\fR" 4 +.IX Item "-o prefix" +The optional argument \fIprefix\fR specifies the prefix to be used +when composing the file names of the core dumps. The file name is +composed as \fIprefix.pid\fR, where \fIpid\fR is the +process ID of the running program being analyzed by \fBgcore\fR. +If not specified, \fIprefix\fR defaults to \fIgcore\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for GDB is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing GDB: A Guide to the GNU Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs +Free Documentation", with the Front-Cover Texts being "A GNU Manual," +and with the Back-Cover Texts as in (a) below. +.PP +(a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." diff --git a/upstream/fedora-40/man1/gdiffmk.1 b/upstream/fedora-40/man1/gdiffmk.1 new file mode 100644 index 00000000..34c08985 --- /dev/null +++ b/upstream/fedora-40/man1/gdiffmk.1 @@ -0,0 +1,304 @@ +.TH gdiffmk 1 "24 January 2024" "groff 1.23.0" +.SH Name +gdiffmk \- mark differences between +.IR groff / nroff / troff +files +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2004-2020 Free Software Foundation, Inc. +.\" +.\" This file is part of gdiffmk, which is part of groff, the GNU roff +.\" type-setting system. +.\" +.\" This program is free software: you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_gdiffmk_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY gdiffmk +.RB [ \-a\~\c +.IR add-mark ] +.RB [ \-c\~\c +.IR change-mark ] +.RB [ \-d\~\c +.IR delete-mark ] +.RB [ \-x\~\c +.IR diff-command ] +.RB [ \-D +.RB [ \-B ] +.RB [ \-M +.IR "mark1 mark2" ]] +.RB [ \-\- ] +.I file1 +.I file2 +.RI [ output ] +.YS +. +. +.SY gdiffmk +.B \-\-help +.YS +. +. +.SY gdiffmk +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I gdiffmk +compares two +.MR roff 7 +documents, +.I file1 +and +.IR file2 , +and creates a +.I roff +document consisting of +.I file2 +with added margin character +.RB ( .mc ) +requests indicating output lines that differ from +.I file1. +. +If the +.I file1 +or +.I file2 +argument is +.RB \[lq] \- \[rq], +.I gdiffmk +reads the standard input stream for that input. +. +If the +.I output +operand is present, +.I gdiffmk +writes output to a file of that name. +. +If it is +.RB \[lq] \- \[rq] +or absent, +.I gdiffmk +writes output to the standard output stream. +. +.RB \[lq] \- \[rq] +cannot be both an input and output operand. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message +and +.B \-\-version +shows version information; +both exit afterward. +. +. +.TP +.BI \-a\~ add-mark +Use +.I add-mark +for source lines not in +.I file1 +but present in +.IR file2 . +. +Default: +.RB \[lq] + \[rq]. +. +. +.TP +.B \-B +By default, +the deleted texts marked by the +.B \-D +option end with an added +.I roff +break request, +.BR .br , +to ensure that the deletions are marked properly. +. +This is the only way to guarantee that deletions and small +changes get flagged. +. +This option directs the program not to insert these breaks; +it makes no sense to use it without +.BR \-D . +. +. +.TP +.BI \-c\~ change-mark +Use +.I change-mark +for changed source lines. +. +Default: +.RB \[lq] | \[rq]. +. +. +.TP +.BI \-d\~ delete-mark +Use the +.I delete-mark +for deleted source lines. +. +Default: +.RB \[lq] * \[rq]. +. +.TP +.B \-D +Show the deleted portions from changed and deleted text. +. +. +.TP +.BI \-M\~ "mark1 mark2" +Change the delimiting marks for the +.B \-D +option. +. +It makes no sense to use this option without +.BR \-D . +. +Default delimiting marks: +.RB \[lq] [[ "\[rq] .\|.\|.\& \[lq]" ]] \[rq]. +. +. +.TP +.BI \-x\~ diff-command +Use the +.I diff-command +command to perform the comparison of +.I file1 +and +.IR file2 . +. +In particular, +.I diff-command +should accept the GNU +.MR diff 1 +.B \-D +option. +. +Default: +.BR diff . +. +. +.TP +.B \-\- +Treat all subsequent arguments as file names, +even if they begin with +.RB \[lq] \- \[rq]. +. +. +.\" ==================================================================== +.SH Bugs +.\" ==================================================================== +. +The output is not necessarily compatible with all macro packages +and all preprocessors. +. +A workaround that often overcomes preprocessor problems is to run +.I gdiffmk +on the output of all the preprocessors instead of the input source. +. +. +.LP +.I gdiffmk +relies on the +.B \-D +option of GNU +.I diff +to make a merged \[lq]#ifdef\[rq] output format. +. +Busybox +.I diff +is known to not support it. +. +Also see the +.BI \-x\~ diff-command +option. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +.I gdiffmk +was written by +.MT MBianchi@\:Foveal\:.com +Mike Bianchi +.ME , +now retired. +. +It is maintained by the +.I groff +developers. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR groff 1 , +.MR nroff 1 , +.MR gtroff 1 , +.MR roff 7 , +.MR diff 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_gdiffmk_1_man_C] +.do rr *groff_gdiffmk_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/gemtopbm.1 b/upstream/fedora-40/man1/gemtopbm.1 new file mode 100644 index 00000000..08b60fe1 --- /dev/null +++ b/upstream/fedora-40/man1/gemtopbm.1 @@ -0,0 +1,29 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Gemtopbm User Manual" 0 "May 2000" "netpbm documentation" + +.SH NAME + +gemtopbm - replaced by gemtopnm + +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBgemtopbm\fP was replaced in Netpbm 9.1 (May 2000) by +.BR "gemtopnm" (1)\c +\&. +.PP +\fBgemtopnm\fP is backward compatible with \fBgemtopbm\fP, but +works on color images as well. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/gemtopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/gemtopnm.1 b/upstream/fedora-40/man1/gemtopnm.1 new file mode 100644 index 00000000..e3d8c3d1 --- /dev/null +++ b/upstream/fedora-40/man1/gemtopnm.1 @@ -0,0 +1,67 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Gemtopnm User Manual" 0 "30 April 2000" "netpbm documentation" + +.SH NAME +gemtopnm - convert a GEM .img file into a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBgemtopnm\fP +[\fB-d\fP] +[\fIgemfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBgemtopnm\fP reads a GEM .img file, either the one plane +(black/white) or four plane (16 color) varieety, as input and produces +a PBM or PPM file as output, depending on whether the input is one or +four plane. +.PP +The input file is \fIgemfile\fP if you specify that argument, or +Standard Input otherwise. Output is to Standard Output. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBgemtopnm\fP recognizes the following +command line option: + + +.TP +\fB-d\fP +Produce output describing the contents of the .img file. + + + +.UN seealso +.SH SEE ALSO +.BR "pbmtogem" (1)\c +\&, +.BR "pnm" (1)\c +\& + +.UN author +.SH AUTHOR +.PP +Copyright (C) 1988 Diomidis D. Spinellis (\fIdds@cc.ic.ac.uk\fP). +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/gemtopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/genhostid.1 b/upstream/fedora-40/man1/genhostid.1 new file mode 100644 index 00000000..436d9537 --- /dev/null +++ b/upstream/fedora-40/man1/genhostid.1 @@ -0,0 +1,12 @@ +.TH GENHOSTID 1 +.SH NAME +genhostid \- generate and set a hostid for the current host +.SH SYNOPSIS +.B genhostid + +.SH DESCRIPTION +\fBgenhostid\fR generates a random hostid and stores it in /etc/hostid, +if /etc/hostid does not already exist. + +.SH "SEE ALSO" +hostid(1), gethostid(2), sethostid(2) diff --git a/upstream/fedora-40/man1/genisoimage.1 b/upstream/fedora-40/man1/genisoimage.1 new file mode 100644 index 00000000..69d70436 --- /dev/null +++ b/upstream/fedora-40/man1/genisoimage.1 @@ -0,0 +1,2881 @@ +'\" t +.\" genisoimage.1 -*- nroff -*- To render, first run through tbl +.\" Copyright 1993-1998 by Yggdrasil Computing +.\" Copyright 1996-1997 by Robert Leslie +.\" Copyright 1997-2001 by James Pearson +.\" Copyright 1999-2006 by Joerg Schilling +.\" Copyright 2002-2003 by Jungshik Shin +.\" Copyright 2003 by Jaakko Heinonen +.\" Copyright 2006 by the Cdrkit maintainers +.\" +.TH GENISOIMAGE 1 "13 Dec 2006" +.\" ---------------------------------------- +.SH NAME +genisoimage \- create ISO9660/Joliet/HFS filesystem with optional Rock Ridge attributes +.\" ---------------------------------------- +.SH SYNOPSIS +.B genisoimage +.RI [ options ] +.RB [ \-o +.IR filename ] +.IR pathspec " [" "pathspec ..." ] +.\" ---------------------------------------- +.SH DESCRIPTION +.B genisoimage +is a pre-mastering program to generate ISO9660/Joliet/HFS hybrid +filesystems. +.PP +.B genisoimage +is capable of generating the +.B System Use Sharing Protocol records (SUSP) +specified by the +.BR "Rock Ridge Interchange Protocol" . +This is used to further describe the +files in the ISO9660 filesystem to a Unix host, and provides information such +as long filenames, UID/GID, POSIX permissions, symbolic links, and +block and character device files. +.PP +If Joliet or HFS hybrid command line options are specified, +.B genisoimage +will create the additional filesystem metadata needed for Joliet or HFS. +Otherwise +.B genisoimage +will generate a pure ISO9660 filesystem. +.PP +.B genisoimage +can generate a +.I true +(or +.IR shared ) +HFS hybrid filesystem. The same files are seen as HFS files when +accessed from a Macintosh and as ISO9660 files when accessed from other +machines. HFS stands for +.I Hierarchical File System +and is the native filesystem used on Macintosh computers. +.PP +As an alternative, +.B genisoimage +can generate the +.I Apple Extensions to ISO9660 +for each file. These extensions provide each file with CREATOR, TYPE and +certain Finder flags when accessed from a Macintosh. See the +.B HFS MACINTOSH FILE FORMATS +section below. +.PP +.B genisoimage +takes a snapshot of a given directory tree, and generates a +binary image which will correspond to an ISO9660 and/or HFS filesystem when +written to a block device. +.PP +Each file written to the ISO9660 filesystem must have a filename in the 8.3 +format (up to 8 characters, period, up to 3 characters, all uppercase), even +if Rock Ridge is in use. This filename is used on systems that are not able +to make use of the Rock Ridge extensions (such as MS-DOS), and each filename +in each directory must be different from the other filenames in the same +directory. +.B genisoimage +generally tries to form correct names by forcing the Unix filename to +uppercase and truncating as required, but often this yields unsatisfactory +results when the truncated names are not all unique. +.B genisoimage +assigns weightings to each filename, and if two names that are otherwise the +same are found, the name with the lower priority is renamed to include a +3-digit number (guaranteed to be unique). For example, the two files +.I foo.bar +and +.I foo.bar.~1~ +could be rendered as +.I FOO.BAR;1 +and +.IR FOO000.BAR;1 . +.PP +When used with various HFS options, +.B genisoimage +will attempt to recognise files stored in a number of Apple/Unix file formats +and will copy the data and resource forks as well as any +relevant Finder information. See the +.B HFS MACINTOSH FILE FORMATS +section below for more about formats +.B genisoimage +supports. +.PP +Note that +.B genisoimage +is not designed to communicate with the writer directly. Most writers +have proprietary command sets which vary from one manufacturer to +another, and you need a specialized tool to actually burn the disc. +.B wodim +is one such tool. The latest version of +.B wodim +is available from +.IR http://www.cdrkit.org/ . +.PP +.B pathspec +is the path of the directory tree to be copied into the ISO9660 filesystem. +Multiple paths can be specified, and +.B genisoimage +will merge the files found in all of the specified path components to +form the filesystem image. If an error is encountered while handling directory tree, +only error messages are produced and the process is aborted - incomplete image is not created. +.PP +If the option +.B \-graft\-points +has been specified, it is possible to graft the paths at points other +than the root directory, and it is possible to graft files or +directories onto the cdrom image with names different than what they +have in the source filesystem. This is easiest to illustrate with a +couple of examples. Let's start by assuming that a local file +.I ../old.lis +exists, and you wish to include it in the cdrom image. +.IP +foo/bar/=../old.lis +.PP +will include +.I old.lis +in the cdrom image at +.IR /foo/bar/old.lis , +while +.IP +foo/bar/xxx=../old.lis +.PP +will include +.I old.lis +in the cdrom image at +.IR /foo/bar/xxx . +The same sort of syntax can be used with directories as well. +.B genisoimage +will create any directories required such that the graft +points exist on the cdrom image \(em the directories do not need to +appear in one of the paths. By default, any directories that are created on +the fly like this will have permissions 0555 and appear to be owned by the +person running +.BR genisoimage . +If you wish other permissions or owners of +the intermediate directories, see +.BR \-uid ", " \-gid ", " \-dir\-mode ", " \-file\-mode " and " \-new\-dir\-mode . +.PP +.B genisoimage +will also run on Windows machines when compiled with Cygnus' cygwin +(available from +.IR http://www.cygwin.com/ ). +Therefore most references in this man page to +.I Unix +can be replaced with +.IR Win32 . +.\" ---------------------------------------- +.SH OPTIONS +.PP +Several options can be specified as defaults in a +.I .genisoimagerc +configuration file, as well as on the command line. If a parameter is +specified in both places, the setting from the command line is used. +For details on the format and possible locations of this file, see +.BR genisoimagerc (5). +.TP +.BI \-abstract " file" +Specifies the abstract filename. There is space for 37 characters. +Equivalent to +.B ABST +in the +.I .genisoimagerc +file. +.TP +.BI \-A " application_id" +.TP +.BI \-appid " application_id" +Specifies a text string that will be written into the volume header. +This should describe the application that will be on the disc. There +is space for 128 characters. Equivalent to +.B APPI +in the +.I .genisoimagerc +file. +.TP +.B \-allow\-limited\-size +When processing files larger than 2GiB which cannot be easily represented in +ISO9660, add them with a shrunk visible file size to ISO9660 and with the +correct visible file size to the UDF system. The result is an inconsistent +filesystem and users need to make sure that they really use UDF rather than +ISO9660 driver to read a such disk. Implies enabling +.BR \-udf. +.TP +.B \-allow\-leading\-dots +.TP +.B \-ldots +Allow ISO9660 filenames to begin with a period. Usually, a leading dot is +replaced with an underscore in order to maintain MS-DOS compatibility. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.B \-allow\-lowercase +This options allows lowercase characters to appear in ISO9660 filenames. +.br +This violates the ISO9660 standard, but it happens to work on some systems. +Use with caution. +.TP +.B \-allow\-multidot +This options allows more than one dot to appear in ISO9660 filenames. +A leading dot is not affected by this option, it +may be allowed separately using +.BR \-allow\-leading\-dots . +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-biblio " file" +Specifies the bibliographic filename. There is space for 37 characters. +Equivalent to +.B BIBL +in the +.I .genisoimagerc +file. +.TP +.B \-cache\-inodes +.TP +.B \-no\-cache\-inodes +Enable or disable caching inode and device numbers to find hard links +to files. If +.B genisoimage +finds a hard link (a file with multiple names), the file will also be +hard-linked on the CD, so the file contents only appear once. This +helps to save space. +.B \-cache\-inodes +is default on Unix-like operating systems, but +.B \-no\-cache\-inodes +is default on some other systems such as Cygwin, because it is not safe +to assume that inode numbers are unique on those systems. (Some +versions of Cygwin create fake inode numbers using a weak hashing +algorithm, which may produce duplicates.) If two files have the same +inode number but are not hard links to the same file, +.B genisoimage \-cache\-inodes +will not behave correctly. +.B \-no\-cache\-inodes +is safe in all situations, but in that case +.B genisoimage +cannot detect hard links, so the resulting CD image may be larger +than necessary. +.TP +.BI \-alpha\-boot " alpha_boot_image" +Specifies the path and filename of the boot image to be used when +making an Alpha/SRM bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +.TP +.BI \-hppa\-bootloader " hppa_bootloader_image" +Specifies the path and filename of the boot image to be used when +making an HPPA bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +Other options are required, at the very least a kernel filename and +a boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-cmdline " hppa_boot_command_line" +Specifies the command line to be passed to the HPPA boot loader when +making a bootable CD. Separate the parameters with spaces or +commas. More options must be passed to +.B genisoimage, +at the very least a kernel filename and the boot loader filename. +See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-kernel\-32 " hppa_kernel_32" +.TP +.BI \-hppa\-kernel\-64 " hppa_kernel_64" +Specifies the path and filename of the 32-bit and/or 64-bit kernel images +to be used when making an HPPA bootable CD. The pathnames must be +relative to the source path specified to +.BR genisoimage . +Other options are required, at the very least the boot loader filename +and the boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-ramdisk " hppa_ramdisk_image" +Specifies the path and filename of the ramdisk image to be used when +making an HPPA bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +This parameter is optional. Other options are required, at the very +least a kernel filename and the boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-mips\-boot " mips_boot_image" +Specifies the path and filename of the boot image to be used when +making an SGI/big-endian MIPS bootable CD. The pathname must be +relative to the source path specified to +.BR genisoimage . +This option may be specified several times, to store up to 15 boot +images. +.TP +.BI \-mipsel\-boot " mipsel_boot_image" +Specifies the path and filename of the boot image to be used when +making an DEC/little-endian MIPS bootable CD. The pathname must be +relative to the source path specified to +.BR genisoimage . +.TP +.BI \-B " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +.TP +.BI \-sparc\-boot " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +Specifies a comma-separated list of boot images that are needed to make +a bootable CD for SPARC systems. +Partition 0 is used for the ISO9660 image, the first image file is mapped +to partition 1. +The comma-separated list may have up to 7 fields, including empty fields. +This option is required to make a bootable CD for Sun SPARC systems. +If +.B \-B +or +.B \-sparc\-boot +has been specified, the first sector of the resulting image will +contain a Sun disk label. This disk label specifies slice 0 for the +ISO9660 image and slices 1 to 7 for the boot images that +have been specified with this option. Byte offsets 512 to 8191 +within each of the additional boot images must contain a primary boot +that works for the appropriate SPARC architecture. The rest of each +of the images usually contains a UFS filesystem used for the primary +kernel boot stage. +.IP +The implemented boot method is the one found with SunOS 4.x and SunOS 5.x. +However, it does not depend on SunOS internals but only on properties of +the Open Boot prom, so it should be usable for any OS for SPARC systems. +For more information also see the +.B NOTES +section below. +.IP +If the special filename +.B ... +is used, the actual and all following boot partitions are mapped to the +previous partition. If +.B genisoimage +is called with +.BI \-G " image " \-B " ..." +all boot partitions are mapped to the partition that contains the ISO9660 +filesystem image and the generic boot image that is located in the first +16 sectors of the disc is used for all architectures. +.TP +.BI \-G " generic_boot_image" +Specifies the path and filename of the generic boot image to be used when making +a generic bootable CD. The boot image will be placed on the first 16 +sectors of the CD, before the ISO9660 primary volume descriptor. +If this option is used together with +.BR \-sparc\-boot , +the Sun disk label will overlay the first 512 bytes of the generic +boot image. +.TP +.BI \-b " eltorito_boot_image" +.TP +.BI \-eltorito\-boot " eltorito_boot_image" +Specifies the path and filename of the boot image to be used when making +an El Torito bootable CD for x86 PCs. The pathname must be relative to +the source path specified to +.BR genisoimage . +This option is required to make an El Torito bootable CD. +The boot image must be exactly 1200 kB, 1440 kB or 2880 kB, and +.B genisoimage +will use this size when creating the output ISO9660 filesystem. The PC +BIOS will use the image to emulate a floppy disk, so the first 512-byte +sector should contain PC boot code. This will work, for example, if +the boot image is a LILO-based boot floppy. +.IP +If the boot image is not an image of a floppy, you need to add either +.BR \-hard\-disk\-boot " or " \-no\-emul\-boot . +If the system should not boot off the emulated disk, use +.BR \-no\-boot . +.IP +If +.B \-sort +has not been specified, the boot images are sorted +with low priority (+2) to the beginning of the medium. +If you don't like this, you need to specify a sort weight of 0 for the boot images. +.TP +.B \-eltorito\-alt\-boot +Start with a new set of El Torito boot parameters. Up to 63 El Torito +boot entries may be stored on a single CD. +.TP +.BI \-hard\-disk\-boot +Specifies that the boot image used to create El Torito bootable CDs is +a hard disk image. The image must begin with a master boot +record that contains a single partition. +.TP +.BI \-no\-emul\-boot +Specifies that the boot image used to create El Torito bootable CDs is +a "no emulation" image. The system will load and execute this image without +performing any disk emulation. +.TP +.BI \-no\-boot +Specifies that the created El Torito CD should be marked as not bootable. The +system will provide an emulated drive for the image, but will boot off +a standard boot device. +.TP +.BI \-boot\-load\-seg " segment_address" +Specifies the load segment address of the boot image for no-emulation +El Torito CDs. +.TP +.BI \-boot\-load\-size " load_sectors" +Specifies the number of "virtual" (512-byte) sectors to load in +no-emulation mode. The default is to load the entire boot file. Some +BIOSes may have problems if this is not a multiple of 4. +.TP +.B \-boot\-info\-table +Specifies that a 56-byte table with information of the CD-ROM layout +will be patched in at offset 8 in the boot file. If this option is +given, the boot file is +.IR "modified in the source filesystem" , +so make a copy of this file if it cannot be easily regenerated! +See the +.B EL TORITO BOOT INFO TABLE +section for a description of this table. +.TP +.BI \-C " last_sess_start,next_sess_start" +.TP +.BI \-cdrecord\-params " last_sess_start,next_sess_start" +This option is needed to create a CD Extra or the image of a second +session or a higher-level session for a multisession disc. +.B \-C +takes two numbers separated by a comma. The first is the first sector +in the last session of the disc that should be appended to. +The second number is the starting sector number of the new session. +The correct numbers may be retrieved by calling +.B wodim \-msinfo ... +If +.B \-C +is used in conjunction with +.BR \-M , +.B genisoimage +will create a filesystem image that is intended to be a continuation +of the previous session. +If +.B \-C +is used without +.BR \-M , +.B genisoimage +will create a filesystem image that is intended to be used for a second +session on a CD Extra. This is a multisession CD that holds audio data +in the first session and an ISO9660 filesystem in the second session. +.TP +.BI \-c " boot_catalog" +.TP +.BI \-eltorito\-catalog " boot_catalog" +Specifies the path and filename of the boot catalog, which is required +for an El Torito bootable CD. The pathname must be relative to the source +path specified to +.BR genisoimage . +This file will be inserted into the output tree and not created +in the source filesystem, so be +sure the specified filename does not conflict with an existing file, or +it will be excluded. Usually a name like +.I boot.catalog +is chosen. +.IP +If +.B \-sort +has not been specified, the boot catalog sorted +with low priority (+1) to the beginning of the medium. +If you don't like this, you need to specify a sort weight of 0 for the boot catalog. +.TP +.B \-check\-oldnames +Check all filenames imported from the old session for compliance with +the ISO9660 file naming rules. +Without this option, only names longer than 31 characters are checked, +as these files are a serious violation of the ISO9660 standard. +.TP +.BI \-check\-session " file" +Check all old sessions for compliance with actual +.B genisoimage +ISO9660 file naming rules. +This is a high-level option that combines +.B \-M +.I file +.BR "\-C 0,0 \-check\-oldnames" . +For the parameter +.IR file , +see the description of +.BR \-M . +.TP +.BI \-checksum_algorithm_iso " alg1,alg2,..." +Specify the checksum types desired for the output image. +.TP +.BI \-checksum_algorithm_template " alg1,alg2,..." +Specify the checksum types desired for the output jigdo template. +.TP +.BI \-copyright " file" +Specifies copyright information, typically a filename on the disc. +There is space for 37 characters. Equivalent to +.B COPY +in the +.I .genisoimagerc +file. +.TP +.B \-d +.TP +.B \-omit\-period +Do not append a period to files that do not have one. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.B \-D +.TP +.B \-disable\-deep\-relocation +Do not use deep directory relocation, and instead just pack them in the +way we see them. +.br +If ISO9660:1999 has not been selected, +this violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.B \-debug +Set debug flag. +.TP +.BI \-dir\-mode " mode" +Overrides the mode of directories used to create the image to +.IR mode , +specified as 4 digits of permission bits as in +.BR chmod (1). +This option automatically enables Rock Ridge extensions. +.TP +.B \-dvd\-video +Generate a DVD-Video compliant UDF filesystem. This is done by sorting the +order of the content of the appropriate files and by adding padding +between the files if needed. +Note that the sorting only works if the DVD-Video filenames include uppercase +characters only. +.IP +Note that in order to get a DVD-Video compliant filesystem image, you +need to prepare a DVD-Video compliant directory tree. This requires a +directory +.B VIDEO_TS +(all caps) in the root directory of the resulting DVD, and usually +another directory +.BR AUDIO_TS . +.B VIDEO_TS +needs to include all needed files (filenames must be all caps) for a +compliant DVD-Video filesystem. +.TP +.BI \-e " efi_boot_file" +.TP +.BI \-efi\-boot " efi_boot_file" +Set EFI boot image name. +.TP +.B \-f +.TP +.B \-follow\-links +Follow symbolic links when generating the filesystem. When this option is not +in use, symbolic links will be entered using Rock Ridge if enabled, otherwise +they will be ignored. +.TP +.BI \-file\-mode " mode" +Overrides the mode of regular files used to create the image to +.IR mode , +specified as 4 digits of permission bits as in +.BR chmod (1). +This option automatically enables Rock Ridge extensions. +.TP +.BI \-gid " gid" +Overrides the group ID read from the source files to the value of +.IR gid . +Specifying this option automatically enables Rock Ridge extensions. +.TP +.B \-gui +Switch the behaviour for a GUI. This currently makes the output more verbose +but may have other effects in the future. +.TP +.B \-graft\-points +Allow use of graft points for filenames. If this option is used, all +filenames are checked for graft points. The filename is divided at the +first unescaped equal sign. All occurrences of `\(rs' and `=' characters +must be escaped with `\(rs' if +.B \-graft\-points +has been specified. +.TP +.BI \-hide " glob" +Hide any files matching +.IR glob , +a shell wildcard pattern, from being seen in the ISO9660 or Rock Ridge +directory. +.I glob +may match any part of the filename or path. If +.I glob +matches a directory, the contents of that directory will be hidden. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +All the hidden files will still be written to the output CD image file. +See also +.BR \-hide\-joliet , +and +.IR README.hide . +This option may be used multiple times. +.TP +.BI \-hide\-list " file" +A file containing a list of shell wildcards to be hidden. See +.BR \-hide . +.TP +.BI \-hidden " glob" +Add the hidden (existence) ISO9660 directory attribute for files and +directories matching +.IR glob , +a shell wildcard pattern. This attribute will prevent the files from +being shown by some MS-DOS and Windows commands. +.I glob +may match any part of the filename or path. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +This option may be used multiple times. +.TP +.BI \-hidden\-list " file" +A file containing a list of shell wildcards to get the hidden +attribute. See +.BR \-hidden . +.TP +.BI \-hide\-joliet " glob" +Hide files and directories matching +.IR glob , +a shell wildcard pattern, from being seen in the Joliet directory. +.I glob +may match any part of the filename or path. If +.I glob +matches a directory, the contents of that directory will be hidden. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +All the hidden files will still be written to the output CD image file. +This option is usually used with +.BR \-hide . +See also +.IR README.hide . +This option may be used multiple times. +.TP +.BI \-hide\-joliet\-list " file" +A file containing a list of shell wildcards to be hidden from the +Joliet tree. See +.BR \-hide\-joliet . +.TP +.B \-hide\-joliet\-trans\-tbl +Hide the +.I TRANS.TBL +files from the Joliet tree. +These files usually don't make sense in the Joliet world as they list +the real name and the ISO9660 name which may both be different from the +Joliet name. +.TP +.B \-hide\-rr\-moved +Rename the directory +.I RR_MOVED +to +.I .rr_moved +in the Rock Ridge tree. +It seems to be impossible to completely hide the +.I RR_MOVED +directory from the Rock Ridge tree. +This option only makes the visible tree less confusing for +people who don't know what this directory is for. +If you need to have no +.I RR_MOVED +directory at all, you should use +.BR \-D . +Note that if +.B \-D +has been specified, the resulting filesystem is not ISO9660 +level-1 compliant and will not be readable on MS-DOS. +See also the +.B NOTES +section. +.TP +.BI \-input\-charset " charset" +Input charset that defines the characters used in local filenames. +To get a list of valid charset names, call +.BR "genisoimage \-input\-charset help" . +To get a 1:1 mapping, you may use +.B default +as charset name. The default initial values are +.I cp437 +on DOS-based systems and +.I iso8859-1 +on all other systems. See the +.B CHARACTER SETS +section below for more details. +.TP +.BI \-output\-charset " charset" +Output charset that defines the characters that will be used in Rock Ridge +filenames. Defaults to the input charset. See +.B CHARACTER SETS +section below for more details. +.TP +.BI \-iso\-level " level" +Set the ISO9660 conformance level. Valid numbers are 1 to 4. +.IP +With level 1, files may only consist of one section and filenames are +restricted to 8.3 characters. +.IP +With level 2, files may only consist of one section. +.IP +With level 3, no restrictions (other than ISO-9660:1988) do apply. +.IP +With all ISO9660 levels from 1 to 3, all filenames are restricted to +uppercase letters, numbers and underscores (_). Filenames are +limited to 31 characters, directory nesting is limited to 8 +levels, and pathnames are limited to 255 characters. +.IP +Level 4 officially does not exist but +.B genisoimage +maps it to ISO-9660:1999, which is ISO9660 version 2. +.IP +With level 4, an enhanced volume descriptor with version number +and file structure version number set to 2 is emitted. +Directory nesting is not limited to 8 levels, +there is no need for a file to contain a dot and the dot has no +special meaning, filenames do not have version numbers, +.\" (f XXX ??? The character used for filling byte positions which are +.\" specified to be characters is subject to agreement between the +.\" originator and the recipient of the volume), +and filenames can be up to 207 characters long, or 197 characters if +Rock Ridge is used. +.IP +When creating Version 2 images, +.B genisoimage +emits an enhanced volume descriptor, similar but not identical to a +primary volume descriptor. Be careful not to use broken software +to make ISO9660 images bootable by assuming a second PVD copy and patching +this putative PVD copy into an El Torito VD. +.TP +.B \-J +Generate Joliet directory records in addition to regular ISO9660 +filenames. This is primarily useful when the discs are to be used on +Windows machines. Joliet filenames are specified in Unicode and each +path component can be up to 64 Unicode characters long. +Note that Joliet is not a standard \(em only Microsoft Windows and Linux +systems can read Joliet extensions. For greater portability, consider +using both Joliet and Rock Ridge extensions. +.TP +.B \-joliet\-long +Allow Joliet filenames to be up to 103 Unicode characters, instead of +64. This breaks the Joliet specification, but appears to work. Use +with caution. +.\" The number 103 is derived from: the maximum Directory Record Length +.\" (254), minus the length of Directory Record (33), minus CD-ROM XA +.\" System Use Extension Information (14), divided by the UTF-16 +.\" character size (2). +.TP +.BI \-jcharset " charset" +A combination of +.B \-J \-input\-charset +.IR charset . +See the +.B CHARACTER SETS +section below for more details. +.TP +.B \-l +.TP +.B \-full\-iso9660\-filenames +Allow full 31-character filenames. Normally the ISO9660 filename will be in an +8.3 format which is compatible with MS-DOS, even though the ISO9660 standard +allows filenames of up to 31 characters. If you use this option, the disc may +be difficult to use on a MS-DOS system, but will work on most other systems. +Use with caution. +.TP +.B \-L +Outdated option; use +.B \-allow\-leading\-dots +instead. +.TP +.BI \-jigdo\-jigdo " jigdo_file" +Produce a +.B jigdo +.I .jigdo +metadata file as well as the filesystem image. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-template " template_file" +Produce a +.B jigdo +.I .template +file as well as the filesystem image. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-min\-file\-size " size" +Specify the minimum size for a file to be listed in the +.I .jigdo +file. Default (and minimum allowed) is 1KB. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-force\-md5 " path" +Specify a file pattern where files +.I must +be contained in the externally-supplied MD5 list as supplied by +.BR \-md5\-list . +See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-exclude " path" +Specify a file pattern where files will not be listed in the +.I .jigdo +file. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-map " path" +Specify a pattern mapping for the jigdo file +(e.g. +.IR Debian=/mirror/debian ). +See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-md5\-list " md5_file" +Specify a file containing the MD5sums, sizes and pathnames of the +files to be included in the +.I .jigdo +file. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-template\-compress " algorithm +Specify a compression algorithm to use for template date. gzip and +bzip2 are currently supported, and gzip is the default. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-log\-file " log_file" +Redirect all error, warning and informational messages to +.I log_file +instead of the standard error. +.TP +.BI \-m " glob" +Exclude files matching +.IR glob , +a shell wildcard pattern, from being written to CD-ROM. +.I glob +may match either the filename component or the full pathname. +This option may be used multiple times. For example: +.sp + genisoimage \-o rom \-m \(aq*.o\(aq \-m core \-m foobar +.sp +would exclude all files ending in `.o', or called +.IR core " or " foobar +from the image. Note that if you had a directory called +.IR foobar , +it too (and of course all its descendants) would be excluded. +.TP +.BI \-exclude\-list " file" +A file containing a list of shell wildcards to be excluded. See +.BR \-m . +.TP +.B \-max\-iso9660\-filenames +Allow ISO9660 filenames to be up to 37 characters long. +This option enables +.B \-N +as the extra name space is taken from the space reserved for +file version numbers. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Although a conforming application needs to provide a buffer space of at +least 37 characters, discs created with this option may cause a buffer +overflow in the reading operating system. Use with extreme care. +.TP +.BI \-M " path" +.TP +.BI \-M " device" +.TP +.BI \-dev " device" +Specifies path to existing ISO9660 image to be merged. The alternate form +takes a SCSI device specifier that uses the same syntax as the +.B dev= +parameter of +.BR wodim . +The output of +.B genisoimage +will be a new session which should get written to the end of the +image specified in +.BR \-M . +Typically this requires multisession capability for the CD recorder +used to write the image. This option may only be used in conjunction +with +.BR \-C . +.TP +.B \-N +.TP +.B \-omit\-version\-number +Omit version numbers from ISO9660 filenames. +.br +This violates the ISO9660 standard, but no one really uses the +version numbers anyway. Use with caution. +.TP +.BI \-new\-dir\-mode " mode" +Specify the mode, a 4-digit number as used in +.BR chmod (1), +to use when creating new directories in the filesystem image. The +default is 0555. +.TP +.B \-nobak +.TP +.B \-no\-bak +Exclude backup files files on the ISO9660 filesystem; that is, +filenames that contain the characters `~' or `#' or end in +.IR .bak . +These are typically backup files for Unix text editors. +.TP +.B \-force\-rr +Do not use the automatic Rock Ridge attributes recognition for previous sessions. +This can work around problems with images created by, e.g., NERO Burning ROM. +.TP +.B \-no\-rr +Do not use the Rock Ridge attributes from previous sessions. +This may help to avoid problems when +.B genisoimage +finds illegal Rock Ridge signatures on an old session. +.TP +.B \-no\-split\-symlink\-components +Don't split the symlink components, but begin a new Continuation Area (CE) +instead. This may waste some space, but the SunOS 4.1.4 cdrom driver +has a bug in reading split symlink components. +.IP +It is questionable whether this option is useful nowadays. +.TP +.B \-no\-split\-symlink\-fields +Don't split the symlink fields, but begin a new Continuation Area (CE) +instead. This may waste some space, but the SunOS 4.1.4 and +Solaris 2.5.1 cdrom driver have a bug in reading split symlink fields +(a `/' can be dropped). +.IP +It is questionable whether this option is useful nowadays. +.TP +.BI \-o " filename" +Specify the output file for the the ISO9660 filesystem image. +This can be a disk file, a tape drive, or it can correspond directly +to the device name of the optical disc writer. If not specified, stdout is +used. Note that the output can also be a block device for a regular +disk partition, in which case the ISO9660 filesystem can be mounted +normally to verify that it was generated correctly. +.TP +.B \-pad +Pad the end of the whole image by 150 sectors (300 kB). This option is +enabled by default. If used in combination with +.BR \-B , +padding is inserted between the ISO9660 partition and the boot +partitions, such that the first boot partition starts +on a sector number that is a multiple of 16. +.IP +The padding is needed as many operating systems (e.g. Linux) +implement read-ahead bugs in their filesystem I/O. These bugs result in read +errors on files that are located near the end of a track, particularly +if the disc is written in Track At Once mode, or where a CD audio track +follows the data track. +.\" XXX: Someone should check to see if the Linux readahead bug is +.\" XXX: still present, and update this comment accordingly. +.TP +.B \-no\-pad +Do not pad the end by 150 sectors (300 kB) and do not make the the boot partitions +start on a multiple of 16 sectors. +.TP +.BI \-path\-list " file" +A file containing a list of +.I pathspec +directories and filenames to be added to the ISO9660 filesystem. This list +of pathspecs are processed after any that appear on the command line. If the +argument is +.IR \- , +the list is read from the standard input. +.TP +.B \-P +Outdated option; use +.B \-publisher +instead. +.TP +.BI \-publisher " publisher_id" +Specifies a text string that will be written into the volume header. +This should describe the publisher of the CD-ROM, usually with a +mailing address and phone number. There is space for 128 characters. +Equivalent to +.B PUBL +in the +.I .genisoimagerc +file. +.TP +.BI \-p " preparer_id" +.TP +.BI \-preparer " preparer_id" +Specifies a text string that will be written into the volume header. +This should describe the preparer of the CD-ROM, usually with a mailing +address and phone number. There is space for 128 characters. +Equivalent to +.B PREP +in the +.I .genisoimagerc +file. +.TP +.B \-print\-size +Print estimated filesystem size in multiples of the sector size (2048 bytes) +and exit. This option is needed for +Disk At Once mode and with some CD-R drives when piping directly into +.BR wodim , +cases where +.B wodim +needs to know the size of the filesystem image in advance. +Old versions of +.B mkisofs +wrote this information (among other information) to +.IR stderr . +As this turns out to be hard to parse, the number without any other information +is now printed on +.I stdout +too. +If you like to write a simple shell script, redirect +.I stderr +and catch the number from +.IR stdout . +This may be done with: +.sp + cdblocks=\` genisoimage \-print\-size \-quiet .\|.\|. \` +.br + genisoimage .\|.\|. | wodim .\|.\|. tsize=${cdblocks}s \- +.TP +.B \-quiet +This makes +.B genisoimage +even less verbose. No progress output will be provided. +.TP +.B \-R +.TP +.B \-rock +Generate SUSP and RR records using the Rock Ridge protocol to further describe +the files on the ISO9660 filesystem. +.TP +.B \-r +.TP +.B \-rational\-rock +This is like the \-R option, but file ownership and modes are set to +more useful values. The uid and gid are set to zero, because they are +usually only useful on the author's system, and not useful to the +client. All the file read bits are set true, so that files and +directories are globally readable on the client. If any execute bit is +set for a file, set all of the execute bits, so that executables are +globally executable on the client. If any search bit is set for a +directory, set all of the search bits, so that directories are globally +searchable on the client. All write bits are cleared, because the +filesystem will be mounted read-only in any case. If any of the special +mode bits are set, clear them, because file locks are not useful on a +read-only filesystem, and set-id bits are not desirable for uid 0 or +gid 0. +When used on Win32, the execute bit is set on +.I all +files. This is a result of the lack of file permissions on Win32 and the +Cygwin POSIX emulation layer. See also +.BR \-uid ", " \-gid , +.BR \-dir\-mode ", " \-file\-mode +and +.BR \-new\-dir\-mode . +.TP +.B \-relaxed\-filenames +Allows ISO9660 filenames to include all 7-bit ASCII characters except +lowercase letters. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-root " dir" +Moves all files and directories into +.I dir +in the image. This is essentially the +same as using +.B \-graft\-points +and adding +.I dir +in front of every pathspec, but is easier to use. +.I dir +may actually be several levels deep. It is +created with the same permissions as other graft points. +.TP +.BI \-old-root " dir" +This option is necessary when writing a multisession +image and the previous (or even older) session was written with +.B -root +.IR dir . +Using a directory name not found in the previous session +causes +.B genisoimage +to abort with an error. +Without this option, +.B genisoimage +would not be able to find unmodified files and would +be forced to write their data into the image once more. +.B \-root +and +.B \-old-root +are meant to be used together to do incremental backups. +The initial session would e.g. use: +.B genisoimage \-root backup_1 +.IR dirs . +The next incremental backup with +.B genisoimage \-root backup_2 \-old-root backup_1 +.I dirs +would take another snapshot of these directories. The first +snapshot would be found in +.BR backup_1 , +the second one in +.BR backup_2 , +but only modified or new files need to be written +into the second session. +Without these options, new files would be added and old ones would be +preserved. But old ones would be overwritten if the file was +modified. Recovering the files by copying the whole directory back +from CD would also restore files that were deleted +intentionally. Accessing several older versions of a file requires +support by the operating system to choose which sessions are to be +mounted. +.TP +.BI \-s " sector type" +.TP +.BI \-sectype " sector type" +Set output sector type to e.g. data/xa1/raw. + .TP +.BI \-sort " sort_file" +Sort file locations on the media. Sorting is controlled by a file that +contains pairs of filenames and sorting offset weighting. +If the weighting is higher, the file will be located closer to the +beginning of the media, if the weighting is lower, the file will be located +closer to the end of the media. There must be only one space or tabs +character between the filename and the +weight and the weight must be the last characters on a line. The filename +is taken to include all the characters up to, but not including the last +space or tab character on a line. This is to allow for space characters to +be in, or at the end of a filename. +This option does +.B not +sort the order of the filenames that appear +in the ISO9660 directory. It sorts the order in which the file data is +written to the CD image, which is useful in order to optimize the +data layout on a CD. See +.B README.sort +for more details. +.TP +.BI \-sparc\-boot " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +See +.B \-B +above. +.TP +.BI \-sparc\-label " label" +Set the Sun disk label name for the Sun disk label that is created with +.BR \-sparc-boot . +.TP +.B \-split\-output +Split the output image into several files of approximately 1 GB each. +This helps to create DVD-sized ISO9660 images on operating systems without +large file support. +.B wodim +will concatenate more than one file into a single track if writing to a DVD. +To make +.B \-split\-output +work, +.BI \-o " filename" +must be specified. The resulting output images will be named: +.IR filename_00 ", " filename_01 ", " filename_02 .... +.TP +.BI \-stream\-media\-size " #" +Select streaming operation and set the media size to # sectors. +This allows you to pipe the output of the +.BR tar (1) +program into +.B genisoimage +and to create an ISO9660 filesystem without the need of an intermediate +tar archive file. +If this option has been specified, +.B genisoimage +reads from +.I stdin +and creates a file with the name +.IR STREAM.IMG . +The maximum size of the file (with padding) is 200 sectors less than the +specified media size. If +.B \-no\-pad +has been specified, the file size is 50 sectors less than the specified media size. +If the file is smaller, +.B genisoimage +will write padding. This may take awhile. +.IP +The option +.B \-stream\-media\-size +creates simple ISO9660 filesystems only and may not used together with multisession +or hybrid filesystem options. +.TP +.BI \-stream\-file\-name " name" +Reserved for future use. +.TP +.BI \-sunx86\-boot " UFS_img,,,AUX1_img" +Specifies a comma-separated list of filesystem images that are needed to make +a bootable CD for Solaris x86 systems. +.IP +Note that partition 1 is used for the ISO9660 image and that partition 2 is +the whole disk, so partition 1 and 2 may not be used by external partition data. +The first image file is mapped to partition 0. +There may be empty fields in the comma-separated list, +and list entries for partition 1 and 2 must be empty. +The maximum number of supported partitions is 8 (although the Solaris x86 +partition table could support up to 16 partitions), so it is impossible +to specify more than 6 partition images. +This option is required to make a bootable CD for Solaris x86 systems. +.IP +If +.B \-sunx86\-boot +has been specified, the first sector of the resulting image will +contain a PC fdisk label with a Solaris type 0x82 fdisk partition that +starts at offset 512 and spans the whole CD. +In addition, for the Solaris type 0x82 fdisk partition, there is a +SVr4 disk label at offset 1024 in the first sector of the CD. +This disk label specifies slice 0 for the first (usually UFS type) +filesystem image that is used to boot the PC and slice 1 for +the ISO9660 image. +Slice 2 spans the whole CD slice 3 .\|.\|. slice 7 may be used for additional +filesystem images that have been specified with this option. +.IP +A Solaris x86 boot CD uses a 1024 byte sized primary boot that uses the +.B El-Torito no-emulation +boot mode and a secondary generic boot that is in CD sectors 1\|.\|.15. +For this reason, both +.BI "-b " bootimage " \-no\-emul\-boot" +and +.BI \-G " genboot" +must be specified. +.TP +.BI \-sunx86\-label " label" +Set the SVr4 disk label name for the SVr4 disk label that is created with +.BR \-sunx86-boot . +.TP +.BI \-sysid " ID" +Specifies the system ID. There is space for 32 characters. +Equivalent to +.B SYSI +in the +.I .genisoimagerc +file. +.TP +.B \-T +.TP +.B \-translation\-table +Generate a file +.I TRANS.TBL +in each directory on the CD-ROM, which can be used +on non-Rock\ Ridge-capable systems to help establish the correct filenames. +There is also information present in the file that indicates the major and +minor numbers for block and character devices, and each symlink has the name of +the link file given. +.TP +.BI \-table\-name " table_name" +Alternative translation table filename (see above). Implies +.BR \-T . +If you are creating a multisession image you must use the same name +as in the previous session. +.TP +.BI \-ucs\-level " level" +Set Unicode conformance level in the Joliet SVD. The default level is 3. +It may be set to 1..3 using this option. +.TP +.B \-udf +Include UDF filesystem support in the generated filesystem image. UDF +support is currently in alpha status and for this reason, it is not +possible to create UDF-only images. UDF data structures are currently +coupled to the Joliet structures, so there are many pitfalls with the +current implementation. There is no UID/GID support, there is no POSIX +permission support, there is no support for symlinks. Note that UDF +wastes the space from sector ~20 to sector 256 at the beginning of the +disc in addition to the space needed for real UDF data structures. +.TP +.BI \-uid " uid" +Overrides the uid read from the source files to the value of +.IR uid . +Specifying this option automatically enables Rock Ridge extensions. +.TP +.B \-use\-fileversion +The option +.B \-use\-fileversion +allows +.B genisoimage +to use file version numbers from the filesystem. +If the option is not specified, +.B genisoimage +creates a version number of 1 for all files. +File versions are strings in the range +.I ;1 +to +.I ;32767 +This option is the default on VMS. +.TP +.B \-U +.TP +.B \-untranslated\-filenames +Allows "untranslated" filenames, completely violating the ISO9660 standards +described above. Enables the following flags: +.B \-d \-l \-N \-allow\-leading\-dots \-relaxed\-filenames +.BR "\-allow\-lowercase \-allow\-multidot \-no\-iso\-translate" . +Allows more than one `.' character in the filename, as well as +mixed-case filenames. This is useful on HP-UX, where the built-in +.I cdfs +filesystem does not recognize any extensions. Use with extreme caution. +.TP +.B \-no\-iso\-translate +Do not translate the characters `#' and `~' which are invalid for ISO9660 filenames. +Although invalid, these characters are often used by Microsoft systems. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-V " volid" +Specifies the volume ID (volume name or label) to be written into the +master block. There is space for 32 characters. Equivalent to +.B VOLI +in the +.I .genisoimagerc +file. The volume ID is used as the mount point by the Solaris volume +manager and as a label assigned to a disc on various other platforms +such as Windows and Apple Mac OS. +.TP +.BI \-volset " ID" +Specifies the volume set ID. There is space for 128 characters. +Equivalent to +.B VOLS +in the +.I .genisoimagerc +file. +.TP +.BI \-volset\-size " #" +Sets the volume set size to #. +The volume set size is the number of CDs that are in a CD volume set. +A volume set is a collection of one or more volumes, on which a set of +files is recorded. +.IP +Volume Sets are not intended to be used to create a set numbered CDs +that are part of e.g. a Operation System installation set of CDs. +Volume Sets are rather used to record a big directory tree that would not +fit on a single volume. +Each volume of a Volume Set contains a description of all the directories +and files that are recorded on the volumes where the sequence numbers +are less than, or equal to, the assigned Volume Set Size of the current +volume. +.IP +.B genisoimage +currently does not support a +.B \-volset\-size +that is larger than 1. +.IP +The option +.B \-volset\-size +must be specified before +.B \-volset\-seqno +on each command line. +.TP +.BI \-volset\-seqno " #" +Sets the volume set sequence number to #. +The volume set sequence number is the index number of the current +CD in a CD set. +The option +.B \-volset\-size +must be specified before +.B \-volset\-seqno +on each command line. +.TP +.B \-v +.TP +.B \-verbose +Verbose execution. If given twice on the command line, extra debug information +will be printed. +.TP +.BI \-x " glob" +Identical to +.B \-m +.IR glob . +.TP +.B \-XA +Generate XA directory attruibutes. +.TP +.B \-xa +Generate rationalized XA directory attruibutes. +.TP +.B \-z +.TP +.B \-transparent\-compression +Generate special +.I RRIP +records for transparently compressed files. +This is only of use and interest for hosts that support transparent +decompression, such as Linux 2.4.14 or later. You must specify +.BR \-R " or " \-r +to enable Rock Ridge, and generate compressed files using the +.B mkzftree +utility before running +.BR genisoimage . +Note that transparent compression is a nonstandard Rock Ridge extension. +The resulting disks are only transparently readable if used on Linux. +On other operating systems you will need to call +.B mkzftree +by hand to decompress the files. +.\" ---------------------------------------- +.SH "HFS OPTIONS" +.TP +.B \-hfs +Create an ISO9660/HFS hybrid CD. This option should be used in conjunction +with the +.BR \-map , +.B \-magic +and/or the various +.I double dash +options given below. +.TP +.B \-apple +Create an ISO9660 CD with Apple's extensions. Similar to +.BR \-hfs , +except that the Apple Extensions to ISO9660 are added instead of +creating an HFS hybrid volume. +Former +.B genisoimage +versions did include Rock Ridge attributes by default if +.B \-apple +was specified. This versions of +.B genisoimage +does not do this anymore. If you like to have Rock Ridge attributes, +you need to specify this separately. +.TP +.BI \-map " mapping_file" +Use the +.I mapping_file +to set the CREATOR and TYPE information for a file based on the +filename's extension. A filename is +mapped only if it is not one of the know Apple/Unix file formats. See the +.B HFS CREATOR/TYPE +section below. +.TP +.BI \-magic " magic_file" +The CREATOR and TYPE information is set by using a file's +.I magic number +(usually the first few bytes of a file). The +.I magic_file +is only used if a file is not one of the known Apple/Unix file formats, or +the filename extension has not been mapped using +.BR \-map . +See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.BI \-hfs\-creator " creator" +Set the default CREATOR for all files. Must be exactly 4 characters. See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.BI \-hfs\-type " type" +Set the default TYPE for all files. Must be exactly 4 characters. See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.B \-probe +Search the contents of files for all the known Apple/Unix file formats. +See the +.B HFS MACINTOSH FILE FORMATS +section below for more about these formats. +However, the only way to check for +.I MacBinary +and +.I AppleSingle +files is to open and read them, so this option may +increase processing time. It is better to use one or more +.I double dash +options given below if the Apple/Unix formats in use are known. +.TP +.B \-no\-desktop +Do not create (empty) Desktop files. New HFS Desktop files will be created +when the CD is used on a Macintosh (and stored in the System Folder). +By default, empty Desktop files are added to the HFS volume. +.TP +.B \-mac\-name +Use the HFS filename as the starting point for the ISO9660, Joliet and +Rock Ridge filenames. See the +.B HFS MACINTOSH FILENAMES +section below for more information. +.TP +.BI \-boot\-hfs\-file " driver_file" +Installs the +.I driver_file +that +.I may +make the CD bootable on a Macintosh. See the +.B HFS BOOT DRIVER +section below. (Alpha). +.TP +.B \-part +Generate an HFS partition table. By default, no partition table is generated, +but some older Macintosh CD-ROM drivers need an HFS partition table on the +CD-ROM to be able to recognize a hybrid CD-ROM. +.TP +.BI \-auto " AutoStart_file" +Make the HFS CD use the QuickTime 2.0 Autostart feature to launch an +application or document. The given filename must be the name of a document or +application located at the top level of the CD. The filename must be less +than 12 characters. (Alpha). +.TP +.BI \-cluster\-size " size" +Set the size in bytes of the cluster or allocation units of PC Exchange +files. Implies +.BR \-\-exchange . +See the +.B HFS MACINTOSH FILE FORMATS +section below. +.TP +.BI \-hide\-hfs " glob" +Hide +.IR glob , +a shell wildcard pattern, from the HFS volume. The file or directory +will still exist in the ISO9660 and/or Joliet directory. +.I glob +may match any part of the filename. Multiple globs may be excluded. +Example: +.sp + genisoimage \-o rom \-hfs \-hide\-hfs \(aq*.o\(aq \-hide\-hfs foobar +.sp +would exclude all files ending in `.o' or called +.I foobar +from the HFS volume. Note that if you had a directory called +.IR foobar , +it too (and of course all its descendants) would be excluded. The +.I glob +can also be a path name relative to the source directories given on the +command line. Example: +.sp + genisoimage \-o rom \-hfs \-hide\-hfs src/html src +.sp +would exclude just the file or directory called +.I html +from the +.I src +directory. Any other file or directory called +.I html +in the tree will not be excluded. Should be used with +.B \-hide +and/or +.BR \-hide\-joliet . +In order to match a directory name, make sure the pattern does not +include a trailing `/' character. See +.I README.hide +for more details. +.TP +.BI \-hide\-hfs\-list " file" +Specify a file containing a list of wildcard patterns to be hidden as in +.BR \-hide\-hfs . +.TP +.BI \-hfs\-volid " hfs_volid" +Volume name for the HFS partition. This is the name that is +assigned to the disc on a Macintosh and replaces the +.I volid +used with +.BR \-V . +.TP +.B \-icon\-position +Use the icon position information, if it exists, from the Apple/Unix file. +The icons will appear in the same position as they would on a Macintosh +desktop. Folder location and size on screen, its scroll positions, folder +View (view as Icons, Small Icons, etc.) are also preserved. +.\" This option may become set by default in the future. +(Alpha). +.TP +.BI \-root\-info " file" +Set the location, size on screen, scroll positions, folder View etc. for the +root folder of an HFS volume. See +.I README.rootinfo +for more information. (Alpha) +.TP +.BI \-prep\-boot " file" +PReP boot image file. Up to 4 are allowed. See +.I README.prep_boot +for more information. (Alpha) +.TP +.BI \-chrp\-boot +Add CHRP boot header. +.TP +.BI \-input\-hfs\-charset " charset" +Input charset that defines the characters used in HFS filenames when +used with +.BR \-mac\-name . +The default charset is +.I cp10000 +(Mac Roman). See the +.B CHARACTER SETS +and +.B HFS MACINTOSH FILENAMES +sections below for more details. +.TP +.BI \-output\-hfs\-charset " charset" +Output charset that defines the characters that will be used in the HFS +filenames. Defaults to the input charset. See the +.B CHARACTER SETS +section below for more details. +.TP +.B \-hfs\-unlock +By default, +.B genisoimage +will create an HFS volume that is locked. +This option leaves the volume unlocked so that other applications (e.g. +.BR hfsutils ) +can modify the volume. See the +.B HFS PROBLEMS/LIMITATIONS +section below for warnings about using this option. +.TP +.BI \-hfs\-bless " folder_name" +"Bless" the given directory (folder). This is usually the +.I System Folder +and is used in creating HFS bootable CDs. The name of the directory must +be the whole path name as +.B genisoimage +sees it. E.g., if the given pathspec is +.I ./cddata +and the required folder is called +.IR "System Folder" , +the whole path name is +.I \(dq/cddata/System Folder\(dq +(remember to use quotes if the name contains spaces). +.TP +.BI \-hfs\-parms " parameters" +Override certain parameters used to create the HFS filesystem. Unlikely to +be used in normal circumstances. See the +.I libhfs_iso/hybrid.h +source file for details. +.TP +.B \-\-cap +Look for AUFS CAP Macintosh files. Search for CAP Apple/Unix file formats +only. Searching for the other possible Apple/Unix file formats is disabled, +unless other +.I double dash +options are given. +.TP +.B \-\-netatalk +Look for NETATALK Macintosh files +.TP +.B \-\-double +Look for AppleDouble Macintosh files +.TP +.B \-\-ethershare +Look for Helios EtherShare Macintosh files +.TP +.B \-\-ushare +Look for IPT UShare Macintosh files +.TP +.B \-\-exchange +Look for PC Exchange Macintosh files +.TP +.B \-\-sgi +Look for SGI Macintosh files +.TP +.B \-\-xinet +Look for XINET Macintosh files +.TP +.B \-\-macbin +Look for MacBinary Macintosh files +.TP +.B \-\-single +Look for AppleSingle Macintosh files +.TP +.B \-\-dave +Look for Thursby Software Systems DAVE Macintosh files +.TP +.B \-\-sfm +Look for Microsoft's Services for Macintosh files (NT only) (Alpha) +.TP +.B \-\-osx\-double +Look for Mac OS X AppleDouble Macintosh files +.TP +.B \-\-osx\-hfs +Look for Mac OS X HFS Macintosh files +.\" ---------------------------------------- +.SH "CHARACTER SETS" +.B genisoimage +processes filenames in a POSIX-compliant way as strings of 8-bit characters. +To represent all codings for all languages, 8-bit characters are not +sufficient. Unicode or ISO-10646 +define character codings that need at least 21 bits to represent all +known languages. They may be represented with +.IR UTF-32 ", " UTF-16 " or " UTF-8 +coding. UTF-32 uses a plain 32-bit coding but seems to be uncommon. +UTF-16 is used by Microsoft with Win32 with the disadvantage that +16-bit characters are not compliant with the POSIX filesystem +interface. +.PP +Modern Unix operating systems may use UTF-8 coding for filenames. +Each 32-bit character is represented by one or more 8-bit characters. +If a character is coded in +.I ISO-8859-1 +(used in Central Europe and North America) is maps 1:1 to a +UTF-32 or UTF-16 coded Unicode character. +If a character is coded in +.I 7-Bit ASCII +(used in USA and other countries with limited character set) +is maps 1:1 to a UTF-32, UTF-16 or UTF-8 coded Unicode character. +Character codes that cannot be represented as a single byte in UTF-8 +(if the value is > 0x7F) use escape sequences that map to more than +one 8-bit character. +.PP +If all operating systems used UTF-8, +.B genisoimage +would not need to recode characters in filenames. +Unfortunately, Apple uses completely nonstandard codings and Microsoft +uses a Unicode coding that is not compatible with the POSIX filename +interface. +.PP +For all non-UTF-8-coded operating systems, the actual character +that each byte represents depends on the +.I character set +or +.I codepage +(the name used by Microsoft) +used by the local operating system \(em the characters in a character +set will reflect the region or natural language set by the user. +.PP +Usually character codes 0x00-0x1f are control characters, codes 0x20-0x7f +are the 7-bit ASCII characters and (on PCs and Macs) 0x80-0xff are used +for other characters. +.PP +As there are a lot more than 256 characters/symbols in use, only a small +subset are represented in a character set. Therefore the same character code +may represent a different character in different character sets. So a filename +generated, say in central Europe, may not display the same character +when viewed on a machine in, say eastern Europe. +.PP +To make matters more complicated, different operating systems use +different character sets for the region or language. For example, the +character code for `\('e' (small e with acute accent) +may be character code 0x82 on a PC, +code 0x8e on a Macintosh, code 0xe9 on a Unix system in western Europe, +and code 0x000e9 in Unicode. +.PP +As long as not all operating systems and applications use the same +character set as the basis for filenames, it may be +necessary to specify which character set your filenames use in and which +character set the filenames should appear on the CD. +.PP +There are four options to specify the character sets you want to use: +.TP +.B \-input\-charset +Defines the local character set you are using on your host machine. +Any character set conversions that take place will use this character +set as the starting point. The default input character sets are +.I cp437 +on MS-DOS-based systems and +.I iso8859-1 +on all other systems. If +.B \-J +is given, the Unicode equivalents of the input character set +will be used in the Joliet directory. +.B \-jcharset +is the same as +.BR "\-input\-charset \-J" . +.TP +.B \-output\-charset +Defines the character set that will be used with for the Rock Ridge names +on the CD. Defaults to the input character set. +.TP +.B \-input\-hfs\-charset +Defines the HFS character set used for HFS filenames decoded from +any of the various Apple/Unix file formats. Only useful when used with +.BR \-mac\-name . +See the +.B HFS MACINTOSH FILENAMES +for more information. Defaults to +.I cp10000 +(Mac Roman). +.TP +.B \-output\-hfs\-charset +Defines the HFS character set used to create HFS filenames from the input +character set in use. In most cases this will be from the character set +given with +.BR \-input\-charset . +Defaults to the input HFS character set. +.PP +There are a number of character sets built in to +.BR genisoimage . +To get a listing, use +.BR "\-input\-charset help" . +This list doesn't include the charset derived from the current locale, +if +.B genisoimage +is built with +.I iconv +support. +.PP +Additional character sets can be read from file for any of the character +set options by giving a filename as the argument to the options. The given +file will only be read if its name does not match one of the built-in +character sets. +.PP +The format of the character set files is the same as the mapping files +available from +.IR http://www.unicode.org/Public/MAPPINGS . +This format is: +.IP +Column #1 is the input byte code (in hex as 0xXX) +.br +Column #2 is the Unicode (in hex as 0xXXXX) +.br +The rest of the line is ignored. +.PP +Any blank line, line without two (or more) columns in the above format +or comments lines (starting with the # character) are ignored without any +warnings. Any missing input code is mapped to Unicode character 0x0000. +.PP +Note that, while UTF-8 is supported, other Unicode encodings such as +UCS-2/UTF-16 and UCS-4/UTF-32 are not, as POSIX operating systems +cannot handle them natively. +.PP +A 1:1 character set mapping can be defined by using the keyword +.I default +as the argument to any of the character set options. This is the behaviour +of old versions of +.BR mkisofs . +.PP +The ISO9660 filenames generated from the input filenames are not converted +from the input character set. The ISO9660 character set is a very limited +subset of the ASCII characters, so any conversion would be pointless. +.PP +Any character that +.B genisoimage +cannot convert will be replaced with a `_' character. +.\" ---------------------------------------- +.SH "HFS CREATOR/TYPE" +A Macintosh file has two properties associated with it which define +which application created the file, the +.I CREATOR +and what data the file contains, the +.IR TYPE . +Both are (exactly) 4 letter strings. Usually this +allows a Macintosh user to double-click on a file and launch the correct +application etc. The CREATOR and TYPE of a particular file can be found by +using something like ResEdit (or similar) on a Macintosh. +.PP +The CREATOR and TYPE information is stored in all the various Apple/Unix +encoded files. +For other files it is possible to base the CREATOR and TYPE on the +filename's extension using a +.I mapping +file (with +.BR \-map ) +and/or using the +.I magic number +(usually a +.I signature +in the first few bytes) of a file (with +.BR \-magic ). +If both these options are given, their order on the command +line is significant. If +.B \-map +is given first, a filename extension match is attempted +before a magic number match. However, if +.B \-magic +is given first, a magic number match is attempted before a +filename extension match. +.PP +If a mapping or magic file is not used, or no match is found, the default +CREATOR and TYPE for all regular files can be set by using entries in the +.I .genisoimagerc +file or using +.B \-hfs\-creator +and/or +.BR \-hfs\-type , +otherwise the default CREATOR and TYPE are +.IR Unix " and " TEXT . +.PP +The format of the +.I mapping +file is the same +.I afpfile +format as used by +.BR aufs . +This file has five columns for the +.IR extension , +.IR "file translation" , +.IR CREATOR , +.IR TYPE " and" +.IR Comment . +Lines starting with the `#' character are +comment lines and are ignored. An example file would be like: +.PP +.TS +tab (/); +l s s s s +l s s s s +l l l l l . +# Example filename mapping file +# +# EXTN/XLate/CREATOR/TYPE/Comment +\&.tif/Raw/\(aq8BIM\(aq/\(aqTIFF\(aq/\(dqPhotoshop TIFF image\(dq +\&.hqx/Ascii/\(aqBnHq\(aq/\(aqTEXT\(aq/\(dqBinHex file\(dq +\&.doc/Raw/\(aqMSWD\(aq/\(aqWDBN\(aq/\(dqWord file\(dq +\&.mov/Raw/\(aqTVOD\(aq/\(aqMooV\(aq/\(dqQuickTime Movie\(dq +*/Ascii/\(aqttxt\(aq/\(aqTEXT\(aq/\(dqText file\(dq +.TE +.PP +Where: +.IP +The first column +.I EXTN +defines the Unix filename extension to be +mapped. The default mapping for any filename extension that doesn't +match is defined with the `*' character. +.IP +The +.I Xlate +column defines the type of text translation between the Unix and +Macintosh file it is ignored by +.BR genisoimage , +but is kept to be compatible with +.BR aufs (1). +Although +.B genisoimage +does not alter the contents of a file, if a binary file has its TYPE +set as +.IR TEXT ", it " may +be read incorrectly on a Macintosh. Therefore a better choice for the +default TYPE may be +.IR ???? . +.IP +The +.I CREATOR +and +.I TYPE +keywords must be 4 characters long and enclosed in single quotes. +.IP +The comment field is enclosed in double quotes \(em it is ignored by +.BR genisoimage , +but is kept to be compatible with +.BR aufs . +.PP +The format of the +.I magic +file is almost identical to the +.BR magic (5) +file used by the +.BR file (1) +command. +.PP +This file has four tab-separated columns for the +.IR "byte offset" , +.IR type , +.I test +and +.IR message . +Lines starting with the `#' character are +comment lines and are ignored. An example file would be like: +.PP +.TS +tab (/); +l s s s +l s s s +l l l l . +# Example magic file +# +# off/type/test/message +0/string/GIF8/8BIM GIFf GIF image +0/beshort/0xffd8/8BIM JPEG image data +0/string/SIT!/SIT! SIT! StuffIt Archive +0/string/\(rs037\(rs235/LZIV ZIVU standard Unix compress +0/string/\(rs037\(rs213/GNUz ZIVU gzip compressed data +0/string/%!/ASPS TEXT Postscript +0/string/\(rs004%!/ASPS TEXT PC Postscript with a ^D to start +4/string/moov/txtt MooV QuickTime movie file (moov) +4/string/mdat/txtt MooV QuickTime movie file (mdat) +.TE +.PP +The format of the file is described in +.BR magic (5). +The only difference here is that for each entry in the magic file, the +.I message +for the initial offset must be be 4 characters for the CREATOR followed +by 4 characters for the TYPE \(em white space is +optional between them. Any other characters on this line are ignored. +Continuation lines (starting with a `>') are also ignored, i.e., only +the initial offset lines are used. +.PP +Using +.B \-magic +may significantly increase processing time as each file has to opened +and read to find its magic number. +.PP +In summary, for all files, the default CREATOR is +.I Unix +and the default TYPE is +.IR TEXT . +These can be changed by using entries in the +.I .genisoimagerc +file or by using +.B \-hfs\-creator +and/or +.BR \-hfs\-type . +.PP +If the a file is in one of the known Apple/Unix formats (and the format +has been selected), the CREATOR and TYPE are taken from the values +stored in the Apple/Unix file. +.PP +Other files can have their CREATOR and TYPE set from their filename +extension (with +.BR \-map ), +or their magic number (with +.BR \-magic ). +If the default match is used in the +.I mapping +file, these values override the default CREATOR and TYPE. +.PP +A full CREATOR/TYPE database can be found at +.IR http://www.angelfire.com/il/szekely/ . +.\" ---------------------------------------- +.SH "HFS MACINTOSH FILE FORMATS" +Macintosh files have two parts called the +.I Data +and +.IR "Resource fork" . +Either may be empty. Unix (and many other OSs) can only +cope with files having one part (or fork). To add to this, Macintosh files +have a number of attributes associated with them \(em probably the most +important are the TYPE and CREATOR. Again, Unix has no concept of these +types of attributes. +.PP +E.g., a Macintosh file may be a JPEG image where the image is stored in the +Data fork and a desktop thumbnail stored in the Resource fork. It is usually +the information in the data fork that is useful across platforms. +.PP +Therefore to store a Macintosh file on a Unix filesystem, a way has to be +found to cope with the two forks and the extra attributes (which are +referred to as the +.IR "Finder info" ). +Unfortunately, it seems that every software package that stores Macintosh +files on Unix has chosen a completely different storage method. +.PP +The Apple/Unix formats that +.B genisoimage +(partially) supports are: +.IP "CAP AUFS format" +Data fork stored in a file. Resource fork in subdirectory +.I .resource +with same filename as data fork. Finder info in subdirectory +.I .finderinfo +with same filename. +.IP "AppleDouble/Netatalk" +Data fork stored in a file. Resource fork stored in a file with +same name prefixed with `%'. Finder info also stored in same +`%' file. Netatalk uses the same format, but the resource +fork/Finder info stored in subdirectory +.I .AppleDouble +with same filename as data fork. +.IP AppleSingle +Data structures similar to above, except both forks and Finder +info are stored in one file. +.IP "Helios EtherShare" +Data fork stored in a file. Resource fork and Finder info together in +subdirectory +.I .rsrc +with same filename as data fork. +.IP "IPT UShare" +Like the EtherShare format, but the Finder info +is stored slightly differently. +.IP MacBinary +Both forks and Finder info stored in one file. +.IP "Apple PC Exchange" +Used by Macintoshes to store Apple files on DOS (FAT) disks. +Data fork stored in a file. Resource fork in subdirectory +.IR resource.frk " (or " RESOURCE.FRK ). +Finder info as one record in file +.IR finder.dat " (or " FINDER.DAT ). +Separate +.I finder.dat +for each data fork directory. +.IP +Note: +.B genisoimage +needs to know the native FAT cluster size of the disk that the PC Exchange +files are on (or have been copied from). This size is given by +.BR \-cluster\-size . +The cluster or allocation size can be found by using the DOS utility +.BR chkdsk . +.IP +May not work with PC Exchange v2.2 or higher files (available with MacOS 8.1). +DOS media containing PC Exchange files should be mounted as type +.I msdos +(not +.IR vfat ) +when using Linux. +.IP SGI/XINET +Used by SGI machines when they mount HFS disks. Data fork stored +in a file. Resource fork in subdirectory +.I .HSResource +with same filename. Finder info as one record in file +.IR .HSancillary ". Separate " .HSancillary +for each data fork directory. +.IP "Thursby Software Systems DAVE" +Allows Macintoshes to store Apple files on SMB servers. +Data fork stored in a file. Resource fork in subdirectory +.IR resource.frk . +Uses the AppleDouble format to store resource fork. +.IP "Services for Macintosh" +Format of files stored by NT Servers on NTFS filesystems. Data fork is +stored as +.IR filename . +Resource fork stored as a NTFS stream called +.IR filename:AFP_Resource . +The Finder info is stored as a NTFS stream called +.IR filename:Afp_AfpInfo . +NTFS streams are normally invisible to the user. +.IP +Warning: +.B genisoimage +only partially supports the SFM format. If an HFS file +or folder stored on the NT server contains an illegal +NT character in its name, NT converts these characters to +.I Private Use Unicode +characters. The characters are: \(dq * / < > ? \(rs | and a space or +period if it is the last character of the filename, character codes 0x01 +to 0x1f (control characters) and Apple's apple logo. +.IP +Unfortunately, these private Unicode characters are not readable by the +.B genisoimage +NT executable. Therefore any file or directory +name containing these characters will be ignored \(em including the contents of +any such directory. +.IP "Mac OS X AppleDouble" +When HFS/HFS+ files are copied or saved by Mac OS X on to a non-HFS +filesystem (e.g. UFS, NFS etc.), the files are stored in AppleDouble format. +Data fork stored in a file. Resource fork stored in a file with +same name prefixed with `._'. Finder info also stored in same `._' file. +.IP "Mac OS X HFS (Alpha)" +Not really an Apple/Unix encoding, but actual HFS/HFS+ files on a Mac\ OS\ X +system. Data fork stored in a file. Resource fork stored in a pseudo file +with the same name with the suffix +.IR /rsrc . +The Finder info is only available via a Mac OS X library call. +.IP +See also +.IR README.macosx . +.IP +Only works when used on Mac OS X. +.IP +If a file is found with a zero +length resource fork and empty finderinfo, it is assumed not to have +any Apple/Unix encoding \(em therefore a TYPE and CREATOR can be set using +other methods. +.PP +.B genisoimage +will attempt to set the CREATOR, TYPE, date and possibly other flags from +the finder info. Additionally, if it exists, the Macintosh filename is set +from the finder info, otherwise the Macintosh name is based on the Unix +filename \(em see the +.B HFS MACINTOSH FILENAMES +section below. +.PP +When using +.BR \-apple , +the TYPE and CREATOR are stored in the optional System Use or +.I SUSP +field +in the ISO9660 Directory Record \(em in much the same way as the Rock Ridge +attributes are. In fact to make life easy, the Apple extensions are added +at the beginning of the existing Rock Ridge attributes (i.e., to get the Apple +extensions you get the Rock Ridge extensions as well). +.PP +The Apple extensions require the resource fork to be stored as an ISO9660 +.I associated +file. This is just like any normal file stored in the ISO9660 filesystem +except that the associated file flag is set in the Directory Record (bit +2). This file has the same name as the data fork (the file seen by +non-Apple machines). Associated files are normally ignored by other OSs +.PP +When using +.BR \-hfs , +the TYPE and CREATOR plus other finder info, are stored in a separate +HFS directory, not visible on the ISO9660 volume. The HFS directory references +the same data and resource fork files described above. +.PP +In most cases, it is better to use +.B \-hfs +instead of +.BR \-apple , +as the latter imposes the limited ISO9660 characters allowed in +filenames. However, the Apple extensions do give the advantage that the +files are packed on the disk more efficiently and it may be possible to fit +more files on a CD. +.\" ---------------------------------------- +.SH "HFS MACINTOSH FILENAMES" +Where possible, the HFS filename that is stored with an Apple/Unix file +is used for the HFS part of the CD. However, not all the Apple/Unix +encodings store the HFS filename with the finderinfo. In these cases, +the Unix filename is used \(em with escaped special characters. Special +characters include `/' and characters with codes over 127. +.PP +AUFS escapes these characters by using `:' followed by the character code +as two hex digits. Netatalk and EtherShare have a similar scheme, but uses +`%' instead of a `:'. +.PP +If +.B genisoimage +cannot find an HFS filename, it uses the Unix name, with any +.IR %xx " or " :xx +characters +.RI ( xx +are two hex digits) converted to a single character code. If +.I xx +are not hex digits ([0-9a-fA-F]), they are +left alone \(em although any remaining `:' is converted to `%', as `:' +is the HFS directory separator. Care must be taken, as an ordinary Unix +file with +.I %xx +or +.I :xx +will also be converted. e.g. +.PP +.TS +l l +l s +l l +l s +l l . +This:2fFile converted to This/File + +This:File converted to This%File + +This:t7File converted to This%t7File +.TE +.PP +Although HFS filenames appear to support uppercase and lowercase letters, +the filesystem is case-insensitive, i.e., the filenames +.IR aBc " and " AbC +are the same. If a file is found in a directory with the same HFS name, +.B genisoimage +will attempt to make a unique name by adding `_' characters +to one of the filenames. +.PP +If an HFS filename exists for a file, +.B genisoimage +can use this name as the starting point for the ISO9660, Joliet and +Rock Ridge filenames using +.BR \-mac\-name . +Normal Unix files without an HFS name will still use their Unix name. +e.g. +.PP +If a MacBinary (or PC Exchange) file is stored as +.I someimage.gif.bin +on the Unix filesystem, but contains a HFS file called +.IR someimage.gif , +this is the name that would appear on the HFS part of the CD. However, as +.B genisoimage +uses the Unix name as the starting point for the other names, +the ISO9660 name generated will probably be +.I SOMEIMAG.BIN +and the Joliet/Rock Ridge would be +.IR someimage.gif.bin . +This option will use +the HFS filename as the starting point and the ISO9660 name will probably be +.I SOMEIMAG.GIF +and the Joliet/Rock Ridge would be +.IR someimage.gif . +.PP +.B \-mac\-name +will not currently work with +.B \-T +\(em the Unix name will be used in the +.I TRANS.TBL +file, not the Macintosh name. +.PP +The character set used to convert any HFS filename to a Joliet/Rock Ridge +filename defaults to +.I cp10000 +(Mac Roman). +The character set used can be specified using +.BR \-input\-hfs\-charset . +Other built-in HFS character sets are: +.I cp10006 +(MacGreek), +.I cp10007 +(MacCyrillic), +.I cp10029 +(MacLatin2), +.I cp10079 +(MacIcelandandic) and +.I cp10081 +(MacTurkish). +.PP +Note: the character codes used by HFS filenames taken from the various +Apple/Unix formats will not be converted as they are assumed to be in the +correct Apple character set. Only the Joliet/Rock Ridge names derived from +the HFS filenames will be converted. +.PP +The existing +.B genisoimage +code will filter out any illegal characters for the ISO9660 and Joliet +filenames, but as +.B genisoimage +expects to be dealing directly with Unix names, it leaves the Rock +Ridge names as is. But as `/' is a legal HFS filename character, +.B \-mac\-name +converts `/' to a `_' in Rock Ridge filenames. +.PP +If the Apple extensions are used, only the ISO9660 filenames will +appear on the Macintosh. However, as the Macintosh ISO9660 drivers can use +.I Level 2 +filenames, you can use options like +.B \-allow\-multidot +without problems on +a Macintosh \(em still take care over the names, for example +.I this.file.name +will be converted to +.I THIS.FILE +i.e. only have one `.', also filename +.I abcdefgh +will be seen as +.I ABCDEFGH +but +.I abcdefghi +will be seen as +.I ABCDEFGHI. +i.e. with a `.' at the end \(em don't know if this is a Macintosh +problem or a +.BR genisoimage / mkhybrid +problem. All filenames will be in uppercase +when viewed on a Macintosh. Of course, DOS/Win3.X machines will not be able +to see Level 2 filenames... +.\" ---------------------------------------- +.SH "HFS CUSTOM VOLUME/FOLDER ICONS" +To give a HFS CD a custom icon, make sure the root (top level) folder includes +a standard Macintosh volume icon file. To give a volume a custom icon on +a Macintosh, an icon has to be pasted over the volume's icon in the "Get Info" +box of the volume. This creates an invisible file called +.I Icon\(rsr +(`\(rsr' is the carriage return character) in the root folder. +.P +A custom folder icon is very similar \(em an invisible file called +.I Icon\(rsr +exists in the folder itself. +.P +Probably the easiest way to create a custom icon that +.B genisoimage +can use is to format a blank HFS floppy disk on a Mac and paste an icon +to its "Get Info" box. If using Linux with the HFS module installed, +mount the floppy: +.IP +mount \-t hfs /dev/fd0 /mnt/floppy +.PP +The floppy will be mounted as a CAP filesystem by default. Then run +.B genisoimage +using something like: +.IP +genisoimage \-\-cap \-o output source_dir /mnt/floppy +.PP +If you are not using Linux, you can use +.B hfsutils +to copy the icon file from the floppy. However, care has to be taken, +as the icon file contains a control character. For example: +.IP +hmount /dev/fd0 +.br +hdir \-a +.br +hcopy \-m Icon^V^M icon_dir/icon +.PP +Where `^V^M' is control-V followed by control-M. Then run +.B genisoimage +by using something like: +.IP +genisoimage \-\-macbin \-o output source_dir icon_dir +.PP +The procedure for creating/using custom folder icons is very similar \(em paste +an icon to folder's "Get Info" box and transfer the resulting +.I Icon\(rsr +file to the relevant directory in the +.B genisoimage +source tree. +.PP +You may want to hide the icon files from the ISO9660 and Joliet trees. +.PP +To give a custom icon to a Joliet CD, follow the instructions found at +.IR http://www.cdrfaq.org/faq03.html#S3-21-1 . +.\" ---------------------------------------- +.SH "HFS BOOT DRIVER" +It +.I may +be possible to make the hybrid CD bootable on a Macintosh. +.PP +A bootable HFS CD requires an Apple CD-ROM (or compatible) driver, a bootable +HFS partition and the necessary System, Finder, etc. files. +.PP +A driver can be obtained from any other Macintosh bootable CD-ROM using the +.B apple_driver +utility. This file can then be used with +.BR \-boot\-hfs\-file . +.PP +The HFS partition (i.e. the hybrid disk in our case) must contain a +suitable System Folder, again from another CD-ROM or disk. +.PP +For a partition to be bootable, it must have its +.I boot block +set. The boot +block is in the first two blocks of a partition. For a non-bootable partition +the boot block is full of zeros. Normally, when a System file is copied to +partition on a Macintosh disk, the boot block is filled with a number of +required settings \(em unfortunately I don't know the full spec for the boot +block, so I'm guessing that the following will work. +.PP +Therefore, the utility +.B apple_driver +also extracts the boot block from the +first HFS partition it finds on the given CD-ROM and this is used for the +HFS partition created by +.BR genisoimage . +.PP +.I Please note: +By using a driver from an Apple CD and copying Apple software to your CD, +you become liable to obey Apple Computer, Inc. Software License Agreements. +.\" ---------------------------------------- +.SH "EL TORITO BOOT INFORMATION TABLE" +When +.B \-boot\-info\-table +is given, +.B genisoimage +will modify the boot file specified by +.B \-b +by inserting a 56-byte +.I boot information table +at offset 8 in +the file. This modification is done in the source filesystem, so make +sure you use a copy if this file is not easily recreated! This file +contains pointers which may not be easily or reliably obtained at boot +time. +.PP +The format of this table is as follows; all integers are in +section 7.3.1 ("little endian") format. +.sp +.RS +.2i +.ta 1.0i 2.5i 3.5i +.nf +Offset Name Size Meaning + 8 bi_pvd 4 bytes LBA of primary volume descriptor +12 bi_file 4 bytes LBA of boot file +16 bi_length 4 bytes Boot file length in bytes +20 bi_csum 4 bytes 32-bit checksum +24 bi_reserved 40 bytes Reserved +.fi +.RE +.IP +The 32-bit checksum is the sum of all the 32-bit words in the boot +file starting at byte offset 64. All linear block addresses (LBAs) +are given in CD sectors (normally 2048 bytes). +.\" ---------------------------------------- +.SH "HPPA NOTES" +To make a bootable CD for HPPA, at the very least a boot loader file +.RB ( \-hppa\-bootloader ), +a kernel image file (32-bit, 64-bit, or both, depending on hardware) +and a boot command line +.RB ( \-hppa\-cmdline ) +must be specified. Some systems can boot either a 32- or a 64-bit +kernel, and the firmware will choose one if both are present. +Optionally, a ramdisk can be used for the root filesystem using +.BR \-hppa\-cmdline . +.\" ---------------------------------------- +.SH "JIGDO NOTES" +Jigdo is a tool to help in the distribution of large files like CD and +DVD images; see +.I http://atterer.org/jigdo/ +for more details. Debian CDs and DVD ISO +images are published on the web in jigdo format to allow end users to download +them more efficiently. +.PP +To create jigdo and template files alongside the ISO image from +.BR genisoimage , +you must first generate a list of the files that will be +used, in the following format: +.sp +.RS +.2i +.ta 2.0i 2.0i 5.0i +.nf +MD5sum File size Path +32 chars 12 chars to end of line +.fi +.RE +.IP +.PP +The MD5sum must be written in standard hexadecimal notation, the +file size must list the size of the file in bytes, and the path +must list the absolute path to the file. For example: +.sp +.nf +00006dcd58ff0756c36d2efae21be376 14736 /mirror/debian/file1 +000635c69b254a1be8badcec3a8d05c1 211822 /mirror/debian/file2 +00083436a3899a09633fc1026ef1e66e 22762 /mirror/debian/file3 +.fi +.PP +Once you have this file, call +.B genisoimage +with all of your normal command-line parameters. Specify the output +filenames for the jigdo and template files using +.BR \-jigdo\-jigdo " and " \-jigdo\-template , +and pass in the location of your MD5 list with +.BR \-md5\-list . +.PP +If there are files that you do NOT want to be added into the jigdo +file (e.g. if they are likely to change often), specify them using +\-jigdo\-exclude. If you want to verify some of the files as they are +written into the image, specify them using \-jigdo\-force\-md5. If any +files don't match, +.B genisoimage +will then abort. Both of these options take +regular expressions as input. It is possible to restrict the set of +files that will be used further based on size \(em use the +\-jigdo\-min\-file\-size option. +.PP +Finally, the jigdo code needs to know how to map the files it is given +onto a mirror-style configuration. Specify how to map paths using +.BR \-jigdo\-map . +Using +.I Debian=/mirror/debian +will cause all +paths starting with +.I /mirror/debian +to be mapped to +.I Debian: +in the output jigdo file. +.\" ---------------------------------------- +.SH EXAMPLES +.PP +To create a vanilla ISO9660 filesystem image in the file +.IR cd.iso , +where the directory +.I cd_dir +will become the root directory of the CD, call: +.IP +% genisoimage \-o cd.iso cd_dir +.PP +To create a CD with Rock Ridge extensions of +the source directory +.IR cd_dir : +.IP +% genisoimage \-o cd.iso \-R cd_dir +.PP +To create a CD with Rock Ridge extensions of +the source directory +.I cd_dir +where all files have at least read permission and all files +are owned by +.IR root , +call: +.IP +% genisoimage \-o cd.iso \-r cd_dir +.PP +To write a tar archive directly to a CD that will later contain a simple +ISO9660 filesystem with the tar archive call: +.IP +% tar cf \- . | genisoimage \-stream\-media\-size 333000 | \(rs +.br + wodim dev=b,t,l \-dao tsize=333000s \- +.PP +To create a HFS hybrid CD with the Joliet and Rock Ridge extensions of +the source directory +.IR cd_dir : +.IP +% genisoimage \-o cd.iso \-R \-J \-hfs cd_dir +.PP +To create a HFS hybrid CD from the source directory +.I cd_dir +that contains +Netatalk Apple/Unix files: +.IP +% genisoimage \-o cd.iso \-\-netatalk cd_dir +.PP +To create a HFS hybrid CD from the source directory +.IR cd_dir , +giving all files +CREATOR and TYPES based on just their filename extensions listed in the file +"mapping".: +.IP +% genisoimage \-o cd.iso \-map mapping cd_dir +.PP +To create a CD with the Apple Extensions to ISO9660, from the source +directories +.I cd_dir +and +.IR another_dir . +Files in all the known Apple/Unix format +are decoded and any other files are given CREATOR and TYPE based on their +magic number given in the file +.IR magic : +.IP +% genisoimage \-o cd.iso \-apple \-magic magic \-probe \(rs +.br + cd_dir another_dir +.PP +The following example puts different files on the CD that all have +the name README, but have different contents when seen as a +ISO9660/Rock Ridge, Joliet or HFS CD. +.PP +Current directory contains: +.IP +% ls \-F +.br +README.hfs README.joliet README.Unix cd_dir/ +.PP +The following command puts the contents of the directory +.I cd_dir +on the +CD along with the three README files \(em but only one will be seen from +each of the three filesystems: +.IP +% genisoimage \-o cd.iso \-hfs \-J \-r \-graft\-points \(rs +.br + \-hide README.hfs \-hide README.joliet \(rs +.br + \-hide\-joliet README.hfs \-hide\-joliet README.Unix \(rs +.br + \-hide\-hfs README.joliet \-hide\-hfs README.Unix \(rs +.br + README=README.hfs README=README.joliet \(rs +.br + README=README.Unix cd_dir +.PP +i.e. the file README.hfs will be seen as README on the HFS CD and the +other two README files will be hidden. Similarly for the Joliet and +ISO9660/Rock Ridge CD. +.PP +There are probably all sorts of strange results possible with +combinations of the hide options ... +.\" ---------------------------------------- +.SH NOTES +.PP +.B genisoimage +may safely be installed suid root. This may be needed to allow +.B genisoimage +to read the previous session when creating a multisession image. +.PP +If +.B genisoimage +is creating a filesystem image with Rock Ridge attributes and the +directory nesting level of the source directory tree is too much +for ISO9660, +.B genisoimage +will do deep directory relocation. +This results in a directory called +.B RR_MOVED +in the root directory of the CD. You cannot avoid this directory. +.PP +Many boot code options for different platforms are mutualy exclusive because +the boot blocks cannot coexist, ie. different platforms share the same data +locations in the image. See +http://lists.debian.org/debian-cd/2006/12/msg00109.html for details. +.\" ---------------------------------------- +.SH BUGS +.PP +Any files that have hard links to files not in the tree being copied to the +ISO9660 filesystem will have an incorrect file reference count. +.PP +Does not check for SUSP record(s) in `.' entry of the +root directory to verify the existence of Rock Ridge +enhancements. +This problem is present when reading old sessions while +adding data in multisession mode. +.PP +Does not properly read relocated directories in multisession +mode when adding data. +Any relocated deep directory is lost if the new session does not +include the deep directory. +.\" Repeat by: create first session with deep directory relocation +.\" then add new session with a single dir that differs from the +.\" old deep path. +.PP +Does not re-use +.I RR_MOVED +when doing multisession from +.IR TRANS.TBL . +.PP +Does not create whole_name entry for +.I RR_MOVED +in multisession mode. +.PP +There may be other bugs. Please, report them to the maintainers. +.\" ---------------------------------------- +.SH "HFS PROBLEMS/LIMITATIONS" +I have had to make several assumptions on how I expect the modified +libhfs routines to work, however there may be situations that either +I haven't thought of, or come across when these assumptions fail. +Therefore I can't guarantee that +.B genisoimage +will work as expected +(although I haven't had a major problem yet). Most of the HFS features work +fine, but some are not fully tested. These are marked as +.I Alpha +above. +.PP +Although HFS filenames appear to support uppercase and lowercase letters, +the filesystem is case-insensitive, i.e., the filenames +.IR aBc " and "AbC +are the same. If a file is found in a directory with the same HFS name, +.B genisoimage +will attempt to make a unique name by adding `_' characters +to one of the filenames. +.PP +HFS file/directory names that share the first 31 characters have +`_N' (a decimal number) substituted for the last few characters +to generate unique names. +.PP +Care must be taken when "grafting" Apple/Unix files or directories (see +above for the method and syntax involved). It is not possible to use a +new name for an Apple/Unix encoded file/directory. e.g. If a Apple/Unix +encoded file called +.I oldname +is to added to the CD, you cannot use the command line: +.IP +genisoimage \-o output.raw \-hfs \-graft\-points newname=oldname cd_dir +.PP +.B genisoimage +will be unable to decode +.IR oldname . +However, you can graft +Apple/Unix encoded files or directories as long as you do not attempt to +give them new names as above. +.PP +When creating an HFS volume with the multisession options, +.B \-M +and +.BR \-C , +only files in the last session will be in the HFS volume. i.e. +.B genisoimage +cannot +.I add +existing files from previous sessions to the HFS volume. +.PP +However, if each session is created with +.BR \-part , +each session will appear as +separate volumes when mounted on a Mac. In this case, it is worth using +.BR \-V " or " \-hfs\-volid +to give each session a unique volume name, +otherwise each "volume" will appear on the Desktop with the same name. +.PP +Symbolic links (as with all other non-regular files) are not added to +the HFS directory. +.PP +Hybrid volumes may be larger than pure ISO9660 volumes +containing the same data. In some cases (e.g. DVD sized volumes) the +difference can be significant. As an HFS volume gets bigger, so does the +allocation block size (the smallest amount of space a file can occupy). +For a 650MB CD, the allocation block is 10kB, for a 4.7GB DVD it will be +about 70kB. +.PP +The maximum number of files in an HFS volume is about 65500 \(em although +the real limit will be somewhat less than this. +.PP +The resulting hybrid volume can be accessed on a Unix machine by using +the hfsutils routines. However, no changes can be made to the volume as it +is set as +.B locked. +The option +.B \-hfs\-unlock +will create an output image that is unlocked \(em however no changes should be +made to the contents of the volume (unless you really know what you are +doing) as it's not a "real" HFS volume. +.PP +.B \-mac\-name +will not currently work with +.B \-T +\(em the Unix name will be used in the +.I TRANS.TBL +file, not the Macintosh name. +.PP +Although +.B genisoimage +does not alter the contents of a file, if a binary file has its TYPE +set as +.IR TEXT ", it " may +be read incorrectly on a Macintosh. Therefore a better choice for the +default TYPE may be +.IR ???? . +.PP +.B \-mac\-boot\-file +may not work at all... +.PP +May not work with PC Exchange v2.2 or higher files (available with MacOS 8.1). +DOS media containing PC Exchange files should be mounted as type +.B msdos +(not +.BR vfat ) +when using Linux. +.PP +The SFM format is only partially supported \(em see +.B HFS MACINTOSH FILE FORMATS +section above. +.PP +It is not possible to use +.BR \-sparc\-boot " or " \-generic\-boot " with" +.BR \-boot\-hfs\-file " or " \-prep\-boot . +.PP +.B genisoimage +should be able to create HFS hybrid images over 4Gb, although this has not +been fully tested. +.\" ---------------------------------------- +.SH "SEE ALSO" +.BR genisoimagerc (5), +.BR wodim (1), +.BR mkzftree (8), +.BR magic (5). +.\" ---------------------------------------- +.SH AUTHORS +.B genisoimage +is derived from +.B mkisofs +from the +.B cdrtools 2.01.01a08 +package from May 2006 (with few updates extracted from cdrtools 2.01.01a24 from +March 2007) from .IR http://cdrecord.berlios.de/ , +but is now part of the +.B cdrkit +suite, maintained by Joerg Jaspert, Eduard Bloch, Steve McIntyre, Peter +Samuelson, Christian Fromme, Ben Hutchings, and other contributors. +The maintainers can be contacted at +.IR debburn-devel@lists.alioth.debian.org , +or see the +.B cdrkit +project web site at +.IR http://www.cdrkit.org/ . +.PP +Eric Youngdale wrote the first versions (1993\(en1998) of +.BR mkisofs . +J\(:org Schilling wrote the SCSI transport library and its +interface, and has maintained +.B mkisofs +since 1999. James Pearson wrote the HFS hybrid code, using +.I libhfs +by Robert Leslie. Pearson, Schilling, Jungshik Shin and Jaakko +Heinonen contributed to the character set conversion code. The +.B cdrkit +maintainers have maintained +.B genisoimage +since 2006. +.PP +.nf +Copyright 1993-1998 by Yggdrasil Computing, Inc. +Copyright 1996-1997 by Robert Leslie +Copyright 1997-2001 by James Pearson +Copyright 1999-2006 by J\(:org Schilling +Copyright 2007 by J\(:org Schilling (originating few updates) +Copyright 2002-2003 by Jungshik Shin +Copyright 2003 by Jaakko Heinonen +Copyright 2006 by the Cdrkit maintainers +.fi +.PP +If you want to take part in the development of +.BR genisoimage , +you may join the +.B cdrkit +developer mailing list by following the instructions on +.IR http://alioth.debian.org/mail/?group_id=31006 . +The email address of the list is +.IR debburn-devel@lists.alioth.debian.org . +This is also the address for user support questions. Note that +.BR cdrkit " and " cdrtools +are not affiliated. +.PP +.\" ---------------------------------------- +.SH ACKNOWLEDGEMENTS +UNIX is a registered trademark of The Open Group in the US and other countries. diff --git a/upstream/fedora-40/man1/getent.1 b/upstream/fedora-40/man1/getent.1 new file mode 100644 index 00000000..6639bfd8 --- /dev/null +++ b/upstream/fedora-40/man1/getent.1 @@ -0,0 +1,387 @@ +.\" Copyright (c) 2011, Mark R. Bannister +.\" Copyright (c) 2015, Robin H. Johnson +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getent 1 2023-11-01 "Linux man-pages 6.06" +.SH NAME +getent \- get entries from Name Service Switch libraries +.SH SYNOPSIS +.nf +.B getent [\fIoption\fP]... \fIdatabase\fP \fIkey\fP... +.fi +.SH DESCRIPTION +The +.B getent +command displays entries from databases supported by the +Name Service Switch libraries, +which are configured in +.IR /etc/nsswitch.conf . +If one or more +.I key +arguments are provided, +then only the entries that match the supplied keys will be displayed. +Otherwise, if no +.I key +is provided, all entries will be displayed (unless the database does not +support enumeration). +.P +The +.I database +may be any of those supported by the GNU C Library, listed below: +.TP +.B ahosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +This is identical to using +.BR hosts (5). +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaddrinfo (3) +with the address family +.BR AF_UNSPEC , +enumerating each socket address structure returned. +.TP +.B ahostsv4 +Same as +.BR ahosts , +but use the address family +.BR AF_INET . +.TP +.B ahostsv6 +Same as +.BR ahosts , +but use the address family +.BR AF_INET6 . +The call to +.BR getaddrinfo (3) +in this case includes the +.B AI_V4MAPPED +flag. +.TP +.B aliases +When no +.I key +is provided, use +.BR setaliasent (3), +.BR getaliasent (3), +and +.BR endaliasent (3) +to enumerate the aliases database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaliasbyname (3) +and display the result. +.TP +.B ethers +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR ether_aton (3) +and +.BR ether_hostton (3) +until a result is obtained, and display the result. +Enumeration is not supported on +.BR ethers , +so a +.I key +must be provided. +.TP +.B group +When no +.I key +is provided, use +.BR setgrent (3), +.BR getgrent (3), +and +.BR endgrent (3) +to enumerate the group database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getgrgid (3) +and each nonnumeric +.I key +to +.BR getgrnam (3) +and display the result. +.TP +.B gshadow +When no +.I key +is provided, use +.BR setsgent (3), +.BR getsgent (3), +and +.BR endsgent (3) +to enumerate the gshadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getsgnam (3) +and display the result. +.TP +.B hosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +When one or more +.I key +arguments are provided, pass each +.I key +to +.BR gethostbyaddr (3) +or +.BR gethostbyname2 (3), +depending on whether a call to +.BR inet_pton (3) +indicates that the +.I key +is an IPv6 or IPv4 address or not, and display the result. +.TP +.B initgroups +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getgrouplist (3) +and display the result. +Enumeration is not supported on +.BR initgroups , +so a +.I key +must be provided. +.TP +.B netgroup +When one +.I key +is provided, pass the +.I key +to +.BR setnetgrent (3) +and, using +.BR getnetgrent (3) +display the resulting string triple +.RI ( hostname ", " username ", " domainname ). +Alternatively, three +.I keys +may be provided, which are interpreted as the +.IR hostname , +.IR username , +and +.I domainname +to match to a netgroup name via +.BR innetgr (3). +Enumeration is not supported on +.BR netgroup , +so either one or three +.I keys +must be provided. +.TP +.B networks +When no +.I key +is provided, use +.BR setnetent (3), +.BR getnetent (3), +and +.BR endnetent (3) +to enumerate the networks database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getnetbyaddr (3) +and each nonnumeric +.I key +to +.BR getnetbyname (3) +and display the result. +.TP +.B passwd +When no +.I key +is provided, use +.BR setpwent (3), +.BR getpwent (3), +and +.BR endpwent (3) +to enumerate the passwd database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getpwuid (3) +and each nonnumeric +.I key +to +.BR getpwnam (3) +and display the result. +.TP +.B protocols +When no +.I key +is provided, use +.BR setprotoent (3), +.BR getprotoent (3), +and +.BR endprotoent (3) +to enumerate the protocols database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getprotobynumber (3) +and each nonnumeric +.I key +to +.BR getprotobyname (3) +and display the result. +.TP +.B rpc +When no +.I key +is provided, use +.BR setrpcent (3), +.BR getrpcent (3), +and +.BR endrpcent (3) +to enumerate the rpc database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getrpcbynumber (3) +and each nonnumeric +.I key +to +.BR getrpcbyname (3) +and display the result. +.TP +.B services +When no +.I key +is provided, use +.BR setservent (3), +.BR getservent (3), +and +.BR endservent (3) +to enumerate the services database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getservbynumber (3) +and each nonnumeric +.I key +to +.BR getservbyname (3) +and display the result. +.TP +.B shadow +When no +.I key +is provided, use +.BR setspent (3), +.BR getspent (3), +and +.BR endspent (3) +to enumerate the shadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getspnam (3) +and display the result. +.SH OPTIONS +.TP +.BI \-\-service\~ service +.TQ +.BI \-s\~ service +.\" commit 9d0881aa76b399e6a025c5cf44bebe2ae0efa8af (glibc) +Override all databases with the specified service. +(Since glibc 2.2.5.) +.TP +.BI \-\-service\~ database : service +.TQ +.BI \-s\~ database : service +.\" commit b4f6f4be85d32b9c03361c38376e36f08100e3e8 (glibc) +Override only specified databases with the specified service. +The option may be used multiple times, +but only the last service for each database will be used. +(Since glibc 2.4.) +.TP +.B \-\-no\-idn +.TQ +.B \-i +.\" commit a160f8d808cf8020b13bd0ef4a9eaf3c11f964ad (glibc) +Disables IDN encoding in lookups for +.BR ahosts / getaddrinfo (3) +(Since glibc-2.13.) +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR getent . +.SH EXIT STATUS +One of the following exit values can be returned by +.BR getent : +.TP +.B 0 +Command completed successfully. +.TP +.B 1 +Missing arguments, or +.I database +unknown. +.TP +.B 2 +One or more supplied +.I key +could not be found in the +.IR database . +.TP +.B 3 +Enumeration not supported on this +.IR database . +.SH SEE ALSO +.BR nsswitch.conf (5) diff --git a/upstream/fedora-40/man1/gettext.1 b/upstream/fedora-40/man1/gettext.1 new file mode 100644 index 00000000..4d073f37 --- /dev/null +++ b/upstream/fedora-40/man1/gettext.1 @@ -0,0 +1,74 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. +.TH GETTEXT "1" "June 2023" "GNU gettext-runtime 0.22" "User Commands" +.SH NAME +gettext \- translate message +.SH SYNOPSIS +.B gettext +[\fI\,OPTION\/\fR] [[\fI\,TEXTDOMAIN\/\fR] \fI\,MSGID\/\fR] +.br +.B gettext +[\fI\,OPTION\/\fR] \fI\,-s \/\fR[\fI\,MSGID\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +The \fBgettext\fP program translates a natural language message into the +user's language, by looking up the translation in a message catalog. +.PP +Display native language translation of a textual message. +.TP +\fB\-d\fR, \fB\-\-domain\fR=\fI\,TEXTDOMAIN\/\fR +retrieve translated messages from TEXTDOMAIN +.TP +\fB\-c\fR, \fB\-\-context\fR=\fI\,CONTEXT\/\fR +specify context for MSGID +.TP +\fB\-e\fR +enable expansion of some escape sequences +.TP +\fB\-n\fR +suppress trailing newline +.TP +\fB\-E\fR +(ignored for compatibility) +.TP +[TEXTDOMAIN] MSGID +retrieve translated message corresponding +to MSGID from TEXTDOMAIN +.SS "Informative output:" +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help and exit +.TP +\fB\-V\fR, \fB\-\-version\fR +display version information and exit +.PP +If the TEXTDOMAIN parameter is not given, the domain is determined from the +environment variable TEXTDOMAIN. If the message catalog is not found in the +regular directory, another location can be specified with the environment +variable TEXTDOMAINDIR. +When used with the \fB\-s\fR option the program behaves like the 'echo' command. +But it does not simply copy its arguments to stdout. Instead those messages +found in the selected catalog are translated. +Standard search directory: /usr/share/locale +.SH AUTHOR +Written by Ulrich Drepper. +.SH "REPORTING BUGS" +Report bugs in the bug tracker at +or by email to . +.SH COPYRIGHT +Copyright \(co 1995\-2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B gettext +is maintained as a Texinfo manual. If the +.B info +and +.B gettext +programs are properly installed at your site, the command +.IP +.B info gettext +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/gettextize.1 b/upstream/fedora-40/man1/gettextize.1 new file mode 100644 index 00000000..e31009fb --- /dev/null +++ b/upstream/fedora-40/man1/gettextize.1 @@ -0,0 +1,56 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. +.TH GETTEXTIZE "1" "June 2023" "GNU gettext-tools 0.22" "User Commands" +.SH NAME +gettextize \- install or upgrade gettext infrastructure +.SH SYNOPSIS +.B gettextize +[\fI\,OPTION\/\fR]... [\fI\,package-dir\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Prepares a source package to use gettext. +.SH OPTIONS +.TP +\fB\-\-help\fR +print this help and exit +.TP +\fB\-\-version\fR +print version information and exit +.TP +\fB\-f\fR, \fB\-\-force\fR +force writing of new files even if old exist +.TP +\fB\-\-po\-dir\fR=\fI\,DIR\/\fR +specify directory with PO files +.TP +\fB\-\-no\-changelog\fR +don't update or create ChangeLog files +.TP +\fB\-\-symlink\fR +make symbolic links instead of copying files +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +print modifications but don't perform them +.SH AUTHOR +Written by Ulrich Drepper +.SH "REPORTING BUGS" +Report bugs in the bug tracker at +or by email to . +.SH COPYRIGHT +Copyright \(co 1995\-2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B gettextize +is maintained as a Texinfo manual. If the +.B info +and +.B gettextize +programs are properly installed at your site, the command +.IP +.B info gettextize +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/giftopnm.1 b/upstream/fedora-40/man1/giftopnm.1 new file mode 100644 index 00000000..36df904c --- /dev/null +++ b/upstream/fedora-40/man1/giftopnm.1 @@ -0,0 +1,235 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Giftopnm User Manual" 0 "13 September 2012" "netpbm documentation" + +.SH NAME +giftopnm - convert a GIF file into a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBgiftopnm\fP +[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}] +[\fB-verbose\fP] +[\fB-comments\fP] +[\fB-image=\fP{\fIN\fP,\fBall\fP}] +[\fB-repair\fP] +[\fB-quitearly\fP] +[\fIGIFfile\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +This is a graphics format converter from the GIF format to the PNM +(i.e. PBM, PGM, or PPM) format. +.PP +If the image contains only black and maximally bright white, the +output is PBM. If the image contains more than those two colors, but +only grays, the output is PGM. If the image contains other colors, +the output is PPM. +.PP + A GIF image contains rectangular pixels. They all have the same +aspect ratio, but may not be square (it's actually quite unusual for +them not to be square, but it could happen). The pixels of a Netpbm +image are always square. Because of the engineering complexity to do +otherwise, \fBgiftopnm\fP converts a GIF image to a Netpbm image +pixel-for-pixel. This means if the GIF pixels are not square, the +Netpbm output image has the wrong aspect ratio. In this case, +\fBgiftopnm\fP issues an informational message telling you to run +\fBpamscale\fP to correct the output. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBgiftopnm\fP recognizes the following +command line options: + + +.TP +\fB--alphaout=\fP\fIalpha-filename\fP +\fBgiftopnm \fP creates a PBM file containing the transparency +information from the input image. This transparency image is the same +dimensions as the input image, and each pixel of the transparency image tells +whether the corresponding pixel of the input image is transparent. Black +means transparent; white means opaque. If you don't +specify \fB--alphaout\fP, \fBgiftopnm\fP does not generate a transparency +file, and if the input image has a transparency channel, \fBgiftopnm\fP simply +discards it. +.sp +If you specify \fB-\fP as the filename, \fBgiftopnm\fP writes the +transparency output to Standard Output and discards the image. +.sp +See +.BR "pamcomp" (1)\c +\& for one way to use +the transparency output file. + +.TP +\fB-verbose\fP +Produce verbose output about the GIF file input. + +.TP +\fB-comments\fP +With this option, \fBgiftopnm\fP issues messages showing the GIF comments +(A GIF89 stream can contain comments in comment extensions). +.sp +By default, \fBgiftopnm\fP ignores comment extensions. + + +.TP +\fB-image=\fP{\fIN\fP,\fBall\fP} +This option identifies which image from the GIF stream you want. +You can select either one image or all the images. Select all the +images with \fBall\fP. Select one image by specifying its sequence +number in the stream: \fB1\fP, \fB2\fP, \fB3\fP, etc. +.sp +The default is just Image 1. +.sp +A GIF stream normally contains only one image, so you don't need +this option. But some streams, including animated GIFs, have multiple +images. +.sp +When you select multiple GIF images, the output is a PNM stream with +multiple images. +.sp +If you specify a single image, \fBgiftopnm\fP must read and +partially validate the images before that in the stream. It may or may +not do the same for the images after it; see \fB-quitearly\fP. +.sp +The \fBall\fP value was added in Netpbm 10.16 (June 2003). Earlier +\fBgiftopnm\fP can extract only one image. + +.TP +\fB-repair\fP +This option makes \fBgiftopnm\fP try to salvage what it can from an +invalid GIF input. +.sp +In particular, when \fBgiftopnm\fP detects that the GIF input is +invalid so that it is impossible to determine what the pixels are +intended to be, it produces a single arbitrary color for all further +pixels in the image. \fBgiftopnm\fP processes the image from top to +bottom, left to right, so this means the bottommost pixels will be +this padding. +.sp +\fBgiftopnm\fP issues warning messages when it salvages an image +in this way. +.sp +Without this option, \fBgiftopnm\fP fails when it detects invalid +GIF input. Any output it produces is arbitrary, and typically is not +a valid PNM image. +.sp +It is fairly common for an image to be corrupted such that is +started off as a valid GIF, but had the end of the file cut off. An +interrupted network transfer tends to do this. In this case, +\fBgiftopnm\fP's salvage operation will produce a valid PNM image of +the proper dimensions, but with a single arbitrary color for the pixels +that were left out of the file. +.sp +This option was new in Netpbm 10.38 (March 2007). From 10.32 through +10.37, \fBgiftopnm\fP always fails if it detects invalid GIF input. +Before 10.32, it succeeds in the case of a truncated image, and replaces +the missing pixels with arbitrary colors, not necessarily all the same +(The pre-10.32 behavior wasn't actually intended by the design). + + +.TP +\fB-quitearly\fP +This option makes \fBgiftopnm\fP stop reading its input file as soon +as it has converted and output the images from the input that you requested. +By default, \fBgiftopnm\fP reads until the end of the GIF stream, ignoring +any data after the images you requested. +.sp +Two reasons \fInot\fP to use this option: + +.IP \(bu +The input file is a pipe and the process that is filling that pipe +expects the pipe to take the entire stream and will fail or get stuck +if it doesn't. + +.IP \(bu +You want to validate the entire GIF stream. + + +.sp +Two reasons to use this option: + + +.IP \(bu +It saves the time and other resources to read the end of the stream. +.IP \(bu +There are errors in the end of the stream that make \fBgiftopnm\fP fail. + +.sp +This option has no effect if you also specify \fB-image=all\fP +.sp +This option was new in Netpbm 10.35 (August 2006). Before that, +\fBgiftopnm\fP always reads the entire stream. + + + +.UN restrictions +.SH RESTRICTIONS +.PP +This does not correctly handle the Plain Text Extension of the +GIF89 standard, since I did not have any example input files +containing them. + +.UN seealso +.SH SEE ALSO +.BR "pamtogif" (1)\c +\&, +.BR "ppmcolormask" (1)\c +\&, +.BR "pamcomp" (1)\c +\&, +.UR http://www.lcdf.org/gifsicle +http://www.lcdf.org/gifsicle +.UE +\&, +.BR "ppm" (1)\c +\&. + +.UN author +.SH AUTHOR +.PP +Copyright (c) 1993 by David Koblas (\fIkoblas@netcom.com\fP) + +.UN license +.SH LICENSE +.PP +As a historical note, for a long time if you used \fBgiftopnm\fP, +you were using a patent on the LZW compression method which was owned +by Unisys, and in all probability you did not have a license from +Unisys to do so. Unisys typically asked $5000 for a license for +trivial use of the patent. Unisys never enforced the patent against +trivial users, and made statements that it is much less concerned +about people using the patent for decompression (which is what +\fBgiftopnm\fP does than for compression. The patent expired in +2003. +.PP +Rumor has it that IBM also owns a patent covering \fBgiftopnm\fP. +.PP +A replacement for the GIF format that has never required any patent +license to use is the PNG format. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/giftopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/gnumeric.1 b/upstream/fedora-40/man1/gnumeric.1 new file mode 100644 index 00000000..05cfaa29 --- /dev/null +++ b/upstream/fedora-40/man1/gnumeric.1 @@ -0,0 +1,199 @@ +.de URL +\\$2 \(laURL: \\$1 \(ra\\$3 +.. +.if \n[.g] .mso www.tmac +.TH GNUMERIC 1 "2009-02-08" gnumeric "GNOME" +.SH NAME +gnumeric \- a GNOME spreadsheet application. + +.SH SYNOPSIS +\fBgnumeric\fR [\fIOPTIONS\fR] [\fIfiles\fR \fI...\fR ] + +.SH DESCRIPTION +\fBGnumeric\fR is a powerful spreadsheet program created by the GNOME +project. \fBGnumeric\fR intends to compete with commercial +spreadsheets by becoming fully compatible with Microsoft Excel(TM) and +through the support of most popular spreadsheet file formats such as +Excel(TM), Lotus 1-2-3(TM), Applix(TM), Sylk(TM), XBase(TM), +Oleo(TM) and OpenOffice.org formats. + +\fBGnumeric\fR supports advanced calculations using statistical, +financial and database access functions. Plotting data is supported +through an incomplete but powerful plotting system. A plugin system +extends \fBgnumeric\fR , for instance enabling the export of data to +the LaTeX \\longtable format. Plugins can be used to define custom +functionality. A rudimentary scripting API for the Python language +exists and will be extended in the near future. Since \fBgnumeric\fR +is \fBfree\fR software, \fBgnumeric\fR can also be extended directly +at the source code level by any competent programmer. + +The program can be started from the command line as \fBgnumeric\fR or +from one of the menus provided by the underlying platform. When started +on the command line, \fBgnumeric\fR may be followed by the options listed +below and possibly the names of files in various spreadsheet formats +which will then be opened immediately. For instance, the command: + + gnumeric myfile.gnumeric + +will launch \fBgnumeric\fR and open the file called +"myfile.gnumeric". The default \fBgnumeric\fR file format is in +extensible markup language (XML) which subsequently has been +compressed with \fBgzip\fR. + +.SH USER OPTIONS +This program follows the usual GNU command line syntax, with single +letter options starting with a single dash (`-') and longer options +starting with two dashes (`--'). + +.SS "Help options" +.B \-?, \-\-help +Show help message. +.TP +.B \-\-usage +Displays a brief usage message. + +.SS "Gnumeric options" +.TP +.B \-v, \-\-version +Displays the version number of the installed instance of +\fBgnumeric\fR. +.TP +.B \-\-no-splash +Start \fBgnumeric\fR without showing the splash screen. The splash +screen is normally shown if loading files takes too long. + +.SS "Options for window placement" +.TP +\fB\-g, \-\-geometry=WIDTHxHEIGHT+XOFF+YOFF +Set the size and position of the first window. All units are in +pixels. The X offset is from the left hand side of the screen, the Y +offset is from the top of the screen. For example, \-g=800x600+20+30 +will open a gnumeric window 800 pixels wide by 600 pixels high, with +the left edge of gnumeric 20 pixels from the left of the screen and +the top edge of gnumeric 30 pixels from the top of the screen. +.TP +.B \fB\-\-display=\fR\fIDISPLAY\fR +X display to use, where DISPLAY has the form +machinename:Xdisplay.Screen. Note that the machine displaying gnumeric +must have granted the machine running gnumeric the right to display +(see xhost). + +.TP +.B \fB\-\-screen=\fR\fISCREEN\fR +X screen to use, a more compact form of the functionality described +above. + + + + +.SH ADVANCED OPTIONS + +.SS "GNOME options" +.TP +.B \-\-disable-sound +Disable sound server usage. +.TP +.B \-\-enable-sound +Enable sound server usage. +.TP +\fB\-\-espeaker=\fR\fIHOSTNAME:PORT\fR +Host:port on which the sound server to use is running. +.TP +.B \-\-disable-crash-dialog +Disable the bug submission dialog which appears if Gnumeric crashes. + +.SS "GTK options" +.TP +\fB\-\-gdk-debug=\fR\fIFLAGS\fR +Gdk debugging flags to set. +.TP +\fB\-\-gdk-no-debug=\fR\fIFLAGS\fR +Gdk debugging flags to unset. +.TP +.B \-\-sync +Make X calls synchronous. +.TP +\fB\-\-name=\fR\fINAME\fR +Program name as used by the window manager. +.TP +\fB\-\-class=\fR\fICLASS\fR +Program class as used by the window manager. +.TP +\fB\-\-gxid_host=\fR\fIHOST\fR +The host on which to contact the gxid daemon. This overrides the GXID_HOST environment variable. This option is only available if GTK+ has been configured with \-\-gdk-target=x11. +.TP +\fB\-\-gxid_port=\fR\fIPORT\fR +The port for the connection to gxid. This overrides the GXID_PORT environment variable. This option is only available if GTK+ has been configured with \-\-gdk-target=x11. +.TP +\fB\-\-gtk-debug=\fR\fIFLAGS\fR +Gtk+ debugging flags to set. +.TP +\fB\-\-gtk-no-debug=\fR\fIFLAGS\fR +Gtk+ debugging flags to unset. +.TP +\fB\-\-g-fatal-warnings\fR +Make all warnings fatal. +.TP +\fB\-\-gtk-module=\fR\fIMODULE\fR +Load an additional Gtk module. + +.SS "Session management options" +.TP +\fB\-\-sm-client-id=\fR\fIID\fR +Specify session management ID. +.TP +\fB\-\-sm-config-prefix=\fR\fIPREFIX\fR +Specify prefix of saved configuration. +.TP +.B \-\-sm-disable +Disable connection to session manager. + + +.SH VERSION +This manual page describes \fBgnumeric\fR version 1.8. + +.SH BUGS +For the list of known \fBgnumeric\fR bugs, or to report new ones +please visit \fIhttp://bugzilla.gnome.org\fR. + +.SH "SEE ALSO" +\fBssconvert\fR(1), +\fBssindex\fR(1), +\fBssdiff\fR(1) +\fBssgrep\fR(1) +.PP +.B The Gnumeric Manual +Available through the \fBHelp\fR menu or +.URL "http://www.gnome.org/projects/gnumeric/doc/gnumeric.shtml" online . +.PP +.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" . +.PP +.URL "http://www.gnome.org/" "The GNOME project page" . + +.SH LICENSE + +\fBGnumeric\fR is licensed under the terms of the General Public +License (GPL), version 2 or 3. For information on this license look at the +source code that came with the software or see the +.URL "http://www.gnu.org/" "GNU project page" . + +.SH COPYRIGHT + +The copyright on the \fBgnumeric\fR software and source code is held +by the individual authors as is documented in the source code. + + +.SH AUTHORS +.SS "Gnumeric" +Jody Goldberg +.br +Miguel de Icaza +.br +Morten Welinder +.br + +-- and many others. For a more complete list, see the About dialog. +.SS "This manual page" +Jan Schaumann +.br +Adrian Custer diff --git a/upstream/fedora-40/man1/gouldtoppm.1 b/upstream/fedora-40/man1/gouldtoppm.1 new file mode 100644 index 00000000..db7bc896 --- /dev/null +++ b/upstream/fedora-40/man1/gouldtoppm.1 @@ -0,0 +1,52 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Gouldtoppm User Manual" 0 "20 May 1990" "netpbm documentation" + +.SH NAME +gouldtoppm - convert Gould scanner file into a PPM image + +.UN synopsis +.SH SYNOPSIS + +\fBgouldtoppm\fP +[\fIgouldfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBgouldtoppm\fP reads a file produced by the Gould scanner as +input and produces a PPM image as output. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBgouldtoppm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "ppm" (1)\c +\& + +.UN author +.SH AUTHOR +.PP +Copyright(C) 1990 by Stephen Paul Lesniewski +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/gouldtoppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/gpm-root.1 b/upstream/fedora-40/man1/gpm-root.1 new file mode 100644 index 00000000..6df6f2fa --- /dev/null +++ b/upstream/fedora-40/man1/gpm-root.1 @@ -0,0 +1,230 @@ +.TH GPM-ROOT 1 "February 1995" +.UC 4 +.SH NAME +gpm-root \- a default handler for gpm, used to draw menus on +the root window +.SH SYNOPSIS +.B gpm-root +[ +.I options +] +.br +.SH DESCRIPTION + +.LP +The program gpm-root is designed to handle Control-Mouse events to +draw menus on the background of the current tty. The actual menus +are described by a configuration file in the user's home directory. + +.LP +Please note that gpm-root needs to run with Linux 1.1.73 or +newer, because previous kernels lack some screen handling capabilities +required by the program. + +.LP +The program uses the files /dev/vcs* to draw to the console screen. +These are available only from kernel 1.1.81 onward. If you miss those +device nodes, you should create them using create_vcs in the +distribution directory. The tool won't run with kernels older than 1.1.81, +because they lacked a full screen dump/restore capability. + +.LP +Available command line options are the following: +.TP +-m \fBnumber\fP +Choose the modifier to use (by default: control). The modifier +can be provided either as a number or as a symbolic string. +Allowed strings are shift, anyAlt, leftAlt, +rightAlt, control. +.TP +-u +Deny using user-specific configuration files. With this +option on, only /etc/gpm-root.conf will be used as a source +of configuration information. This option +is intended for those system administrators who fear security could +be broken by this daemon. Things should be sufficiently secure, but +if you find a hole please tell me about it. +.TP +-D +Do not automatically enter background operation when started, +and log messages to the standard error stream, not the syslog +mechanism. This is useful for debugging; in previous releases +it was done with a compile-time option. +.TP +-V \fBverbosity increment\fP +Raise the maximum level of messages that will be logged. Thus a +positive argument has the effect of making the program more +verbose. One can also give a negative argument to hush the +program; however, note that due to \fBgetopt(3)\fP rules a negative +argument must follow the option with no space betwixt (that is, +-V-1 but not -V -1). Program Arguments,,,libc. +The argument is optional and its default value is 1. + +.LP +Each time a menu is drawn, the configuration file is reparsed if it has +changed. This allows modification of personal setup without reinvoking +the daemon. + +.LP +The actual configuration file is better introduced by looking at your +/etc/gpm-root.conf. +.fi + +.LP +The syntax for the file won't be described here, being it quite apparent +from the example above. Blanks and newlines are unused in parsing the +file, and the layout of the file is free. Comments are allowed in the +file: any hash mark (#) found at the beginning of the line or +after white space makes the parser discard anything up to the next +line. To insert quotes (") in strings precede them with a backslash. + +.LP +Note that recursive menus are allowed, to any level of recursion. + +.LP +Keywords belong to three groups: the button keyword, the cfg +keywords and the action keywords. They are all described in the table +below: +.TP +button \fBnumber\fP \fBmenu\fP +The button keyword is used to introduce a menu. It is +followed by the number of the relevant button (1=left, +2=middle, 3=right), an open brace, a menu and a closed brace. +A menu is made up of cfg statements, followed by +action statements. Cfg statements can come in any order, +while the order of action statements tells the actual order +in which actions will appear on the screen, top to bottom. + +.LP +The following statements belong to the cfg set. +.TP +name \fBstring\fP +If the name keyword is present, the specified +\fBstring\fP will be used as the name for the current menu. +.TP +background \fBcolor\fP +This statements is used to specify the +background color to be used in the current menu. The \fBcolor\fP +can be specified with one of the eight canonical strings black, +red, cyan etc. The background defaults to black. +.TP +foreground \fBcolor\fP +This statements is used to specify the +foreground color for menu items. Its value defaults to white. +An optional bright keyword can appear before the actual color. +.TP +border \fBcolor\fP +border is used to specify the +border color for the menu. Its value defaults to white. +An optional bright keyword can appear before the actual color. +.TP +head \fBcolor\fP +head is used to specify the +foreground color for the title of the menu. Its value defaults +to white. +An optional bright keyword can appear before the actual color. + +.LP +The following statements belong to the action set. +.TP +\fBstring\fP f.fgcmd \fBcmdstring\fP +When the mouse button is +released above the corresponding menu item, the \fBcmdstring\fP is +pasted in the keyboard queue of the current console. This is +not yet implemented. +.TP +\fBstring\fP f.bgcmd \fBcmdstring\fP +When the mouse button is released above the +corresponding menu item, a shell (/bin/sh) is forked to +execute the specified command, with stdin +connected to /dev/null, and stdout, stderr connected +to the active console. +.TP +\fBstring\fP f.jptty \fBttynumber\fP +When the mouse button is +released above the corresponding menu item, the console is +switched to the one specified. The \fBttynumber\fP must be specified +as a string. Any tty can be reached this way, even those which are +not accessible via the keyboard. +.TP +\fBstring\fP f.mktty \fBttynumber\fP +When the mouse button is +released above the corresponding menu item, an unused console is +selected, and /sbin/mingetty is executed in it. The current console +is switched to the newly opened console. I use this command to save +kernel memory by opening a single console through /etc/inittab +and requesting the others only when i need to login. +.TP +\fBstring\fP \fBWhole-menu\fP +A menu can directly follow the label string. +When the mouse pointer leaves the menu frame at the level of \fBstring\fP, +a second menu is posted on screen. +.TP +\fBstring\fP f.lock +When the mouse button is +released above the corresponding menu item, the keyboard and the +screen are locked, and only the locking user or the superuser +can unlock them. This is not yet implemented. +.TP +\fBstring\fP f.load +The current loadavg when the menu is posted is concatenated to \fBstring\fP +to build the actual message displayed on screen. Nothing happens at +button release. +.TP +\fBstring\fP f.free +The free memory and swap when the menu is posted is concatenated +to \fBstring\fP +to build the actual message displayed on screen. Nothing happens at +button release. +.TP +\fBstring\fP f.time +The current time is formatted with \fBstrftime(3)\fP, according to +\fBstring\fP. The resulting string is +the actual message displayed on screen. Nothing happens at +button release. +.TP +\fBstring\fP f.pipe \fBcmdline\fP +When the mouse pointer leaves the menu frame at the level of \fBstring\fP, +a message box is posted on screen showing the last ten lines +of the output of \fBcmdline\fP. \fBcmdline\fP is executed +by /bin/sh. This is not yet implemented. + + +.TP +\fBstring\fP f.nop +This does nothing, it only displays \fBstring\fP on the menu. + +.LP +The HOME, LOGNAME and USER environment variables are setup +to the values for the invoking user before spawning an external +process (f.bgcmd, f.pipe). The current directory is always /. + +.LP +.SH BUGS + +.LP +Known bugs have been fixed. In particular, if you invoke gpm-root +right after gpm, it will delay a few seconds before trying to connect +to the daemon. + +.LP +.SH AUTHOR +Alessandro Rubini + +.LP +.SH FILES +.nf +/dev/gpmctl The socket used to connect to gpm. +/etc/gpm-root.conf The default configuration file. +$(HOME)/.gpm-root The user configuration file. +/dev/vcs* Virtual Console Screens +.fi + +.LP +.SH SEE ALSO +.nf +\fB gpm(8) \fP + +.fi +The info file about `gpm', which gives more complete information and +explains how to write a gpm client. diff --git a/upstream/fedora-40/man1/gprof.1 b/upstream/fedora-40/man1/gprof.1 new file mode 100644 index 00000000..918f5eeb --- /dev/null +++ b/upstream/fedora-40/man1/gprof.1 @@ -0,0 +1,698 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "GPROF 1" +.TH GPROF 1 2024-02-12 binutils-2.41 GNU +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +gprof \- display call graph profile data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ABCeEfFJnNOpPqQRStZ][\fIname\fR] ] + [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ] + [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ] + [ \-\-[no\-]annotated\-source[=\fIname\fR] ] + [ \-\-[no\-]exec\-counts[=\fIname\fR] ] + [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ] + [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ] + [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ] + [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ] + [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ] + [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-inline\-file\-names ] + [ \-\-min\-count=\fIn\fR ] [ \-\-no\-static ] [ \-\-print\-path ] + [ \-\-separate\-files ] [ \-\-static\-call\-graph ] [ \-\-sum ] + [ \-\-table\-length=\fIlen\fR ] [ \-\-traditional ] [ \-\-version ] + [ \-\-width=\fIn\fR ] [ \-\-ignore\-non\-functions ] + [ \-\-demangle[=\fISTYLE\fR] ] [ \-\-no\-demangle ] + [\-\-external\-symbol\-table=name] + [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77 +programs. The effect of called routines is incorporated in the profile +of each caller. The profile data is taken from the call graph profile file +(\fIgmon.out\fR default) which is created by programs +that are compiled with the \fB\-pg\fR option of +\&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR. +The \fB\-pg\fR option also links in versions of the library routines +that are compiled for profiling. \f(CW\*(C`Gprof\*(C'\fR reads the given object +file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between +its symbol table and the call graph profile from \fIgmon.out\fR. +If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR +output shows the sum of the profile information in the given profile files. +.PP +\&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine. +Next, these times are propagated along the edges of the call graph. +Cycles are discovered, and calls into a cycle are made to share the time +of the cycle. +.PP +Several forms of output are available from the analysis. +.PP +The \fIflat profile\fR shows how much time your program spent in each function, +and how many times that function was called. If you simply want to know +which functions burn most of the cycles, it is stated concisely here. +.PP +The \fIcall graph\fR shows, for each function, which functions called it, which +other functions it called, and how many times. There is also an estimate +of how much time was spent in the subroutines of each function. This can +suggest places where you might try to eliminate function calls that use a +lot of time. +.PP +The \fIannotated source\fR listing is a copy of the program's +source code, labeled with the number of times each line of the +program was executed. +.SH OPTIONS +.IX Header "OPTIONS" +These options specify which of several output formats +\&\f(CW\*(C`gprof\*(C'\fR should produce. +.PP +Many of these options take an optional \fIsymspec\fR to specify +functions to be included or excluded. These options can be +specified multiple times, with different symspecs, to include +or exclude sets of symbols. +.PP +Specifying any of these options overrides the default (\fB\-p \-q\fR), +which prints a flat profile and call graph analysis +for all functions. +.ie n .IP """\-A[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-A[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-A[symspec]" +.PD 0 +.ie n .IP """\-\-annotated\-source[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-annotated\-source[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--annotated-source[=symspec]" +.PD +The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code. +If \fIsymspec\fR is specified, print output only for matching symbols. +.ie n .IP """\-b""" 4 +.el .IP \f(CW\-b\fR 4 +.IX Item "-b" +.PD 0 +.ie n .IP """\-\-brief""" 4 +.el .IP \f(CW\-\-brief\fR 4 +.IX Item "--brief" +.PD +If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the +verbose blurbs that try to explain the meaning of all of the fields in +the tables. This is useful if you intend to print out the output, or +are tired of seeing the blurbs. +.ie n .IP """\-B""" 4 +.el .IP \f(CW\-B\fR 4 +.IX Item "-B" +The \fB\-B\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. +.ie n .IP """\-C[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-C[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-C[symspec]" +.PD 0 +.ie n .IP """\-\-exec\-counts[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-exec\-counts[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--exec-counts[=symspec]" +.PD +The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to +print a tally of functions and the number of times each was called. +If \fIsymspec\fR is specified, print tally only for matching symbols. +.Sp +If the profile data file contains basic-block count records, specifying +the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block +execution counts to be tallied and displayed. +.ie n .IP """\-i""" 4 +.el .IP \f(CW\-i\fR 4 +.IX Item "-i" +.PD 0 +.ie n .IP """\-\-file\-info""" 4 +.el .IP \f(CW\-\-file\-info\fR 4 +.IX Item "--file-info" +.PD +The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information +about the profile data file(s) and then exit. The number of histogram, +call graph, and basic-block count records is displayed. +.ie n .IP """\-I \fIdirs\fR""" 4 +.el .IP "\f(CW\-I \fR\f(CIdirs\fR\f(CW\fR" 4 +.IX Item "-I dirs" +.PD 0 +.ie n .IP """\-\-directory\-path=\fIdirs\fR""" 4 +.el .IP \f(CW\-\-directory\-path=\fR\f(CIdirs\fR\f(CW\fR 4 +.IX Item "--directory-path=dirs" +.PD +The \fB\-I\fR option specifies a list of search directories in +which to find source files. Environment variable \fIGPROF_PATH\fR +can also be used to convey this information. +Used mostly for annotated source output. +.ie n .IP """\-J[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-J[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-J[symspec]" +.PD 0 +.ie n .IP """\-\-no\-annotated\-source[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-annotated\-source[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-annotated-source[=symspec]" +.PD +The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to +print annotated source code. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source, +but excludes matching symbols. +.ie n .IP """\-L""" 4 +.el .IP \f(CW\-L\fR 4 +.IX Item "-L" +.PD 0 +.ie n .IP """\-\-print\-path""" 4 +.el .IP \f(CW\-\-print\-path\fR 4 +.IX Item "--print-path" +.PD +Normally, source filenames are printed with the path +component suppressed. The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR +to print the full pathname of +source filenames, which is determined +from symbolic debugging information in the image file +and is relative to the directory in which the compiler +was invoked. +.ie n .IP """\-p[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-p[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-p[symspec]" +.PD 0 +.ie n .IP """\-\-flat\-profile[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-flat\-profile[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--flat-profile[=symspec]" +.PD +The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile. +If \fIsymspec\fR is specified, print flat profile only for matching symbols. +.ie n .IP """\-P[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-P[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-P[symspec]" +.PD 0 +.ie n .IP """\-\-no\-flat\-profile[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-flat\-profile[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-flat-profile[=symspec]" +.PD +The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile, +but excludes matching symbols. +.ie n .IP """\-q[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-q[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-q[symspec]" +.PD 0 +.ie n .IP """\-\-graph[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-graph[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--graph[=symspec]" +.PD +The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. +If \fIsymspec\fR is specified, print call graph only for matching symbols +and their children. +.ie n .IP """\-Q[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-Q[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-Q[symspec]" +.PD 0 +.ie n .IP """\-\-no\-graph[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-graph[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-graph[=symspec]" +.PD +The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the +call graph. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph, +but excludes matching symbols. +.ie n .IP """\-t""" 4 +.el .IP \f(CW\-t\fR 4 +.IX Item "-t" +.PD 0 +.ie n .IP """\-\-table\-length=\fInum\fR""" 4 +.el .IP \f(CW\-\-table\-length=\fR\f(CInum\fR\f(CW\fR 4 +.IX Item "--table-length=num" +.PD +The \fB\-t\fR option causes the \fInum\fR most active source lines in +each source file to be listed when source annotation is enabled. The +default is 10. +.ie n .IP """\-y""" 4 +.el .IP \f(CW\-y\fR 4 +.IX Item "-y" +.PD 0 +.ie n .IP """\-\-separate\-files""" 4 +.el .IP \f(CW\-\-separate\-files\fR 4 +.IX Item "--separate-files" +.PD +This option affects annotated source output only. +Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files +to standard-output. If this option is specified, +annotated source for a file named \fIpath/filename\fR +is generated in the file \fIfilename\-ann\fR. If the underlying +file system would truncate \fIfilename\-ann\fR so that it +overwrites the original \fIfilename\fR, \f(CW\*(C`gprof\*(C'\fR generates +annotated source in the file \fIfilename.ann\fR instead (if the +original file name has an extension, that extension is \fIreplaced\fR +with \fI.ann\fR). +.ie n .IP """\-Z[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-Z[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-Z[symspec]" +.PD 0 +.ie n .IP """\-\-no\-exec\-counts[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-exec\-counts[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-exec-counts[=symspec]" +.PD +The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to +print a tally of functions and the number of times each was called. +If \fIsymspec\fR is specified, print tally, but exclude matching symbols. +.ie n .IP """\-r""" 4 +.el .IP \f(CW\-r\fR 4 +.IX Item "-r" +.PD 0 +.ie n .IP """\-\-function\-ordering""" 4 +.el .IP \f(CW\-\-function\-ordering\fR 4 +.IX Item "--function-ordering" +.PD +The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a +suggested function ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which support arbitrary +ordering of functions in an executable. +.Sp +The exact details of how to force the linker to place functions +in a particular order is system dependent and out of the scope of this +manual. +.ie n .IP """\-R \fImap_file\fR""" 4 +.el .IP "\f(CW\-R \fR\f(CImap_file\fR\f(CW\fR" 4 +.IX Item "-R map_file" +.PD 0 +.ie n .IP """\-\-file\-ordering \fImap_file\fR""" 4 +.el .IP "\f(CW\-\-file\-ordering \fR\f(CImap_file\fR\f(CW\fR" 4 +.IX Item "--file-ordering map_file" +.PD +The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a +suggested .o link line ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which do not support arbitrary +ordering of functions in an executable. +.Sp +Use of the \fB\-a\fR argument is highly recommended with this option. +.Sp +The \fImap_file\fR argument is a pathname to a file which provides +function name to object file mappings. The format of the file is similar to +the output of the program \f(CW\*(C`nm\*(C'\fR. +.Sp +.Vb 8 +\& c\-parse.o:00000000 T yyparse +\& c\-parse.o:00000004 C yyerrflag +\& c\-lang.o:00000000 T maybe_objc_method_name +\& c\-lang.o:00000000 T print_lang_statistics +\& c\-lang.o:00000000 T recognize_objc_keyword +\& c\-decl.o:00000000 T print_lang_identifier +\& c\-decl.o:00000000 T print_lang_type +\& ... +.Ve +.Sp +To create a \fImap_file\fR with GNU \f(CW\*(C`nm\*(C'\fR, type a command like +\&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR. +.ie n .IP """\-T""" 4 +.el .IP \f(CW\-T\fR 4 +.IX Item "-T" +.PD 0 +.ie n .IP """\-\-traditional""" 4 +.el .IP \f(CW\-\-traditional\fR 4 +.IX Item "--traditional" +.PD +The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in +"traditional" BSD style. +.ie n .IP """\-w \fIwidth\fR""" 4 +.el .IP "\f(CW\-w \fR\f(CIwidth\fR\f(CW\fR" 4 +.IX Item "-w width" +.PD 0 +.ie n .IP """\-\-width=\fIwidth\fR""" 4 +.el .IP \f(CW\-\-width=\fR\f(CIwidth\fR\f(CW\fR 4 +.IX Item "--width=width" +.PD +Sets width of output lines to \fIwidth\fR. +Currently only used when printing the function index at the bottom +of the call graph. +.ie n .IP """\-x""" 4 +.el .IP \f(CW\-x\fR 4 +.IX Item "-x" +.PD 0 +.ie n .IP """\-\-all\-lines""" 4 +.el .IP \f(CW\-\-all\-lines\fR 4 +.IX Item "--all-lines" +.PD +This option affects annotated source output only. +By default, only the lines at the beginning of a basic-block +are annotated. If this option is specified, every line in +a basic-block is annotated by repeating the annotation for the +first line. This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR. +.ie n .IP """\-\-demangle[=\fIstyle\fR]""" 4 +.el .IP \f(CW\-\-demangle[=\fR\f(CIstyle\fR\f(CW]\fR 4 +.IX Item "--demangle[=style]" +.PD 0 +.ie n .IP """\-\-no\-demangle""" 4 +.el .IP \f(CW\-\-no\-demangle\fR 4 +.IX Item "--no-demangle" +.PD +These options control whether C++ symbol names should be demangled when +printing output. The default is to demangle symbols. The +\&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different +compilers have different mangling styles. The optional demangling style +argument can be used to choose an appropriate demangling style for your +compiler. +.SS "Analysis Options" +.IX Subsection "Analysis Options" +.ie n .IP """\-a""" 4 +.el .IP \f(CW\-a\fR 4 +.IX Item "-a" +.PD 0 +.ie n .IP """\-\-no\-static""" 4 +.el .IP \f(CW\-\-no\-static\fR 4 +.IX Item "--no-static" +.PD +The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of +statically declared (private) functions. (These are functions whose +names are not listed as global, and which are not visible outside the +file/function/block where they were defined.) Time spent in these +functions, calls to/from them, etc., will all be attributed to the +function that was loaded directly before it in the executable file. +This option affects both the flat profile and the call graph. +.ie n .IP """\-c""" 4 +.el .IP \f(CW\-c\fR 4 +.IX Item "-c" +.PD 0 +.ie n .IP """\-\-static\-call\-graph""" 4 +.el .IP \f(CW\-\-static\-call\-graph\fR 4 +.IX Item "--static-call-graph" +.PD +The \fB\-c\fR option causes the call graph of the program to be +augmented by a heuristic which examines the text space of the object +file and identifies function calls in the binary machine code. +Since normal call graph records are only generated when functions are +entered, this option identifies children that could have been called, +but never were. Calls to functions that were not compiled with +profiling enabled are also identified, but only if symbol table +entries are present for them. +Calls to dynamic library routines are typically \fInot\fR found +by this option. +Parents or children identified via this heuristic +are indicated in the call graph with call counts of \fB0\fR. +.ie n .IP """\-D""" 4 +.el .IP \f(CW\-D\fR 4 +.IX Item "-D" +.PD 0 +.ie n .IP """\-\-ignore\-non\-functions""" 4 +.el .IP \f(CW\-\-ignore\-non\-functions\fR 4 +.IX Item "--ignore-non-functions" +.PD +The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which +are not known to be functions. This option will give more accurate +profile data on systems where it is supported (Solaris and HPUX for +example). +.ie n .IP """\-k \fIfrom\fR/\fIto\fR""" 4 +.el .IP "\f(CW\-k \fR\f(CIfrom\fR\f(CW/\fR\f(CIto\fR\f(CW\fR" 4 +.IX Item "-k from/to" +The \fB\-k\fR option allows you to delete from the call graph any arcs from +symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR. +.ie n .IP """\-l""" 4 +.el .IP \f(CW\-l\fR 4 +.IX Item "-l" +.PD 0 +.ie n .IP """\-\-line""" 4 +.el .IP \f(CW\-\-line\fR 4 +.IX Item "--line" +.PD +The \fB\-l\fR option enables line-by-line profiling, which causes +histogram hits to be charged to individual source code lines, +instead of functions. This feature only works with programs compiled +by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler. Newer versions of +\&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead. +.Sp +If the program was compiled with basic-block counting enabled, +this option will also identify how many times each line of +code was executed. +While line-by-line profiling can help isolate where in a large function +a program is spending its time, it also significantly increases +the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical +inaccuracies. +.ie n .IP """\-\-inline\-file\-names""" 4 +.el .IP \f(CW\-\-inline\-file\-names\fR 4 +.IX Item "--inline-file-names" +This option causes \f(CW\*(C`gprof\*(C'\fR to print the source file after each +symbol in both the flat profile and the call graph. The full path to the +file is printed if used with the \fB\-L\fR option. +.ie n .IP """\-m \fInum\fR""" 4 +.el .IP "\f(CW\-m \fR\f(CInum\fR\f(CW\fR" 4 +.IX Item "-m num" +.PD 0 +.ie n .IP """\-\-min\-count=\fInum\fR""" 4 +.el .IP \f(CW\-\-min\-count=\fR\f(CInum\fR\f(CW\fR 4 +.IX Item "--min-count=num" +.PD +This option affects execution count output only. +Symbols that are executed less than \fInum\fR times are suppressed. +.ie n .IP """\-n\fIsymspec\fR""" 4 +.el .IP \f(CW\-n\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "-nsymspec" +.PD 0 +.ie n .IP """\-\-time=\fIsymspec\fR""" 4 +.el .IP \f(CW\-\-time=\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "--time=symspec" +.PD +The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, +to only propagate times for symbols matching \fIsymspec\fR. +.ie n .IP """\-N\fIsymspec\fR""" 4 +.el .IP \f(CW\-N\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "-Nsymspec" +.PD 0 +.ie n .IP """\-\-no\-time=\fIsymspec\fR""" 4 +.el .IP \f(CW\-\-no\-time=\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "--no-time=symspec" +.PD +The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, +not to propagate times for symbols matching \fIsymspec\fR. +.ie n .IP """\-S\fIfilename\fR""" 4 +.el .IP \f(CW\-S\fR\f(CIfilename\fR\f(CW\fR 4 +.IX Item "-Sfilename" +.PD 0 +.ie n .IP """\-\-external\-symbol\-table=\fIfilename\fR""" 4 +.el .IP \f(CW\-\-external\-symbol\-table=\fR\f(CIfilename\fR\f(CW\fR 4 +.IX Item "--external-symbol-table=filename" +.PD +The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table +file, such as \fI/proc/kallsyms\fR, rather than read the symbol table +from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful +for profiling kernel modules. +.ie n .IP """\-z""" 4 +.el .IP \f(CW\-z\fR 4 +.IX Item "-z" +.PD 0 +.ie n .IP """\-\-display\-unused\-functions""" 4 +.el .IP \f(CW\-\-display\-unused\-functions\fR 4 +.IX Item "--display-unused-functions" +.PD +If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all +functions in the flat profile, even those that were never called, and +that had no time spent in them. This is useful in conjunction with the +\&\fB\-c\fR option for discovering which routines were never called. +.SS "Miscellaneous Options" +.IX Subsection "Miscellaneous Options" +.ie n .IP """\-d[\fInum\fR]""" 4 +.el .IP \f(CW\-d[\fR\f(CInum\fR\f(CW]\fR 4 +.IX Item "-d[num]" +.PD 0 +.ie n .IP """\-\-debug[=\fInum\fR]""" 4 +.el .IP \f(CW\-\-debug[=\fR\f(CInum\fR\f(CW]\fR 4 +.IX Item "--debug[=num]" +.PD +The \fB\-d\fR \fInum\fR option specifies debugging options. +If \fInum\fR is not specified, enable all debugging. +.ie n .IP """\-h""" 4 +.el .IP \f(CW\-h\fR 4 +.IX Item "-h" +.PD 0 +.ie n .IP """\-\-help""" 4 +.el .IP \f(CW\-\-help\fR 4 +.IX Item "--help" +.PD +The \fB\-h\fR option prints command line usage. +.ie n .IP """\-O\fIname\fR""" 4 +.el .IP \f(CW\-O\fR\f(CIname\fR\f(CW\fR 4 +.IX Item "-Oname" +.PD 0 +.ie n .IP """\-\-file\-format=\fIname\fR""" 4 +.el .IP \f(CW\-\-file\-format=\fR\f(CIname\fR\f(CW\fR 4 +.IX Item "--file-format=name" +.PD +Selects the format of the profile data files. Recognized formats are +\&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and +\&\fBprof\fR (not yet supported). +.ie n .IP """\-s""" 4 +.el .IP \f(CW\-s\fR 4 +.IX Item "-s" +.PD 0 +.ie n .IP """\-\-sum""" 4 +.el .IP \f(CW\-\-sum\fR 4 +.IX Item "--sum" +.PD +The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information +in the profile data files it read in, and write out a profile data +file called \fIgmon.sum\fR, which contains all the information from +the profile data files that \f(CW\*(C`gprof\*(C'\fR read in. The file \fIgmon.sum\fR +may be one of the specified input files; the effect of this is to +merge the data in the other input files into \fIgmon.sum\fR. +.Sp +Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the +cumulative data in the file \fIgmon.sum\fR. +.ie n .IP """\-v""" 4 +.el .IP \f(CW\-v\fR 4 +.IX Item "-v" +.PD 0 +.ie n .IP """\-\-version""" 4 +.el .IP \f(CW\-\-version\fR 4 +.IX Item "--version" +.PD +The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version +number, and then exit. +.SS "Deprecated Options" +.IX Subsection "Deprecated Options" +These options have been replaced with newer versions that use symspecs. +.ie n .IP """\-e \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-e \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-e function_name" +The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print +information about the function \fIfunction_name\fR (and its +children...) in the call graph. The function will still be listed +as a child of any functions that call it, but its index number will be +shown as \fB[not printed]\fR. More than one \fB\-e\fR option may be +given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR +option. +.ie n .IP """\-E \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-E \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-E function_name" +The \f(CW\*(C`\-E \fR\f(CIfunction\fR\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but +time spent in the function (and children who were not called from +anywhere else), will not be used to compute the percentages-of-time for +the call graph. More than one \fB\-E\fR option may be given; only one +\&\fIfunction_name\fR may be indicated with each \fB\-E\fR option. +.ie n .IP """\-f \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-f \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-f function_name" +The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the +call graph to the function \fIfunction_name\fR and its children (and +their children...). More than one \fB\-f\fR option may be given; +only one \fIfunction_name\fR may be indicated with each \fB\-f\fR +option. +.ie n .IP """\-F \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-F \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-F function_name" +The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but +only time spent in the function and its children (and their +children...) will be used to determine total-time and +percentages-of-time for the call graph. More than one \fB\-F\fR option +may be given; only one \fIfunction_name\fR may be indicated with each +\&\fB\-F\fR option. The \fB\-F\fR option overrides the \fB\-E\fR option. +.SH FILES +.IX Header "FILES" +.ie n .IP """\fIa.out\fR""" 4 +.el .IP \f(CW\fR\f(CIa.out\fR\f(CW\fR 4 +.IX Item "a.out" +the namelist and text space. +.ie n .IP """\fIgmon.out\fR""" 4 +.el .IP \f(CW\fR\f(CIgmon.out\fR\f(CW\fR 4 +.IX Item "gmon.out" +dynamic call graph and profile. +.ie n .IP """\fIgmon.sum\fR""" 4 +.el .IP \f(CW\fR\f(CIgmon.sum\fR\f(CW\fR 4 +.IX Item "gmon.sum" +summarized dynamic call graph and profile. +.SH BUGS +.IX Header "BUGS" +The granularity of the sampling is shown, but remains +statistical at best. +We assume that the time for each execution of a function +can be expressed by the total time for the function divided +by the number of times the function is called. +Thus the time propagated along the call graph arcs to the function's +parents is directly proportional to the number of times that +arc is traversed. +.PP +Parents that are not themselves profiled will have the time of +their profiled children propagated to them, but they will appear +to be spontaneously invoked in the call graph listing, and will +not have their time propagated further. +Similarly, signal catchers, even though profiled, will appear +to be spontaneous (although for more obscure reasons). +Any profiled children of signal catchers should have their times +propagated properly, unless the signal catcher was invoked during +the execution of the profiling routine, in which case all is lost. +.PP +The profiled program must call \f(CW\*(C`exit\*(C'\fR(2) +or return normally for the profiling information to be saved +in the \fIgmon.out\fR file. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBmonitor\fR\|(3), \fBprofil\fR\|(2), \fBcc\fR\|(1), \fBprof\fR\|(1), and the Info entry for \fIgprof\fR. +.PP +"An Execution Profiler for Modular Programs", +by S. Graham, P. Kessler, M. McKusick; +Software \- Practice and Experience, +Vol. 13, pp. 671\-685, 1983. +.PP +"gprof: A Call Graph Execution Profiler", +by S. Graham, P. Kessler, M. McKusick; +Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, +SIGPLAN Notices, Vol. 17, No 6, pp. 120\-126, June 1982. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". diff --git a/upstream/fedora-40/man1/grap2graph.1 b/upstream/fedora-40/man1/grap2graph.1 new file mode 100644 index 00000000..40b69003 --- /dev/null +++ b/upstream/fedora-40/man1/grap2graph.1 @@ -0,0 +1,205 @@ +.TH grap2graph 1 "24 January 2024" "groff 1.23.0" +.SH Name +grap2graph \- convert a +.I grap +diagram into a cropped image +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" This documentation is released to the public domain. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grap2graph_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grap2graph +.RB [ \-unsafe ] +.RB [ \-format\~\c +.IR output-format ] +.RI [ convert-argument \~.\|.\|.] +.YS +. +. +.SY grap2graph +.B \-\-help +.YS +. +. +.SY grap2graph +.B \-v +. +.SY grap2graph +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I grap2graph +reads a +.MR grap 1 +program from the standard input and writes an image file, +by default in Portable Network Graphics (PNG) format, +to the standard output. +. +. +.PP +The input GRAP code should +.I not +be wrapped with the +.B .G1 +and +.B .G2 +macros that normally guard it within +.MR groff 1 +documents. +. +. +.\" FIXME: How old? This text hasn't been touched since 2008 at latest. +.\" Older versions of +.\" .I \%convert +.\" will produce a black-on-white graphic; newer ones may produce a +.\" black-on-transparent graphic. +. +.PP +Arguments not recognized by +.I grap2graph +are passed to the ImageMagick or GraphicsMagick program +.MR convert 1 . +. +. +By specifying these, you can give your image a border, +.\" Transparent backgrounds are the default in 2018. +.\" force the background transparent, +set the image's pixel density, +or perform other useful transformations. +. +. +.PP +The output image is clipped using +.IR \%convert 's +.B \-trim +option to the smallest possible bounding box that contains all the black +pixels. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-format\~ output-format +Write the image in +.IR output-format , +which must be understood by +.IR \%convert ; +the default is PNG. +. +. +.TP +.B \-unsafe +Run +.I groff +in +.I unsafe +mode, enabling the PIC command +.B sh +to execute arbitrary Unix shell commands. +. +The +.I groff +default is to forbid this. +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I \%GROFF_TMPDIR +.TQ +.I \%TMPDIR +.TQ +.I TMP +.TQ +.I TEMP +These environment variables are searched in the given order to determine +the directory where temporary files will be created. +. +If none are set, +.I /tmp +is used. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +.I grap2graph +was written by +.MT esr@\:thyrsus\:.com +Eric S.\& Raymond +.ME , +based on a recipe for +.MR pic2graph 1 , +by W.\& Richard Stevens. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR pic2graph 1 , +.MR eqn2graph 1 , +.MR grap 1 , +.MR \%pic 1 , +.MR groff 1 , +.MR convert 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grap2graph_1_man_C] +.do rr *groff_grap2graph_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grep.1 b/upstream/fedora-40/man1/grep.1 new file mode 100644 index 00000000..7758ed1e --- /dev/null +++ b/upstream/fedora-40/man1/grep.1 @@ -0,0 +1,1358 @@ +.\" GNU grep man page +.de dT +.ds Dt \\$2 +.. +.dT Time-stamp: "2019-12-29" +.\" Update the above date whenever a change to either this file or +.\" grep.c's 'usage' function results in a nontrivial change to the man page. +.\" In Emacs, you can update the date by running 'M-x time-stamp' +.\" after you make a change that you decide is nontrivial. +.\" It is no big deal to forget to update the date. +. +.TH GREP 1 \*(Dt "GNU grep 3.11" "User Commands" +. +.if !\w|\*(lq| \{\ +.\" groff an-old.tmac does not seem to be in use, so define lq and rq. +. ie \n(.g \{\ +. ds lq \(lq\" +. ds rq \(rq\" +. \} +. el \{\ +. ds lq `` +. ds rq '' +. \} +.\} +. +.if !\w|\*(la| \{\ +.\" groff an-ext.tmac does not seem to be in use, so define the parts of +.\" it that are used below. For a copy of groff an-ext.tmac, please see: +.\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac +.\" --- Start of lines taken from groff an-ext.tmac +. +.\" Check whether we are using grohtml. +.nr mH 0 +.if \n(.g \ +. if '\*(.T'html' \ +. nr mH 1 +. +. +.\" Map mono-width fonts to standard fonts for groff's TTY device. +.if n \{\ +. do ftr CR R +. do ftr CI I +. do ftr CB B +.\} +. +.\" groff has glyph entities for angle brackets. +.ie \n(.g \{\ +. ds la \(la\" +. ds ra \(ra\" +.\} +.el \{\ +. ds la <\" +. ds ra >\" +. \" groff's man macros control hyphenation with this register. +. nr HY 1 +.\} +. +.\" Start URL. +.de UR +. ds m1 \\$1\" +. nh +. if \\n(mH \{\ +. \" Start diversion in a new environment. +. do ev URL-div +. do di URL-div +. \} +.. +. +. +.\" End URL. +.de UE +. ie \\n(mH \{\ +. br +. di +. ev +. +. \" Has there been one or more input lines for the link text? +. ie \\n(dn \{\ +. do HTML-NS "" +. \" Yes, strip off final newline of diversion and emit it. +. do chop URL-div +. do URL-div +\c +. do HTML-NS +. \} +. el \ +. do HTML-NS "\\*(m1" +\&\\$*\" +. \} +. el \ +\\*(la\\*(m1\\*(ra\\$*\" +. +. hy \\n(HY +.. +. +. +.\" Start email address. +.de MT +. ds m1 \\$1\" +. nh +. if \\n(mH \{\ +. \" Start diversion in a new environment. +. do ev URL-div +. do di URL-div +. \} +.. +. +. +.\" End email address. +.de ME +. ie \\n(mH \{\ +. br +. di +. ev +. +. \" Has there been one or more input lines for the link text? +. ie \\n(dn \{\ +. do HTML-NS "" +. \" Yes, strip off final newline of diversion and emit it. +. do chop URL-div +. do URL-div +\c +. do HTML-NS +. \} +. el \ +. do HTML-NS "\\*(m1" +\&\\$*\" +. \} +. el \ +\\*(la\\*(m1\\*(ra\\$*\" +. +. hy \\n(HY +.. +.\" --- End of lines taken from groff an-ext.tmac +.\} +. +.hy 0 +. +.SH NAME +grep \- print lines that match patterns +. +.SH SYNOPSIS +.B grep +.RI [ OPTION .\|.\|.]\& +.I PATTERNS +.RI [ FILE .\|.\|.] +.br +.B grep +.RI [ OPTION .\|.\|.]\& +.B \-e +.I PATTERNS +\&.\|.\|.\& +.RI [ FILE .\|.\|.] +.br +.B grep +.RI [ OPTION .\|.\|.]\& +.B \-f +.I PATTERN_FILE +\&.\|.\|.\& +.RI [ FILE .\|.\|.] +. +.SH DESCRIPTION +.B grep +searches for +.I PATTERNS +in each +.IR FILE . +.I PATTERNS +is one or more patterns separated by newline characters, and +.B grep +prints each line that matches a pattern. +Typically +.I PATTERNS +should be quoted when +.B grep +is used in a shell command. +.PP +A +.I FILE +of +.RB "\*(lq" \- "\*(rq" +stands for standard input. +If no +.I FILE +is given, recursive searches examine the working directory, +and nonrecursive searches read standard input. +. +.SH OPTIONS +.SS "Generic Program Information" +.TP +.B \-\^\-help +Output a usage message and exit. +.TP +.BR \-V ", " \-\^\-version +Output the version number of +.B grep +and exit. +.SS "Pattern Syntax" +.TP +.BR \-E ", " \-\^\-extended\-regexp +Interpret +.I PATTERNS +as extended regular expressions (EREs, see below). +.TP +.BR \-F ", " \-\^\-fixed\-strings +Interpret +.I PATTERNS +as fixed strings, not regular expressions. +.TP +.BR \-G ", " \-\^\-basic\-regexp +Interpret +.I PATTERNS +as basic regular expressions (BREs, see below). +This is the default. +.TP +.BR \-P ", " \-\^\-perl\-regexp +Interpret +.I PATTERNS +as Perl-compatible regular expressions (PCREs). +This option is experimental when combined with the +.B \-z +.RB ( \-\^\-null\-data ) +option, and +.B "grep \-P" +may warn of unimplemented features. +.SS "Matching Control" +.TP +.BI \-e " PATTERNS" "\fR,\fP \-\^\-regexp=" PATTERNS +Use +.I PATTERNS +as the patterns. +If this option is used multiple times or is combined with the +.B \-f +.RB ( \-\^\-file ) +option, search for all patterns given. +This option can be used to protect a pattern beginning with \*(lq\-\*(rq. +.TP +.BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE +Obtain patterns from +.IR FILE , +one per line. +If this option is used multiple times or is combined with the +.B \-e +.RB ( \-\^\-regexp ) +option, search for all patterns given. +The empty file contains zero patterns, and therefore matches nothing. +If +.IR FILE +is +.B \- +, read patterns from standard input. +.TP +.BR \-i ", " \-\^\-ignore\-case +Ignore case distinctions in patterns and input data, +so that characters that differ only in case +match each other. +.TP +.B \-\^\-no\-ignore\-case +Do not ignore case distinctions in patterns and input data. +This is the default. +This option is useful for passing to shell scripts that already use +.BR \-i , +to cancel its effects because the two options override each other. +.TP +.BR \-v ", " \-\^\-invert\-match +Invert the sense of matching, to select non-matching lines. +.TP +.BR \-w ", " \-\^\-word\-regexp +Select only those lines containing matches that form whole words. +The test is that the matching substring must either be at the +beginning of the line, or preceded by a non-word constituent +character. +Similarly, it must be either at the end of the line +or followed by a non-word constituent character. +Word-constituent characters are letters, digits, and the underscore. +This option has no effect if +.B \-x +is also specified. +.TP +.BR \-x ", " \-\^\-line\-regexp +Select only those matches that exactly match the whole line. +For a regular expression pattern, this is like parenthesizing the +pattern and then surrounding it with +.B ^ +and +.BR $ . +.SS "General Output Control" +.TP +.BR \-c ", " \-\^\-count +Suppress normal output; instead print a count of +matching lines for each input file. +With the +.BR \-v ", " \-\^\-invert\-match +option (see above), count non-matching lines. +.TP +.BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ] +Surround the matched (non-empty) strings, matching lines, context lines, +file names, line numbers, byte offsets, and separators (for fields and +groups of context lines) with escape sequences to display them in color +on the terminal. +The colors are defined by the environment variable +.BR GREP_COLORS . +.I WHEN +is +.BR never ", " always ", or " auto . +.TP +.BR \-L ", " \-\^\-files\-without\-match +Suppress normal output; instead print the name +of each input file from which no output would +normally have been printed. +.TP +.BR \-l ", " \-\^\-files\-with\-matches +Suppress normal output; instead print +the name of each input file from which output +would normally have been printed. +Scanning each input file stops upon first match. +.TP +.BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM +Stop reading a file after +.I NUM +matching lines. +If +.I NUM +is zero, +.B grep +stops right away without reading input. +A +.I NUM +of \-1 is treated as infinity and +.B grep +does not stop; this is the default. +If the input is standard input from a regular file, +and +.I NUM +matching lines are output, +.B grep +ensures that the standard input is positioned to just after the last +matching line before exiting, regardless of the presence of trailing +context lines. +This enables a calling process to resume a search. +When +.B grep +stops after +.I NUM +matching lines, it outputs any trailing context lines. +When the +.B \-c +or +.B \-\^\-count +option is also used, +.B grep +does not output a count greater than +.IR NUM . +When the +.B \-v +or +.B \-\^\-invert\-match +option is also used, +.B grep +stops after outputting +.I NUM +non-matching lines. +.TP +.BR \-o ", " \-\^\-only\-matching +Print only the matched (non-empty) parts of a matching line, +with each such part on a separate output line. +.TP +.BR \-q ", " \-\^\-quiet ", " \-\^\-silent +Quiet; do not write anything to standard output. +Exit immediately with zero status if any match is found, +even if an error was detected. +Also see the +.B \-s +or +.B \-\^\-no\-messages +option. +.TP +.BR \-s ", " \-\^\-no\-messages +Suppress error messages about nonexistent or unreadable files. +.SS "Output Line Prefix Control" +.TP +.BR \-b ", " \-\^\-byte\-offset +Print the 0-based byte offset within the input file +before each line of output. +If +.B \-o +.RB ( \-\^\-only\-matching ) +is specified, +print the offset of the matching part itself. +.TP +.BR \-H ", " \-\^\-with\-filename +Print the file name for each match. +This is the default when there is more than one file to search. +This is a GNU extension. +.TP +.BR \-h ", " \-\^\-no\-filename +Suppress the prefixing of file names on output. +This is the default when there is only one file +(or only standard input) to search. +.TP +.BI \-\^\-label= LABEL +Display input actually coming from standard input as input coming from file +.IR LABEL . +This can be useful for commands that transform a file's contents +before searching, +e.g., +.BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H 'some pattern'" . +See also the +.B \-H +option. +.TP +.BR \-n ", " \-\^\-line\-number +Prefix each line of output with the 1-based line number +within its input file. +.TP +.BR \-T ", " \-\^\-initial\-tab +Make sure that the first character of actual line content lies on a +tab stop, so that the alignment of tabs looks normal. +This is useful with options that prefix their output to the actual content: +.BR \-H , \-n , +and +.BR \-b . +In order to improve the probability that lines +from a single file will all start at the same column, +this also causes the line number and byte offset (if present) +to be printed in a minimum size field width. +.TP +.BR \-Z ", " \-\^\-null +Output a zero byte (the ASCII +.B NUL +character) instead of the character that normally follows a file name. +For example, +.B "grep \-lZ" +outputs a zero byte after each file name instead of the usual newline. +This option makes the output unambiguous, even in the presence of file +names containing unusual characters like newlines. +This option can be used with commands like +.BR "find \-print0" , +.BR "perl \-0" , +.BR "sort \-z" , +and +.B "xargs \-0" +to process arbitrary file names, +even those that contain newline characters. +.SS "Context Line Control" +.TP +.BI \-A " NUM" "\fR,\fP \-\^\-after\-context=" NUM +Print +.I NUM +lines of trailing context after matching lines. +Places a line containing a group separator +.RB ( \-\^\- ) +between contiguous groups of matches. +With the +.B \-o +or +.B \-\^\-only\-matching +option, this has no effect and a warning is given. +.TP +.BI \-B " NUM" "\fR,\fP \-\^\-before\-context=" NUM +Print +.I NUM +lines of leading context before matching lines. +Places a line containing a group separator +.RB ( \-\^\- ) +between contiguous groups of matches. +With the +.B \-o +or +.B \-\^\-only\-matching +option, this has no effect and a warning is given. +.TP +.BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM +Print +.I NUM +lines of output context. +Places a line containing a group separator +.RB ( \-\^\- ) +between contiguous groups of matches. +With the +.B \-o +or +.B \-\^\-only\-matching +option, this has no effect and a warning is given. +.TP +.BI \-\^\-group\-separator= SEP +When +.BR \-A , +.BR \-B , +or +.B \-C +are in use, print +.I SEP +instead of +.B \-\^\- +between groups of lines. +.TP +.B \-\^\-no\-group\-separator +When +.BR \-A , +.BR \-B , +or +.B \-C +are in use, do not print a separator between groups of lines. +.SS "File and Directory Selection" +.TP +.BR \-a ", " \-\^\-text +Process a binary file as if it were text; this is equivalent to the +.B \-\^\-binary\-files=text +option. +.TP +.BI \-\^\-binary\-files= TYPE +If a file's data or metadata +indicate that the file contains binary data, +assume that the file is of type +.IR TYPE . +Non-text bytes indicate binary data; these are either output bytes that are +improperly encoded for the current locale, or null input bytes when the +.B \-z +option is not given. +.IP +By default, +.I TYPE +is +.BR binary , +and +.B grep +suppresses output after null input binary data is discovered, +and suppresses output lines that contain improperly encoded data. +When some output is suppressed, +.B grep +follows any output +with a message to standard error saying that a binary file matches. +.IP +If +.I TYPE +is +.BR without\-match , +when +.B grep +discovers null input binary data it assumes that the rest of the file +does not match; this is equivalent to the +.B \-I +option. +.IP +If +.I TYPE +is +.BR text , +.B grep +processes a binary file as if it were text; this is equivalent to the +.B \-a +option. +.IP +When +.I type +is +.BR binary , +.B grep +may treat non-text bytes as line terminators even without the +.B \-z +option. This means choosing +.B binary +versus +.B text +can affect whether a pattern matches a file. For +example, when +.I type +is +.B binary +the pattern +.B q$ might +match +.B q +immediately followed by a null byte, even though this +is not matched when +.I type +is +.BR text . +Conversely, when +.I type +is +.B binary +the pattern +.B .\& +(period) might not match a null byte. +.IP +.I Warning: +The +.B \-a +option might output binary garbage, +which can have nasty side effects if the output is a terminal and if the +terminal driver interprets some of it as commands. +On the other hand, when reading files whose text encodings are +unknown, it can be helpful to use +.B \-a +or to set +.B LC_ALL='C' +in the environment, in order to find more matches even if the matches +are unsafe for direct display. +.TP +.BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION +If an input file is a device, FIFO or socket, use +.I ACTION +to process it. +By default, +.I ACTION +is +.BR read , +which means that devices are read just as if they were ordinary files. +If +.I ACTION +is +.BR skip , +devices are silently skipped. +.TP +.BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION +If an input file is a directory, use +.I ACTION +to process it. +By default, +.I ACTION +is +.BR read , +i.e., read directories just as if they were ordinary files. +If +.I ACTION +is +.BR skip , +silently skip directories. +If +.I ACTION +is +.BR recurse , +read all files under each directory, recursively, +following symbolic links only if they are on the command line. +This is equivalent to the +.B \-r +option. +.TP +.BI \-\^\-exclude= GLOB +Skip any command-line file with a name suffix that matches the pattern +.IR GLOB , +using wildcard matching; a name suffix is either the whole +name, or a trailing part that starts with a non-slash character +immediately after a slash +.RB ( / ) +in the name. +When searching recursively, skip any subfile whose base name matches +.IR GLOB ; +the base name is the part after the last slash. +A pattern can use +.BR * , +.BR ? , +and +.BR [ .\|.\|. ]\& +as wildcards, and +.B \e +to quote a wildcard or backslash character literally. +.TP +.BI \-\^\-exclude\-from= FILE +Skip files whose base name matches any of the file-name globs read from +.I FILE +(using wildcard matching as described under +.BR \-\^\-exclude ). +.TP +.BI \-\^\-exclude\-dir= GLOB +Skip any command-line directory with a name suffix that matches the +pattern +.IR GLOB . +When searching recursively, skip any subdirectory +whose base name matches +.IR GLOB . +Ignore any redundant trailing slashes in +.IR GLOB . +.TP +.BR \-I +Process a binary file as if it did not contain matching data; this is +equivalent to the +.B \-\^\-binary\-files=without\-match +option. +.TP +.BI \-\^\-include= GLOB +Search only files whose base name matches +.I GLOB +(using wildcard matching as described under +.BR \-\^\-exclude ). +If contradictory +.B \-\^\-include +and +.B \-\^\-exclude +options are given, the last matching one wins. +If no +.B \-\^\-include +or +.B \-\^\-exclude +options match, a file is included unless the first such option is +.BR \-\^\-include . +.TP +.BR \-r ", " \-\^\-recursive +Read all files under each directory, recursively, +following symbolic links only if they are on the command line. +Note that if no file operand is given, +.B grep +searches the working directory. +This is equivalent to the +.B "\-d recurse" +option. +.TP +.BR \-R ", " \-\^\-dereference\-recursive +Read all files under each directory, recursively. +Follow all symbolic links, unlike +.BR \-r . +.SS "Other Options" +.TP +.B \-\^\-line\-buffered +Use line buffering on output. +This can cause a performance penalty. +.TP +.BR \-U ", " \-\^\-binary +Treat the file(s) as binary. +By default, under MS-DOS and MS-Windows, +.B grep +guesses whether a file is text or binary as described for the +.B \-\^\-binary\-files +option. +If +.B grep +decides the file is a text file, it strips the CR characters from the +original file contents (to make regular expressions with +.B ^ +and +.B $ +work correctly). +Specifying +.B \-U +overrules this guesswork, causing all files to be read and passed to the +matching mechanism verbatim; if the file is a text file with CR/LF +pairs at the end of each line, this will cause some regular +expressions to fail. +This option has no effect on platforms +other than MS-DOS and MS-Windows. +.TP +.BR \-z ", " \-\^\-null\-data +Treat input and output data as sequences of lines, each terminated by +a zero byte (the ASCII NUL character) instead of a newline. +Like the +.B \-Z +or +.B \-\^\-null +option, this option can be used with commands like +.B sort -z +to process arbitrary file names. +. +.SH "REGULAR EXPRESSIONS" +A regular expression is a pattern that describes a set of strings. +Regular expressions are constructed analogously to arithmetic +expressions, by using various operators to combine smaller expressions. +.PP +.B grep +understands three different versions of regular expression syntax: +\*(lqbasic\*(rq (BRE), \*(lqextended\*(rq (ERE) and \*(lqperl\*(rq (PCRE). +In GNU +.BR grep , +basic and extended regular expressions are merely different notations +for the same pattern-matching functionality. +In other implementations, basic regular expressions are ordinarily +less powerful than extended, though occasionally it is the other way around. +The following description applies to extended regular expressions; +differences for basic regular expressions are summarized afterwards. +Perl-compatible regular expressions have different functionality, and are +documented in +.BR pcre2syntax (3) +and +.BR pcre2pattern (3), +but work only if PCRE support is enabled. +.PP +The fundamental building blocks are the regular expressions +that match a single character. +Most characters, including all letters and digits, +are regular expressions that match themselves. +Any meta-character with special meaning +may be quoted by preceding it with a backslash. +.PP +The period +.B .\& +matches any single character. +It is unspecified whether it matches an encoding error. +.SS "Character Classes and Bracket Expressions" +A +.I "bracket expression" +is a list of characters enclosed by +.B [ +and +.BR ] . +It matches any single +character in that list. +If the first character of the list +is the caret +.B ^ +then it matches any character +.I not +in the list; it is unspecified whether it matches an encoding error. +For example, the regular expression +.B [0123456789] +matches any single digit. +.PP +Within a bracket expression, a +.I "range expression" +consists of two characters separated by a hyphen. +It matches any single character that sorts between the two characters, +inclusive, using the locale's collating sequence and character set. +For example, in the default C locale, +.B [a\-d] +is equivalent to +.BR [abcd] . +Many locales sort characters in dictionary order, and in these locales +.B [a\-d] +is typically not equivalent to +.BR [abcd] ; +it might be equivalent to +.BR [aBbCcDd] , +for example. +To obtain the traditional interpretation of bracket expressions, +you can use the C locale by setting the +.B LC_ALL +environment variable to the value +.BR C . +.PP +Finally, certain named classes of characters are predefined within +bracket expressions, as follows. +Their names are self explanatory, and they are +.BR [:alnum:] , +.BR [:alpha:] , +.BR [:blank:] , +.BR [:cntrl:] , +.BR [:digit:] , +.BR [:graph:] , +.BR [:lower:] , +.BR [:print:] , +.BR [:punct:] , +.BR [:space:] , +.BR [:upper:] , +and +.BR [:xdigit:] . +For example, +.B [[:alnum:]] +means the character class of numbers and +letters in the current locale. +In the C locale and ASCII +character set encoding, this is the same as +.BR [0\-9A\-Za\-z] . +(Note that the brackets in these class names are part of the symbolic +names, and must be included in addition to the brackets delimiting +the bracket expression.) +Most meta-characters lose their special meaning inside bracket expressions. +To include a literal +.B ] +place it first in the list. +Similarly, to include a literal +.B ^ +place it anywhere but first. +Finally, to include a literal +.B \- +place it last. +.SS Anchoring +The caret +.B ^ +and the dollar sign +.B $ +are meta-characters that respectively match the empty string at the +beginning and end of a line. +.SS "The Backslash Character and Special Expressions" +The symbols +.B \e< +and +.B \e> +respectively match the empty string at the beginning and end of a word. +The symbol +.B \eb +matches the empty string at the edge of a word, +and +.B \eB +matches the empty string provided it's +.I not +at the edge of a word. +The symbol +.B \ew +is a synonym for +.B [_[:alnum:]] +and +.B \eW +is a synonym for +.BR [^_[:alnum:]] . +.SS Repetition +A regular expression may be followed by one of several repetition operators: +.PD 0 +.TP +.B ? +The preceding item is optional and matched at most once. +.TP +.B * +The preceding item will be matched zero or more times. +.TP +.B + +The preceding item will be matched one or more times. +.TP +.BI { n } +The preceding item is matched exactly +.I n +times. +.TP +.BI { n ,} +The preceding item is matched +.I n +or more times. +.TP +.BI {, m } +The preceding item is matched at most +.I m +times. +This is a GNU extension. +.TP +.BI { n , m } +The preceding item is matched at least +.I n +times, but not more than +.I m +times. +.PD +.SS Concatenation +Two regular expressions may be concatenated; the resulting +regular expression matches any string formed by concatenating +two substrings that respectively match the concatenated +expressions. +.SS Alternation +Two regular expressions may be joined by the infix operator +.BR | ; +the resulting regular expression matches any string matching +either alternate expression. +.SS Precedence +Repetition takes precedence over concatenation, which in turn +takes precedence over alternation. +A whole expression may be enclosed in parentheses +to override these precedence rules and form a subexpression. +.SS "Back-references and Subexpressions" +The back-reference +.BI \e n\c +\&, where +.I n +is a single digit, matches the substring +previously matched by the +.IR n th +parenthesized subexpression of the regular expression. +.SS "Basic vs Extended Regular Expressions" +In basic regular expressions the meta-characters +.BR ? , +.BR + , +.BR { , +.BR | , +.BR ( , +and +.BR ) +lose their special meaning; instead use the backslashed +versions +.BR \e? , +.BR \e+ , +.BR \e{ , +.BR \e| , +.BR \e( , +and +.BR \e) . +. +.SH "EXIT STATUS" +Normally the exit status is 0 if a line is selected, 1 if no lines +were selected, and 2 if an error occurred. However, if the +.B \-q +or +.B \-\^\-quiet +or +.B \-\^\-silent +is used and a line is selected, the exit status is 0 even if an error +occurred. +. +.SH ENVIRONMENT +The behavior of +.B grep +is affected by the following environment variables. +.PP +The locale for category +.BI LC_ foo +is specified by examining the three environment variables +.BR LC_ALL , +.BR LC_\fIfoo\fP , +.BR LANG , +in that order. +The first of these variables that is set specifies the locale. +For example, if +.B LC_ALL +is not set, but +.B LC_MESSAGES +is set to +.BR pt_BR , +then the Brazilian Portuguese locale is used for the +.B LC_MESSAGES +category. +The C locale is used if none of these environment variables are set, +if the locale catalog is not installed, or if +.B grep +was not compiled with national language support (NLS). +The shell command +.B "locale \-a" +lists locales that are currently available. +.TP +.B GREP_COLORS +Controls how the +.B \-\^\-color +option highlights output. +Its value is a colon-separated list of capabilities +that defaults to +.B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36 +with the +.B rv +and +.B ne +boolean capabilities omitted (i.e., false). +Supported capabilities are as follows. +.RS +.TP +.B sl= +SGR substring for whole selected lines +(i.e., +matching lines when the +.B \-v +command-line option is omitted, +or non-matching lines when +.B \-v +is specified). +If however the boolean +.B rv +capability +and the +.B \-v +command-line option are both specified, +it applies to context matching lines instead. +The default is empty (i.e., the terminal's default color pair). +.TP +.B cx= +SGR substring for whole context lines +(i.e., +non-matching lines when the +.B \-v +command-line option is omitted, +or matching lines when +.B \-v +is specified). +If however the boolean +.B rv +capability +and the +.B \-v +command-line option are both specified, +it applies to selected non-matching lines instead. +The default is empty (i.e., the terminal's default color pair). +.TP +.B rv +Boolean value that reverses (swaps) the meanings of +the +.B sl= +and +.B cx= +capabilities +when the +.B \-v +command-line option is specified. +The default is false (i.e., the capability is omitted). +.TP +.B mt=01;31 +SGR substring for matching non-empty text in any matching line +(i.e., +a selected line when the +.B \-v +command-line option is omitted, +or a context line when +.B \-v +is specified). +Setting this is equivalent to setting both +.B ms= +and +.B mc= +at once to the same value. +The default is a bold red text foreground over the current line background. +.TP +.B ms=01;31 +SGR substring for matching non-empty text in a selected line. +(This is only used when the +.B \-v +command-line option is omitted.) +The effect of the +.B sl= +(or +.B cx= +if +.BR rv ) +capability remains active when this kicks in. +The default is a bold red text foreground over the current line background. +.TP +.B mc=01;31 +SGR substring for matching non-empty text in a context line. +(This is only used when the +.B \-v +command-line option is specified.) +The effect of the +.B cx= +(or +.B sl= +if +.BR rv ) +capability remains active when this kicks in. +The default is a bold red text foreground over the current line background. +.TP +.B fn=35 +SGR substring for file names prefixing any content line. +The default is a magenta text foreground over the terminal's default background. +.TP +.B ln=32 +SGR substring for line numbers prefixing any content line. +The default is a green text foreground over the terminal's default background. +.TP +.B bn=32 +SGR substring for byte offsets prefixing any content line. +The default is a green text foreground over the terminal's default background. +.TP +.B se=36 +SGR substring for separators that are inserted +between selected line fields +.RB ( : ), +between context line fields, +.RB ( \- ), +and between groups of adjacent lines when nonzero context is specified +.RB ( \-\^\- ). +The default is a cyan text foreground over the terminal's default background. +.TP +.B ne +Boolean value that prevents clearing to the end of line +using Erase in Line (EL) to Right +.RB ( \e33[K ) +each time a colorized item ends. +This is needed on terminals on which EL is not supported. +It is otherwise useful on terminals +for which the +.B back_color_erase +.RB ( bce ) +boolean terminfo capability does not apply, +when the chosen highlight colors do not affect the background, +or when EL is too slow or causes too much flicker. +The default is false (i.e., the capability is omitted). +.PP +Note that boolean capabilities have no +.BR = .\|.\|.\& +part. +They are omitted (i.e., false) by default and become true when specified. +.PP +See the Select Graphic Rendition (SGR) section +in the documentation of the text terminal that is used +for permitted values and their meaning as character attributes. +These substring values are integers in decimal representation +and can be concatenated with semicolons. +.B grep +takes care of assembling the result +into a complete SGR sequence +.RB ( \e33[ .\|.\|. m ). +Common values to concatenate include +.B 1 +for bold, +.B 4 +for underline, +.B 5 +for blink, +.B 7 +for inverse, +.B 39 +for default foreground color, +.B 30 +to +.B 37 +for foreground colors, +.B 90 +to +.B 97 +for 16-color mode foreground colors, +.B 38;5;0 +to +.B 38;5;255 +for 88-color and 256-color modes foreground colors, +.B 49 +for default background color, +.B 40 +to +.B 47 +for background colors, +.B 100 +to +.B 107 +for 16-color mode background colors, and +.B 48;5;0 +to +.B 48;5;255 +for 88-color and 256-color modes background colors. +.RE +.TP +\fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP +These variables specify the locale for the +.B LC_COLLATE +category, +which determines the collating sequence +used to interpret range expressions like +.BR [a\-z] . +.TP +\fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP +These variables specify the locale for the +.B LC_CTYPE +category, +which determines the type of characters, +e.g., which characters are whitespace. +This category also determines the character encoding, that is, whether +text is encoded in UTF-8, ASCII, or some other encoding. In the C or +POSIX locale, all characters are encoded as a single byte and every +byte is a valid character. +.TP +\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP +These variables specify the locale for the +.B LC_MESSAGES +category, +which determines the language that +.B grep +uses for messages. +The default C locale uses American English messages. +.TP +.B POSIXLY_CORRECT +If set, +.B grep +behaves as POSIX requires; otherwise, +.B grep +behaves more like other GNU programs. +POSIX requires that options that follow file names must be +treated as file names; by default, such options are permuted to the +front of the operand list and are treated as options. +Also, POSIX requires that unrecognized options be diagnosed as +\*(lqillegal\*(rq, but since they are not really against the law the default +is to diagnose them as \*(lqinvalid\*(rq. +. +.SH NOTES +This man page is maintained only fitfully; +the full documentation is often more up-to-date. +. +.SH COPYRIGHT +Copyright 1998-2000, 2002, 2005-2023 Free Software Foundation, Inc. +.PP +This is free software; +see the source for copying conditions. +There is NO warranty; +not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +. +.SH BUGS +.SS "Reporting Bugs" +Email bug reports to +.MT bug-grep@gnu.org +the bug-reporting address +.ME . +An +.UR https://lists.gnu.org/mailman/listinfo/bug-grep +email archive +.UE +and a +.UR https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep +bug tracker +.UE +are available. +.SS "Known Bugs" +Large repetition counts in the +.BI { n , m } +construct may cause +.B grep +to use lots of memory. +In addition, +certain other obscure regular expressions require exponential time +and space, and may cause +.B grep +to run out of memory. +.PP +Back-references are very slow, and may require exponential time. +. +.SH EXAMPLE +The following example outputs the location and contents of any line +containing \*(lqf\*(rq and ending in \*(lq.c\*(rq, +within all files in the current directory whose names +contain \*(lqg\*(rq and end in \*(lq.h\*(rq. +The +.B \-n +option outputs line numbers, the +.B \-\- +argument treats expansions of \*(lq*g*.h\*(rq starting with \*(lq\-\*(rq +as file names not options, +and the empty file /dev/null causes file names to be output +even if only one file name happens to be of the form \*(lq*g*.h\*(rq. +.PP +.in +2n +.EX +$ \fBgrep\fP \-n \-\- 'f.*\e.c$' *g*.h /dev/null +argmatch.h:1:/* definitions and prototypes for argmatch.c +.EE +.in +.PP +The only line that matches is line 1 of argmatch.h. +Note that the regular expression syntax used in the pattern differs +from the globbing syntax that the shell uses to match file names. +. +.SH "SEE ALSO" +.SS "Regular Manual Pages" +.BR awk (1), +.BR cmp (1), +.BR diff (1), +.BR find (1), +.BR perl (1), +.BR sed (1), +.BR sort (1), +.BR xargs (1), +.BR read (2), +.BR pcre2 (3), +.BR pcre2syntax (3), +.BR pcre2pattern (3), +.BR terminfo (5), +.BR glob (7), +.BR regex (7) +.SS "Full Documentation" +A +.UR https://www.gnu.org/software/grep/manual/ +complete manual +.UE +is available. +If the +.B info +and +.B grep +programs are properly installed at your site, the command +.IP +.B info grep +.PP +should give you access to the complete manual. +. +.\" Work around problems with some troff -man implementations. +.br +. +.\" Format for Emacs-maintained Dt string defined at this file's start. +.\" Local variables: +.\" time-stamp-format: "%:y-%02m-%02d" +.\" End: diff --git a/upstream/fedora-40/man1/grn.1 b/upstream/fedora-40/man1/grn.1 new file mode 100644 index 00000000..225da054 --- /dev/null +++ b/upstream/fedora-40/man1/grn.1 @@ -0,0 +1,978 @@ +'\" t +.TH \%grn 1 "24 January 2024" "groff 1.23.0" +.SH Name +\%grn \- embed Gremlin images in +.I groff +documents +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grn_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY \%grn +.RB [ \-C ] +.RB [ \-T\~\c +.IR dev ] +.RB [ \-M\~\c +.IR dir ] +.RB [ \-F\~\c +.IR dir ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY \%grn +.B \-? +. +.SY \%grn +.B \-\-help +.YS +. +. +.SY \%grn +.B \-v +. +.SY \%grn +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I \%grn +is a preprocessor for including +.I gremlin +pictures in +.MR \%troff 1 +input. +. +.I \%grn +writes to standard output, +processing only input lines between two that start with +.B .GS +and +.BR .GE . +. +Those lines must contain +.I \%grn +commands +(see below). +. +These macros request a +.I gremlin +file; +the picture in that file is converted and placed in the +.I \%troff +input stream. +. +.B .GS +may be called with a +.BR C , +.BR L , +or +.B R +argument to center, +left-, +or right-justify the whole +.I gremlin +picture +(the default is to center). +. +If no +.I file +is mentioned, +the standard input is read. +. +At the end of the picture, +the position on the page is the bottom of the +.I gremlin +picture. +. +If the +.I \%grn +entry is ended with +.B .GF +instead of +.BR .GE , +the position is left at the top of the picture. +. +. +.PP +Currently only the +.I me +macro package has support for +.BR .GS , +.BR .GE , +and +.BR .GF . +. +. +.PP +.I \%grn +produces drawing escape sequences that use +.IR groff 's +color scheme extension +.RB ( \[rs]D\[aq]F \~.\|.\|.\& \[aq] ), +and thus may not work with other +.IR troff s. +. +. +.\" ==================================================================== +.SS "\f[I]grn\f[] commands" +.\" ==================================================================== +. +Each input line between +.B .GS +and +.B .GE +may have one +.I \%grn +command. +. +Commands consist of one or two strings separated by white space, +the first string being the command and the second its operand. +. +Commands may be upper- or lowercase and abbreviated down to one +character. +. +. +.PP +Commands that affect a picture's environment +(those listed before +.RB \%\[lq] default \[rq], +see below) +are only in effect for the current picture: +the environment is reinitialized to the defaults at the start of the +next picture. +. +The commands are as follows. +. +. +.TP +.BI 1\~ N +.TQ +.BI 2\~ N +.TQ +.BI 3\~ N +.TQ +.BI 4\~ N +. +Set +.IR gremlin 's +text size number 1 +(2, +3, +or 4) +to +.I N +points. +. +The default is 12 +(16, +24, +and 36, +respectively). +. +. +.TP +.BI roman\~ f +.TQ +.BI italics\~ f +.TQ +.BI bold\~ f +.TQ +.BI special\~ f +Set the roman +(italics, +bold, +or special) +font to +.IR \%troff 's +font +.I f +(either a name or number). +. +The default is R +(I, +B, +and S, +respectively). +. +. +.TP +.BI l\~ f +.TQ +.BI stipple\~ f +Set the stipple font to +.IR \%troff 's +stipple font +.I f +(name or number). +. +The command +.B \%stipple +may be abbreviated down as far as +.RB \[lq] st \[rq] +(to avoid confusion with +.RB \%\[lq] special \[rq]). +. +There is +.I no +default for stipples +(unless one is set by the +.RB \%\[lq] default \[rq] +command), +and it is invalid to include a +.I gremlin +picture with polygons without specifying a stipple font. +. +. +.TP +.BI x\~ N +.TQ +.BI scale\~ N +Magnify the picture +(in addition to any default magnification) +by +.IR N , +a floating-point number larger than zero. +. +The command +.B scale +may be abbreviated down to +.RB \[lq] sc \[rq]. +. +. +.TP +.BI narrow\~ N +.TQ +.BI medium\~ N +.TQ +.BI thick\~ N +. +Set the thickness of +.IR gremlin 's +narrow +(medium and thick, +respectively) +lines to +.I N +times 0.15pt +(this value can be changed at compile time). +. +The default is 1.0 +(3.0 and 5.0, +respectively), +which corresponds to 0.15pt +(0.45pt and 0.75pt, +respectively). +. +A thickness value of zero selects the smallest available line thickness. +. +Negative values cause the line thickness to be proportional to the +current point size. +. +. +.TP +.BR pointscale\~ [ off | on ] +Scale text to match the picture. +. +Gremlin text is usually printed in the point size specified with the +commands +.BR 1 , +.BR 2 , +.BR 3 , +.RB or\~ 4 , +regardless of any scaling factors in the picture. +. +Setting +.B pointscale +will cause the point sizes to scale with the picture +(within +.IR \%troff 's +limitations, +of course). +. +An operand of anything but +.B off +will turn text scaling on. +. +. +.TP +.B default +Reset the picture environment defaults to the settings in the current +picture. +. +This is meant to be used as a global parameter setting mechanism at +the beginning of the +.I \%troff +input file, +but can be used at any time to reset the default settings. +. +. +.TP +.BI width\~ N +Force the picture to be +.I N +inches wide. +. +This overrides any scaling factors present in the same picture. +. +.RB \[lq] "width 0" \[rq] +is ignored. +. +. +.TP +.BI height\~ N +Force the picture to be +.I N +inches high, +overriding other scaling factors. +. +If both +.B width +and +.B height +are specified, +the tighter constraint will determine the scale of the picture. +. +.B height +and +.B width +commands are not saved with a +.RB \%\[lq] default \[rq] +command. +. +They will, +however, +affect point size scaling if that option is set. +. +. +.TP +.BI file\~ name +Get picture from +.I gremlin +file +.I name +located the current directory +(or in the library directory; +see the +.B \-M +option above). +. +If multiple +.B file +commands are given, +the last one controls. +. +If +.I name +doesn't exist, +an error message is reported and processing continues from the +.B .GE +line. +. +. +.\" ==================================================================== +.SS "Usage with \f[I]groff\f[]" +.\" ==================================================================== +. +Since +.I \%grn +is a preprocessor, +it has no access to elements of formatter state, +such as +indentation, +line length, +type size, +or +register values. +. +Consequently, +no +.I \%troff +input can be placed between the +.B .GS +and +.B .GE +macros. +. +However, +.I gremlin +text elements are subsequently processed by +.IR \%troff , +so anything valid in a single line of +.I \%troff +input is valid in a line of +.I gremlin +text +(barring the dot control character \[lq].\[rq] at the beginning of a +line). +. +Thus, +it is possible to have equations within a +.I gremlin +figure by including in the +.I gremlin +file +.I eqn \" language +expressions enclosed by previously defined delimiters +(e.g., +\[lq]$$\[rq]). +. +. +.PP +When using +.I \%grn +along with other preprocessors, +it is best to run +.MR \%tbl 1 +before +.IR \%grn , +.MR \%pic 1 , +and/or +.I ideal \" no GNU version yet +to avoid overworking +.IR \%tbl . +. +.MR \%eqn 1 +should always be run last. +. +.MR groff 1 +will automatically run preprocessors in the correct order. +. +. +.PP +A picture is considered an entity, +but that doesn't stop +.I \%troff +from trying to break it up if it falls off the end of a page. +. +Placing the picture between \[lq]keeps\[rq] in the +.I me +macros will ensure proper placement. +. +. +.PP +.I \%grn +uses +.IR \%troff 's +registers +.B g1 +through +.B g9 +and sets registers +.B g1 +and +.B g2 +to the width and height of the +.I gremlin +figure +(in device units) +before entering the +.B .GS +macro +(this is for those who want to rewrite these macros). +. +. +.\" ==================================================================== +.SS "Gremlin file format" +.\" ==================================================================== +. +There exist two distinct +.I gremlin +file formats: +the original format for AED graphic terminals, +and the Sun or X11 version. +. +An extension used by the Sun/X11 version allowing reference points with +negative coordinates is +.I not +compatible with the AED version. +. +As long as a +.I gremlin +file does not contain negative coordinates, +either format will be read correctly by either version of +.I gremlin +or +.IR \%grn . +. +The other difference in +Sun/X11 format is the use of names for picture objects +(e.g., +.BR POLYGON , +.BR CURVE ) +instead of numbers. +. +Files representing the same picture are shown below. +. +. +.PP +.ie t .ne 18v +.el .ne 19v +.TS +center, tab(@); +l lw(0.1i) l. +sungremlinfile@@gremlinfile +0 240.00 128.00@@0 240.00 128.00 +CENTCENT@@2 +240.00 128.00@@240.00 128.00 +185.00 120.00@@185.00 120.00 +240.00 120.00@@240.00 120.00 +296.00 120.00@@296.00 120.00 +*@@\-1.00 \-1.00 +2 3@@2 3 +10 A Triangle@@10 A Triangle +POLYGON@@6 +224.00 416.00@@224.00 416.00 +96.00 160.00@@96.00 160.00 +384.00 160.00@@384.00 160.00 +*@@\-1.00 \-1.00 +5 1@@5 1 +0@@0 +\-1@@\-1 +.TE +. +. +.IP \[bu] 2n +The first line of each +.I gremlin +file contains either the string +.RB \[lq] gremlinfile \[rq] +(AED) +or +.RB \[lq] sungremlinfile \[rq] +(Sun/X11). +. +. +.IP \[bu] +The second line of the file contains an orientation and +.I x +and +.I y +values for a positioning point, +separated by spaces. +. +The orientation, +either +.B 0 +or +.BR 1 , +is ignored by the Sun/X11 version. +. +.B 0 +means that +.I gremlin +will display things in horizontal format +(a drawing area wider than it is tall, +with a menu across the top). +. +.B 1 +means that +.I gremlin +will display things in vertical format +(a drawing area taller than it is wide, +with a menu on the left side). +. +.I x +and +.I y +are floating-point values giving a positioning point to be used when +this file is read into another file. +. +The stuff on this line really isn't all that important; +a value of +.RB \[lq] "1 0.00 0.00" \[rq] +is suggested. +. +. +.IP \[bu] +The rest of the file consists of zero or more element specifications. +. +After the last element specification is a line containing the string +.RB \[lq] \-1 \[rq]. +. +. +.IP \[bu] +Lines longer than 127 characters are truncated to that length. +. +. +.\" ==================================================================== +.SS "Element specifications" +.\" ==================================================================== +. +.IP \[bu] 2n +The first line of each element contains a single decimal number giving +the type of the element (AED) or its name (Sun/X11). +. +. +.IP +.ie t .ne 18v +.el .ne 19v +.TS +center, tab(@); +css +ccc +nBlBl. +\f[I]gremlin\f[] File Format: Object Type Specification +_ +AED Number@Sun/X11 Name@Description +0@BOTLEFT@bottom-left-justified text +1@BOTRIGHT@bottom-right-justified text +2@CENTCENT@center-justified text +3@VECTOR@vector +4@ARC@arc +5@CURVE@curve +6@POLYGON@polygon +7@BSPLINE@b-spline +8@BEZIER@B\['e]zier +10@TOPLEFT@top-left-justified text +11@TOPCENT@top-center-justified text +12@TOPRIGHT@top-right-justified text +13@CENTLEFT@left-center-justified text +14@CENTRIGHT@right-center-justified text +15@BOTCENT@bottom-center-justified text +.TE +. +. +.IP \[bu] +After the object type comes a variable number of lines, +each specifying a point used to display the element. +. +Each line contains an x-coordinate and a y-coordinate in floating-point +format, +separated by spaces. +. +The list of points is terminated by a line containing the string +.RB \[lq] "\-1.0 \-1.0" \[rq] +(AED) or a single asterisk, +.RB \[lq] * \[rq] +(Sun/X11). +. +. +.IP \[bu] +After the points comes a line containing two decimal values, +giving the brush and size for the element. +. +The brush determines the style in which things are drawn. +. +For vectors, +arcs, +and curves there are six valid brush values. +. +. +.IP +.TS +center, tab(@); +nB l. +1@thin dotted lines +2@thin dot-dashed lines +3@thick solid lines +4@thin dashed lines +5@thin solid lines +6@medium solid lines +.TE +. +. +.IP +For polygons, +one more value, +0, +is valid. +. +It specifies a polygon with an invisible border. +. +For text, +the brush selects a font as follows. +. +. +.IP +.TS +center, tab(@); +nB l. +1@roman (R font in \f[I]\%troff\f[]) +2@italics (I font in \f[I]\%troff\f[]) +3@bold (B font in \f[I]\%troff\f[]) +4@special (S font in \f[I]\%troff\f[]) +.TE +. +. +.IP +If you're using +.I \%grn +to run your pictures through +.IR groff , +the font is really just a starting font. +. +The text string can contain formatting sequences like +\[lq]\[rs]fI\[rq] +or +\[lq]\[rs]d\[rq] +which may change the font +(as well as do many other things). +. +For text, +the size field is a decimal value between 1 and 4. +. +It selects the size of the font in which the text will be drawn. +. +For polygons, +this size field is interpreted as a stipple number to fill the polygon +with. +. +The number is used to index into a stipple font at print time. +. +. +.IP \[bu] +The last line of each element contains a decimal number and a string of +characters, +separated by a single space. +. +The number is a count of the number of characters in the string. +. +This information is used only for text elements, +and contains the text string. +. +There can be spaces inside the text. +. +For arcs, +curves, +and vectors, +the character count is zero +.RB ( 0 ), +followed by exactly one space before the newline. +. +. +.\" ==================================================================== +.SS Coordinates +.\" ==================================================================== +. +.I gremlin +was designed for AED terminals, +and its coordinates reflect the AED coordinate space. +. +For vertical pictures, +.IR x \~values +range 116 to 511, +and +.IR y \~values +from 0 to 483. +. +For horizontal pictures, +.IR x \~values +range from 0 to 511, +and +.IR y \~values +from 0 to 367. +. +Although you needn't absolutely stick to this range, +you'll get better results if you at least stay in this vicinity. +. +Also, +point lists are terminated by a point of +(\-1, +\-1), +so you shouldn't ever use negative coordinates. +. +.I gremlin +writes out coordinates using the +.MR printf 3 +format \[lq]%f1.2\[rq]; +it's probably a good idea to use the same format if you want to modify +the +.I \%grn +code. +. +. +.\" ==================================================================== +.SS "Sun/X11 coordinates" +.\" ==================================================================== +. +There is no restriction on the range of coordinates used to create +objects in the Sun/X11 version of +.IR gremlin . +. +However, +files with negative coordinates +.I will +cause problems if displayed on the AED. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-?\& +and +.B \-\-help +display a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-C +Recognize +.B .GS +and +.B .GE +(and +.BR .GF ) +even when followed by a character other than space or newline. +. +. +.TP +.BI \-F\~ dir +Search +.I dir +for subdirectories +.IR dev name +.RI ( name +is the name of the output driver) +for the +.I DESC +file before the default font directories +.IR /etc/\:\%groff/\:\%site\-font , +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font , +and +.IR /usr/\:\%lib/\:\%font . +. +. +.TP +.BI \-M\~ dir +Prepend +.I dir +to the search path for +.I gremlin +files. +. +The default search path is the current directory, +the home directory, +.if !'no'no' .IR /etc/\:\%groff/\:\%site\-tmac , +.IR /etc/\:\%groff/\:\%site\-tmac , +and +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac , +in that order. +.\". +.\". +.\".TP +.\".B \-s +.\"This switch causes the picture to be traversed twice: +.\"The first time, +.\"only the interiors of filled polygons +.\"(as borderless polygons) +.\"are printed. +.\". +.\"The second time, +.\"the outline is printed as a series of line segments. +.\". +.\"This way, +.\"postprocessors that overwrite rather than merge picture elements +.\"(such as PostScript) +.\"can still have text and graphics on a shaded background. +. +. +.TP +.BI \-T\~ dev +Prepare device output using output driver +.IR dev . +. +The default is +.BR \%ps . +. +See +.MR groff 1 +for a list of valid devices. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +David Slattengren and Barry Roitblat wrote the original Berkeley +.IR grn . +. +Daniel Senderowicz and Werner Lemberg modified it for +.IR groff . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR gremlin 1 , +.MR groff 1 , +.MR \%pic 1 , +.MR ideal 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grn_1_man_C] +.do rr *groff_grn_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grodvi.1 b/upstream/fedora-40/man1/grodvi.1 new file mode 100644 index 00000000..3950e968 --- /dev/null +++ b/upstream/fedora-40/man1/grodvi.1 @@ -0,0 +1,633 @@ +.TH grodvi 1 "24 January 2024" "groff 1.23.0" +.SH Name +grodvi \- +.I groff +output driver for TeX DVI format +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2020, 2022 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grodvi_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el .ds tx TeX +. +.\" This macro definition is poor style from a portability standpoint, +.\" but it's a good test and demonstration of the standard font +.\" repertoire for the devices where it has any effect at all, and so +.\" should be retained. +.de FT +. if '\\*(.T'dvi' .ft \\$1 +.. +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grodvi +.RB [ \-dl ] +.RB [ \-F\~\c +.IR dir ] +.RB [ \-p\~\c +.IR paper-format ] +.RB [ \-w\~\c +.IR n ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY grodvi +.B \-\-help +.YS +. +. +.SY grodvi +.B \-v +. +.SY grodvi +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +DVI output driver translates the output of +.MR \%troff 1 +into \*[tx] DVI format. +. +Normally, +.I grodvi +is invoked by +.MR groff 1 +when the latter is given the +.RB \[lq] \-T\~dvi \[rq] +option. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR grodvi . +. +If no +.I file +arguments are given, +or if +.I file +is \[lq]\-\[rq], +.I grodvi +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.P +The DVI file generated by +.I grodvi +can interpreted by any correctly written DVI driver. +. +.I troff \" generic +drawing primitives are implemented using +.I tpic +version\~2 specials. +. +If the driver does not support these, +.B \[rs]D +escape sequences will not produce any output. +. +. +.P +Encapsulated PostScript (EPS) files can be easily included; +use the +.B PSPIC +macro. +. +.I pspic.tmac +is loaded automatically by +.IR dvi.tmac . +. +See +.MR groff_tmac 5 . +. +. +.P +The default color used by the +.B \[rs]m +and +.B \[rs]M +escape sequences is black. +. +Currently, +the stroke color for +.B \[rs]D +drawing escape sequences is black; +fill color values are translated to gray. +. +. +.P +In +.IR groff , +as in AT&T +.IR troff , \" AT&T +the +.B \[rs]N +escape sequence can be used to access any glyph in the current font by +its position in the corresponding TFM file. +. +. +.P +By design, +the DVI format doesn't care about the physical dimensions of the output +medium. +. +Instead, +.I grodvi +emits the equivalent to \*[tx]'s +.BI \%\[rs]special{\:\%papersize= width , length } +on the first page; +.I dvips +(or another DVI driver) +then sets the page size accordingly. +. +If either the page width or length is not positive, +no +.B \%papersize +special is output. +. +. +.P +A device control escape sequence +.BI \[rs]X\[aq] anything \[aq] +is translated to the same DVI file instructions as would be produced by +.BI \%\[rs]special{ anything } +in \*[tx]; +.I anything +cannot contain a newline. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +.I grodvi +supports the standard four styles: +.B R +(roman), +.B I +.RI ( italic ), +.B B +.RB ( bold ), +and +.B BI +(\f[BI]bold-italic\f[]). +. +Fonts are grouped into families +.B T +and +.B H +having members in each style. +. +\[lq]CM\[rq] abbreviates \[lq]Computer Modern\[rq]. +. +. +.RS +.TP +.B TR +.FT TR +CM Roman (cmr10) +.FT +. +.TQ +.B TI +.FT TI +CM Text Italic (cmti10) +.FT +. +.TQ +.B TB +.FT TB +CM Bold Extended Roman (cmbx10) +.FT +. +.TQ +.B TBI +.FT TBI +CM Bold Extended Text Italic (cmbxti10) +.FT +. +.TQ +.B HR +.FT HR +CM Sans Serif (cmss10) +.FT +. +.TQ +.B HI +.FT HI +CM Slanted Sans Serif (cmssi10) +.FT +. +.TQ +.B HB +.FT HB +CM Sans Serif Bold Extended (cmssbx10) +.FT +. +.TQ +.B HBI +.FT HBI +CM Slanted Sans Serif Bold Extended (cmssbxo10) +.FT +.RE +. +. +.LP +The following fonts are not members of a family. +. +. +.RS +.TP +.B CW +.FT CW +CM Typewriter Text (cmtt10) +.FT +. +.TQ +.B CWI +.FT CWI +CM Italic Typewriter Text (cmitt10) +.FT +.RE +. +. +.P +Special fonts include +.B MI +(cmmi10), +.B S +(cmsy10), +.B EX +(cmex10), +.B SC +(cmtex10, +only for +.BR CW ), +and, +perhaps surprisingly, +.BR TR , +.BR TI , +and +.BR CW , +.\" See font/devdvi/generate/Makefile for details. +because \*[tx] places some glyphs in text fonts that +.I troff \" generic +generally does not. +. +For italic fonts, +.B CWI +is used instead of +.BR CW . +. +. +.P +Finally, +the symbol fonts of the American Mathematical Society are available as +special fonts +.B SA +(msam10) and +.B SB +(msbm10). +. +They are are not mounted by default. +. +. +.br +.ne 2v +.P +The +.I \%troff +option +.B \-mec +loads the +.I ec.tmac +macro file, +employing the EC and TC fonts instead of CM. +. +These are designed similarly to the Computer Modern fonts; +further, +they provide Euro +.B \[rs][Eu] +and per mille +.B \[rs][%0] +glyphs. +. +.I ec.tmac +must be loaded before any language-specific macro files because it does +not set up the codes necessary for automatic hyphenation. +. +. +.\" ==================================================================== +.SS "Font description files" +.\" ==================================================================== +. +Use +.MR tfmtodit 1 +to create +.I groff +font description files from TFM +(\*[tx] font metrics) +files. +. +The font description file should contain the following additional +directives, +which +.I tfmtodit +generates automatically. +. +. +.TP +.BI internalname\~ name +The name of the TFM file +(without the +.I .tfm +extension) is +.IR name . +. +. +.TP +.BI checksum\~ n +The checksum in the TFM file is +.IR n . +. +. +.TP +.BI designsize\~ n +The design size in the TFM file is +.IR n . +. +. +.\" ==================================================================== +.SS "Drawing commands" +.\" ==================================================================== +. +.I grodvi +supports an additional drawing command. +. +. +.TP +.BI \[rs]D\[aq]R\~ "dh dv" \[aq] +Draw a rule +(solid black rectangle) +with one corner at the drawing position, +and the diagonally opposite corner at the drawing position +.RI +( dh , dv ), +which becomes the new drawing position afterward. +. +This command produces a rule in the DVI file and so can be printed even +with a driver that does not support +.I tpic +specials, +unlike the other +.B \[rs]D +commands. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-d +Do not use +.I tpic +specials to implement drawing commands. +. +Horizontal and vertical lines are implemented by rules. +. +Other drawing commands are ignored. +. +. +.TP +.BI \-F\~ dir +Prepend directory +.RI dir /dev name +to the search path for font and device description files; +.I name +is the name of the device, +usually +.BR dvi . +. +. +.TP +.B \-l +Use landscape orientation rather than portrait. +. +. +.TP +.BI \-p\~ paper-format +Set physical dimensions of output medium, +overriding the +.BR \%papersize , +.BR \%paperlength , +and +.B \%paperwidth +directives in the +.I DESC +file. +. +.I paper-format +can be any argument accepted by the +.B \%papersize +directive; +see +.MR groff_font 5 . +. +. +.TP +.BI \-w\~ n +Draw rules (lines) with a thickness of +.IR n \~thousandths +of an em. +. +The default thickness is +.B 40 +(0.04\~em). +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +lists directories in which to search for +.IR devdvi , +.IR grodvi 's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devdvi/\:DESC +describes the +.B dvi +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devdvi/ F +describes the font known +.RI as\~ F +on device +.BR dvi . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:dvi\:.tmac +defines font mappings, +special characters, +and colors for use with the +.B dvi +output device. +. +It is automatically loaded by +.I \%troffrc +when the +.B dvi +output device is selected. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:ec\:.tmac +configures the +.B dvi +output device to use +the EC and TC font families instead of CM +(Computer Modern). +. +. +.\" ==================================================================== +.SH Bugs +.\" ==================================================================== +. +DVI files produced by +.I grodvi +use a different resolution +(57,816 units per inch) +from those produced by \*[tx]. +. +Incorrectly written drivers which assume the resolution used by \*[tx], +rather than using the resolution specified in the DVI file, +will not work with +.IR grodvi . +. +. +.LP +When using the +.B \-d +option with boxed tables, +vertical and horizontal lines can sometimes protrude by one pixel. +. +This is a consequence of the way \*[tx] requires that the heights +and widths of rules be rounded. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.UR https://\:texfaq\:.org/\:FAQ\-\:ECfonts +\[lq]What are the EC fonts?\[rq] +.UE ; +\*[tx] FAQ: Frequently Asked Question List for \*[tx] +. +. +.P +.MR tfmtodit 1 , +.MR groff 1 , +.MR \%troff 1 , +.MR groff_out 5 , +.MR groff_font 5 , +.MR groff_char 7 , +.MR groff_tmac 5 +. +. +.\" Clean up. +.rm FT +.rm tx +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grodvi_1_man_C] +.do rr *groff_grodvi_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/groff.1 b/upstream/fedora-40/man1/groff.1 new file mode 100644 index 00000000..c3cdcfdc --- /dev/null +++ b/upstream/fedora-40/man1/groff.1 @@ -0,0 +1,2403 @@ +.TH groff 1 "24 January 2024" "groff 1.23.0" +.SH Name +groff \- front end to the GNU +.I roff +document formatting system +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2022 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, with no Front-Cover Texts, +.\" and with no Back-Cover Texts. +.\" +.\" A copy of the Free Documentation License is included as a file +.\" called FDL in the main directory of the groff source package. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +.\" Define a string for the TeX logo. +.ie t .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el .ds TeX TeX +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY groff +.RB [ \-abcCeEgGijklNpRsStUVXzZ ] +.RB [ \-d\~\c +.IR ctext ] +.RB [ \-d\~\c +.IB string =\c +.IR text ] +.RB [ \-D\~\c +.IR fallback-encoding ] +.RB [ \-f\~\c +.IR font-family ] +.RB [ \-F\~\c +.IR font-directory ] +.RB [ \-I\~\c +.IR inclusion-directory ] +.RB [ \-K\~\c +.IR input-encoding ] +.RB [ \-L\~\c +.IR spooler-argument ] +.RB [ \-m\~\c +.IR macro-package ] +.RB [ \-M\~\c +.IR macro-directory ] +.RB [ \-n\~\c +.IR page-number ] +.RB [ \-o\~\c +.IR page-list ] +.RB [ \-P\~\c +.IR postprocessor-argument ] +.RB [ \-r\~\c +.IR cnumeric-expression ] +.RB [ \-r\~\c +.IB register =\c +.IR numeric-expression ] +.RB [ \-T\~\c +.IR output-device ] +.RB [ \-w\~\c +.IR warning-category ] +.RB [ \-W\~\c +.IR warning-category ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY groff +.B \-h +. +.SY groff +.B \-\-help +.YS +. +. +.SY groff +.B \-v +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +. +.SY groff +.B \-\-version +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I groff +is the primary front end to the GNU +.I roff +document formatting system. +. +.\" BEGIN Keep parallel with groff.texi node "What Is groff?". +.\" This language is slightly expanded from that in the "ANNOUNCE" file +.\" and on the groff home page. +GNU +.I roff +is a typesetting system that reads plain text input files that include +formatting commands to produce output in PostScript, +PDF, +HTML, +DVI, +or other formats, +or for display to a terminal. +. +Formatting commands can be low-level typesetting primitives, +macros from a supplied package, +or user-defined macros. +. +All three approaches can be combined. +. +If no +.I file +operands are specified, +or if +.I file +is +.RB \[lq] \- \[rq], +.I groff +reads the standard input stream. +. +. +.P +A reimplementation and extension of the typesetter from AT&T Unix, +.I groff +is present on most POSIX systems owing to its long association with Unix +manuals +(including man pages). +. +It and its predecessor are notable for their production of several +best-selling software engineering texts. +. +.I groff +is capable of producing typographically sophisticated documents while +consuming minimal system resources. +.\" END Keep parallel with groff.texi node "What Is groff?". +. +. +.P +The +.I groff +command orchestrates the execution of preprocessors, +the transformation of input documents into a device-independent page +description language, +and the production of output from that language. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-h +and +.B \-\-help +display a usage message and exit. +. +. +.P +Because +.I groff +is intended to subsume most users' direct invocations of the +.MR \%troff 1 +formatter, +the two programs share a set of options. +. +However, +.I groff +has some options that +.I \%troff +does not share, +and others which +.I groff +interprets differently. +. +At the same time, +not all valid +.I \%troff +options can be given to +.IR groff . +. +. +.\" ==================================================================== +.SS "\f[I]groff\f[]-specific options" +.\" ==================================================================== +. +The following options either do not exist in +GNU +.I troff \" GNU +or are interpreted differently by +.IR groff . +. +. +.TP +.BI \-D\~ enc +Set fallback input encoding used by +.MR preconv 1 +to +.IR enc ; +implies +.BR \-k . +. +. +.TP +.B \-e +Run +.MR \%eqn 1 +preprocessor. +. +. +.TP +.B \-g +Run +.MR \%grn 1 +preprocessor. +. +. +.TP +.B \-G +Run +.MR grap 1 +preprocessor; +implies +.BR \-p . +. +. +.TP +.BI \-I\~ dir +Works as +.IR \%troff 's +option +(see below), +but also implies +.B \-g +and +.BR \-s . +. +It is passed to +.MR \%soelim 1 +and the output driver, +and +.I \%grn +is passed an +.B \-M +option with +.I dir +as its argument. +. +. +.TP +.B \-j +Run +.MR \%chem 1 +preprocessor; +implies +.BR \-p . +. +. +.TP +.B \-k +Run +.MR preconv 1 +preprocessor. +. +Refer to its man page for its behavior if neither of +.IR groff 's +.B \-K +or +.B \-D +options is also specified. +. +. +.TP +.BI \-K\~ enc +Set input encoding used by +.MR preconv 1 +to +.IR enc ; +implies +.BR \-k . +. +. +.TP +.B \-l +Send the output to a spooler program for printing. +. +The +.RB \[lq] print \[rq] +directive in the device description file +specifies the default command to be used; +see +.MR groff_font 5 . +. +If no such directive is present for the output device, +.ie ''' \{\ +this option is ignored. +.\} +.el \{\ +output is piped to +.MR 1 . +.\} +. +See options +.B \-L +and +.BR \-X . +. +. +.TP +.BI \-L\~ arg +Pass +.I arg +to the print spooler program. +. +If multiple +.IR arg s +are required, +pass each with a separate +.B \-L +option. +. +.I groff +does not prefix an option dash to +.I arg +before passing it to the spooler program. +. +. +.TP +.B \-M +Works as +.IR \%troff 's +option +(see below), +but is also passed to +.MR \%eqn 1 , +.MR grap 1 , +and +.MR \%grn 1 . +. +. +.TP +.B \-N +Prohibit newlines between +.I eqn \" language +delimiters: +pass +.B \-N +to +.MR \%eqn 1 . +. +. +.TP +.B \-p +Run +.MR \%pic 1 +preprocessor. +. +. +.TP +.BI \-P\~ arg +Pass +.I arg +to the postprocessor. +. +If multiple +.IR arg s +are required, +pass each with a separate +.B \-P +option. +. +.I groff +does not prefix an option dash to +.I arg +before passing it to the postprocessor. +. +. +.TP +.B \-R +Run +.MR \%refer 1 +preprocessor. +. +No mechanism is provided for passing arguments to +.I \%refer +because most +.I \%refer +options have equivalent language elements that can be specified within +the document. +. +. +.TP +.B \-s +Run +.MR \%soelim 1 +preprocessor. +. +. +.TP +.B \-S +Operate in \[lq]safer\[rq] mode; +see +.B \-U +below for its opposite. +. +For security reasons, +safer mode is enabled by default. +. +. +.TP +.B \-t +Run +.MR \%tbl 1 +preprocessor. +. +. +.TP +.BI \-T\~ dev +Direct +.I \%troff +to format the input for the output device +.IR dev . +. +.I groff +then calls an output driver to convert +.IR \%troff 's +output to a form appropriate for +.IR dev ; +see subsection \[lq]Output devices\[rq] below. +. +. +.TP +.B \-U +Operate in unsafe mode: +pass the +.B \-U +option to +.I \%pic +and +.IR \%troff . +. +. +.TP +.B \-v +.TQ +.B \-\-version +Write version information for +.I groff +and all programs run by it to the standard output stream; +that is, +the given command line is processed in the usual way, +passing +.B \-v +to the formatter and any pre- or postprocessors invoked. +. +. +.TP +.B \-V +Output the pipeline that +.I groff +would run to the standard output stream, +but do not execute it. +. +If given more than once, +.I groff +both writes and runs the pipeline. +. +. +.TP +.B \-X +Use +.MR gxditview 1 +instead of the usual postprocessor to (pre)view a document on an X11 +display. +. +Combining this option with +.B \-Tps +uses the font metrics of the PostScript device, +whereas the +.B \-TX75 +and +.B \-TX100 +options use the metrics of X11 fonts. +. +. +.TP +.B \-Z +Disable postprocessing. +. +.I \%troff +output will appear on the standard output stream +(unless suppressed with +.BR \-z ); +see +.MR groff_out 5 +for a description of this format. +. +. +.\" ==================================================================== +.SS "Transparent options" +.\" ==================================================================== +. +The following options are passed as-is to the formatter program +.MR \%troff 1 +and described in more detail in its man page. +. +. +.TP +.B \-a +Generate a plain text approximation of the typeset output. +. +. +.TP +.B \-b +Write a backtrace to the standard error stream on each error or warning. +. +. +.TP +.B \-c +Start with color output disabled. +. +. +.TP +.B \-C +Enable AT&T +.I troff \" AT&T +compatibility mode; +implies +.BR \-c . +. +. +.TP +.BI \-d\~ cs +.TQ +.BI \-d\~ name = string +Define string. +. +. +.TP +.B \-E +Inhibit +.I \%troff +error messages; +implies +.BR \-Ww . +. +. +.TP +.BI \-f\~ fam +Set default font family. +. +. +.TP +.BI \-F\~ dir +Search in directory +.I dir +for the selected output device's directory of device and font +description files. +. +. +.TP +.B \-i +Process standard input after the specified input files. +. +. +.TP +.BI \-I\~ dir +Search +.I dir +for input files. +. +. +.TP +.BI \-m\~ name +Process +.RI name .tmac +before input files. +. +. +.TP +.BI \-M\~ dir +Search directory +.I dir +for macro files. +. +. +.TP +.BI \-n\~ num +Number the first page +.IR num . +. +. +.TP +.BI \-o\~ list +Output only pages in +.IR list . +. +. +.TP +.BI \-r\~ cnumeric-expression +.TQ +.BI \-r\~ register = numeric-expression +Define register. +. +. +.TP +.BI \-w\~ name +.TQ +.BI \-W\~ name +Enable +.RB ( \-w ) +or inhibit +.RB ( \-W ) +emission of warnings in category +.IR name . +. +. +.TP +.B \-z +Suppress formatted device-independent output of +.IR \%troff . +. +. +.\" ==================================================================== +.SH Usage +.\" ==================================================================== +. +The architecture of the GNU +.I roff +system +follows that of other device-independent +.I roff +implementations, +comprising preprocessors, +macro packages, +output drivers +(or \[lq]postprocessors\[rq]), +a suite of utilities, +and the formatter +.I \%troff +at its heart. +. +See +.MR roff 7 +for a survey of how a +.I roff +system works. +. +. +.P +The front end programs available in the GNU +.I roff +system make it easier to use than traditional +.IR roff s +that required the construction of pipelines or use of temporary files to +carry a source document from maintainable form to device-ready output. +. +The discussion below summarizes the constituent parts of the GNU +.I roff +system. +. +It complements +.MR roff 7 +with +.IR groff -specific +information. +. +. +.\" ==================================================================== +.SS "Getting started" +.\" ==================================================================== +. +Those who prefer to learn by experimenting or are desirous of rapid +feedback from the system may wish to start with a \[lq]Hello, +world!\&\[rq] document. +. +. +.P +.EX +$ \c +.B echo \[dq]Hello, world!\[dq] | groff \-Tascii \ +| sed \[aq]/\[ha]$/d\[aq] +Hello, world! +.EE +. +. +.P +We used a +.I sed +command only to eliminate the 65 blank lines that would otherwise flood +the terminal screen. +. +.RI ( roff +systems were developed in the days of paper-based terminals with 66 +lines to a page.) +. +. +.P +Today's users may prefer output to a UTF-8-capable terminal. +. +. +.P +.EX +$ \c +.B echo \[dq]Hello, world!\[dq] | groff \-Tutf8 \ +| sed \[aq]/\[ha]$/d\[aq] +.EE +. +. +.P +Producing PDF, +HTML, +or \*[TeX]'s DVI is also straightforward. +. +The hard part may be selecting a viewer program for the output. +. +. +.P +.EX +$ \c +.B echo \[dq]Hello, world!\[dq] | groff \-Tpdf > hello.pdf +$ \c +.B evince hello.pdf +$ \c +.B echo \[dq]Hello, world!\[dq] | groff \-Thtml > hello.html +$ \c +.B firefox hello.html +$ \c +.B echo \[dq]Hello, world!\[dq] | groff \-Tdvi > hello.dvi +$ \c +.B xdvi hello.html +.EE +. +. +.\" ==================================================================== +.SS "Using \f[I]groff\f[] as a REPL" +.\" ==================================================================== +. +Those with a programmer's bent may be pleased to know that they can use +.I groff +in a read-evaluate-print loop (REPL). +. +Doing so can be handy to verify one's understanding of the formatter's +behavior and/or the syntax it accepts. +. +Turning on all warnings with +.B \-ww +can aid this goal. +. +. +.P +.EX +$ \c +.B groff \-ww \-Tutf8 +.B \[rs]# This is a comment. Let\[aq]s define a register. +.B .nr a 1 +.B \[rs]# Do integer arithmetic with operators evaluated left-to-right. +.B .nr b \[rs]n[a]+5/2 +.ne 2v +.B \[rs]# Let\[aq]s get the result on the standard error stream. +.B .tm \[rs]n[b] +3 +.B \[rs]# Now we\[aq]ll define a string. +.B .ds name Leslie\[rs]" This is another form of comment. +.B .nr b (\[rs]n[a] + (7/2)) +.B \[rs]# Center the next two text input lines. +.B .ce 2 +.B Hi, \[rs]*[name]. +.B Your secret number is \[rs]n[b]. +.B \[rs]# We will see that the division rounded toward zero. +.B It is +.B \[rs]# Here\[aq]s an if-else control structure. +.B .ie (\[rs]n[b] % 2) odd. +.B .el even. +.B \[rs]# This trick sets the page length to the current vertical +.B \[rs]# position, so that blank lines don\[aq]t spew when we\[aq]re \ +done. +.B .pl \[rs]n[nl]u +.I + Hi, Leslie. + Your secret number is 4. +It is even. +.EE +. +. +.\" ==================================================================== +.SS "Paper format" +.\" ==================================================================== +. +In GNU +.IR roff , +the page dimensions for the formatter +.I \%troff +and for output devices are handled separately. +. +In the formatter, +requests are used to set the page length +.RB ( .pl ), +page offset +(or left margin, +.BR .po ), +and line length +.RB ( .ll ). +. +The right margin is not explicitly configured; +the combination of page offset and line length provides the information +necessary to derive it. +. +The +.I papersize +macro package, +automatically loaded by +.IR \%troff , +provides an interface for configuring page dimensions by convenient +names, +like \[lq]letter\[rq] or +\[lq]A4\[rq]; +see +.MR groff_tmac 5 . +. +The formatter's default in this installation is +.RB \[lq] \%letter \[rq]. +. +. +.P +It is up to each macro package to respect the page dimensions configured +in this way. +. +Some offer alternative mechanisms. +. +. +.P +For each output device, +the size of the output medium can be set in its +.I DESC +file. +. +Most output drivers also recognize a command-line option +.B \-p +to override the default dimensions and an option +.B \-l +to use landscape orientation. +. +See +.MR groff_font 5 +for a description of the +.B papersize +directive, +which takes an argument of the same form as +.BR \-p . +. +The output driver's man page, +such as +.MR grops 1 , +may also be helpful. +. +.I groff +uses the command-line option +.B \-P +to pass options to output devices; +for example, +use the following for PostScript output on A4 paper in landscape +orientation. +. +. +.IP +.EX +groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps +.EE +. +. +.\" ==================================================================== +.SS "Front end" +.\" ==================================================================== +. +The +.I groff +program is a wrapper around the +.MR \%troff 1 +program. +. +It allows one to specify preprocessors via command-line options and +automatically runs the appropriate postprocessor for the selected +output device. +. +Doing so, +the manual construction of pipelines or management of temporary files +required of users of traditional +.MR roff 7 +systems can be avoided. +. +Use the +.MR grog 1 +program to infer an appropriate +.I groff +command line to format a document. +. +. +.\" ==================================================================== +.SS Language +.\" ==================================================================== +. +Input to a +.I roff +system is in plain text interleaved with control lines and escape +sequences. +. +The combination constitutes a document in one of a family of languages +we also call +.IR roff ; +see +.MR roff 7 +for background. +. +An overview of GNU +.I roff +language syntax and features, +including lists of all supported escape sequences, +requests, +and predefined registers, +can be found in +.MR groff 7 . +. +GNU +.I roff +extensions to the AT&T +.I troff +language, +a common subset of +.I roff +dialects extant today, +are detailed in +.MR groff_diff 7 . +. +. +.\" ==================================================================== +.SS Preprocessors +.\" ==================================================================== +. +A preprocessor interprets a domain-specific language that produces +.I roff +language output. +. +Frequently, +such input is confined to sections or regions of a +.I roff +input file +(bracketed with macro calls specific to each preprocessor), +which it replaces. +. +Preprocessors therefore often interpret a subset of +.I roff +syntax along with their own language. +. +GNU +.I roff +provides reimplementations of most preprocessors familiar to users of +AT&T +.IR troff ; \" AT&T +these routinely have extended features and/or require GNU +.I troff \" GNU +to format their output. +. +. +.br +.ne 10v +.P +.RS +.TS +tab($); +Li Lx. +\%tbl$lays out tables; +\%eqn$typesets mathematics; +\%pic$draws diagrams; +\%refer$processes bibliographic references; +\%soelim$preprocesses \[lq]sourced\[rq] input files; +\%grn$T{ +renders +.MR gremlin 1 +diagrams; +T} +\%chem$T{ +draws chemical structural formul\[ae] +using +.IR pic ; \" generic +T} +gperl$T{ +populates +.I groff +registers and strings using +.MR perl 1 ; +T} +glilypond$T{ +embeds +.I LilyPond +sheet music; +and +T} +gpinyin$T{ +eases Mandarin Chinese input using Hanyu Pinyin. +T} +.TE +.RE +. +. +.P +A preprocessor unique to GNU +.I roff +is +.MR preconv 1 , +which converts various input encodings to something GNU +.I troff \" GNU +can understand. +. +When used, +it is run before any other preprocessors. +. +. +.P +Most preprocessors enclose content between a pair of characteristic +tokens. +. +Such a token must occur at the beginning of an input line and use the +dot control character. +. +Spaces and tabs must not follow the control character or precede the +end of the input line. +. +Deviating from these rules defeats a token's recognition by the +preprocessor. +. +Tokens are generally preserved in preprocessor output and interpreted as +macro calls subsequently by +.IR \%troff . +. +The +.I \%ideal +preprocessor is not yet available in +.IR groff . +. +. +.P +.TS +box, center, tab (^); +c | c | c +CfCR | CfCR | CfCR. +preprocessor^starting token^ending token += +\%chem^.cstart^.cend +\%eqn^.EQ^.EN +grap^.G1^.G2 +\%grn^.GS^.GE +.\" Keep the .IF line below the \%ideal line. +\%ideal^.IS^.IE +^^.IF +.\" Keep the .PF line below the \%pic line. +\%pic^.PS^.PE +^^.PF +^^.PY +\%refer^.R1^.R2 +\%tbl^.TS^.TE +_ +glilypond^.lilypond start^.lilypond stop +gperl^.Perl start^.Perl stop +gpinyin^.pinyin start^.pinyin stop +.TE +. +. +.\" ==================================================================== +.SS "Macro packages" +.\" ==================================================================== +. +Macro files are +.I roff +input files designed to produce no output themselves but instead ease +the preparation of other +.I roff +documents. +. +When a macro file is installed at a standard location and suitable for +use by a general audience, +it is termed a +.IR "macro package" . +. +. +.P +Macro packages can be loaded prior to any +.I roff +input documents with the +.BR \-m \~option. +. +The GNU +.I roff +system implements most well-known macro packages for AT&T +.I troff \" AT&T +.\" exceptions: mpm, mv +in a compatible way and extends them. +. +These have one- or two-letter names arising from intense practices of +naming economy in early Unix culture, +a laconic approach that led to many of the packages being identified in +general usage with the +.I nroff +and +.I troff +option letter used to invoke them, +sometimes to punning effect, +as with \[lq]man\[rq] +(short for \[lq]manual\[rq]), +and even with the option dash, +as in the case of the +.I s +package, +much better known as +.I ms +or even +.IR \-ms . +. +. +.P +Macro packages serve a variety of purposes. +. +Some are \[lq]full-service\[rq] packages, +adopting responsibility for page layout among other fundamental tasks, +and defining their own lexicon of macros for document composition; +each such package stands alone and a given document can use at most one. +. +. +.TP +.I an +is used to compose man pages in the format originating in Version\~7 +Unix (1979); +see +.MR groff_man 7 . +. +It can be specified on the command line as +.BR \-man . +. +. +.TP +.I doc +is used to compose man pages in the format originating in 4.3BSD-Reno +(1990); +see +.MR groff_mdoc 7 . +. +It can be specified on the command line as +.BR \-mdoc . +. +. +.TP +.I e +is the Berkeley general-purpose macro suite, +developed as an alternative to AT&T's +.IR s ; +see +.MR groff_me 7 . +. +It can be specified on the command line as +.BR \-me . +. +. +.TP +.I m +implements the format used by the +second-generation AT&T macro suite for general documents, +a successor to +.IR s ; +see +.MR groff_mm 7 . +. +It can be specified on the command line as +.BR \-mm . +. +. +.TP +.I om +(invariably called \[lq]mom\[rq]) +is a modern package written by Peter Schaffter specifically for GNU +.IR roff . +. +Consult the +.UR file://\:/usr/\:\%share/\:\%doc/\:\%groff/\:\%html/\:mom/\:toc\:.html +.I mom +HTML manual +.UE +for extensive documentation. +. +She\[em]for +.I mom +takes the female pronoun\[em]can be specified on the command line as +.BR \-mom . +. +. +.TP +.I s +is the original AT&T general-purpose document format; +see +.MR groff_ms 7 . +. +It can be specified on the command line as +.BR \-ms . +. +. +.P +Others are supplemental. +. +For instance, +. +.I \%andoc +is a wrapper package specific to GNU +.I roff +that recognizes whether a document uses +.I man +or +.I mdoc +format and loads the corresponding macro package. +. +It can be specified on the command line as +.BR \%\-mandoc . +. +A +.MR man 1 +librarian program \" such as man-db, since 2001 +may use this macro file to delegate loading of the correct macro +package; +it is thus unnecessary for +.I man +itself to scan the contents of a document to decide the issue. +. +. +.P +Many macro files augment the function of the full-service packages, +or of +.I roff +documents that do not employ such a package\[em]the latter are sometimes +characterized as \[lq]raw\[rq]. +. +These auxiliary packages are described, +along with +details of macro file naming and placement, +in +.MR groff_tmac 5 . +. +. +.\" ==================================================================== +.SS Formatters +.\" ==================================================================== +. +The formatter, +the program that interprets +.I roff +language input, +is +.MR \%troff 1 . +. +It provides the features of the AT&T +.I troff \" AT&T +and +.I nroff \" AT&T +programs as well as many extensions. +. +The command-line option +.B \-C +switches +.I \%troff +into +.IR "compatibility mode" , +which tries to emulate AT&T +.I troff \" AT&T +as closely as is practical to enable the formatting of documents written +for the older system. +. +. +.P +A shell script, +.MR \%nroff 1 , +emulates the behavior of AT&T +.IR nroff . \" AT&T +. +It attempts to correctly encode the output based on the locale, +relieving the user of the need to specify an output device with the +.B \-T +option and is therefore convenient for use with terminal output devices, +described in the next subsection. +. +. +.P +GNU +.I troff \" GNU +generates output in a device-independent, +but not device-agnostic, +page description language detailed in +.MR groff_out 5 . +. +. +.\" ==================================================================== +.SS "Output devices" +.\" ==================================================================== +. +.I \%troff +output is formatted for a particular +.IR "output device" , +typically specified by the +.B \-T +option to the formatter or a front end. +. +If neither this option nor the +.I \%GROFF_TYPESETTER +environment variable is used, +the default output device is +.BR \%ps . +. +An output device may be any of the following. +. +. +.TP 9n \" to fit "X100\-12" even on troff devices +.B ascii +for terminals using the ISO 646 1991:IRV character set and encoding, +also known as US-ASCII. +. +. +.TP +.B cp1047 +for terminals using the IBM code page 1047 character set and encoding. +. +. +.TP +.B dvi +for TeX DVI format. +. +. +.TP +.B html +.TQ +.B xhtml +for HTML and XHTML output, +respectively. +. +. +.TP +.B latin1 +for terminals using the ISO Latin-1 +(ISO 8859-1) +character set and encoding. +. +. +.TP +.B lbp +for Canon CaPSL printers +(LBP-4 and LBP-8 series laser printers). +. +. +.TP +.B lj4 +for HP LaserJet4-compatible +(or other PCL5-compatible) +printers. +. +. +.TP +.B pdf +for PDF output. +. +. +.TP +.B ps +for PostScript output. +. +. +.TP +.B utf8 +for terminals using the ISO 10646 (\[lq]Unicode\[rq]) character set in +UTF-8 encoding. +. +. +.TP +.B X75 +for previewing with +.I \%gxditview +using +75 dpi resolution and a +10-point base type size. +. +. +.TP +.B X75\-12 +for previewing with +.I \%gxditview +using +75 dpi resolution and a +12-point base type size. +. +. +.TP +.B X100 +for previewing with +.I \%gxditview +using +100 dpi resolution and a +10-point base type size. +. +. +.TP +.B X100\-12 +for previewing with +.I \%gxditview +using +100 dpi resolution +and a +12-point base type size. +. +. +.\" ==================================================================== +.SS Postprocessors +.\" ==================================================================== +. +Any program that interprets the output of +GNU +.I troff \" GNU +is a +postprocessor. +. +The postprocessors provided by GNU +.I roff +are +.IR "output drivers" , +which prepare a document for viewing or printing. +. +Postprocessors for other purposes, +such as page resequencing or statistical measurement of a document, +are conceivable. +. +. +.P +An output driver supports one or more output devices, +each with its own device description file. +. +A device determines its postprocessor with the +.B postpro +directive in its device description file; +see +.MR groff_font 5 . +. +The +.B \-X +option overrides this selection, +causing +.I \%gxditview +to serve as the output driver. +. +. +.TP +.MR grodvi 1 +provides +.BR dvi . +. +. +.TP +.MR grohtml 1 +provides +.B html +and +.BR xhtml . +. +. +.TP +.MR grolbp 1 +provides +.BR lbp . +. +. +.TP +.MR grolj4 1 +provides +.BR lj4 . +. +. +.TP +.MR gropdf 1 +provides +.BR pdf . +. +. +.TP +.MR grops 1 +provides +.BR ps . +. +. +.TP +.MR grotty 1 +provides +.BR ascii , +.BR cp1047 , +.BR latin1 , +and +.BR utf8 . +. +. +.TP +.MR gxditview 1 +provides +.BR X75 , +.BR X75\-12 , +.BR X100 , +and +.BR X100\-12 , +and additionally can preview +.BR ps . +. +. +.\" ==================================================================== +.SS Utilities +.\" ==================================================================== +. +GNU +.I roff +includes a suite of utilities. +. +. +.TP +.MR gdiffmk 1 +marks differences between a pair of +.I roff +input files. +. +. +.TP +.MR grog 1 +infers the +.I groff +command a document requires. +. +. +.P +Several utilities prepare descriptions of fonts, +enabling the formatter to use them when producing output for a given +device. +. +. +.TP +.MR addftinfo 1 +adds information to AT&T +.I troff \" AT&T +font description files to enable their use with +GNU +.IR troff .\" GNU +. +. +.TP +.MR afmtodit 1 +creates font description files for PostScript Type\~1 fonts. +. +. +.TP +.MR pfbtops 1 +translates a PostScript Type\~1 font in PFB +(Printer Font Binary) +format to PFA +(Printer Font ASCII), +which can then be interpreted by +.IR \%afmtodit . +. +. +.TP +.MR hpftodit 1 +creates font description files for the HP LaserJet\~4 family of +printers. +. +. +.TP +.MR tfmtodit 1 +creates font description files for the TeX DVI device. +. +. +.TP +.MR xtotroff 1 +creates font description files for X Window System core fonts. +. +. +.P +A trio of tools transform material constructed using +.I roff +preprocessor languages into graphical image files. +. +. +.TP +.MR eqn2graph 1 +converts an +.I eqn +equation into a cropped image. +. +. +.TP +.MR grap2graph 1 +converts a +.I grap +diagram into a cropped image. +. +. +.TP +.MR pic2graph 1 +converts a +.I pic +diagram into a cropped image. +. +. +.P +Another set of programs works with the bibliographic data files used +by the +.MR refer 1 +preprocessor. +. +. +.TP +.MR \%indxbib 1 +makes inverted indices for bibliographic databases, +speeding lookup operations on them. +. +. +.TP +.MR lkbib 1 +searches the databases. +. +. +.TP +.MR \%lookbib 1 +interactively searches +the databases. +. +. +.\" ==================================================================== +.SH "Exit status" +.\" ==================================================================== +. +.I groff +exits with a failure status if there was a problem parsing its arguments +and a successful status if either of the options +.B \-h +or +.B \-\-help +was specified. +. +Otherwise, +.I groff +runs a pipeline to process its input; +if all commands within the pipeline exit successfully, +.I groff +does likewise. +. +If not, +.IR groff 's +exit status encodes a summary of problems encountered, +setting bit\~0 if a command exited with a failure status, +bit\~1 if a command was terminated with a signal, +and bit\~2 if a command could not be executed. +. +(Thus, +if all three misfortunes befell one's pipeline, +.I groff +would exit with status 2\[ha]0 + 2\[ha]1 + 2\[ha]2 = 1+2+4 = 7.) +. +To troubleshoot pipeline problems, +you may wish to re-run the +.I groff +command with the +.B \-V +option and break the reported pipeline down into separate stages, +inspecting the exit status of and diagnostic messages emitted by each +command. +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +Normally, +the path separator in environment variables ending with +.I PATH +is the colon; +this may vary depending on the operating system. +. +For example, +Windows uses a semicolon instead. +. +. +.TP +.I GROFF_BIN_PATH +This search path, +followed by +.IR PATH , +is used to locate commands executed by +.IR groff . +. +If it is not set, +the installation directory of the GNU +.I roff +executables, +.IR /usr/\:\%bin , +is searched before +.IR PATH . +. +. +.TP +.I GROFF_COMMAND_PREFIX +GNU +.I roff +can be configured at compile time to apply a prefix to the names of the +programs it provides that had a counterpart in AT&T +.IR troff , \" AT&T +so that name collisions are avoided at run time. +. +The default prefix is empty. +. +. +.IP +When used, +this prefix is conventionally the letter \[lq]g\[rq]. +. +For example, +GNU +.I troff \" GNU +would be installed as +.IR gtroff . +. +Besides +.IR troff , \" GNU +the prefix applies to +the formatter +.IR nroff ; \" GNU +the preprocessors +.IR eqn , \" generic +.IR grn , \" generic +.IR pic , \" generic +.IR \%refer , \" generic +.IR tbl , \" generic +and +.IR \%soelim ; \" generic +and the utilities +.I \%indxbib \" generic +and +.IR \%lookbib . \" generic +. +. +.TP +.I GROFF_ENCODING +The value of this variable is passed to the +.IR preconv (1) +preprocessor's +.B \-e +option to select the character encoding of input files. +. +This variable's existence implies +the +.I groff +option +.BR \-k . +. +If set but empty, +.I groff +calls +.I preconv +without an +.B \-e +option. +. +.IR groff 's +.B \-K +option overrides +.IR \%GROFF_ENCODING . +. +. +.TP +.I GROFF_FONT_PATH +Seek the selected output device's directory of device and font +description files in this list of directories. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.TP +.I GROFF_TMAC_PATH +Seek macro files in this list of directories. +. +See +.MR \%troff 1 +and +.MR groff_tmac 5 . +. +. +.TP +.I GROFF_TMPDIR +Create temporary files in this directory. +. +If not set, +but the environment variable +.I \%TMPDIR +is set, +temporary files are created there instead. +. +On Windows systems, +if neither of the foregoing are set, +the environment variables +.I TMP +and +.I TEMP +(in that order) +are checked also. +. +Otherwise, +temporary files are created in +.IR /tmp . +. +The +.MR \%refer 1 , +.MR grohtml 1 , +and +.MR grops 1 +commands use temporary files. +. +. +.TP +.I GROFF_TYPESETTER +Set the default output device. +. +If empty or not set, +.B \%ps +is used. +. +The +.B \-T +option overrides +.IR \%GROFF_TYPESETTER . +. +. +.TP +.I SOURCE_DATE_EPOCH +A time stamp +(expressed as seconds since the Unix epoch) +to use as the output creation time stamp in place of the current time. +. +The time is converted to human-readable form using +.MR localtime 3 +when the formatter starts up and stored in registers usable by documents +and macro packages. +. +. +.TP +.I TZ +The time zone to use when converting the current time +(or value of +.IR SOURCE_DATE_EPOCH ) +to human-readable form; +see +.MR tzset 3 . +. +. +.\" ==================================================================== +.SH Examples +.\" ==================================================================== +. +.I roff +systems are best known for formatting man pages. +. +Once a +.MR man 1 +librarian program has located a man page, +it may execute a +.I groff +command much like the following. +. +.RS +.EX +groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1 +.EE +.RE +. +The librarian will also pipe the output through a pager, +which might not interpret the SGR terminal escape sequences +.I groff +emits for boldface, +underlining, +or italics; +see section \[lq]Limitations\[rq] below. +. +. +.P +To process a +.I roff +input file using the preprocessors +.I \%tbl +and +.I \%pic +and the +.I me +macro package in the way to which AT&T +.I troff \" AT&T +users were accustomed, +one would type +(or script) +a pipeline. +. +. +.IP +.EX +\%pic foo.me | \%tbl | \%troff \-me \-Tutf8 | grotty +.EE +. +. +.P +Using +.IR groff , +this pipe can be shortened to an equivalent command. +. +.IP +.EX +groff \-p \-t \-me \-T utf8 foo.me +.EE +. +. +.P +An even easier way to do this is to use +.MR grog 1 +to guess the preprocessor and macro options and execute the result by +using the command substitution feature of the shell. +. +.IP +.EX +$(grog \-Tutf8 foo.me) +.EE +. +. +.P +Each command-line option to a postprocessor must be specified with any +required leading dashes +.RB \[lq] \- \[rq] +.\" No GNU roff postprocessor uses long options for anything except +.\" --help or --version. +.\"or +.\".RB \[lq] \-\- \[rq] +because +.I groff +passes the arguments as-is to the postprocessor; +this permits arbitrary arguments to be transmitted. +. +For example, +to pass a title to the +.I gxditview +postprocessor, +the shell commands +. +.RS +.EX +groff \-X \-P \-title \-P \[aq]trial run\[aq] mydoc.t +.EE +.RE +. +and +. +.RS +.EX +groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial run\[aq] \- +.EE +.RE +. +are equivalent. +. +. +.\" ==================================================================== +.SH Limitations +.\" ==================================================================== +. +When paging output for the +.BR ascii , +.BR cp1047 , +.BR latin1 , +and +.B utf8 +devices, +programs like +.MR more 1 +and +.MR less 1 +may require command-line options to correctly handle some terminal +escape sequences; +see +.MR grotty 1 . +. +. +.P +On EBCDIC hosts such as OS/390 Unix, +the output devices +.B ascii +and +.B latin1 +aren't available. +. +Conversely, +the output device +.B cp1047 +is not available on systems based on the ISO\~646 or ISO\~8859 character +encoding standards. +. +. +.\" ==================================================================== +.SH "Installation directories" +.\" ==================================================================== +. +GNU +.I roff +installs files in varying locations depending on its compile-time +configuration. +. +On this installation, +the following locations are used. +. +. +.if !'/usr/\:\%share/\:\%X11/\:\%app\-defaults'' \{\ +.TP +.I /usr/\:\%share/\:\%X11/\:\%app\-defaults +Application defaults directory for +.MR gxditview 1 . +.\} +. +. +.TP +.I /usr/\:\%bin +Directory containing +.IR groff 's +executable commands. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%eign +List of common words for +.MR indxbib 1 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0 +Directory for data files. +. +. +.TP +.I /usr/\:\%dict/\:\%papers/\:\%Ind +Default index for +.MR lkbib 1 +and +.MR refer 1 . +. +. +.TP +.I /usr/\:\%share/\:\%doc/\:\%groff +Documentation directory. +. +. +.TP +.I /usr/\:\%share/\:\%doc/\:\%groff/\:\%examples +Example directory. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font +Font directory. +. +. +.TP +.I /usr/\:\%share/\:\%doc/\:\%groff/\:\%html +HTML documentation directory. +. +. +.TP +.I /usr/\:\%lib/\:\%font +Legacy font directory. +. +. +.TP +.I /etc/\:\%groff/\:\%site\-font +Local font directory. +. +. +.TP +.I /etc/\:\%groff/\:\%site\-tmac +Local macro package +.RI ( tmac +file) directory. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac +Macro package +.RI ( tmac +file) directory. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont +Font directory for compatibility with old versions of +.IR groff ; +see +.MR grops 1 . +. +. +.TP +.I /usr/\:\%share/\:\%doc/\:\%groff/\:\%pdf +PDF documentation directory. +. +. +.if !'no'no' \{\ +.TP +.I /etc/\:\%groff/\:\%site\-tmac +System macro package +.RI ( tmac +file) directory. +.\} +. +. +.\" ==================================================================== +.SS "\f[I]groff\f[] macro directory" +.\" ==================================================================== +. +Most macro files supplied with GNU +.I roff +are stored in +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac +for the installation corresponding to this document. +. +As a rule, +multiple directories are searched for macro files; +see +.MR \%troff 1 . +. +For a catalog of macro files GNU +.I roff +provides, +see +.MR groff_tmac 5 . +. +. +.\" ==================================================================== +.SS "\f[I]groff\f[] device and font description directory" +.\" ==================================================================== +. +Device and font description files supplied with GNU +.I roff +are stored in +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font +for the installation corresponding to this document. +. +As a rule, +multiple directories are searched for device and font description files; +see +.MR \%troff 1 . +. +For the formats of these files, +see +.MR groff_font 5 . +. +. +.\" ==================================================================== +.SH Availability +.\" ==================================================================== +. +Obtain links to +.I groff +releases for download, +its source repository, +discussion mailing lists, +a support ticket tracker, +and further information from the +.UR http://\:www\:.gnu\:.org/\:software/\:groff +.I groff +page of the GNU website +.UE . +. +. +.P +A free implementation of the +.I grap +preprocessor, +written by +.MT faber@\:lunabase\:.org +Ted Faber +.ME , +can be found at the +.UR http://\:www\:.lunabase\:.org/\:\[ti]faber/\:Vault/\:software/\ +\:grap/ +.I grap +website +.UE . +. +.I groff +supports only this +.IR grap . +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +.I groff +(both the front-end command and the overall system) +was primarily written by +.MT jjc@\:jclark\:.com +James Clark +.ME . +. +Contributors to this document include Clark, +Trent A.\& Fisher, +.MT wl@gnu.org +Werner Lemberg +.ME , +.MT groff\-bernd.warken\-72@\:web\:.de +Bernd Warken +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.\" groff ships 59 man pages generated from 58 source files. The +.\" numbered comments refer to their sorting order in the source tree, +.\" so that it is easier to tell that we've enumerated all of them. +.TP +Introduction, \c +history, \c +and further reading: +.MR roff 7 \" #23 +. +. +.TP +.RI "Viewer for\~" groff "\~(and AT&T device-independent\~" troff \ +)\~documents: +.MR gxditview 1 \" #33 +. +. +.TP +Preprocessors: +.MR \%chem 1 , \" #1 +.MR \%eqn 1 , \" #34 +.MR \%neqn 1 , \" #35 +.MR glilypond 1 , \" #4 +.MR \%grn 1 , \" #36 +.MR preconv 1 , \" #38 +.MR gperl 1 , \" #5 +.MR \%pic 1 , \" #37 +.MR gpinyin 1 , \" #6 +.MR \%refer 1 , \" #39 +.MR \%soelim 1 , \" #40 +.MR \%tbl 1 \" #41 +. +. +.TP +Macro packages and package-specific utilities: +.MR groff_hdtbl 7 , \" #9 +.MR groff_man 7 , \" #55a +.MR groff_man_style 7 , \" #55b +.MR groff_mdoc 7 , \" #56 +.MR groff_me 7 , \" #57 +.MR groff_mm 7 , \" # 10 +.MR groff_mmse 7 , \" # 11 +.MR mmroff 1 , \" #12 +.MR groff_mom 7 , \" #13 +.MR pdfmom 1 , \" #30 +.MR groff_ms 7 , \" #58 +.MR groff_rfc1345 7 , \" 16 +.MR groff_trace 7 , \" #59 +.MR groff_www 7 \" #60 +. +. +.TP +Bibliographic database management tools: +.MR \%indxbib 1 , \" #49 +.MR lkbib 1 , \" #50 +.MR \%lookbib 1 \" #51 +. +. +.TP +Language, \c +conventions, \c +and GNU extensions: +.MR groff 7 , \" #17 +.MR groff_char 7 , \" #18 +.MR groff_diff 7 , \" #19 +.MR groff_font 5 , \" #20 +.MR groff_tmac 5 \" #22 +. +. +.TP +Intermediate output language: +.MR groff_out 5 \" #21 +. +. +.TP +Formatter program: +.MR \%troff 1 \" #45 +. +. +.TP +Formatter wrappers: +.\".MR groff 1 , \" 42 -- this page +.MR \%nroff 1 , \" #44 +.MR pdfroff 1 \" #14 +. +. +.TP +Postprocessors for output devices: +.MR grodvi 1 , \" #24 +.MR grohtml 1 , \" #25 +.MR grolbp 1 , \" #26 +.MR grolj4 1 , \" #27 +.MR gropdf 1 , \" #29 +.MR grops 1 , \" #31 +.MR grotty 1 \" #32 +. +. +.TP +Font support utilities: +.MR addftinfo 1 , \" #46 +.MR afmtodit 1 , \" #47 +.MR hpftodit 1 , \" #48 +.MR pfbtops 1 , \" #52 +.MR tfmtodit 1 , \" #53 +.MR xtotroff 1 \" #54 +. +. +.TP +Graphics conversion utilities: +.MR eqn2graph 1 , \" #2 +.MR grap2graph 1 , \" #7 +.MR pic2graph 1 \" #15 +. +. +.TP +Difference-marking utility: +.MR gdiffmk 1 \" #3 +. +. +.TP +\[lq]groff guess\[rq] utility: +.MR grog 1 \" #43 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_1_man_C] +.do rr *groff_groff_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grohtml.1 b/upstream/fedora-40/man1/grohtml.1 new file mode 100644 index 00000000..07619768 --- /dev/null +++ b/upstream/fedora-40/man1/grohtml.1 @@ -0,0 +1,731 @@ +.TH grohtml 1 "24 January 2024" "groff 1.23.0" +.SH Name +grohtml, post\-grohtml, pre\-grohtml \- +.I groff +output driver for HTML +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1999-2022 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grohtml_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY pre\-grohtml +.RB [ \-epV ] +.RB [ \-a +.IR anti-aliasing-text-bits ] +.RB [ \-D +.IR image-directory ] +.RB [ \-F +.IR font-directory ] +.RB [ \-g +.IR anti-aliasing-graphic-bits ] +.RB [ \-i +.IR resolution ] +.RB [ \-I +.IR image-stem ] +.RB [ \-o +.IR image-vertical-offset ] +.RB [ \-x +.IR html-dialect ] +.I troff-command +.I troff-argument +\&.\|.\|. +.YS +. +. +.SY pre\-grohtml +.B \-\-help +.YS +. +. +.SY pre\-grohtml +.B \-v +. +.SY pre\-grohtml +.B \-\-version +.YS +. +. +.SY post\-grohtml +.RB [ \-bCGhlnrVy ] +.RB [ \-F +.IR font-directory ] +.RB [ \-j +.IR output-stem ] +.RB [ \-s +.IR base-point-size ] +.RB [ \-S +.IR heading-level ] +.RB [ \-x +.IR html-dialect ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY post\-grohtml +.B \-\-help +.YS +. +. +.SY post\-grohtml +.B \-v +. +.SY post\-grohtml +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +system's HTML support consists of a preprocessor, +.IR \%pre\-grohtml , +and an output driver, +.IR \%post\-grohtml ; +together, +they translate +.MR roff 7 +documents to HTML. +. +Because a preprocessor is (uniquely) required for this output driver, +users should invoke +.I \%grohtml +via the +.MR groff 1 +command with the +.B \-Thtml +or +.B \-Txhtml +options. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR \%grohtml . +. +If no operands are given, +or if +.I file +is +.RB \[lq] \- \[rq], +.I \%grohtml +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.P +.I \%grohtml +invokes +.I groff +twice. +. +In the first pass, +the preprocessor +.I \%pre\-grohtml +renders +pictures, +equations, +and tables as images in PostScript format using the +.B ps +output device. +. +In the second pass, +the output driver +.I \%post\-grohtml +translates the output of +.MR \%troff 1 +to HTML. +. +. +.P +.I \%grohtml +writes output encoded in \%UTF-8 and has built-in HTML entities for all +non-composite Unicode characters. +. +In spite of this, +.I groff +may issue warnings about unknown special characters if they can't be +found during the first pass. +. +Such warnings can be safely ignored unless the special characters +appear inside a table or equation. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +.I \%grohtml +supports the standard four styles: +.B R +(roman), +.B I +.RI ( italic ), +.B B +.RB ( bold ), +and +.B BI +(\f[BI]bold-italic\f[]). +. +Fonts are grouped into families +.B T +and +.B C +having members in each style. +. +. +.RS +.TP +.B TR +Times roman +. +.TQ +.B TI +Times italic +. +.TQ +.B TB +Times bold +. +.TQ +.B TBI +Times bold-italic +. +.TQ +.B CR +Courier roman +. +.TQ +.B CI +Courier italic +. +.TQ +.B CB +Courier bold +. +.TQ +.B CBI +Courier bold-italic +.RE +. +. +.P +A special font, +.BR S , +is also provided to accommodate +.I roff +documents that expect it to always be available. +. +. +.\" ==================================================================== +.SS "Font description files" +.\" ==================================================================== +. +The font description files used with +.I \%grohtml +expose the same glyph repertoire in their +.B charset +sections. +. +See +.MR groff_font 5 . +. +. +.\" ==================================================================== +.SS Dependencies +.\" ==================================================================== +. +.I \%pre\-grohtml +generates an image whenever an +.I \%eqn +equation, +.I \%tbl +table, +or +.I \%pic +picture is encountered in the input. +. +.I \%grohtml +therefore may run several commands as part of its operation. +. +These include the \%Netpbm tools +.IR \%pnmcrop , +.IR \%pnmcut , +and +.IR \%pnmtopng ; +\%Ghostscript +.RI ( gs ); +and the \%PSUtils tool +.IR \%psselect . +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-a \~anti-aliasing-text-bits +Number of bits of antialiasing information to be used by text when +generating PNG images. +. +The default +.RB is\~ 4 +but +.BR 0 , +.BR 1 , +and +.B 2 +are also valid. +. +Your system's version of +.I gs +must support the +.B \%\-dTextAlphaBits +option in order to exploit antialiasing. +.\" XXX: How antiquated are the ones that don't? Get rid of this? +. +A value +.RB of\~ 0 +stops +.I \%grohtml +from issuing antialiasing commands to +.IR gs . +. +. +.TP +.B \-b +Initialize the background color to white. +. +. +.TP +.B \-C +Suppress output of \[lq]CreationDate:\[rq] HTML comment. +. +. +.TP +.BI \-D \~image-directory +Instruct +.I \%grohtml +to place all image files into directory +.IR image-directory . +. +. +.TP +.B \-e +Direct +.I \%eqn +to produce MathML. +. +. +.IP +This option should not be manually specified; +it is synthesized by +.I groff +depending on whether it was given the +.B \-Thtml +or +.B \-Txhtml +option. +. +. +.TP +.BI \-F \~font-directory +Prepend directory +.RI font-directory /dev name +to the search path for font and device description files; +.I name +is the name of the device, +usually +.BR html . +. +. +.TP +.BI \-g \~anti-aliasing-graphic-bits +Number of bits of antialiasing information to be used by graphics when +generating PNG images. +. +The default +.RB is\~ 4 +but +.BR 0 , +.BR 1 , +and +.B 2 +are also valid. +. +Your system's version of +.I gs +must support the +.B \%\-dGraphicAlphaBits +option in order to exploit antialiasing. +.\" XXX: How antiquated are the ones that don't? Get rid of this? +. +A value +.RB of\~ 0 +stops +.I \%grohtml +from issuing antialiasing commands to +.IR gs . +. +. +.TP +.B \-G +Suppress output of \[lq]Creator:\[rq] HTML comment. +. +. +.TP +.B \-h +Generate section headings by using HTML +.B B +elements and increasing the font size, +rather than HTML +.B H +elements. +. +. +.TP +.BI \-i \~resolution +Set the image resolution in pixels per inch; +the default +.RB is\~ 100 . +. +. +.TP +.BI \-I \~image-stem +Determine the image file name stem. +. +If omitted, +.I \%grohtml +uses +.IR \%grohtml\- XXXXX +(where +.I XXXXX +is the process ID). +. +A dash is appended to the stem to separate it from the following image +number. +. +. +.TP +.BI \-j \~output-stem +Instruct +.I \%grohtml +to split the HTML output into multiple files. +. +Output is written to a new file at each section heading +(but see option +.B \-S +below) +named +.IR output-stem\- n .html . +. +. +.TP +.B \-l +Turn off the production of automatic section links at the top of the +document. +. +. +.TP +.B \-n +Generate simple heading anchors whenever a section/number heading is +found. +. +Without the option the anchor value is the textual heading. +. +This can cause problems when a heading contains a \[lq]?\[rq] on older +versions of some browsers. +. +This feature is automatically enabled if a heading contains an image. +. +. +.TP +.BI \-o \~image-vertical-offset +Specify the vertical offset of images in points. +. +. +.TP +.B \-p +Display page rendering progress to the standard error stream. +. +.I \%grohtml +displays a page number only when an image is required. +. +. +.TP +.B \-r +Turn off the automatic header and footer line +(HTML rule). +. +. +.TP +.BI \-s \~base-type-size +Set the document's base type size in points. +. +When this size is used in the source, +it corresponds to the HTML base type size. +. +Every increase of two points in the source will produce a +.RB \[lq] big \[rq] +element, +and conversely when a decrease of two points is seen, +a +.RB \[lq] small \[rq] +element is emitted. +. +. +.TP +.BI \-S \~heading-level +When splitting HTML output +(see option +.B \-j +above), +split at each nested heading level defined by +.IR heading-level , +or higher). +. +The default is +.BR 1 . +. +. +.TP +.B \-V +Create an XHTML or HTML validator button at the bottom of each page of +the document. +. +. +.TP +.BI \-x \~html-dialect +Select HTML dialect. +. +Currently, +.I html-dialect +should be either the +.RB digit\~ 4 +or the +.RB letter\~ x , +which indicates whether +.I \%grohtml +should generate HTML\~4 or XHTML, +respectively. +. +. +.IP +This option should not be manually specified; +it is synthesized by +.I groff +depending on whether it was given the +.B \-Thtml +or +.B \-Txhtml +option. +. +. +.TP +.B \-y +Produce a right-aligned +.I groff +signature at the end of the document +(only if +.B \-V +is also specified). +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +lists directories in which to search for +.IR devhtml , +.IR grohtml 's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.TP +.I SOURCE_DATE_EPOCH +A timestamp +(expressed as seconds since the Unix epoch) +to use as the output creation timestamp in place of the current time. +. +The time is converted to human-readable form using +.MR ctime 3 +and recorded in an HTML comment. +. +. +.TP +.I TZ +The time zone to use when converting the current time +(or value of +.IR SOURCE_DATE_EPOCH ) +to human-readable form; +see +.MR tzset 3 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devhtml/\:DESC +describes the +.B html +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devhtml/ F +describes the font known +.RI as\~ F +on device +.BR html . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:html\:.tmac +defines font mappings, +special characters, +and colors for use with the +.B html +output device. +. +It is automatically loaded by +.I \%troffrc +when either of the +.B html +or +.B xhtml +output devices is selected. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:html\-end\:.tmac +finalizes setup of the +.B html +output device. +. +It is automatically loaded by +.I \%troffrc\-end +when either of the +.B html +or +.B xhtml +output devices is selected. +. +. +.P +.I \%grohtml +uses temporary files. +. +See +.MR groff 1 +for details about where such files are created. +. +. +.\" ==================================================================== +.SH Bugs +.\" ==================================================================== +. +.I \%grohtml +is still beta code. +. +. +.PP +.I \%grohtml +does not truly support hyphenation, +but you can fool it into hyphenating long input lines, +which can appear in HTML output with a hyphenated word followed by a +space but no line break. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.\" IR afmtodit (1), +.MR groff 1 , +.MR \%troff 1 , +.\" IR psbb (1), \" XXX: what is this? +.\" IR groff_out (5), +.\" IR groff_char (7), +.MR groff_font 5 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grohtml_1_man_C] +.do rr *groff_grohtml_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grolbp.1 b/upstream/fedora-40/man1/grolbp.1 new file mode 100644 index 00000000..4459430b --- /dev/null +++ b/upstream/fedora-40/man1/grolbp.1 @@ -0,0 +1,504 @@ +'\" t +.TH grolbp 1 "24 January 2024" "groff 1.23.0" +.SH Name +grolbp \- +.I groff +output driver for Canon CaPSL printers +. +. +.\" Modified from grolj4 man page by Francisco Andrés Verdú +.\" for the grolbp program. +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1994-2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grolbp_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grolbp +.RB [ \-l ] +.RB [ \-c\~\c +.IR num-copies ] +.RB [ \-F\~\c +.IR font-directory ] +.RB [ \-o\~\c +.IR orientation ] +.RB [ \-p\~\c +.IR paper-format ] +.RB [ \-w\~\c +.IR width ] +.RI [ file\~ .\|.\|.] +. +.SY grolbp +[\c +.BI \-\-copies= num-copies\c +] [\c +.BI \-\-fontdir= font-directory\c +] [\c +.B \-\-landscape\c +] [\c +.BI \-\-linewidth= width\c +] [\c +.BI \-\-orientation= orientation\c +] [\c +.BI \-\-papersize= paper-format\c +] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY grolbp +.B \-h +. +.SY grolbp +.B \-\-help +.YS +. +. +.SY grolbp +.B \-v +. +.SY grolbp +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +This GNU +.I roff +output driver translates the output of +.MR \%troff 1 +into a CaPSL and VDM format suitable for Canon LBP-4 and LBP-8 printers. +. +Normally, +.I grolbp +is invoked by +.MR groff 1 +when the latter is given the +.RB \[lq] \-T\~lbp \[rq] +option. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR grolbp . +. +If no +.I file +arguments are given, +or if +.I file +is \[lq]\-\[rq], +.I grolbp +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +The driver supports the Dutch, +Swiss, +and Swiss-Narrow scalable typefaces, +each in the regular, +bold, +italic, +and bold-italic styles. +. +Additionally, +the bitmapped, +monospaced Courier and Elite typefaces are available in regular, +bold, +and +italic styles; +Courier at 8 and 12 points, +Elite at 8 and 10 points. +. +The following chart summarizes the +.I groff +font names used to access them. +. +. +.P +.TS +tab(|) allbox center; +Cb Cb Cb Cb Cb +L L L L L +. +Typeface | Roman | Bold | Italic | Bold-Italic +Dutch | TR | TB | TI | TBI +Swiss | HR | HB | HI | HBI +Swiss Narrow | HNR | HNB | HNI | HNBI +Courier | CR | CB | CI | +Elite | ER | EB | EI | +.TE +. +. +.\" ==================================================================== +.SS "Paper format, orientation, and device description file" +.\" ==================================================================== +. +.I grolbp +supports paper formats +.RB \[lq] A4 \[rq], +.RB \[lq] letter \[rq], +.RB \[lq] legal \[rq], +and +.RB \[lq] executive \[rq]. +. +These are matched case-insensitively. +. +The +.BR \-p , +.B \-\-papersize +option overrides any setting in the device description file +.IR DESC . +. +If neither specifies a paper format, +A4 is assumed. +. +. +.P +In its +.I DESC +file, +.I grolbp +(case-insensitively) recognizes an +.B orientation +directive accepting one mandatory argument, +.B portrait +or +.BR landscape . +. +The first valid orientation directive encountered controls. +.\" XXX: This is inconsistent with other description file processing. +. +The +.BR \-l , +.BR \-o , +and +.B \-\-orientation +command-line options +override any setting in +.IR DESC . +. +If none of the foregoing specify the orientation, +portrait is assumed. +. +. +.\" ==================================================================== +.SS "Font description files" +.\" ==================================================================== +. +In addition to the font description file directives documented in +.MR groff_font 5 , +.I grolbp +recognizes +.BR lbpname , +which maps the +.I groff +font name to the font name used internally by the printer. +. +Its syntax is as follows. +.RS +.EX +.RI lbpname\~ printer-font-name +.EE +.RE +. +. +.BR lbpname 's +argument is case-sensitive. +. +The printer's font names are encoded as follows. +. +. +.P +For bitmapped fonts, +.I printer-font_name +has the form +.RS +.EX +.RI N\[la] base-font-name \[ra]\[la] font-style \[ra] +.EE +.RE +.I base-font-name +is the font name as it appears in the printer's font listings without +the first letter, +up to +(but not including) +the font size. +. +.I font-style +can be one of the letters +.BR R , +.BR I , +or +.BR B , +.\" The bold-italic style apparently was not supported for bitmap fonts. +indicating the roman, +italic, +and bold styles, +respectively. +. +For instance, +if the printer's \[lq]font listing A\[rq] +shows \[lq]Nelite12I.ISO_USA\[rq], +the corresponding entry in the +.I groff +font description file is +.RS +.EX +lbpname NeliteI +.EE +.RE +. +You may need to modify +.I grolbp +to add support for new bitmapped fonts, +since the available font names and font sizes of bitmapped fonts +(as documented above) +are hard-coded into the program. +. +. +.P +For scalable fonts, +.I printer-font-name +is identical to the font name as it appears in the printer's \[lq]font +listing A\[rq]. +. +For instance, +to select the \[lq]Swiss\[rq] font in bold-italic style, +which appears in the font listing +as \%\[lq]Swiss\-BoldOblique\[rq], +.RS +.EX +lbpname Swiss\-BoldOblique +.EE +.RE +is the required directive, +and this is what we find in the +.I groff +font description file +.I HBI +for the +.B lbp +device. +. +. +.\" ==================================================================== +.SS "Drawing commands" +.\" ==================================================================== +. +For compatibility with +.MR grolj4 1 , +an additional drawing command is available. +. +. +.TP +.BI \[rs]D\[aq]R\~ "dh dv" \[aq] +Draw a rule +(solid black rectangle) +with one corner at the drawing position, +and the diagonally opposite corner at the drawing position +.RI +( dh , dv ). +.\" XXX , at which the drawing position will be afterward. ? +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-h +and +.B \-\-help +display a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-c " num-copies" +.TQ +.BI \-\-copies= num-copies +Produce +.I num-copies +copies of each page. +. +. +.TP +.BI \-F " font-directory" +.TQ +.BI \-\-fontdir= font-directory +Prepend directory +.RI font-directory /dev name +to the search path for font and device description files; +.I name +is the name of the device, +usually +.BR lbp . +. +. +.TP +.B \-l +.TQ +.B \-\-landscape +Format the document in landscape orientation. +. +. +.TP +.BI \-o " orientation" +.TQ +.BI \-\-orientation= orientation +Format the document in the given +.IR orientation , +which must be +.RB \%\[lq] portrait \[rq] +or +.RB \%\[lq] landscape \[rq]. +. +. +.TP +.BI \-p " paper-format" +.TQ +.BI \-\-papersize= paper-format +Set the paper format to +.IR paper-format , +which must be a valid paper format as described above. +. +. +.TP +.BI \-w " width" +.TQ +.BI \-\-linewidth= width +Set the default line thickness to +.I width +thousandths of an em; +the default is +.B 40 +(0.04\~em). +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +lists directories in which to seek the selected output device's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlbp/\:DESC +describes the +.B lbp +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlbp/ F +describes the font known +.RI as\~ F +on device +.BR lbp . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:lbp\:.tmac +defines macros for use with the +.B lbp +output device. +. +It is automatically loaded by +.I troffrc +when the +.B lbp +output device is selected. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR groff 1 , +.MR \%troff 1 , +.MR groff_out 5 , +.MR groff_font 5 , +.MR groff_char 7 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grolbp_1_man_C] +.do rr *groff_grolbp_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grolj4.1 b/upstream/fedora-40/man1/grolj4.1 new file mode 100644 index 00000000..24fa9af8 --- /dev/null +++ b/upstream/fedora-40/man1/grolj4.1 @@ -0,0 +1,896 @@ +.TH grolj4 1 "24 January 2024" "groff 1.23.0" +.SH Name +grolj4 \- +.I groff +output driver for HP LaserJet 4 and compatible printers +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1994-2020, 2022 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grolj4_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +.\" This macro definition is poor style from a portability standpoint, +.\" but it's a good test and demonstration of the standard font +.\" repertoire for the devices where it has any effect at all, and so +.\" should be retained. +.de FT +. if '\\*(.T'lj4' .ft \\$1 +.. +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grolj4 +.RB [ \-l ] +.RB [ \-c\~\c +.IR num-copies ] +.RB [ \-d +.RI [ n ]] +.RB [ \-F\~\c +.IR font-directory ] +.RB [ \-p\~\c +.IR paper-format ] +.RB [ \-w\~\c +.IR line-width ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY grolj4 +.B \-\-help +.YS +. +. +.SY grolj4 +.B \-v +. +.SY grolj4 +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +This GNU +.I roff +output driver translates the output of +.MR \%troff 1 +into a PCL5 format suitable for an HP LaserJet 4 printer. +. +Normally, +.I grolj4 +is invoked by +.MR groff 1 +when the latter is given the +.RB \[lq] \-T\~lj4 \[rq] +option. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR grolj4 . +. +If no +.I file +arguments are given, +or if +.I file +is \[lq]\-\[rq], +.I grolj4 +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +.I grolj4 +supports the standard four styles: +.B R +(roman), +.B I +.RI ( italic ), +.B B +.RB ( bold ), +and +.B BI +(\f[BI]bold-italic\f[]). +. +Fonts are grouped into families +.BR A , +.BR C , +.BR G , +.BR O , +.BR T , +.BR TN , +.BR U , +and +.B UC +having members in each style. +. +. +.RS +.TP 14n +.B AB +.FT AB +Arial Bold +.FT +. +.TQ +.B ABI +.FT ABI +Arial Bold Italic +.FT +. +.TQ +.B AI +.FT AI +Arial Italic +.FT +. +.TQ +.B AR +.FT AR +Arial Roman +.FT +. +.TQ +.B CB +.FT CB +Courier Bold +.FT +. +.TQ +.B CBI +.FT CBI +Courier Bold Italic +.FT +. +.TQ +.B CI +.FT CI +Courier Italic +.FT +. +.TQ +.B CR +.FT CR +Courier Roman +.FT +. +.TQ +.B GB +.FT GB +Garamond Halbfett +.FT +. +.TQ +.B GBI +.FT GBI +Garamond Kursiv Halbfett +.FT +. +.TQ +.B GI +.FT GI +Garamond Kursiv +.FT +. +.TQ +.B GR +.FT GR +Garamond Antiqua +.FT +. +.TQ +.B OB +.FT OB +CG Omega Bold +.FT +. +.TQ +.B OBI +.FT OBI +CG Omega Bold Italic +.FT +. +.TQ +.B OI +.FT OI +CG Omega Italic +.FT +. +.TQ +.B OR +.FT OR +CG Omega Roman +. +.TQ +.B OB +.FT OB +CG Omega Bold +.FT +. +.TQ +.B OBI +.FT OBI +CG Omega Bold Italic +.FT +. +.TQ +.B OI +.FT OI +CG Omega Italic +.FT +. +.TQ +.B OR +.FT OR +CG Omega Roman +.FT +. +.TQ +.B TB +.FT TB +CG Times Bold +.FT +. +.TQ +.B TBI +.FT TBI +CG Times Bold Italic +.FT +. +.TQ +.B TI +.FT TI +CG Times Italic +.FT +. +.TQ +.B TR +.FT TR +CG Times Roman +.FT +. +.TQ +.B TNRB +.FT TNRB +M Times Bold +.FT +. +.TQ +.B TNRBI +.FT TNRBI +M Times Bold Italic +.FT +. +.TQ +.B TNRI +.FT TNRI +M Times Italic +.FT +. +.TQ +.B TNRR +.FT TNRR +M Times Roman +.FT +. +.TQ +.B UB +.FT UB +Univers Bold +.FT +. +.TQ +.B UBI +.FT UBI +Univers Bold Italic +.FT +. +.TQ +.B UI +.FT UI +Univers Medium Italic +.FT +. +.TQ +.B UR +.FT UR +Univers Medium +.FT +. +.TQ +.B UCB +.FT UCB +Univers Condensed Bold +.FT +. +.TQ +.B UCBI +.FT UCBI +Univers Condensed Bold Italic +.FT +. +.TQ +.B UCI +.FT UCI +Univers Condensed Medium Italic +.FT +. +.TQ +.B UCR +.FT UCR +Univers Condensed Medium +.FT +.RE +. +. +.P +The following fonts are not members of a family. +. +. +.RS +.TP 14n +.B ALBB +.FT ALBB +Albertus Extra Bold +.FT +. +.TQ +.B ALBR +.FT ALBR +Albertus Medium +.FT +. +.TQ +.B AOB +.FT AOB +Antique Olive Bold +. +.TQ +.B AOI +.FT AOI +Antique Olive Italic +. +.TQ +.B AOR +.FT AOR +Antique Olive Roman +. +.TQ +.B CLARENDON +.FT CLARENDON +Clarendon +. +.TQ +.B CORONET +.FT CORONET +Coronet +. +.TQ +.B LGB +.FT LGB +Letter Gothic Bold +. +.TQ +.B LGI +.FT LGI +Letter Gothic Italic +. +.TQ +.B LGR +.FT LGR +Letter Gothic Roman +. +.TQ +.B MARIGOLD +.FT MARIGOLD +Marigold +.RE +. +. +.P +The special font is +.B S +(PostScript Symbol); +.B SYMBOL +(M Symbol), +and +.B WINGDINGS +(Wingdings) +are also available but not mounted by default. +. +. +.\" ==================================================================== +.SS "Paper format and device description file" +.\" ==================================================================== +. +.I grolj4 +supports paper formats +.RB \[lq] A4 \[rq], +.RB \[lq] B5 \[rq], +.RB \[lq] C5 \[rq], +.RB \[lq] com10 \[rq], +.RB \[lq] DL \[rq], +.RB \%\[lq] executive \[rq], +.RB \%\[lq] legal \[rq], +.RB \%\[lq] letter \[rq], +and +.RB \[lq] monarch \[rq]. +. +These are matched case-insensitively. +. +The +.B \-p +option overrides any setting in the device description file +.IR DESC . +. +If neither specifies a paper format, +\[lq]letter\[rq] is assumed. +. +. +.\" ==================================================================== +.SS "Font description files" +.\" ==================================================================== +. +.I grolj4 +recognizes four font description file directives in addition to those +documented in +.MR groff_font 5 . +. +. +.TP +.BI pclweight\~ n +Set the stroke weight to +.IR n , +an integer in the range \-7 to +7; +the default is\~0. +. +. +.TP +.BI pclstyle\~ n +Set the style to +.IR n , +an integer in the range 0 to 32767; +the default is\~0. +. +. +.TP +.BI pclproportional\~ n +Set the proportional spacing Boolean flag to +.IR n , +which can be either 0 or\~1; +the default is\~0. +. +. +.TP +.BI pcltypeface\~ n +Set the typeface family to +.IR n , +an integer in the range 0 to 65535; +the default is\~0. +. +. +.\" ==================================================================== +.SS "Drawing commands" +.\" ==================================================================== +. +An additional drawing command is recognized as an extension to those +documented in +.MR groff 7 . +. +. +.TP +.BI \[rs]D\[aq]R\~ "dh dv" \[aq] +Draw a rule +(solid black rectangle) +with one corner at the drawing position, +and the diagonally opposite corner at the drawing position +.RI +( dh , dv ), +at which the drawing position will be afterward. +. +This generates a PCL fill rectangle command, +and so will work on printers that do not support HP-GL/2, +unlike the other +.B \[rs]D +commands. +. +. +.\" ==================================================================== +.SS Fonts +.\" ==================================================================== +. +Nominally, +all Hewlett-Packard LaserJet\~\%4-series and newer printers have the +same internal fonts: +45 scalable fonts and one bitmapped Lineprinter font. +. +The scalable fonts are available in sizes between 0.25 points and 999.75 +points, +in 0.25-point increments; +the Lineprinter font is available only in 8.5-point size. +. +. +.P +The LaserJet font files included with +.I groff +assume that all printers since the LaserJet\~4 are identical. +. +There are some differences between fonts in the earlier and more recent +printers, +however. +. +The LaserJet\~4 printer used Agfa Intellifont technology for 35 of the +internal scalable fonts; +the remaining 10 scalable fonts were TrueType. +. +Beginning with the LaserJet\~\%4000-series printers introduced in 1997, +all scalable internal fonts have been TrueType. +. +The number of printable glyphs differs slightly between Intellifont and +TrueType fonts +(generally, +the TrueType fonts include more glyphs), +and +there are some minor differences in glyph metrics. +. +Differences among printer models are described in the +.I "PCL\~5 Comparison Guide" +and the +.I "PCL\~5 Comparison Guide Addendum" +(for printers introduced since approximately 2001). +. +. +.P +LaserJet printers reference a glyph by a combination of a 256-glyph +symbol set and an index within that symbol set. +. +Many glyphs appear in more than one symbol set; +all combinations of symbol set and index that reference the same glyph +are equivalent. +. +For each glyph, +.MR hpftodit 1 +searches a list of symbol sets, +and selects the first set that contains the glyph. +. +The printing code generated by +.I hpftodit +is an integer that encodes a numerical value for the symbol set in the +high byte(s), +and the index in the low byte. +. +See +.MR groff_font 5 +for a complete description of the font file format; +symbol sets are described in greater detail in the +.IR "PCL\~5 Printer Language Technical Reference Manual" . +. +. +.P +Two of the scalable fonts, +Symbol and Wingdings, +are bound to 256-glyph symbol sets; +the remaining scalable fonts, +as well as the Lineprinter font, +support numerous symbol sets, +sufficient to enable printing of more than 600 glyphs. +. +. +.P +The metrics generated by +.I hpftodit +assume that the +.I DESC +file contains values of 1200 for +.I res +and 6350 for +.IR unitwidth , +or any combination +(e.g., +2400 and 3175) +for which +.IR res \~\[tmu]\~ unitwidth \~=\~7\|620\|000. +. +Although HP PCL\~5 LaserJet printers support an internal resolution of +7200 units per inch, +they use a 16-bit signed integer for positioning; +if +.B devlj4 +is to support U.S.\& ledger paper (11\~in\~\[mu]\~17\~in; +in = inch), +the maximum usable resolution is 32\|767\~\[di]\~17, +or 1927 units per inch, +which rounds down to 1200 units per inch. +. +If the largest required paper dimension is less +(e.g., +8.5\~in\~\[mu]\~11\~in, +or A5), +a greater +.I res +(and lesser +.IR unitwidth ) +can be specified. +. +. +.P +Font metrics for Intellifont fonts were provided by Tagged Font Metric +(TFM) files originally developed by Agfa/Compugraphic. +. +The TFM files provided for these fonts supported 600+ glyphs and +contained extensive lists of kerning pairs. +. +. +.P +To accommodate developers who had become accustomed to TFM files, +HP also provided TFM files for the 10 TrueType fonts included in the +LaserJet\~4. +. +The TFM files for TrueType fonts generally included less information +than the Intellifont TFMs, +supporting fewer glyphs, +and in most cases, +providing no kerning information. +. +By the time the LaserJet\~4000 printer was introduced, +most developers had migrated to other means of obtaining font metrics, +and support for new TFM files was very limited. +. +The TFM files provided for the TrueType fonts in the LaserJet\~4000 +support only the Latin 2 (ISO 8859-2) symbol set, +and include no kerning information; +consequently, +they are of little value for any but the most rudimentary documents. +. +. +.P +Because the Intellifont TFM files contain considerably more information, +they generally are preferable to the TrueType TFM files even for use +with the TrueType fonts in the newer printers. +. +The metrics for the TrueType fonts are very close, +though not identical, +to those for the earlier Intellifont fonts of the same names. +. +Although most output using the Intellifont metrics with the newer +printers is quite acceptable, +a few glyphs may fail to print as expected. +. +The differences in glyph metrics may be particularly noticeable with +composite parentheses, +brackets, +and braces used by +.MR eqn 1 . +. +A script, +located in +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:generate , +can be used to adjust the metrics for these glyphs in the special font +\[lq]S\[rq] for use with printers that have all TrueType fonts. +. +. +.P +At the time HP last supported TFM files, +only version 1.0 of the Unicode standard was available. +. +Consequently, +many glyphs lacking assigned code points were assigned by HP to the +Private Use Area (PUA). +. +Later versions of the Unicode standard included code points outside the +PUA for many of these glyphs. +. +The HP-supplied TrueType TFM files use the PUA assignments; +TFM files generated from more recent TrueType font files require the +later Unicode values to access the same glyphs. +. +Consequently, +two different mapping files may be required: +one for the HP-supplied TFM files, +and one for more recent TFM files. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-c\~ num-copies +Format +.I num-copies +copies of each page. +. +. +.TP +.BR \-d \~[\c +.IR n ] +Use duplex mode +.IR n : +1\~is long-side binding (default), +and 2\~is short-side binding. +. +. +.TP +.BI \-F " font-directory" +Prepend directory +.IR font-directory /dev name +to the search path for font and device description files; +.I name +is the name of the device, +usually +.BR lj4 . +. +. +.TP +.B \-l +Format the document in landscape orientation. +. +. +.TP +.BI \-p " paper-format" +Set the paper format to +.IR paper-format , +which must be a valid paper format as described above. +. +. +.TP +.BI \-w " line-width" +Set the default line thickness to +.I line-width +thousandths of an em; +the default is +.B 40 +(0.04\~em). +. +. +.br +.ne 4v \" Keep section heading and paragraph together. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +lists directories in which to seek the selected output device's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:DESC +describes the +.B lj4 +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/ F +describes the font known +.RI as\~ F +on device +.BR lj4 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:lj4\:.tmac +defines macros for use with the +.B lj4 +output device. +. +It is automatically loaded by +.I troffrc +when the +.B lj4 +output device is selected. +. +. +.\" ==================================================================== +.SH Bugs +.\" ==================================================================== +. +.\" XXX: What does this mean? The period/full stop glyph? Flyspecks? +Small dots. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.UR http://\:www\:.hp\:.com/\:ctg/\:Manual/\:bpl13210\:.pdf +.I HP PCL/PJL Reference: +.I PCL\~5 Printer Language Technical Reference Manual, +.I Part I +.UE +. +. +.P +.MR hpftodit 1 , +.MR groff 1 , +.MR \%troff 1 , +.MR groff_out 5 , +.MR groff_font 5 , +.MR groff_char 7 +. +. +.\" Clean up. +.rm FT +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grolj4_1_man_C] +.do rr *groff_grolj4_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grops.1 b/upstream/fedora-40/man1/grops.1 new file mode 100644 index 00000000..8807e80e --- /dev/null +++ b/upstream/fedora-40/man1/grops.1 @@ -0,0 +1,1831 @@ +.TH grops 1 "24 January 2024" "groff 1.23.0" +.SH Name +grops \- +.I groff +output driver for PostScript +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2018, 2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grops_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" This macro definition is poor style from a portability standpoint, +.\" but it's a good test and demonstration of the standard font +.\" repertoire for the devices where it has any effect at all, and so +.\" should be retained. +.de FT +. if '\\*(.T'ps' .ft \\$1 +. if '\\*(.T'pdf' .ft \\$1 +.. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grops +.RB [ \-glm ] +.RB [ \-b\~\c +.IR brokenness-flags ] +.RB [ \-c\~\c +.IR num-copies ] +.RB [ \-F\~\c +.IR font-directory ] +.RB [ \-I\~\c +.IR inclusion-directory ] +.RB [ \-p\~\c +.IR paper-format ] +.RB [ \-P\~\c +.IR prologue-file ] +.RB [ \-w\~\c +.IR rule-thickness ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY grops +.B \-\-help +.YS +. +. +.SY grops +.B \-v +. +.SY grops +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +PostScript output driver translates the output of +.MR \%troff 1 +into PostScript. +. +Normally, +.I grops +is invoked by +.MR groff 1 +when the latter is given the +.RB \[lq] \-T\~ps \[rq] +option. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR grops . +. +If no +.I file +arguments are given, +or if +.I file +is \[lq]\-\[rq], +.I grotty +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.P +When called with multiple +.I file +arguments, +.I grops +doesn't produce a valid document structure +(one conforming to the Document Structuring Conventions). +. +To print such concatenated output, +it is necessary to deactivate DSC handling in the printing program or +previewer. +. +. +.P +See section \[lq]Font installation\[rq] below for a guide to installing +fonts for +.IR grops . +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-b\~ n +Work around problems with spoolers, +previewers, +and older printers. +. +Normally, +.I grops +produces output at PostScript \%LanguageLevel\~2 that conforms to +version 3.0 of the Document Structuring Conventions. +. +Some software and devices can't handle such a data stream. +. +The value +.RI of\~ n +determines what +.I grops +does to make its output acceptable to such consumers. +. +If +.I n +is +.BR 0 , +.I grops +employs no workarounds, +which is the default; +it can be changed by modifying the +.B broken +directive in +.IR grops 's +.I DESC +file. +. +. +.IP +Add\~1 to suppress generation of +.B %%Begin\%Document\%Setup +and +.B %%End\%Document\%Setup +comments; +this is needed for early versions of TranScript that get confused by +anything between the +.B %%End\%Prolog +comment and the first +.B %%Page +comment. +. +. +.IP +Add\~2 to omit lines in included files beginning with +.BR %!\& , +which confuse Sun's +.I pageview +previewer. +. +. +.IP +Add\~4 to omit lines in included files beginning with +.BR %%Page , +.B %%Trailer +and +.BR %%End\%Prolog ; +this is needed for spoolers that don't understand +.B %%Begin\%Document +and +.B %%End\%Document +comments. +. +. +.IP +Add\~8 to write +.B %!PS\-Adobe\-2.0 +rather than +.B %!PS\-Adobe\-3.0 +as the first line of the PostScript output; +this is needed when using Sun's Newsprint with a printer that requires +page reversal. +. +. +.IP +Add\~16 to omit media size information +(that is, +output neither a +.B %%Document\%Media +comment nor the +.B setpagedevice +PostScript command). +. +This was the behavior of +.I groff +1.18.1 and earlier; +it is +needed for older printers that don't understand PostScript +\%LanguageLevel\~2, +and is also necessary if the output is further processed to produce an +EPS file; +see subsection \[lq]Escapsulated PostScript\[rq] below. +. +. +.TP +.BI \-c\~ n +Output +.I n +copies of each page. +. +. +.TP +.BI \-F\~ dir +Prepend directory +.RI dir /dev name +to the search path for +font and device description and PostScript prologue files; +.I name +is the name of the device, +usually +.BR ps . +. +. +.TP +.B \-g +Generate PostScript code to guess the page length. +. +The guess is correct only if the imageable area is vertically centered +on the page. +. +This option allows you to generate documents that can be printed on both +U.S.\& letter and A4 paper formats without change. +. +. +.TP +.BI \-I\~ dir +Search the directory +.I dir +for files named in +.B \[rs]X\[aq]ps: file\[aq] +and +.B \[rs]X\[aq]ps: import\[aq] +escape sequences. +. +.B \-I +may be specified more than once; +each +.I dir +is searched in the given order. +. +To search the current working directory before others, +add +.RB \[lq] "\-I .\&" \[rq] +at the desired place; +it is otherwise searched last. +. +. +.TP +.B \-l +Use landscape orientation rather than portrait. +. +. +.TP +.B \-m +Turn on manual feed for the document. +. +. +.TP +.BI \-p\~ fmt +Set physical dimensions of output medium, +overriding the +.BR \%papersize , +.BR \%paperlength , +and +.B \%paperwidth +directives in the +.I DESC +file. +. +.I fmt +can be any argument accepted by the +.B \%papersize +directive; +see +.MR groff_font 5 . +. +. +.TP +.BI \-P\~ prologue +Use the file +.IR prologue , +sought in the +.I groff +font search path, +as the PostScript prologue, +overriding the default +(see section \[lq]Files\[rq] below) +and the environment variable +.I GROPS_PROLOGUE. +. +. +.TP +.BI \-w\~ n +Draw rules (lines) with a thickness of +.IR n \~thousandths +of an em. +. +The default thickness is +.B 40 +(0.04\~em). +. +. +.\" ==================================================================== +.SH Usage +.\" ==================================================================== +. +The input to +.I grops +must be in the format output by +.MR \%troff 1 , +described in +.MR groff_out 5 . +. +In addition, +the device and font description files for the device used must meet +certain requirements. +. +The device resolution must be an integer multiple of\~72 times the +.BR sizescale . +. +The device description file must contain a valid paper format; +see +.MR groff_font 5 . +. +Each font description file must contain a directive +. +.RS +.EX +.RI internalname\~ psname +.EE +.RE +. +which says that the PostScript name of the font is +.IR psname . +. +. +.P +A font description file may also contain a directive +. +.RS +.EX +.RI encoding\~ enc-file +.EE +.RE +. +which says that +the PostScript font should be reencoded using the encoding described in +.IR enc-file ; +this file should consist of a sequence of lines of the form +. +. +.RS +.EX +.I pschar code +.EE +.RE +. +where +.I pschar +is the PostScript name of the character, +and +.I code +is its position in the encoding expressed as a decimal integer; +valid values are in the range 0 to\~255. +. +Lines starting with +.B # +and blank lines are ignored. +. +The code for each character given in the font description file must +correspond to the code for the character in encoding file, +or to the code in the default encoding for the font if the PostScript +font is not to be reencoded. +. +This code can be used with the +.B \[rs]N +escape sequence in +.I \%troff +to select the character, +even if it does not have a +.I groff +glyph name. +. +Every character in the font description file must exist in the +PostScript font, +and the widths given in the font description file must match the widths +used in the PostScript font. +. +.I grops +assumes that a character with a +.I groff +name of +.B space +is blank +(makes no marks on the page); +it can make use of such a character to generate more efficient and +compact PostScript output. +. +. +.P +.I grops +is able to display all glyphs in a PostScript font; +it is not limited to 256 of them. +. +.I enc-file +(or the default encoding if no encoding file is specified) +just defines the +order of glyphs for the first 256 characters; +all other glyphs are accessed with additional encoding vectors which +.I grops +produces on the fly. +. +. +.P +.I grops +can embed fonts in a document that are necessary to render it; +this is called \[lq]downloading\[rq]. +. +Such fonts must be in PFA format. +. +Use +.MR pfbtops 1 +to convert a Type\~1 font in PFB format. +. +Downloadable fonts must be listed a +.I download +file containing lines of the form +. +.RS +.EX +.I psname file +.EE +.RE +. +where +.I psname +is the PostScript name of the font, +and +.I file +is the name of the file containing it; +lines beginning with +.B # +and blank lines are ignored; +fields may be separated by tabs or spaces. +. +.I file +is sought using the same mechanism as that for +.I groff +font description files. +. +The +.I download +file itself is also sought using this mechanism; +currently, +only the first matching file found in the device and font description +search path is used. +. +. +.P +If the file containing a downloadable font or imported document +conforms to the Adobe Document Structuring Conventions, +then +.I grops +interprets any comments in the files sufficiently to ensure that its +own output is conforming. +. +It also supplies any needed font resources that are listed in the +.I download +file +as well as any needed file resources. +. +It is also able to handle inter-resource dependencies. +. +For example, +suppose that you have a downloadable font called Garamond, +and also a downloadable font called Garamond-Outline which depends on +Garamond +(typically it would be defined to copy Garamond's font dictionary, +and change the PaintType), +then it is necessary for Garamond to appear before Garamond-Outline in +the PostScript document. +. +.I grops +handles this automatically provided that the downloadable font file +for Garamond-Outline indicates its dependence on Garamond by means of +the Document Structuring Conventions, +for example by beginning with the following lines. +. +.RS +.EX +%!PS\-Adobe\-3.0 Resource\-Font +%%DocumentNeededResources: font Garamond +%%EndComments +%%IncludeResource: font Garamond +.EE +.RE +. +In this case, +both Garamond and Garamond-Outline would need to be listed +in the +.I download +file. +. +A downloadable font should not include its own name in a +.B %%Document\%Supplied\%Resources +comment. +. +. +.P +.I grops +does not interpret +.B %%Document\%Fonts +comments. +. +The +.BR %%Document\%Needed\%Resources , +.BR %%Document\%Supplied\%Resources , +.BR %%Include\%Resource , +.BR %%Begin\%Resource , +and +.B %%End\%Resource +comments +(or possibly the old +.BR %%Document\%Needed\%Fonts , +.BR %%Document\%Supplied\%Fonts , +.BR %%Include\%Font , +.BR %%Begin\%Font , +and +.B %%End\%Font +comments) +should be used. +. +. +.P +The default stroke and fill color is black. +. +For colors defined in the \[lq]rgb\[rq] color space, +.B setrgbcolor +is used; +for \[lq]cmy\[rq] and \[lq]cmyk\[rq], +.BR setcmykcolor ; +and for \[lq]gray\[rq], +.BR setgray . +. +.B setcmykcolor +is a PostScript \%LanguageLevel\~2 command and thus not available on +some older printers. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +.P +Styles called +.BR R , +.BR I , +.BR B , +and +.B BI +mounted at font positions 1 to\~4. +. +Text fonts are grouped into families +.BR A , +.BR BM , +.BR C , +.BR H , +.BR HN , +.BR N , +.BR P , +.RB and\~ T , +each having members in each of these styles. +. +. +.RS +.TP +.B AR +.FT AR +AvantGarde-Book +.FT +. +.TQ +.B AI +.FT AI +AvantGarde-BookOblique +.FT +. +.TQ +.B AB +.FT AB +AvantGarde-Demi +.FT +. +.TQ +.B ABI +.FT ABI +AvantGarde-DemiOblique +.FT +. +.TQ +.B BMR +.FT BMR +Bookman-Light +.FT +. +.TQ +.B BMI +.FT BMI +Bookman-LightItalic +.FT +. +.TQ +.B BMB +.FT BMB +Bookman-Demi +.FT +. +.TQ +.B BMBI +.FT BMBI +Bookman-DemiItalic +.FT +. +.TQ +.B CR +.FT CR +Courier +.FT +. +.TQ +.B CI +.FT CI +Courier-Oblique +.FT +. +.TQ +.B CB +.FT CB +Courier-Bold +.FT +. +.TQ +.B CBI +.FT CBI +Courier-BoldOblique +.FT +. +.TQ +.B HR +.FT HR +Helvetica +.FT +. +.TQ +.B HI +.FT HI +Helvetica-Oblique +.FT +. +.TQ +.B HB +.FT HB +Helvetica-Bold +.FT +. +.TQ +.B HBI +.FT HBI +Helvetica-BoldOblique +.FT +. +.TQ +.B HNR +.FT HNR +Helvetica-Narrow +.FT +. +.TQ +.B HNI +.FT HNI +Helvetica-Narrow-Oblique +.FT +. +.TQ +.B HNB +.FT HNB +Helvetica-Narrow-Bold +.FT +. +.TQ +.B HNBI +.FT HNBI +Helvetica-Narrow-BoldOblique +.FT +. +.TQ +.B NR +.FT NR +NewCenturySchlbk-Roman +.FT +. +.TQ +.B NI +.FT NI +NewCenturySchlbk-Italic +.FT +. +.TQ +.B NB +.FT NB +NewCenturySchlbk-Bold +.FT +. +.TQ +.B NBI +.FT NBI +NewCenturySchlbk-BoldItalic +.FT +. +.TQ +.B PR +.FT PR +Palatino-Roman +.FT +. +.TQ +.B PI +.FT PI +Palatino-Italic +.FT +. +.TQ +.B PB +.FT PB +Palatino-Bold +.FT +. +.TQ +.B PBI +.FT PBI +Palatino-BoldItalic +.FT +. +.TQ +.B TR +.FT TR +Times-Roman +.FT +. +.TQ +.B TI +.FT TI +Times-Italic +.FT +. +.TQ +.B TB +.FT TB +Times-Bold +.FT +. +.TQ +.B TBI +.FT TBI +Times-BoldItalic +.FT +.RE +. +. +.br +.ne 2v +.P +Another text font is not a member of a family. +. +. +.RS +.TP +.B ZCMI +.FT ZCMI +ZapfChancery-MediumItalic +.FT +.RE +. +. +.P +Special fonts include +.BR S , +the PostScript Symbol font; +.BR ZD , +Zapf Dingbats; +.B SS +(slanted symbol), +which contains oblique forms of lowercase Greek letters derived from +Symbol; +.BR EURO , +which offers a Euro glyph for use with old devices lacking it; +and +.BR ZDR , +a reversed version of ZapfDingbats +(with symbols flipped about the vertical axis). +. +Most glyphs in these fonts are unnamed and must be accessed using +.BR \[rs]N . +. +The last three are not standard PostScript fonts, +but supplied by +.I groff +and therefore included in the default +.I download +file. +. +. +.\" ==================================================================== +.SS "Device control commands" +.\" ==================================================================== +. +.I grops +recognizes device control commands produced by the +.B \[rs]X +escape sequence, +but interprets only those that begin with a +.RB \[lq] ps: \[rq] +tag. +. +. +.TP +.BI "\[rs]X\[aq]ps: exec\~" code \[aq] +.RS +Execute the arbitrary PostScript commands +.IR code . +. +The PostScript +.I \%currentpoint +is set to the +.I groff +drawing position when the +.B \[rs]X +escape sequence is interpreted before executing +.IR code . +. +The origin is at the top left corner of the page; +.IR x \~coordinates +increase to the right, +and +.IR y \~coordinates +down the page. +. +A +.RB procedure\~ u +is defined that converts +.I groff +basic units to the coordinate system in effect +(provided the user doesn't change the scale). +. +For example, +. +.RS +.EX +\&.nr x 1i +\[rs]X\[aq]ps: exec \[rs]nx u 0 rlineto stroke\[aq] +.EE +.RE +. +draws a horizontal line one inch long. +. +.I code +may make changes to the graphics state, +but any changes persist only to the end of the page. +. +A dictionary containing the definitions specified by the +.B def +and +.B mdef +commands is on top of the dictionary stack. +. +If your code adds definitions to this dictionary, +you should allocate space for them using +.RB \[lq] "\[rs]X\[aq]ps: mdef\~" +.IB n \[aq]\c +\[rq]. +. +Any definitions persist only until the end of the page. +. +If you use the +.B \[rs]Y +escape sequence with an argument that names a macro, +.I code +can extend over multiple lines. +. +For example, +. +.RS +.EX +\&.nr x 1i +\&.de y +\&ps: exec +\&\[rs]nx u 0 rlineto +\&stroke +\&.. +\&\[rs]Yy +.EE +.RE +. +is another way to draw a horizontal line one inch long. +. +The single backslash before +.RB \[lq] nx \[rq]\[em]the +only reason to use a register while defining the macro +.RB \[lq] y \[rq]\[em]is +to convert a user-specified dimension +.RB \[lq] 1i \[rq] +to +.I groff +basic units which are in turn converted to PostScript units with the +.B u +procedure. +. +. +.P +.I grops +wraps user-specified PostScript code into a dictionary, +nothing more. +. +In particular, +it doesn't start and end the inserted code with +.B save +and +.BR restore , +respectively. +. +This must be supplied by the user, +if necessary. +.RE +. +. +.TP +.BI "\[rs]X\[aq]ps: file\~" name \[aq] +This is the same as the +.B exec +command except that the PostScript code is read from file +.IR name . +. +. +.TP +.BI "\[rs]X\[aq]ps: def\~" code \[aq] +Place a PostScript definition contained in +.I code +in the prologue. +. +There should be at most one definition per +.B \[rs]X +command. +. +Long definitions can be split over several +.B \[rs]X +commands; +all the +.I code +arguments are simply joined together separated by newlines. +. +The definitions are placed in a dictionary which is automatically +pushed on the dictionary stack when an +.B exec +command is executed. +. +If you use the +.B \[rs]Y +escape sequence with an argument that names a macro, +.I code +can extend over multiple lines. +. +. +.TP +.BI "\[rs]X\[aq]ps: mdef\~" "n code" \[aq] +Like +.BR def , +except that +.I code +may contain up to +.IR n \~definitions. +. +.I grops +needs to know how many definitions +.I code +contains +so that it can create an appropriately sized PostScript dictionary +to contain them. +. +. +.TP +.BI "\[rs]X\[aq]ps: import\~" "file llx lly urx ury width\~"\c +.RI [ height ]\c +.B \[aq] +Import a PostScript graphic from +.IR file . +. +The arguments +.IR llx , +.IR lly , +.IR urx , +and +.I ury +give the bounding box of the graphic in the default PostScript +coordinate system. +. +They should all be integers: +.I llx +and +.I lly +are the +.I x +and +.IR y \~coordinates +of the lower left corner of the graphic; +.I urx +and +.I ury +are the +.I x +and +.IR y \~coordinates +of the upper right corner of the graphic; +.I width +and +.I height +are integers that give the desired width and height in +.I groff +basic units of the graphic. +. +. +.IP +The graphic is scaled so that it has this width and height +and translated so that the lower left corner of the graphic is +located at the position associated with +.B \[rs]X +command. +. +If the height argument is omitted it is scaled uniformly in the +.I x +and +.IR y \~axes +so that it has the specified width. +. +. +.IP +The contents of the +.B \[rs]X +command are not interpreted by +.IR \%troff , +so vertical space for the graphic is not automatically added, +and the +.I width +and +.I height +arguments are not allowed to have attached scaling indicators. +. +. +.IP +If the PostScript file complies with the Adobe Document Structuring +Conventions and contains a +.B %%Bounding\%Box +comment, +then the bounding box can be automatically extracted from within +.I groff +input by using the +.B psbb +request. +. +. +.IP +See +.MR groff_tmac 5 +for a description of the +.B PSPIC +macro which provides a convenient high-level interface for inclusion of +PostScript graphics. +. +. +.TP +.B \[rs]X\[aq]ps: invis\[aq] +.TQ +.B \[rs]X\[aq]ps: endinvis\[aq] +No output is generated for text and drawing commands +that are bracketed with these +.B \[rs]X +commands. +. +These commands are intended for use when output from +.I \%troff +is previewed before being processed with +.IR grops ; +if the previewer is unable to display certain characters +or other constructs, +then other substitute characters or constructs can be used for +previewing by bracketing them with these +.B \[rs]X +commands. +. +. +.RS +.P +For example, +.I \%gxditview +is not able to display a proper +.B \[rs][em] +character because the standard X11 fonts do not provide it; +this problem can be overcome by executing the following +request +. +. +.IP +.EX +\&.char \[rs][em] \[rs]X\[aq]ps: invis\[aq]\[rs] +\[rs]Z\[aq]\[rs]v\[aq]-.25m\[aq]\[rs]h\[aq].05m\[aq]\c +\[rs]D\[aq]l .9m 0\[aq]\[rs]h\[aq].05m\[aq]\[aq]\[rs] +\[rs]X\[aq]ps: endinvis\[aq]\[rs][em] +.EE +. +. +.P +In this case, +.I \%gxditview +is unable to display the +.B \[rs][em] +character and draws the line, +whereas +.I grops +prints the +.B \[rs][em] +character +and ignores the line +(this code is already in file +.IR Xps.tmac , +which is loaded if a document intended for +.I grops +is previewed with +.IR \%gxditview ). +.RE +. +. +.P +If a PostScript procedure +.B BPhook +has been defined via a +.RB \[lq] "ps: def" \[rq] +or +.RB \[lq] "ps: mdef" \[rq] +device control command, +it is executed at the beginning of every page +(before anything is drawn or written by +.IR groff ). +. +For example, +to underlay the page contents with the word \[lq]DRAFT\[rq] in light +gray, +you might use +. +. +.RS +.P +.EX +\&.de XX +ps: def +/BPhook +{ gsave .9 setgray clippath pathbbox exch 2 copy + .5 mul exch .5 mul translate atan rotate pop pop + /NewCenturySchlbk-Roman findfont 200 scalefont setfont + (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show + grestore } +def +\&.. +\&.devicem XX +.EE +.RE +. +. +.P +Or, +to cause lines and polygons to be drawn with square linecaps and mitered +linejoins instead of the round linecaps and linejoins normally used by +.IR grops , +use +. +.RS +.EX +\&.de XX +ps: def +/BPhook { 2 setlinecap 0 setlinejoin } def +\&.. +\&.devicem XX +.EE +.RE +. +(square linecaps, +as opposed to butt linecaps +.RB (\[lq] "0 setlinecap" \[rq]), +give true corners in boxed tables even though the lines are drawn +unconnected). +. +. +.\" ==================================================================== +.SS "Encapsulated PostScript" +.\" ==================================================================== +. +.I grops +itself doesn't emit bounding box information. +. +The following script, +.IR groff2eps , +produces an EPS file. +. +. +.RS +.P +.EX +#! /bin/sh +groff \-P\-b16 "$1" > "$1".ps +gs \-dNOPAUSE \-sDEVICE=bbox \-\- "$1".ps 2> "$1".bbox +sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs] + \-e "/\[ha]%!PS\-Adobe\-3.0/s/$/ EPSF\-3.0/" "$1".ps > "$1".eps +rm "$1".ps "$1".bbox +.EE +.RE +. +. +.P +You can then use +.RB \[lq] "groff2eps foo" \[rq] +to convert file +.I foo +to +.IR foo.eps . +. +. +.\" ==================================================================== +.SS "TrueType and other font formats" +.\" ==================================================================== +. +TrueType fonts can be used with +.I grops +if converted first to Type\~42 format, +a PostScript wrapper equivalent to the PFA format described in +.MR pfbtops 1 . +. +Several methods exist to generate a Type\~42 wrapper; +some of them involve the use of a PostScript interpreter such as +Ghostscript\[em]see +.MR gs 1 . +. +. +.P +One approach is to use +.UR https://fontforge.org/ +FontForge +.UE , +a font editor that can convert most outline font formats. +. +Here's an example of using the Roboto Slab Serif font with +.IR groff . +. +Several variables are used so that you can more easily adapt it into +your own script. +. +. +.RS 4 +.P +.EX +MAP=/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/devps/generate/text.map +TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab\-Regular.ttf +BASE=$(basename \[dq]$TTF\[dq]) +INT=${BASE%.ttf} +PFA=$INT.pfa +AFM=$INT.afm +GFN=RSR +DIR=$HOME/.local/groff/font +mkdir \-p \[dq]$DIR\[dq]/devps +fontforge \-lang=ff \-c \[dq]Open(\[rs]\[dq]$TTF\[rs]\[dq]);\[rs] +\tGenerate(\[rs]\[dq]$DIR/devps/$PFA\[rs]\[dq]);\[dq] +afmtodit \[dq]$DIR/devps/$AFM\[dq] \[dq]$MAP\[dq] \ +\[dq]$DIR/devps/$GFN\[dq] +printf \[dq]$BASE\[rs]t$PFA\[rs]n\[dq] >> \[dq]$DIR/devps/download\[dq] +.EE +.RE +. +. +.P +.I fontforge +and +.I afmtodit +may generate warnings depending on the attributes of the font. +. +The test procedure is simple. +. +. +.RS 4 +.P +.EX +printf \[dq].ft RSR\[rs]nHello, world!\[rs]n\[dq] | groff \-F \ +\[dq]$DIR\[dq] > hello.ps +.EE +.RE +. +. +.P +Once you're satisfied that the font works, +you may want to generate any available related styles +(for instance, +Roboto Slab +also has \[lq]Bold\[rq], +\[lq]Light\[rq], +and +\[lq]Thin\[rq] +styles) +and set up +.I GROFF_FONT_PATH +in your environment to include the directory you keep the generated +fonts in so that you don't have to use the +.B \-F +option. +. +. +.\" ==================================================================== +.SH "Font installation" +.\" ==================================================================== +. +The following is a step-by-step font installation guide for +.I grops. +. +. +.IP \[bu] 2n +Convert your font to something +.I groff +understands. +. +This is a PostScript Type\~1 font in PFA format or a PostScript +Type\~42 font, +together with an AFM file. +. +A PFA file begins as follows. +. +.RS +.RS \" two RS calls to get inboard of IP indentation +.EX +%!PS\-AdobeFont\-1.0: +.EE +.RE +. +A PFB file contains this string as well, +preceded by some non-printing bytes. +. +If your font is in PFB format, +use +.IR groff 's +.MR pfbtops 1 +program to convert it to PFA. +. +For TrueType and other font formats, +we recommend +.IR fontforge , +which can convert most outline font formats. +. +A Type\~42 font file begins as follows. +. +.RS +.EX +%!PS\-TrueTypeFont +.EE +.RE +. +This is a wrapper format for TrueType fonts. +. +Old PostScript printers might not support them +(that is, +they might not have a built-in TrueType font interpreter). +. +In the following steps, +we will consider the use of CTAN's +.UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr +BrushScriptX-Italic +.UE +font in PFA format. +.RE \" now restore left margin +. +. +.IP \[bu] +Convert the AFM file to a +.I groff +font description file with the +.MR afmtodit 1 +program. +. +For instance, +. +.RS +.RS \" two RS calls to get inboard of IP indentation +.EX +$ \c +.B afmtodit BrushScriptX\-Italic.afm text.map BSI +.EE +.RE +. +converts the Adobe Font Metric file +.I BrushScriptX\-Italic.afm +to the +.I groff +font description file +.IR BSI . +.RE \" now restore left margin +. +. +.IP +If you have a font family which provides regular upright (roman), +bold, +italic, +and +bold-italic styles +(where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]), +we recommend using the letters +.BR R , +.BR B , +.BR I , +and +.BR BI , +respectively, +as suffixes to the +.I groff +font family name to enable +.IR groff 's +font family and style selection features. +. +An example is +.IR groff 's +built-in support for Times: +the font family +name is abbreviated as +.BR T , +and the +.I groff +font names are therefore +.BR TR , +.BR TB , +.BR TI , +and +.BR TBI . +. +In our example, +however, +the BrushScriptX font is available in a single style only, +italic. +. +. +.IP \[bu] +Install the +.I groff +font description file(s) in a +.I devps +subdirectory in the search path that +.I groff +uses for device and font file descriptions. +. +See the +.I GROFF_FONT_PATH +entry in section \[lq]Environment\[rq] of +.MR \%troff 1 +for the current value of the font search path. +. +While +.I groff +doesn't directly use AFM files, +it is a good idea to store them alongside its font description files. +. +. +.IP \[bu] +Register fonts in the +.I devps/download +file so they can be located for embedding in PostScript files +.I grops +generates. +. +Only the first +.I download +file encountered in the font search path is read. +. +If in doubt, +copy the default +.I download +file +(see section \[lq]Files\[rq] below) +to the first directory in the font search path and add your fonts there. +. +The PostScript font name used by +.I grops +is stored in the +.B internalname +field in the +.I groff +font description file. +. +(This name does not necessarily resemble the font's file name.) +. +We add the following line to +.IR download . +. +.RS +.RS \" two RS calls to get inboard of IP indentation +.EX +BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa +.EE +.RE \" but only one to get back to it +. +A tab character, +depicted as \[->], +separates the fields. +.RE \" now restore left margin +. +. +.IP \[bu] +Test the selection and embedding of the new font. +. +.RS +.RS \" two RS calls to get inboard of IP indentation +.EX +printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \ +| groff \-T ps \-P \-e >hello.ps +see hello.pdf +.EE +.RE +.RE \" now restore left margin +. +. +.\" ==================================================================== +.SH "Old fonts" +.\" ==================================================================== +. +.I groff +versions 1.19.2 and earlier contained descriptions of a slightly +different set of the base 35 PostScript level 2 fonts defined by Adobe. +. +The older set has 229 glyphs and a larger set of kerning pairs; +the newer one has 314 glyphs and includes the Euro glyph. +. +For backwards compatibility, +these old font descriptions are also installed in the +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont/\:\%devps +directory. +. +. +.P +To use them, +make sure that +.I grops +finds the fonts before the default system fonts +(with the same names): +either give +.I grops +the +.B \-F +command-line option, +. +.RS +.EX +$ \c +.B groff \-Tps \-P\-F \-P/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont \c +\&.\|.\|. +.EE +.RE +. +or add the directory to +.IR groff 's +font and device description search path environment variable, +. +.RS +.EX +$ \c +.B GROFF_FONT_PATH=\:/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont \[rs] +.RS +.B groff \-Tps \c +\&.\|.\|. +.RE +.EE +.RE +. +when the command runs. +. +. +.br +.ne 3v +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +A list of directories in which to seek the selected output device's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.TP +.I GROPS_PROLOGUE +If this is set to +.IR foo , +then +.I grops +uses the file +.I foo +(in the font path) instead of the default prologue file +.IR prologue . +. +The option +.B \-P +overrides this environment variable. +. +. +.TP +.I SOURCE_DATE_EPOCH +A timestamp +(expressed as seconds since the Unix epoch) +to use as the output creation timestamp in place of the current time. +. +The time is converted to human-readable form using +.MR ctime 3 +and recorded in a PostScript comment. +. +. +.TP +.I TZ +The time zone to use when converting the current time +(or value of +.IR SOURCE_DATE_EPOCH ) +to human-readable form; +see +.MR tzset 3 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:DESC +describes the +.B ps +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/ F +describes the font known +.RI as\~ F +on device +.BR ps . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%download +lists fonts available for embedding within the PostScript document +(or download to the device). +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%prologue +is the default PostScript prologue prefixed to every output file. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:text.enc +describes the encoding scheme used by most PostScript Type\~1 fonts; +the +.B \%encoding +directive of +font description files for the +.B ps +device refers to it. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:ps.tmac +defines macros for use with the +.B ps +output device. +. +It is automatically loaded by +.I troffrc +when the +.B ps +output device is selected. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:pspic.tmac +defines the +.B PSPIC +macro for embedding images in a document; +see +.MR groff_tmac 5 . +. +It is automatically loaded by +.I troffrc. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/psold.tmac +provides replacement glyphs for text fonts that lack complete coverage +of the ISO Latin-1 character set; +using it, +.I groff +can produce glyphs like eth (\[Sd]) and thorn (\[Tp]) that older +PostScript printers do not natively support. +. +. +.P +.I grops +creates temporary files using the template +.RI \[lq] grops XXXXXX\[rq]; +see +.MR groff 1 +for details on their storage location. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.UR http://\:partners\:.adobe\:.com/\:public/\:developer/\:en/\:ps/\ +\:5001\:.DSC_Spec\:.pdf +PostScript Language Document Structuring Conventions Specification +.UE +. +. +.P +.MR afmtodit 1 , +.MR groff 1 , +.MR \%troff 1 , +.MR pfbtops 1 , +.MR groff_char 7 , +.MR groff_font 5 , +.MR groff_out 5 , +.MR groff_tmac 5 +. +. +.\" Clean up. +.rm FT +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grops_1_man_C] +.do rr *groff_grops_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/grotty.1 b/upstream/fedora-40/man1/grotty.1 new file mode 100644 index 00000000..94d4dcb5 --- /dev/null +++ b/upstream/fedora-40/man1/grotty.1 @@ -0,0 +1,810 @@ +.TH grotty 1 "24 January 2024" "groff 1.23.0" +.SH Name +grotty \- +.I groff +output driver for typewriter-like (terminal) devices +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2021 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_grotty_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY grotty +.RB [ \-dfho ] +.RB [ \-i | \-r ] +.RB [ \-F\~\c +.IR dir ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY "grotty \-c" +.RB [ \-bBdfhouU ] +.RB [ \-F\~\c +.IR dir ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY grotty +.B \-\-help +.YS +. +. +.SY grotty +.B \-v +. +.SY grotty +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +TTY +(\[lq]Teletype\[rq]) +output driver translates the output of +.MR \%troff 1 +into a form suitable for typewriter-like devices, +including terminal emulators. +. +Normally, +.I grotty +is invoked by +.MR groff 1 +when the latter is given one of the +.RB \[lq] \-T\~ascii \[rq], +.RB \[lq] \-T\~latin1 \[rq], +.BR \-Tlatin1 , +or +.RB \[lq] \-T\~utf8 \[rq] +options on systems using ISO character encoding standards, +or with +.RB \[lq] \-T\~cp1047 \[rq] +or +.RB \[lq] \-T\~utf8 \[rq] +on EBCDIC-based hosts. +. +(In this installation, +.B \%ps +is the default output device.) +. +Use +.IR groff 's +.B \-P +option to pass any options shown above to +.IR grotty . +. +If no +.I file +arguments are given, +or if +.I file +is \[lq]\-\[rq], +.I grotty +reads the standard input stream. +. +Output is written to the standard output stream. +. +. +.P +By default, +.I grotty +emits SGR escape sequences +(from ISO\~6429, +popularly called \[lq]ANSI escapes\[rq]) +to change text attributes +(bold, +italic, +underline, +reverse video +.\" ECMA-48, 2nd edition (1979) calls it "negative image". +[\[lq]negative image\[rq]] +and colors). +. +Devices supporting the appropriate sequences can view +.I roff +documents using eight different background and foreground colors. +. +Following ISO\~6429, +the following colors are defined in +.IR tty.tmac : +black, +white, +red, +green, +blue, +yellow, +magenta, +and cyan. +. +Unrecognized colors are mapped to the default color, +which is dependent on the settings of the terminal. +. +OSC\~8 hyperlinks are produced for these devices. +. +. +.P +In keeping with long-standing practice and the rarity of terminals +(and emulators) +that support oblique or italic fonts, +italicized text is represented with underlining by default\[em]but see +the +.B \-i +option below. +. +. +.\" ==================================================================== +.SS "SGR and OSC support in pagers" +.\" ==================================================================== +. +When paging +.IR grotty 's +output with +.MR less 1 , +the latter program must be instructed to pass SGR and OSC sequences +through to the device; +its +.B \-R +option is one way to achieve this +.RI ( less +version 566 or later is required for OSC\~8 support). +. +Consequently, +programs like +.MR man 1 +that page +.I roff +documents with +.I less +must call it with an appropriate option. +. +. +.\" ==================================================================== +.SS "Legacy output format" +.\" ==================================================================== +. +The +.B \-c +option tells +.I grotty +to use an output format compatible with paper terminals, +like the Teletype machines for which +.I roff +and +.I nroff +were first developed but which are no longer in wide use. +. +SGR escape sequences are not emitted; +bold, +italic, +and underlining character attributes are thus not manipulated. +. +Instead, +.I grotty +overstrikes, +representing a bold character +.I c +with the sequence +.RI \[lq] c\~\c +BACKSPACE\~\c +.IR c \[rq], +an italic character +.I c +with the sequence +.RB \[lq] _\~\c +BACKSPACE\~\c +.IR c \[rq], +and bold italics with +.RB \[lq] _\~\c +BACKSPACE\~\c +.I c +BACKSPACE\~\c +.IR c \[rq]. +. +This rendering is inherently ambiguous when the character +.I c +is itself the underscore. +. +. +.P +The legacy output format can be rendered on a video terminal +(or emulator) +by piping +.IR grotty 's +output through +.MR ul 1 , +.\" from bsdmainutils 11.1.2+b1 (on Debian Buster) +which may render bold italics as reverse video. +. +.\" 'more' from util-linux 2.33.1 (on Debian Buster) neither renders +.\" double-struck characters as bold nor supports -b, but does render +.\" SGR sequences (including color) with no flags required. +Some implementations of +.MR more 1 +are also able to display these sequences; +you may wish to experiment with that command's +.B \-b +option. +. +.\" Version 487 of... +.I less +renders legacy bold and italics without requiring options. +. +In contrast to the terminal output drivers of some other +.I roff +implementations, +.I grotty +never outputs reverse line feeds. +. +There is therefore no need to filter its output through +.MR col 1 . +. +. +.\" ==================================================================== +.SS "Device control commands" +.\" ==================================================================== +. +.I grotty +understands one device control function produced by the +.I roff +.B \[rs]X +escape sequence in a document. +. +. +.TP +.BR "\[rs]X\[aq]tty: link " [\c +.IR uri \~[ key\c +.BI = value\c +] \|.\|.\|.\|]\c +.B \[aq] +. +Embed a hyperlink using the OSC 8 terminal escape sequence. +. +Specifying +.I uri +starts hyperlinked text, +and omitting it ends the hyperlink. +. +When +.I uri +is present, +any number of additional key/value pairs can be specified; +their interpretation is the responsibility of the pager or terminal. +. +Spaces or tabs cannot appear literally in +.IR uri , +.IR key , +or +.IR value ; +they must be represented in an alternate form. +. +. +.\" ==================================================================== +.SS "Device description files" +.\" ==================================================================== +. +If the +.I DESC +file for the character encoding contains the +.RB \[lq] unicode \[rq] +directive, +.I grotty +emits Unicode characters in UTF-8 encoding. +. +Otherwise, +it emits characters in a single-byte encoding depending on the data in +the font description files. +. +See +.MR groff_font 5 . +. +. +.P +A font description file may contain a directive +.RB \[lq] internalname\~\c +.IR n \[rq] +where +.I n +is a decimal integer. +. +If the 01 bit in +.I n +is set, +then the font is treated as an italic font; +if the 02 bit is set, +then it is treated as a bold font. +. +.\" The following seems to say nothing that is not true of font +.\" description files in general; if so, it belongs in groff_font(5). +.\"The code field in the font description field gives the code which is +.\"used to output the character. +.\". +.\"This code can also be used in the +.\".I groff +.\".B \[rs]N +.\"escape sequence in a document. +. +. +.\" ==================================================================== +.SS Typefaces +.\" ==================================================================== +. +.I grotty +supports the standard four styles: +.B R +(roman), +.B I +.RI ( italic ), +.B B +.RB ( bold ), +and +.B BI +(\f[BI]bold-italic\f[]). +. +Because the output driver operates in +.I nroff +mode, +attempts to set or change the font family or type size are ignored. +. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-b +Suppress the use of overstriking for bold characters in legacy output +format. +. +. +.TP +.B \-B +Use only overstriking for bold-italic characters in legacy output +format. +. +. +.TP +.B \-c +Use +.IR grotty 's +legacy output format +(see subsection \[lq]Legacy output format\[rq] above). +. +SGR and OSC escape sequences are not emitted. +. +. +.TP +.B \-d +Ignore all +.B \[rs]D +drawing escape sequences in the input. +. +By default, +.I grotty +renders +.BR \[rs]D\[aq]l \|.\|.\|.\& \[aq] +escape sequences that have at least one zero argument +(and so are either horizontal or vertical) +using Unicode box drawing characters +(for the +.B utf8 +device) +or the +.BR \- , +.BR | , +and +.B + +characters +(for all other devices). +. +.I grotty +handles +.BR \[rs]D\[aq]p \|.\|.\|.\& \[aq] +escape sequences that consist entirely of horizontal and vertical +lines similarly. +. +. +.TP +.B \-f +Emit a form feed at the end of each page having no output on its last +line. +. +. +.TP +.BI \-F\~ dir +Prepend directory +.RI dir /dev name +to the search path for font and device description files; +.I name +describes the output device's character encoding, +one of +.BR ascii , +.BR latin1 , +.BR utf8 , +or +.BR cp1047 . +. +. +.TP +.B \-h +Use literal horizontal tab characters in the output. +. +Tabs are assumed to be set every 8 columns. +. +. +.TP +.B \-i +Render oblique-styled fonts +.RB ( I +and +.BR BI ) +with the SGR attribute for italic text +rather than underlined text. +. +Many terminals don't support this attribute; +however, +.MR xterm 1 , +since patch\~#314 (2014-12-28), +does. +. +Ignored if +.B \-c +is also specified. +. +. +.TP +.B \-o +Suppress overstriking +(other than for bold and/or underlined characters when the legacy output +format is in use). +. +. +.TP +.B \-r +Render oblique-styled fonts +.RB ( I +and +.BR BI ) +with the SGR attribute for reverse video text +rather than underlined text. +. +Ignored if +.B \-c +or +.B \-i +is also specified. +. +. +.TP +.B \-u +Suppress the use of underlining for italic characters in legacy output +format. +. +. +.TP +.B \-U +Use only underlining for bold-italic characters in legacy output format. +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.TP +.I GROFF_FONT_PATH +A list of directories in which to seek the selected output device's +directory of device and font description files. +. +See +.MR \%troff 1 +and +.MR groff_font 5 . +. +. +.TP +.I GROFF_NO_SGR +If set, +.IR grotty 's +legacy output format is used just as if the +.B \-c +option were specified; +see subsection \[lq]Legacy output format\[rq] above. +. +. +.br +.ne 3v \" Keep section heading and paragraph tag together. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devascii/\:DESC +describes the +.B ascii +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devascii/ F +describes the font known +.RI as\~ F +on device +.BR ascii . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devcp1047/\:DESC +describes the +.B cp1047 +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devcp1047/ F +describes the font known +.RI as\~ F +on device +.BR cp1047 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlatin1/\:DESC +describes the +.B latin1 +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlatin1/ F +describes the font known +.RI as\~ F +on device +.BR latin1 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devutf8/\:DESC +describes the +.B utf8 +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devutf8/ F +describes the font known +.RI as\~ F +on device +.BR utf8 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:tty\:.tmac +defines macros for use with the +.BR ascii , +.BR cp1047 , +.BR latin1 , +and +.B utf8 +output devices. +. +It is automatically loaded by +.I troffrc +when any of those output devices is selected. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:tty\-char\:.tmac +defines fallback characters for use with +.I grotty. +. +See +.MR nroff 1 . +. +. +.\" XXX: The following no longer seems to be true; an inspection of the +.\" font/*/dev*.am files suggests no evidence of it, at any rate. +.\".P +.\"Note that on EBCDIC hosts, +.\"only files for the +.\".B cp1047 +.\"device are installed. +. +. +.\" ==================================================================== +.SH Limitations +.\" ==================================================================== +. +.I grotty +is intended only for simple documents. +. +. +.IP \[bu] 2n +There is no support for fractional horizontal or vertical motions. +. +. +.IP \[bu] +.I roff +.B \[rs]D +escape sequences producing anything other than horizontal and vertical +lines are not supported. +. +. +.IP \[bu] +Characters above the first line +(that is, +with a vertical drawing position of\~0) +cannot be rendered. +. +. +.IP \[bu] +Color handling differs from other output drivers. +. +The +.I groff +requests and escape sequences that set the stroke and fill colors +instead set the foreground and background character cell colors, +respectively. +. +. +.\" ==================================================================== +.SH Examples +.\" ==================================================================== +. +The following +.I groff +document exercises several features for which output device support +varies: +(1)\~bold style; +(2)\~italic (underline) style; +(3)\~bold-italic style; +(4)\~character composition by overstriking (\[lq]co\[:o]perate\[rq]); +(5)\~foreground color; +(6)\~background color; +and +(7)\~horizontal and vertical line-drawing. +. +. +.P +.RS +.EX +You might see \ef[B]bold\ef[] and \ef[I]italic\ef[]. +Some people see \ef[BI]both\ef[]. +If the output device does (not) co\ez\e[ad]operate, +you might see \em[red]red\em[]. +Black on cyan can have a \eM[cyan]\em[black]prominent\em[]\eM[] +\eD\[aq]l 1i 0\[aq]\eD\[aq]l 0 2i\[aq]\eD\[aq]l 1i 0\[aq] look. +\&.\e" If in nroff mode, end page now. +\&.if n .pl \en[nl]u +.EE +.RE +. +. +.P +Given the foregoing input, +compare and contrast the output of the following. +. +. +.P +.RS +.EX +$ \c +.B groff \-T ascii \c +.I file +$ \c +.B groff \-T utf8 \-P \-i \c +.I file +$ \c +.B groff \-T utf8 \-P \-c \c +.I file \c +.B | ul +.EE +.RE +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +\[lq]Control Functions for Coded Character Sets\[rq] +(ECMA-48) +5th\~edition, +Ecma International, +June\~1991. +. +A gratis version of ISO\~6429, +this document includes a normative description of SGR escape sequences. +. +Available at +.UR http://\:www\:.ecma\-international\:.org/\:publications/\:files/\:\ +ECMA\-ST/\:Ecma\-048\:.pdf +.UE . +. +. +.P +.UR https://\:gist\:.github\:.com/\:egmontkob/\:\ +eb114294efbcd5ad\:b1944c9f3cb5feda +\[lq]Hyperlinks in Terminal Emulators\[rq] +.UE , +Egmont Koblinger. +. +. +.P +.MR groff 1 , +.MR \%troff 1 , +.MR groff_out 5 , +.MR groff_font 5 , +.MR groff_char 7 , +.MR ul 1 , +.MR more 1 , +.MR less 1 , +.MR man 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grotty_1_man_C] +.do rr *groff_grotty_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/groups.1 b/upstream/fedora-40/man1/groups.1 new file mode 100644 index 00000000..661e4ebc --- /dev/null +++ b/upstream/fedora-40/man1/groups.1 @@ -0,0 +1,37 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH GROUPS "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +groups \- print the groups a user is in +.SH SYNOPSIS +.B groups +[\fI\,OPTION\/\fR]... [\fI\,USERNAME\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print group memberships for each USERNAME or, if no USERNAME is specified, for +the current process (which may differ if the groups database has changed). +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by David MacKenzie and James Youngman. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBgetent\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) groups invocation\(aq diff --git a/upstream/fedora-40/man1/grub2-editenv.1 b/upstream/fedora-40/man1/grub2-editenv.1 new file mode 100644 index 00000000..159975a7 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-editenv.1 @@ -0,0 +1,62 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-EDITENV "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-editenv \- edit GRUB environment block +.SH SYNOPSIS +.B grub-editenv +[\fI\,OPTION\/\fR...] \fI\,FILENAME COMMAND\/\fR +.SH DESCRIPTION +Tool to edit environment block. +.IP +Commands: +.TP +create +Create a blank environment block file. +.TP +incr [NAME ...] +Increase value of integer variables. +.TP +list +List the current variables. +.TP +set [NAME=VALUE ...] +Set variables. +.TP +unset [NAME ...] +Delete variables. +.IP +Options: +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +If FILENAME is `\-', the default value \fI\,/boot/grub2/grubenv\/\fP is used. +.PP +There is no `delete' command; if you want to delete the whole environment +block, use `rm /boot/grub2/grubenv'. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-reboot (8), +.BR grub-set-default (8) +.PP +The full documentation for +.B grub-editenv +is maintained as a Texinfo manual. If the +.B info +and +.B grub-editenv +programs are properly installed at your site, the command +.IP +.B info grub-editenv +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-emu.1 b/upstream/fedora-40/man1/grub2-emu.1 new file mode 100644 index 00000000..58e1ad8d --- /dev/null +++ b/upstream/fedora-40/man1/grub2-emu.1 @@ -0,0 +1,68 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-EMU "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-emu \- GRUB emulator +.SH SYNOPSIS +.B grub-emu +[\fI\,OPTION\/\fR...] +.SH DESCRIPTION +GRUB emulator. +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +use GRUB files in the directory DIR +[default=/boot/grub2] +.TP +\fB\-H\fR, \fB\-\-hold\fR[=\fI\,SECS\/\fR] +wait until a debugger will attach +.TP +\fB\-\-memdisk\fR=\fI\,FILE\/\fR +use FILE as memdisk +.TP +\fB\-m\fR, \fB\-\-device\-map\fR=\fI\,FILE\/\fR +use FILE as the device map +[default=/boot/grub2/device.map] +.TP +\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR +Set root device. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-W\fR, \fB\-\-switch\-root\fR +use switch\-root to only switch root filesystem +without restarting the kernel. +.TP +\fB\-X\fR, \fB\-\-kexec\fR +use kexec to boot Linux kernels via systemctl +(pass twice to enable dangerous fallback to +non\-systemctl). +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +If you are trying to install GRUB, then you should use +.BR grub-install (8) +rather than this program. +.PP +The full documentation for +.B grub-emu +is maintained as a Texinfo manual. If the +.B info +and +.B grub-emu +programs are properly installed at your site, the command +.IP +.B info grub-emu +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-file.1 b/upstream/fedora-40/man1/grub2-file.1 new file mode 100644 index 00000000..3aeb9805 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-file.1 @@ -0,0 +1,118 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-FILE "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-file \- check file type +.SH SYNOPSIS +.B file +\fI\,OPTIONS FILE\/\fR +.SH DESCRIPTION +Check if FILE is of specified type. +.TP +\fB\-\-is\-i386\-xen\-pae\-domu\fR +Check if FILE can be booted as i386 PAE Xen unprivileged guest kernel +.TP +\fB\-\-is\-x86_64\-xen\-domu\fR +Check if FILE can be booted as x86_64 Xen unprivileged guest kernel +.TP +\fB\-\-is\-x86\-xen\-dom0\fR +Check if FILE can be used as Xen x86 privileged guest kernel +.TP +\fB\-\-is\-x86\-multiboot\fR +Check if FILE can be used as x86 multiboot kernel +.HP +\fB\-\-is\-x86\-multiboot2\fR Check if FILE can be used as x86 multiboot2 kernel +.TP +\fB\-\-is\-arm\-linux\fR +Check if FILE is ARM Linux +.TP +\fB\-\-is\-arm64\-linux\fR +Check if FILE is ARM64 Linux +.TP +\fB\-\-is\-ia64\-linux\fR +Check if FILE is IA64 Linux +.TP +\fB\-\-is\-mips\-linux\fR +Check if FILE is MIPS Linux +.TP +\fB\-\-is\-mipsel\-linux\fR +Check if FILE is MIPSEL Linux +.TP +\fB\-\-is\-sparc64\-linux\fR +Check if FILE is SPARC64 Linux +.TP +\fB\-\-is\-powerpc\-linux\fR +Check if FILE is POWERPC Linux +.TP +\fB\-\-is\-x86\-linux\fR +Check if FILE is x86 Linux +.TP +\fB\-\-is\-x86\-linux32\fR +Check if FILE is x86 Linux supporting 32\-bit protocol +.TP +\fB\-\-is\-x86\-kfreebsd\fR +Check if FILE is x86 kFreeBSD +.TP +\fB\-\-is\-i386\-kfreebsd\fR +Check if FILE is i386 kFreeBSD +.TP +\fB\-\-is\-x86_64\-kfreebsd\fR +Check if FILE is x86_64 kFreeBSD +.TP +\fB\-\-is\-x86\-knetbsd\fR +Check if FILE is x86 kNetBSD +.TP +\fB\-\-is\-i386\-knetbsd\fR +Check if FILE is i386 kNetBSD +.HP +\fB\-\-is\-x86_64\-knetbsd\fR Check if FILE is x86_64 kNetBSD +.TP +\fB\-\-is\-i386\-efi\fR +Check if FILE is i386 EFI file +.TP +\fB\-\-is\-x86_64\-efi\fR +Check if FILE is x86_64 EFI file +.TP +\fB\-\-is\-ia64\-efi\fR +Check if FILE is IA64 EFI file +.TP +\fB\-\-is\-arm64\-efi\fR +Check if FILE is ARM64 EFI file +.TP +\fB\-\-is\-arm\-efi\fR +Check if FILE is ARM EFI file +.TP +\fB\-\-is\-riscv32\-efi\fR +Check if FILE is RISC\-V 32bit EFI file +.TP +\fB\-\-is\-riscv64\-efi\fR +Check if FILE is RISC\-V 64bit EFI file +.TP +\fB\-\-is\-hibernated\-hiberfil\fR +Check if FILE is hiberfil.sys in hibernated state +.TP +\fB\-\-is\-x86_64\-xnu\fR +Check if FILE is x86_64 XNU (Mac OS X kernel) +.TP +\fB\-\-is\-i386\-xnu\fR +Check if FILE is i386 XNU (Mac OS X kernel) +.TP +\fB\-\-is\-xnu\-hibr\fR +Check if FILE is XNU (Mac OS X kernel) hibernated image +.TP +\fB\-\-is\-x86\-bios\-bootsector\fR +Check if FILE is BIOS bootsector +.PP +\fB\-h\fR, \fB\-\-help\fR Display this help and exit. +\fB\-u\fR, \fB\-\-usage\fR Display the usage of this command and exit. +.SH "SEE ALSO" +The full documentation for +.B grub-file +is maintained as a Texinfo manual. If the +.B info +and +.B grub-file +programs are properly installed at your site, the command +.IP +.B info grub-file +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-fstest.1 b/upstream/fedora-40/man1/grub2-fstest.1 new file mode 100644 index 00000000..1c4d2833 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-fstest.1 @@ -0,0 +1,88 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-FSTEST "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-fstest \- debug tool for GRUB filesystem drivers +.SH SYNOPSIS +.B grub-fstest +[\fI\,OPTION\/\fR...] \fI\,IMAGE_PATH COMMANDS\/\fR +.SH DESCRIPTION +Debug tool for filesystem driver. +.IP +Commands: +.TP +blocklist FILE +Display blocklist of FILE. +.TP +cat FILE +Copy FILE to standard output. +.TP +cmp FILE LOCAL +Compare FILE with local file LOCAL. +.TP +cp FILE LOCAL +Copy FILE to local file LOCAL. +.TP +crc FILE +Get crc32 checksum of FILE. +.TP +hex FILE +Show contents of FILE in hex. +.TP +ls PATH +List files in PATH. +.TP +xnu_uuid DEVICE +Compute XNU UUID of the device. +.TP +\fB\-c\fR, \fB\-\-diskcount\fR=\fI\,NUM\/\fR +Specify the number of input files. +.TP +\fB\-C\fR, \fB\-\-crypto\fR +Mount crypto devices. +.TP +\fB\-d\fR, \fB\-\-debug\fR=\fI\,STRING\/\fR +Set debug environment variable. +.TP +\fB\-K\fR, \fB\-\-zfs\-key\fR=\fI\,FILE\/\fR|prompt +Load zfs crypto key. +.TP +\fB\-n\fR, \fB\-\-length\fR=\fI\,NUM\/\fR +Handle N bytes in output file. +.TP +\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR +Set root device. +.TP +\fB\-s\fR, \fB\-\-skip\fR=\fI\,NUM\/\fR +Skip N bytes from output file. +.TP +\fB\-u\fR, \fB\-\-uncompress\fR +Uncompress data. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "SEE ALSO" +.BR grub-probe (8) +.PP +The full documentation for +.B grub-fstest +is maintained as a Texinfo manual. If the +.B info +and +.B grub-fstest +programs are properly installed at your site, the command +.IP +.B info grub-fstest +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-kbdcomp.1 b/upstream/fedora-40/man1/grub2-kbdcomp.1 new file mode 100644 index 00000000..730e20d3 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-kbdcomp.1 @@ -0,0 +1,42 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-KBDCOMP "1" "February 2024" "grub-kbdcomp ()" "User Commands" +.SH NAME +grub-kbdcomp \- generate a GRUB keyboard layout file +.SH SYNOPSIS +.B grub-kbdcomp +\fI\,-o OUTPUT CKBMAP_ARGUMENTS\/\fR... +.SH DESCRIPTION +grub-kbdcomp processes a X keyboard layout description in +.BR keymaps (5) +format into a format that can be used by GRUB's +.B keymap +command. +.PP +Make GRUB keyboard layout file. +.TP +\fB\-h\fR, \fB\-\-help\fR +print this message and exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print the version information and exit +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE [required] +.PP +grub\-kbdcomp generates a keyboard layout for GRUB using ckbcomp +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mklayout (8) +.PP +The full documentation for +.B grub-kbdcomp +is maintained as a Texinfo manual. If the +.B info +and +.B grub-kbdcomp +programs are properly installed at your site, the command +.IP +.B info grub-kbdcomp +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-menulst2cfg.1 b/upstream/fedora-40/man1/grub2-menulst2cfg.1 new file mode 100644 index 00000000..3acf6992 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-menulst2cfg.1 @@ -0,0 +1,23 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MENULST2CFG "1" "February 2024" "Usage: grub-menulst2cfg [INFILE [OUTFILE]]" "User Commands" +.SH NAME +grub-menulst2cfg \- transform legacy menu.lst into grub.cfg +.SH SYNOPSIS +.B grub-menulst2cfg +[\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]] +.SH DESCRIPTION + +.SH "SEE ALSO" +.BR grub-mkconfig (8) +.PP +The full documentation for +.B grub-menulst2cfg +is maintained as a Texinfo manual. If the +.B info +and +.B grub-menulst2cfg +programs are properly installed at your site, the command +.IP +.B info grub-menulst2cfg +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkfont.1 b/upstream/fedora-40/man1/grub2-mkfont.1 new file mode 100644 index 00000000..ae257ef0 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkfont.1 @@ -0,0 +1,73 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKFONT "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkfont \- make GRUB font files +.SH SYNOPSIS +.B grub-mkfont +[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR] \fI\,FONT_FILES\/\fR +.SH DESCRIPTION +Convert common font file formats into PF2 +.TP +\fB\-a\fR, \fB\-\-force\-autohint\fR +force autohint +.TP +\fB\-b\fR, \fB\-\-bold\fR +convert to bold font +.TP +\fB\-c\fR, \fB\-\-asce\fR=\fI\,NUM\/\fR +set font ascent +.TP +\fB\-d\fR, \fB\-\-desc\fR=\fI\,NUM\/\fR +set font descent +.TP +\fB\-i\fR, \fB\-\-index\fR=\fI\,NUM\/\fR +select face index +.TP +\fB\-\-no\-bitmap\fR +ignore bitmap strikes when loading +.TP +\fB\-\-no\-hinting\fR +disable hinting +.TP +\fB\-n\fR, \fB\-\-name\fR=\fI\,NAME\/\fR +set font family name +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE [required] +.TP +\fB\-r\fR, \fB\-\-range\fR=\fI\,FROM\-TO[\/\fR,FROM\-TO] +set font range +.TP +\fB\-s\fR, \fB\-\-size\fR=\fI\,SIZE\/\fR +set font size +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkconfig (8) +.PP +The full documentation for +.B grub-mkfont +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkfont +programs are properly installed at your site, the command +.IP +.B info grub-mkfont +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkimage.1 b/upstream/fedora-40/man1/grub2-mkimage.1 new file mode 100644 index 00000000..ecd21425 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkimage.1 @@ -0,0 +1,106 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKIMAGE "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkimage \- make a bootable image of GRUB +.SH SYNOPSIS +.B grub-mkimage +[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR]... [\fI\,MODULES\/\fR] +.SH DESCRIPTION +Make a bootable image of GRUB. +.TP +\fB\-c\fR, \fB\-\-config\fR=\fI\,FILE\/\fR +embed FILE as an early config +.TP +\fB\-C\fR, \fB\-\-compression=\fR(xz|none|auto) +choose the compression to use for core image +.TP +\fB\-\-disable\-shim\-lock\fR +disable shim_lock verifier +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +use images and modules under DIR +[default=/usr/lib/grub/] +.TP +\fB\-D\fR, \fB\-\-dtb\fR=\fI\,FILE\/\fR +embed FILE as a device tree (DTB) +.TP +\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR +embed FILE as public key for PGP signature +checking +.TP +\fB\-m\fR, \fB\-\-memdisk\fR=\fI\,FILE\/\fR +embed FILE as a memdisk image +.PP +Implies `\-p (memdisk)/boot/grub' and overrides +.TP +any prefix supplied previously, but the prefix +itself can be overridden by later options +.TP +\fB\-n\fR, \fB\-\-note\fR +add NOTE segment for CHRP IEEE1275 +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +output a generated image to FILE [default=stdout] +.TP +\fB\-O\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR +generate an image in FORMAT +available formats: i386\-coreboot, i386\-multiboot, +i386\-pc, i386\-xen_pvh, i386\-pc\-pxe, +i386\-pc\-eltorito, i386\-efi, i386\-ieee1275, +i386\-qemu, x86_64\-efi, i386\-xen, x86_64\-xen, +mipsel\-yeeloong\-flash, mipsel\-fuloong2f\-flash, +mipsel\-loongson\-elf, powerpc\-ieee1275, +sparc64\-ieee1275\-raw, sparc64\-ieee1275\-cdcore, +sparc64\-ieee1275\-aout, ia64\-efi, mips\-arc, +mipsel\-arc, mipsel\-qemu_mips\-elf, +mips\-qemu_mips\-flash, mipsel\-qemu_mips\-flash, +mips\-qemu_mips\-elf, arm\-uboot, +arm\-coreboot\-vexpress, arm\-coreboot\-veyron, +arm\-efi, arm64\-efi, riscv32\-efi, riscv64\-efi +.TP +\fB\-p\fR, \fB\-\-prefix\fR=\fI\,DIR\/\fR +set prefix directory +.TP +\fB\-s\fR, \fB\-\-sbat\fR=\fI\,FILE\/\fR +SBAT metadata +.TP +\fB\-S\fR, \fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR +Add a note segment reserving SIZE bytes for an +appended signature +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-x\fR, \fB\-\-x509\fR=\fI\,FILE\/\fR +embed FILE as an x509 certificate for appended +signature checking +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-install (8), +.BR grub-mkrescue (1), +.BR grub-mknetdir (8) +.PP +The full documentation for +.B grub-mkimage +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkimage +programs are properly installed at your site, the command +.IP +.B info grub-mkimage +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mklayout.1 b/upstream/fedora-40/man1/grub2-mklayout.1 new file mode 100644 index 00000000..33f2061c --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mklayout.1 @@ -0,0 +1,52 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKLAYOUT "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mklayout \- generate a GRUB keyboard layout file +.SH SYNOPSIS +.B grub-mklayout +[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +grub-mklayout processes a keyboard layout description in +.BR keymaps (5) +format into a format that can be used by GRUB's +.B keymap +command. +.PP +Generate GRUB keyboard layout from Linux console one. +.TP +\fB\-i\fR, \fB\-\-input\fR=\fI\,FILE\/\fR +set input filename. Default is STDIN +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +set output filename. Default is STDOUT +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkconfig (8) +.PP +The full documentation for +.B grub-mklayout +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mklayout +programs are properly installed at your site, the command +.IP +.B info grub-mklayout +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mknetdir.1 b/upstream/fedora-40/man1/grub2-mknetdir.1 new file mode 100644 index 00000000..58a2e334 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mknetdir.1 @@ -0,0 +1,100 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKNETDIR "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mknetdir \- prepare a GRUB netboot directory. +.SH SYNOPSIS +.B grub-mknetdir +[\fI\,OPTION\/\fR...] +.SH DESCRIPTION +Prepares +GRUB network boot images at net_directory/subdir assuming net_directory being +TFTP root. +.TP +\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR +Add a note segment reserving SIZE bytes for an +appended signature +.TP +\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo +compress GRUB files [optional] +.TP +\fB\-\-disable\-shim\-lock\fR +disable shim_lock verifier +.TP +\fB\-\-dtb\fR=\fI\,FILE\/\fR +embed a specific DTB +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +use images and modules under DIR +[default=/usr/lib/grub/] +.TP +\fB\-\-fonts\fR=\fI\,FONTS\/\fR +install FONTS [default=unicode] +.TP +\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR +install only MODULES and their dependencies +[default=all] +.TP +\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR +embed FILE as public key for signature checking +.TP +\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR +[default=/usr/share/locale] +.TP +\fB\-\-locales\fR=\fI\,LOCALES\/\fR +install only LOCALES [default=all] +.TP +\fB\-\-modules\fR=\fI\,MODULES\/\fR +pre\-load specified modules MODULES +.TP +\fB\-\-sbat\fR=\fI\,FILE\/\fR +SBAT metadata +.TP +\fB\-\-themes\fR=\fI\,THEMES\/\fR +install THEMES [default=starfield] +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR +embed FILE as an x509 certificate for signature +checking +.TP +\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto +choose the compression to use for core image +.TP +\fB\-\-net\-directory\fR=\fI\,DIR\/\fR +root directory of TFTP server +.TP +\fB\-\-subdir\fR=\fI\,DIR\/\fR +relative subdirectory on network server +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.PP +Prepares GRUB network boot images at net_directory/subdir assuming +net_directory being TFTP root. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkimage (1) +.PP +The full documentation for +.B grub-mknetdir +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mknetdir +programs are properly installed at your site, the command +.IP +.B info grub-mknetdir +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkpasswd-pbkdf2.1 b/upstream/fedora-40/man1/grub2-mkpasswd-pbkdf2.1 new file mode 100644 index 00000000..d0fc16f2 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkpasswd-pbkdf2.1 @@ -0,0 +1,46 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKPASSWD-PBKDF2 "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkpasswd-pbkdf2 \- generate hashed password for GRUB +.SH SYNOPSIS +.B grub-mkpasswd-pbkdf2 +[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +Generate PBKDF2 password hash. +.TP +\fB\-c\fR, \fB\-\-iteration\-count\fR=\fI\,NUM\/\fR +Number of PBKDF2 iterations +.TP +\fB\-l\fR, \fB\-\-buflen\fR=\fI\,NUM\/\fR +Length of generated hash +.TP +\fB\-s\fR, \fB\-\-salt\fR=\fI\,NUM\/\fR +Length of salt +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkconfig (8) +.PP +The full documentation for +.B grub-mkpasswd-pbkdf2 +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkpasswd-pbkdf2 +programs are properly installed at your site, the command +.IP +.B info grub-mkpasswd-pbkdf2 +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkrelpath.1 b/upstream/fedora-40/man1/grub2-mkrelpath.1 new file mode 100644 index 00000000..ce199813 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkrelpath.1 @@ -0,0 +1,37 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKRELPATH "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkrelpath \- make a system path relative to its root +.SH SYNOPSIS +.B grub-mkrelpath +[\fI\,OPTION\/\fR...] \fI\,PATH\/\fR +.SH DESCRIPTION +Transform a system filename into GRUB one. +.TP +\fB\-r\fR, \fB\-\-relative\fR +use relative path on btrfs +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-probe (8) +.PP +The full documentation for +.B grub-mkrelpath +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkrelpath +programs are properly installed at your site, the command +.IP +.B info grub-mkrelpath +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkrescue.1 b/upstream/fedora-40/man1/grub2-mkrescue.1 new file mode 100644 index 00000000..05c83d19 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkrescue.1 @@ -0,0 +1,131 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKRESCUE "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkrescue \- make a GRUB rescue image +.SH SYNOPSIS +.B grub-mkrescue +[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR] \fI\,SOURCE\/\fR... +.SH DESCRIPTION +Make GRUB CD\-ROM, disk, pendrive and floppy bootable image. +.TP +\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR +Add a note segment reserving SIZE bytes for an +appended signature +.TP +\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo +compress GRUB files [optional] +.TP +\fB\-\-disable\-shim\-lock\fR +disable shim_lock verifier +.TP +\fB\-\-dtb\fR=\fI\,FILE\/\fR +embed a specific DTB +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +use images and modules under DIR +[default=/usr/lib/grub/] +.TP +\fB\-\-fonts\fR=\fI\,FONTS\/\fR +install FONTS [default=unicode] +.TP +\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR +install only MODULES and their dependencies +[default=all] +.TP +\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR +embed FILE as public key for signature checking +.TP +\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR +[default=/usr/share/locale] +.TP +\fB\-\-locales\fR=\fI\,LOCALES\/\fR +install only LOCALES [default=all] +.TP +\fB\-\-modules\fR=\fI\,MODULES\/\fR +pre\-load specified modules MODULES +.TP +\fB\-\-sbat\fR=\fI\,FILE\/\fR +SBAT metadata +.TP +\fB\-\-themes\fR=\fI\,THEMES\/\fR +install THEMES [default=starfield] +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR +embed FILE as an x509 certificate for signature +checking +.TP +\fB\-\-arcs\-boot\fR +enable ARCS (big\-endian mips machines, mostly +SGI) boot. Disables HFS+, APM, sparc64 and boot +as disk image for i386\-pc +.TP +\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto +choose the compression to use for core image +.TP +\fB\-\-label\-bgcolor\fR=\fI\,COLOR\/\fR +use COLOR for label background +.TP +\fB\-\-label\-color\fR=\fI\,COLOR\/\fR +use COLOR for label +.TP +\fB\-\-label\-font\fR=\fI\,FILE\/\fR +use FILE as font for label +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE [required] +.TP +\fB\-\-product\-name\fR=\fI\,STRING\/\fR +use STRING as product name +.TP +\fB\-\-product\-version\fR=\fI\,STRING\/\fR +use STRING as product version +.TP +\fB\-\-rom\-directory\fR=\fI\,DIR\/\fR +save ROM images in DIR [optional] +.TP +\fB\-\-sparc\-boot\fR +enable sparc boot. Disables HFS+, APM, ARCS and +boot as disk image for i386\-pc +.TP +\fB\-\-xorriso\fR=\fI\,FILE\/\fR +use FILE as xorriso [optional] +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.PP +Generates a bootable CD/USB/floppy image. Arguments other than options to +this program are passed to xorriso, and indicate source files, source +directories, or any of the mkisofs options listed by the output of `xorriso +\fB\-as\fR mkisofs \fB\-help\fR'. +.PP +Option \fB\-\-\fR switches to native xorriso command mode. +.PP +Mail xorriso support requests to . +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkimage (1) +.PP +The full documentation for +.B grub-mkrescue +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkrescue +programs are properly installed at your site, the command +.IP +.B info grub-mkrescue +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mkstandalone.1 b/upstream/fedora-40/man1/grub2-mkstandalone.1 new file mode 100644 index 00000000..eac65dc0 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mkstandalone.1 @@ -0,0 +1,110 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MKSTANDALONE "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mkstandalone \- make a memdisk-based GRUB image +.SH SYNOPSIS +.B grub-mkstandalone +[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR] \fI\,SOURCE\/\fR... +.SH DESCRIPTION +Generate a standalone image (containing all modules) in the selected format +.TP +\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR +Add a note segment reserving SIZE bytes for an +appended signature +.TP +\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo +compress GRUB files [optional] +.TP +\fB\-\-disable\-shim\-lock\fR +disable shim_lock verifier +.TP +\fB\-\-dtb\fR=\fI\,FILE\/\fR +embed a specific DTB +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +use images and modules under DIR +[default=/usr/lib/grub/] +.TP +\fB\-\-fonts\fR=\fI\,FONTS\/\fR +install FONTS [default=unicode] +.TP +\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR +install only MODULES and their dependencies +[default=all] +.TP +\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR +embed FILE as public key for signature checking +.TP +\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR +[default=/usr/share/locale] +.TP +\fB\-\-locales\fR=\fI\,LOCALES\/\fR +install only LOCALES [default=all] +.TP +\fB\-\-modules\fR=\fI\,MODULES\/\fR +pre\-load specified modules MODULES +.TP +\fB\-\-sbat\fR=\fI\,FILE\/\fR +SBAT metadata +.TP +\fB\-\-themes\fR=\fI\,THEMES\/\fR +install THEMES [default=starfield] +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR +embed FILE as an x509 certificate for signature +checking +.TP +\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto +choose the compression to use for core image +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +save output in FILE [required] +.TP +\fB\-O\fR, \fB\-\-format\fR=\fI\,FILE\/\fR +generate an image in FORMAT +available formats: i386\-coreboot, i386\-multiboot, +i386\-pc, i386\-xen_pvh, i386\-pc\-pxe, +i386\-pc\-eltorito, i386\-efi, i386\-ieee1275, +i386\-qemu, x86_64\-efi, i386\-xen, x86_64\-xen, +mipsel\-yeeloong\-flash, mipsel\-fuloong2f\-flash, +mipsel\-loongson\-elf, powerpc\-ieee1275, +sparc64\-ieee1275\-raw, sparc64\-ieee1275\-cdcore, +sparc64\-ieee1275\-aout, ia64\-efi, mips\-arc, +mipsel\-arc, mipsel\-qemu_mips\-elf, +mips\-qemu_mips\-flash, mipsel\-qemu_mips\-flash, +mips\-qemu_mips\-elf, arm\-uboot, +arm\-coreboot\-vexpress, arm\-coreboot\-veyron, +arm\-efi, arm64\-efi, riscv32\-efi, riscv64\-efi +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.PP +Graft point syntax (E.g. \fI\,/boot/grub/grub\/\fP.cfg=./grub.cfg) is accepted +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkimage (1) +.PP +The full documentation for +.B grub-mkstandalone +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mkstandalone +programs are properly installed at your site, the command +.IP +.B info grub-mkstandalone +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-mount.1 b/upstream/fedora-40/man1/grub2-mount.1 new file mode 100644 index 00000000..c091092b --- /dev/null +++ b/upstream/fedora-40/man1/grub2-mount.1 @@ -0,0 +1,48 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-MOUNT "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-mount \- export GRUB filesystem with FUSE +.SH SYNOPSIS +.B grub-mount +[\fI\,OPTION\/\fR...] \fI\,IMAGE1 \/\fR[\fI\,IMAGE2 \/\fR...] \fI\,MOUNTPOINT\/\fR +.SH DESCRIPTION +Debug tool for filesystem driver. +.TP +\fB\-C\fR, \fB\-\-crypto\fR +Mount crypto devices. +.TP +\fB\-d\fR, \fB\-\-debug\fR=\fI\,STRING\/\fR +Set debug environment variable. +.TP +\fB\-K\fR, \fB\-\-zfs\-key\fR=\fI\,FILE\/\fR|prompt +Load zfs crypto key. +.TP +\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR +Set root device. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "SEE ALSO" +The full documentation for +.B grub-mount +is maintained as a Texinfo manual. If the +.B info +and +.B grub-mount +programs are properly installed at your site, the command +.IP +.B info grub-mount +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-script-check.1 b/upstream/fedora-40/man1/grub2-script-check.1 new file mode 100644 index 00000000..d079772e --- /dev/null +++ b/upstream/fedora-40/man1/grub2-script-check.1 @@ -0,0 +1,37 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-SCRIPT-CHECK "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-script-check \- check grub.cfg for syntax errors +.SH SYNOPSIS +.B grub-script-check +[\fI\,OPTION\/\fR...] [\fI\,PATH\/\fR] +.SH DESCRIPTION +Checks GRUB script configuration file for syntax errors. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-mkconfig (8) +.PP +The full documentation for +.B grub-script-check +is maintained as a Texinfo manual. If the +.B info +and +.B grub-script-check +programs are properly installed at your site, the command +.IP +.B info grub-script-check +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-set-bootflag.1 b/upstream/fedora-40/man1/grub2-set-bootflag.1 new file mode 100644 index 00000000..9d0cd683 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-set-bootflag.1 @@ -0,0 +1,23 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-SET-BOOTFLAG "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-set-bootflag \- set a bootflag in the GRUB environment block +.SH SYNOPSIS +.B 'grub-set-bootflag +\fI\,', where is one of:\/\fR +.SH DESCRIPTION +.IP +boot_success +menu_show_once +.SH "SEE ALSO" +The full documentation for +.B grub-set-bootflag +is maintained as a Texinfo manual. If the +.B info +and +.B grub-set-bootflag +programs are properly installed at your site, the command +.IP +.B info grub-set-bootflag +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/grub2-syslinux2cfg.1 b/upstream/fedora-40/man1/grub2-syslinux2cfg.1 new file mode 100644 index 00000000..a84bf688 --- /dev/null +++ b/upstream/fedora-40/man1/grub2-syslinux2cfg.1 @@ -0,0 +1,68 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH GRUB-SYSLINUX2CFG "1" "February 2024" "GRUB 2.06" "User Commands" +.SH NAME +grub-syslinux2cfg \- transform syslinux config into grub.cfg +.SH SYNOPSIS +.B grub-syslinux2cfg +[\fI\,OPTION\/\fR...] \fI\,FILE\/\fR +.SH DESCRIPTION +Transform syslinux config into GRUB one. +.TP +\fB\-c\fR, \fB\-\-cwd\fR=\fI\,DIR\/\fR +current directory of syslinux [default is parent +directory of input file]. +.TP +\fB\-i\fR, \fB\-\-isolinux\fR +assume input is an isolinux configuration file. +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +write output to FILE [default=stdout]. +.TP +\fB\-p\fR, \fB\-\-pxelinux\fR +assume input is a pxelinux configuration file. +.TP +\fB\-r\fR, \fB\-\-root\fR=\fI\,DIR\/\fR +root directory of the syslinux disk [default=/]. +.TP +\fB\-s\fR, \fB\-\-syslinux\fR +assume input is a syslinux configuration file. +.TP +\fB\-t\fR, \fB\-\-target\-root\fR=\fI\,DIR\/\fR +root directory as it will be seen on runtime +[default=/]. +.TP +\fB\-T\fR, \fB\-\-target\-cwd\fR=\fI\,DIR\/\fR +current directory of syslinux as it will be seen +on runtime [default is parent directory of input +file]. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print verbose messages. +.TP +\-?, \fB\-\-help\fR +give this help list +.TP +\fB\-\-usage\fR +give a short usage message +.TP +\fB\-V\fR, \fB\-\-version\fR +print program version +.PP +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. +.SH "REPORTING BUGS" +Report bugs to . +.SH "SEE ALSO" +.BR grub-menulst2cfg (8) +.PP +The full documentation for +.B grub-syslinux2cfg +is maintained as a Texinfo manual. If the +.B info +and +.B grub-syslinux2cfg +programs are properly installed at your site, the command +.IP +.B info grub-syslinux2cfg +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/gs.1 b/upstream/fedora-40/man1/gs.1 new file mode 100644 index 00000000..c3897406 --- /dev/null +++ b/upstream/fedora-40/man1/gs.1 @@ -0,0 +1,431 @@ +.TH GS 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*- +.SH NAME +gs \- Ghostscript (PostScript and PDF language interpreter and previewer) +.SH SYNOPSIS +\fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR +.br +\fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR +.br +\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR +.br +\fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR +.de TQ +.br +.ns +.TP \\$1 +.. +.SH DESCRIPTION +The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR) +command invokes \fBGhostscript\fR, an interpreter of Adobe Systems' +\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages. +\fBgs\fR reads "files" in sequence and executes them as Ghostscript +programs. After doing this, it reads further input from the standard input +stream (normally the keyboard), interpreting each line separately and +output to an output device (may be a file or an X11 window preview, +see below). The +interpreter exits gracefully when it encounters the "quit" command (either +in a file or from the keyboard), at end-of-file, or at an interrupt signal +(such as Control-C at the keyboard). +.PP +The interpreter recognizes many option switches, some of which are described +below. Please see the usage documentation for complete information. Switches +may appear anywhere in the command line and apply to all files thereafter. +Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a +message which shows several useful switches, all the devices known to +that executable, and the search path for fonts; on Unix it also shows the +location of detailed documentation. +.PP +Ghostscript may be built to use many different output devices. To see +which devices your executable includes, run "\fBgs -h\fR". +.PP +Unless you +specify a particular device, Ghostscript normally opens the first one of +those and directs output to it. +.PP +If built with X11 support, often +the default device is an X11 window (previewer), else ghostscript will +typically +use the bbox device and print on stdout the dimension of the postscript file. +.PP +So if the first one in the list is the one +you want to use, just issue the command +.PP +.nf + gs myfile.ps +.fi +.PP +You can also check the set of available devices from within Ghostscript: +invoke Ghostscript and type +.PP +.nf + devicenames == +.fi +.PP +but the first device on the resulting list may not be the default device +you determine with "\fBgs -h\fR". To specify "AbcXyz" as the +initial output device, include the switch +.PP +.nf + \-sDEVICE=AbcXyz +.fi +.PP +For example, for output to an Epson printer you might use the command +.PP +.nf + gs \-sDEVICE=epson myfile.ps +.fi +.PP +The "\-sDEVICE=" switch must precede the first mention of a file to print, +and only the switch's first use has any effect. +.PP +Finally, you can specify a default device in the environment variable +\fBGS_DEVICE\fR. The order of precedence for these alternatives from +highest to lowest (Ghostscript uses the device defined highest in the list) +is: +.PP +Some devices can support different resolutions (densities). To specify +the resolution on such a printer, use the "\-r" switch: +.PP +.nf + gs \-sDEVICE= \-rx +.fi +.PP +For example, on a 9-pin Epson-compatible printer, you get the +lowest-density (fastest) mode with +.PP +.nf + gs \-sDEVICE=epson \-r60x72 +.fi +.PP +and the highest-density (best output quality) mode with +.PP +.nf + gs \-sDEVICE=epson \-r240x72. +.fi +.PP +If you select a printer as the output device, Ghostscript also allows you +to choose where Ghostscript sends the output \-\- on Unix systems, usually +to a temporary file. To send the output to a file "foo.xyz", +use the switch +.PP +.nf + \-sOutputFile=foo.xyz +.fi +.PP +You might want to print each page separately. To do this, send the output +to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile=" +switch with "%d" in a filename template: +.PP +.nf + \-sOutputFile=foo%d.xyz +.fi +.PP +Each resulting file receives one page of output, and the files are numbered +in sequence. "%d" is a printf format specification; you can also use a +variant like "%02d". +.PP +On Unix and MS Windows systems you can also send output to a pipe. For example, to +pipe output to the "\fBlpr\fR" command (which, on many Unix systems, +directs it to a printer), use the option +.PP +.nf + \-sOutputFile=%pipe%lpr +.fi +.PP +Note that the '%' characters need to be doubled on MS Windows to avoid +mangling by the command interpreter. +.PP +You can also send output to standard output: +.PP +.nf + \-sOutputFile=\- +.fi +or +.nf + \-sOutputFile=%stdout% +.fi +.PP +In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript +from writing messages to standard output. +.PP +To select a specific paper size, use the command line switch +.PP +.nf + -sPAPERSIZE= +.fi +.PP +for instance +.PP +.nf + -sPAPERSIZE=a4 +.fi +or +.nf + -sPAPERSIZE=legal +.fi +.PP +Most ISO and US paper sizes are recognized. See the usage documentation for +a full list, or the definitions in the initialization file "gs_statd.ps". +.PP +Ghostscript can do many things other than print or view PostScript and +PDF files. For example, if you want to know the bounding box of a +PostScript (or EPS) file, Ghostscript provides a special "device" that +just prints out this information. +.PP +For example, using one of the example files distributed with Ghostscript, +.PP +.nf + gs \-sDEVICE=bbox golfer.ps +.fi +.PP +prints out +.PP +.nf + %%BoundingBox: 0 25 583 732 + %%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445 +.fi +.SH OPTIONS +.TP +.BI \-\- " filename arg1 ..." +Takes the next argument as a file name as usual, but takes all remaining +arguments (even if they have the syntactic form of switches) and defines +the name "ARGUMENTS" in "userdict" (not "systemdict") as an +array of those strings, \fBbefore\fR running the file. When Ghostscript +finishes executing the file, it exits back to the shell. +.TP +.BI \-D name = token +.TQ +.BI \-d name = token +Define a name in "systemdict" with the given definition. The token must be +exactly one token (as defined by the "token" operator) and may contain no +whitespace. +.TP +.BI \-D name +.TQ +.BI \-d name +Define a name in "systemdict" with value=null. +.TP +.BI \-S name = string +.TQ +.BI \-s name = string +Define a name in "systemdict" with a given string as value. This is +different from \fB\-d\fR. For example, \fB\-dname=35\fR is equivalent to the +program fragment +.br + /name 35 def +.br +whereas \fB\-sname=35\fR is equivalent to +.br + /name (35) def +.TP +.B \-P +Makes Ghostscript to look first in the current directory for library files. +By default, Ghostscript no longer looks in the current directory, +unless, of course, the first explicitly supplied directory is "." in \fB-I\fR. +See also the \fBINITIALIZATION FILES\fR section below, and bundled +\fBUse.htm\fR for detailed discussion on search paths and how Ghostcript finds files. +.TP +.B \-q +Quiet startup: suppress normal startup messages, and also do the +equivalent of \fB\-dQUIET\fR. +.TP +.BI \-g number1 x number2 +Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and +\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR. This is for the benefit of devices +(such as X11 windows) that require (or allow) width and height to be +specified. +.TP +.BI \-r number +.TQ +.BI \-r number1 x number2 +Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and +\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR. This is for the benefit of +devices such as printers that support multiple X and Y resolutions. If +only one number is given, it is used for both X and Y resolutions. +.TP +.BI \-I directories +Adds the designated list of directories at the head of the +search path for library files. +.TP +.B \- +This is not really a switch, but indicates to Ghostscript that standard +input is coming from a file or a pipe and not interactively from the +command line. Ghostscript reads from standard input until it reaches +end-of-file, executing it like any other file, and then continues with +processing the command line. When the command line has been entirely +processed, Ghostscript exits rather than going into its interactive mode. +.PP +Note that the normal initialization file "gs_init.ps" makes "systemdict" +read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR, +\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be +superseded by definitions in "userdict" or other dictionaries.) +.SH "SPECIAL NAMES" +.TP +.B \-dNOCACHE +Disables character caching. Useful only for debugging. +.TP +.B \-dNOBIND +Disables the "bind" operator. Useful only for debugging. +.TP +.B \-dNODISPLAY +Suppresses the normal initialization of the output device. +This may be useful when debugging. +.TP +.B \-dNOPAUSE +Disables the prompt and pause at the end of each page. This may be +desirable for applications where another program is driving Ghostscript. +.TP +.B \-dNOPLATFONTS +Disables the use of fonts supplied by the underlying platform (for instance +X Windows). This may be needed if the platform fonts look undesirably +different from the scalable fonts. +.TP +.B \-dSAFER +Restricts file operations the job can perform. Now the default mode of operation. +.TP +.B \-dWRITESYSTEMDICT +Leaves "systemdict" writable. This is necessary when running special +utility programs, but is strongly discouraged as it bypasses normal Postscript +security measures. +.TP +.BI \-sDEVICE= device +Selects an alternate initial output device, as described above. +.TP +.BI \-sOutputFile= filename +Selects an alternate output file (or pipe) for the initial output +device, as described above. +.SH "SAFER MODE" +.PP +The +.B \-dSAFER +option restricts file system accesses to those files and directories +allowed by the relevant environment variables (such as GS_LIB) or +by the command line parameters (see https://ghostscript.com/doc/current/Use.htm +for details). +.PP +SAFER mode is now the default mode of operation. Thus when running programs that +need to open files or set restricted parameters +you should pass the +.B \-dNOSAFER +command line option or its synonym +.BR \-dDELAYSAFER . +.PP +Running with NOSAFER/DELAYSAFER (as the same suggests) loosens the security +and is thus recommended ONLY for debugging or in VERY controlled workflows, +and strongly NOT recommended in any other circumstances. +.SH FILES +.PP +The locations of many Ghostscript run-time files are compiled into the +executable when it is built. On Unix these are typically based in +\fB/usr/local\fR, but this may be different on your system. Under DOS they +are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if +you install Ghostscript with \fBGSview\fR. Run "\fBgs -h\fR" to find the +location of Ghostscript documentation on your system, from which you can +get more details. +.TP +.B /usr/local/share/ghostscript/#.##/* +Startup files, utilities, and basic font definitions +.TP +.B /usr/local/share/ghostscript/fonts/* +More font definitions +.TP +.B /usr/local/share/ghostscript/#.##/examples/* +Ghostscript demonstration files +.TP +.B /usr/local/share/ghostscript/#.##/doc/* +Diverse document files +.SH "INITIALIZATION FILES" +When looking for the initialization files "gs_*.ps", the files related to +fonts, or the file for the "run" operator, Ghostscript first tries to open +the file with the name as given, using the current working directory if no +directory is specified. If this fails, and the file name doesn't specify +an explicit directory or drive (for instance, doesn't contain "/" on Unix +systems or "\\" on MS Windows systems), Ghostscript tries directories in this +order: +.TP 4 +1. +the directories specified by the \fB\-I\fR switches in the command +line (see below), if any; +.TP +2. +the directories specified by the \fBGS_LIB\fR environment variable, +if any; +.TP +3. +the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the +Ghostscript makefile when the executable was built. When \fBgs\fR is built +on Unix, \fBGS_LIB_DEFAULT\fR is usually +"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts" +where "#.##" represents the Ghostscript version number. +.PP +Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter) +may be either a single directory or a list of directories separated by +":". +.SH ENVIRONMENT +.TP +.B GS_OPTIONS +String of options to be processed before the command line options +.TP +.B GS_DEVICE +Used to specify an output device +.TP +.B GS_FONTPATH +Path names used to search for fonts +.TP +.B GS_LIB +Path names for initialization files and fonts +.TP +.B TEMP +Where temporary files are made +.SH X RESOURCES +Ghostscript, or more properly the X11 display device, looks for the +following resources under the program name "Ghostscript": +.TP +.B borderWidth +The border width in pixels (default = 1). +.TP +.B borderColor +The name of the border color (default = black). +.TP +.B geometry +The window size and placement, WxH+X+Y (default is NULL). +.TP +.B xResolution +The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR +and \fBWidthMMOfScreen\fR). +.TP +.B yResolution +The number of y pixels per inch (default is computed from +\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR). +.TP +.B useBackingPixmap +Determines whether backing store is to be used for saving display window +(default = true). +.PP +See the usage document for a more complete list of resources. To set these +resources on Unix, put them in a file such as "~/.Xresources" in the +following form: +.PP +.nf + Ghostscript*geometry: 612x792\-0+0 + Ghostscript*xResolution: 72 + Ghostscript*yResolution: 72 +.fi +.PP +Then merge these resources into the X server's resource database: +.PP +.nf + % xrdb \-merge ~/.Xresources +.fi +.SH SEE ALSO +The various Ghostscript document files (above), especially \fBUse.htm\fR. +.SH BUGS +See http://bugs.ghostscript.com/ and the Usenet news group +comp.lang.postscript. +.SH VERSION +This document was last revised for Ghostscript version 10.02.1. +.SH AUTHOR +Artifex Software, Inc. are the primary maintainers +of Ghostscript. +Russell J. Lang, gsview at ghostgum.com.au, is the author of +most of the MS Windows code in Ghostscript. diff --git a/upstream/fedora-40/man1/gsnd.1 b/upstream/fedora-40/man1/gsnd.1 new file mode 100644 index 00000000..2711357c --- /dev/null +++ b/upstream/fedora-40/man1/gsnd.1 @@ -0,0 +1,19 @@ +.TH GSND 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*- +.SH NAME +gsnd \- Run ghostscript (PostScript and PDF engine) without display +.SH SYNOPSIS +\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... +.SH DESCRIPTION +This script simply invokes +.BR gs (1) +with the +.B -NODISPLAY +flag, followed by any other arguments from the command-line. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 10.02.1. +.SH AUTHOR +Artifex Software, Inc. are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/upstream/fedora-40/man1/gstack.1 b/upstream/fedora-40/man1/gstack.1 new file mode 100644 index 00000000..1f4e406b --- /dev/null +++ b/upstream/fedora-40/man1/gstack.1 @@ -0,0 +1,48 @@ +.\" +.\" gstack manual page. +.\" Copyright (c) 1999 Ross Thompson +.\" Copyright (c) 2001, 2002, 2004, 2008 Red Hat, Inc. +.\" +.\" Original author: Ross Thompson +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2, or (at your option) +.\" any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; see the file COPYING. If not, write to +.\" the Free Software Foundation, 59 Temple Place - Suite 330, +.\" Boston, MA 02111-1307, USA. +.\" +.TH GSTACK 1 "Feb 15 2008" "Red Hat Linux" "Linux Programmer's Manual" + +.SH NAME +gstack \- print a stack trace of a running process + +.SH SYNOPSIS +.B gstack +pid + +.SH DESCRIPTION + +\f3gstack\f1 attaches to the active process named by the \f3pid\f1 on +the command line, and prints out an execution stack trace. If ELF +symbols exist in the binary (usually the case unless you have run +strip(1)), then symbolic addresses are printed as well. + +If the process is part of a thread group, then \f3gstack\f1 will print +out a stack trace for each of the threads in the group. + +.SH SEE ALSO +nm(1), ptrace(2), gdb(1) + +.SH AUTHORS +Ross Thompson + +Red Hat, Inc. diff --git a/upstream/fedora-40/man1/gzexe.1 b/upstream/fedora-40/man1/gzexe.1 new file mode 100644 index 00000000..04e3a732 --- /dev/null +++ b/upstream/fedora-40/man1/gzexe.1 @@ -0,0 +1,57 @@ +.TH GZEXE 1 +.SH NAME +gzexe \- compress executable files in place +.SH SYNOPSIS +.B gzexe +.I "name .\|.\|." +.SH DESCRIPTION +The +.B gzexe +utility allows you to compress executables in place and have them +automatically uncompress and execute when you run them (at a penalty +in performance). For example if you execute ``gzexe /usr/bin/gdb'' it +will create the following two files: +.nf +.br + -rwxr-xr-x 1 root root 1026675 Jun 7 13:53 /usr/bin/gdb + -rwxr-xr-x 1 root root 2304524 May 30 13:02 /usr/bin/gdb~ +.fi +/usr/bin/gdb~ is the original file and /usr/bin/gdb is the self-uncompressing +executable file. You can remove /usr/bin/gdb~ once you are sure that +/usr/bin/gdb works properly. +.PP +This utility is most useful on systems with very small disks. +.SH OPTIONS +.TP +.B \-d +Decompress the given executables instead of compressing them. +.SH "SEE ALSO" +.BR gzip (1), +.BR znew (1), +.BR zmore (1), +.BR zcmp (1), +.BR zforce (1) +.SH CAVEATS +The compressed executable is a shell script. This may create some +security holes. In particular, the compressed executable relies +on the PATH environment variable to find +.B gzip +and some standard utilities +.RB ( basename , +.BR chmod , +.BR ln , +.BR mkdir , +.BR mktemp , +.BR rm , +.BR sleep , +and +.BR tail ). +.SH "BUGS" +The +.B gzexe +command +attempts to retain the original file attributes on the compressed executable, +but you may have to fix them manually in some cases, using +.B chmod +or +.BR chown . diff --git a/upstream/fedora-40/man1/gzip.1 b/upstream/fedora-40/man1/gzip.1 new file mode 100644 index 00000000..657ad0d6 --- /dev/null +++ b/upstream/fedora-40/man1/gzip.1 @@ -0,0 +1,577 @@ +.TH GZIP 1 local +.SH NAME +gzip, gunzip, zcat \- compress or expand files +.SH SYNOPSIS +.ll +8 +.B gzip +.RB [ " \-acdfhklLnNrtvV19 " ] +.RB [ \-S\ suffix ] +[ +.I "name \&..." +] +.ll -8 +.br +.B gunzip +.RB [ " \-acfhklLnNrtvV " ] +.RB [ \-S\ suffix ] +[ +.I "name \&..." +] +.br +.B zcat +.RB [ " \-fhLV " ] +[ +.I "name \&..." +] +.SH DESCRIPTION +The +.B gzip +command +reduces the size of the named files using Lempel-Ziv coding (LZ77). +Whenever possible, +each file is replaced by one with the extension +.BR "\&.gz" , +while keeping the same ownership modes, access and modification times. +(The default extension is +.B "z" +for MSDOS, OS/2 FAT, Windows NT FAT and Atari.) +If no files are specified, or if a file name is "\-", +the standard input is compressed to the standard output. +The +.B gzip +command +will only attempt to compress regular files. +In particular, it will ignore symbolic links. +.PP +If the compressed file name is too long for its file system, +.B gzip +truncates it. +The +.B gzip +command +attempts to truncate only the parts of the file name longer than 3 characters. +(A part is delimited by dots.) If the name consists of small parts only, +the longest parts are truncated. +For example, if file names are limited to 14 characters, +gzip.msdos.exe is compressed to gzi.msd.exe.gz. +Names are not truncated on systems which do not have a limit on file name +length. +.PP +By default, +.B gzip +keeps the original file name and timestamp in the compressed file. +These are used when decompressing the file with the +.B \-N +option. +This is useful when the compressed file name was truncated or +when the timestamp was not preserved after a file transfer. +.PP +Compressed files can be restored to their original form using +.B "gzip \-d" +or +.B gunzip +or +.BR zcat . +If the original name saved in the compressed file is not suitable for its +file system, a new name is constructed from the original one to make it valid. +.PP +.B gunzip +takes a list of files on its command line and replaces each +file whose name ends with .gz, \-gz, .z, \-z, or _z (ignoring case) +and which begins with the correct magic number with an uncompressed +file without the original extension. +.B gunzip +also recognizes the special extensions +.B "\&.tgz" +and +.B "\&.taz" +as shorthands for +.B "\&.tar.gz" +and +.B "\&.tar.Z" +respectively. +When compressing, +.B gzip +uses the +.B "\&.tgz" +extension if necessary instead of truncating a file with a +.B "\&.tar" +extension. +.PP +.B gunzip +can currently decompress files created by +.BR gzip , +.BR zip , +.BR compress , +.B "compress \-H" +or +.BR pack . +The detection of the input format is automatic. +When using the first two formats, +.B gunzip +checks a 32 bit CRC. +For +.B pack +and +.B gunzip +checks the uncompressed length. +The standard +.B compress +format was not designed to allow consistency checks. +However +.B gunzip +is sometimes able to detect a bad .Z file. +If you get an error when uncompressing a .Z file, +do not assume that the .Z file is +correct simply because the standard +.B uncompress +does not complain. +This generally means that the standard +.B uncompress +does not check its input, and happily generates garbage output. +The SCO compress \-H format (lzh compression method) does not include a CRC +but also allows some consistency checks. +.PP +Files created by +.B zip +can be uncompressed by gzip only if they have a single member compressed +with the 'deflation' method. +This feature is only intended to help +conversion of tar.zip files to the tar.gz format. +To extract a +.B zip +file with a single member, use a command like +.RB ' "gunzip foo.gz + gzip \-c file2 >> foo.gz + +Then + + gunzip \-c foo + +is equivalent to + + cat file1 file2 + +In case of damage to one member of a .gz file, other members can +still be recovered (if the damaged member is removed). +However, you can get better compression by compressing all members at once: + + cat file1 file2 | gzip > foo.gz + +compresses better than + + gzip \-c file1 file2 > foo.gz + +If you want to recompress concatenated files to get better compression, do: + + gzip \-cd old.gz | gzip > new.gz + +If a compressed file consists of several members, the uncompressed +size and CRC reported by the \-\-list option applies to the last member only. +If you need the uncompressed size for all members, you can use: + + gzip \-cd file.gz | wc \-c + +If you wish to create a single archive file with multiple members so +that members can later be extracted independently, use an archiver +such as tar or zip. +GNU tar supports the \-z option to invoke gzip transparently. +gzip is designed as a complement to tar, not as a replacement. +.SH "ENVIRONMENT" +The obsolescent environment variable +.B GZIP +can hold a set of default options for +.BR gzip . +These options are interpreted first and can be overwritten by explicit +command line parameters. +As this can cause problems when using scripts, +this feature is supported only for options that are +reasonably likely to not cause too much harm, and +.B gzip +warns if it is used. +This feature will be removed in a future release of +.BR gzip . +.PP +You can use an alias or script instead. +For example, if +.B gzip +is in the directory +.B /usr/bin +you can prepend +.B $HOME/bin +to your +.B PATH +and create an executable script +.B $HOME/bin/gzip +containing the following: + + #! /bin/sh + export PATH=/usr/bin + exec gzip \-9 "$@" +.SH "SEE ALSO" +.BR znew (1), +.BR zcmp (1), +.BR zmore (1), +.BR zforce (1), +.BR gzexe (1), +.BR zip (1), +.BR unzip (1), +.BR compress (1) +.PP +The +.B gzip +file format is specified in P. Deutsch, \s-1GZIP\s0 file format +specification version 4.3, +.BR , +Internet RFC 1952 (May 1996). +The +.B zip +deflation format is specified in P. Deutsch, \s-1DEFLATE\s0 Compressed +Data Format Specification version 1.3, +.BR , +Internet RFC 1951 (May 1996). +.SH "DIAGNOSTICS" +Exit status is normally 0; +if an error occurs, exit status is 1. +If a warning occurs, exit status is 2. +.TP +Usage: gzip [\-cdfhklLnNrtvV19] [\-S suffix] [file ...] +Invalid options were specified on the command line. +.TP +\fIfile\fP\^: not in gzip format +The file specified to +.B gunzip +has not been compressed. +.TP +\fIfile\fP\^: Corrupt input. +Use zcat to recover some data. +The compressed file has been damaged. +The data up to the point of failure can be recovered using + + zcat \fIfile\fP > recover +.TP +\fIfile\fP\^: compressed with \fIxx\fP bits, can only handle \fIyy\fP bits +.B File +was compressed (using LZW) by a program that could deal with +more +bits +than the decompress code on this machine. +Recompress the file with gzip, which compresses better and uses +less memory. +.TP +\fIfile\fP\^: already has .gz suffix \-\- unchanged +The file is assumed to be already compressed. +Rename the file and try again. +.TP +\fIfile\fP already exists; do you wish to overwrite (y or n)? +Respond "y" if you want the output file to be replaced; "n" if not. +.TP +gunzip: corrupt input +A SIGSEGV violation was detected which usually means that the input file has +been corrupted. +.TP +\fIxx.x%\fP Percentage of the input saved by compression. +(Relevant only for +.B \-v +and +.BR \-l \.) +.TP +\-\- not a regular file or directory: ignored +When the input file is not a regular file or directory, +(e.g., a symbolic link, socket, FIFO, device file), it is +left unaltered. +.TP +\-\- has \fIxx\fP other links: unchanged +The input file has links; it is left unchanged. +See +.BR ln "(1)" +for more information. +Use the +.B \-f +flag to force compression of multiply-linked files. +.SH CAVEATS +When writing compressed data to a tape, it is generally necessary to +pad the output with zeroes up to a block boundary. +When the data is read and the whole block is passed to +.B gunzip +for decompression, +.B gunzip +detects that there is extra trailing garbage after the compressed data +and emits a warning by default. +You can use the \-\-quiet option to suppress the warning. +.SH BUGS +In some rare cases, the \-\-best option gives worse compression than +the default compression level (\-6). +On some highly redundant files, +.B compress +compresses better than +.BR gzip . +.SH "REPORTING BUGS" +Report bugs to: bug\-gzip@gnu.org +.br +GNU gzip home page: +.br +General help using GNU software: +.SH "COPYRIGHT NOTICE" +Copyright \(co 1998\(en1999, 2001\(en2002, 2012, 2015\(en2023 +Free Software Foundation, Inc. +.br +Copyright \(co 1992, 1993 Jean-loup Gailly +.PP +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. diff --git a/upstream/fedora-40/man1/hdifftopam.1 b/upstream/fedora-40/man1/hdifftopam.1 new file mode 100644 index 00000000..df6f94f8 --- /dev/null +++ b/upstream/fedora-40/man1/hdifftopam.1 @@ -0,0 +1,72 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Hdifftopam User Manual" 0 "15 April 2002" "netpbm documentation" + +.SH NAME +hdifftopam - convert horizontal difference image to original PAM image + +.UN synopsis +.SH SYNOPSIS + +\fBhdifftopam\fP[\fIpamfile\fP] +[\fB-pnm\fP] +[\fB-verbose\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use +double hyphens instead of single hyphen to denote options. You may +use white space in place of the equals sign to separate an option name +from its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBhdifftopam\fP undoes what \fBpamtohdiff\fP does. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBhdifftopam\fP recognizes the following +command line options: + + +.TP +\fB-pnm\fP + This option tells \fBhdifftopam\fP to create a PNM image (i.e. PGM or + PPM). Without it, \fBhdifftopam\fP creates a PAM image (with a + tuple type of "unhdiff"). If the PAM does not have the proper depth + to be a PGM or PPM (i.e. 1 or 3) and you specify \fB-pnm\fP, + \fBhdifftopam\fP fails. + + +.TP +\fB-verbose\fP + Print output image width, height, depth and maxval to standard error. + + +.UN seealso +.SH SEE ALSO +.BR "pamtohdiff" (1)\c +\& + +.UN author +.SH AUTHOR + +Bryan Henderson +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/hdifftopam.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/head.1 b/upstream/fedora-40/man1/head.1 new file mode 100644 index 00000000..35c138e0 --- /dev/null +++ b/upstream/fedora-40/man1/head.1 @@ -0,0 +1,65 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH HEAD "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +head \- output the first part of files +.SH SYNOPSIS +.B head +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print the first 10 lines of each FILE to standard output. +With more than one FILE, precede each with a header giving the file name. +.PP +With no FILE, or when FILE is \-, read standard input. +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\-]NUM\/\fR +print the first NUM bytes of each file; +with the leading '\-', print all but the last +NUM bytes of each file +.TP +\fB\-n\fR, \fB\-\-lines\fR=\fI\,[\-]NUM\/\fR +print the first NUM lines instead of the first 10; +with the leading '\-', print all but the last +NUM lines of each file +.TP +\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR +never print headers giving file names +.TP +\fB\-v\fR, \fB\-\-verbose\fR +always print headers giving file names +.TP +\fB\-z\fR, \fB\-\-zero\-terminated\fR +line delimiter is NUL, not newline +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +NUM may have a multiplier suffix: +b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024, +GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y, R, Q. +Binary prefixes can be used, too: KiB=K, MiB=M, and so on. +.SH AUTHOR +Written by David MacKenzie and Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBtail\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) head invocation\(aq diff --git a/upstream/fedora-40/man1/hipstopgm.1 b/upstream/fedora-40/man1/hipstopgm.1 new file mode 100644 index 00000000..d650eab8 --- /dev/null +++ b/upstream/fedora-40/man1/hipstopgm.1 @@ -0,0 +1,58 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Hipstopgm User Manual" 0 "24 August 89" "netpbm documentation" + +.SH NAME +hipstopgm - convert a HIPS file into a PGM image + +.UN synopsis +.SH SYNOPSIS + +\fBhipstopgm\fP +[\fIhipsfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBhipstopgm\fP reads a HIPS file as input and produces a PGM +image as output. +.PP +If the HIPS file contains more than one frame in sequence, +\fBhipstopgm\fP will concatenate all the frames vertically. +.PP +HIPS is a format developed at the Human Information Processing +Laboratory, NYU. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBhipstopgm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "pgm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1989 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/hipstopgm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/homectl.1 b/upstream/fedora-40/man1/homectl.1 new file mode 100644 index 00000000..db58c946 --- /dev/null +++ b/upstream/fedora-40/man1/homectl.1 @@ -0,0 +1,1371 @@ +'\" t +.TH "HOMECTL" "1" "" "systemd 255" "homectl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +homectl \- Create, remove, change or inspect home directories +.SH "SYNOPSIS" +.HP \w'\fBhomectl\fR\ 'u +\fBhomectl\fR [OPTIONS...] {COMMAND} [NAME...] +.SH "DESCRIPTION" +.PP +\fBhomectl\fR +may be used to create, remove, change or inspect a user\*(Aqs home directory\&. It\*(Aqs primarily a command interfacing with +\fBsystemd-homed.service\fR(8) +which manages home directories of users\&. +.PP +Home directories managed by +systemd\-homed\&.service +are self\-contained, and thus include the user\*(Aqs full metadata record in the home\*(Aqs data storage itself, making them easy to migrate between machines\&. In particular, a home directory describes a matching user record, and every user record managed by +systemd\-homed\&.service +also implies existence and encapsulation of a home directory\&. The user account and home directory become the same concept\&. +.PP +The following backing storage mechanisms are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An individual LUKS2 encrypted loopback file for a user, stored in +/home/*\&.home\&. At login the file system contained in this files is mounted, after the LUKS2 encrypted volume has been attached\&. The user\*(Aqs password is identical to the encryption passphrase of the LUKS2 volume\&. Access to data without preceding user authentication is thus not possible, even for the system administrator\&. This storage mechanism provides the strongest data security and is thus recommended\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Similar, but the LUKS2 encrypted file system is located on regular block device, such as a USB storage stick\&. In this mode home directories and all data they include are nicely migratable between machines, simply by plugging the USB stick into different systems at different times\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An encrypted directory using +"fscrypt" +on file systems that support it (at the moment this is primarily +"ext4"), located in +/home/*\&.homedir\&. This mechanism also provides encryption, but substantially weaker than LUKS2, as most file system metadata is unprotected\&. Moreover it currently does not support changing user passwords once the home directory has been created\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A +"btrfs" +subvolume for each user, also located in +/home/*\&.homedir\&. This provides no encryption, but good quota support\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A regular directory for each user, also located in +/home/*\&.homedir\&. This provides no encryption, but is a suitable fallback available on all machines, even where LUKS2, +"fscrypt" +or +"btrfs" +support is not available\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An individual Windows file share (CIFS) for each user\&. +.RE +.PP +Note that +systemd\-homed\&.service +and +\fBhomectl\fR +will not manage "classic" UNIX user accounts as created with +\fBuseradd\fR(8) +or similar tools\&. In particular, this functionality is not suitable for managing system users (i\&.e\&. users with a UID below 1000) but is exclusive to regular ("human") users\&. +.PP +Note that users/home directories managed via +\fBsystemd\-homed\&.service\fR +do not show up in +/etc/passwd +and similar files, they are synthesized via glibc NSS during runtime\&. They are thus resolvable and may be enumerated via the +\fBgetent\fR(1) +tool\&. +.PP +This tool interfaces directly with +systemd\-homed\&.service, and may execute specific commands on the home directories it manages\&. Since every home directory managed that way also defines a JSON user and group record these home directories may also be inspected and enumerated via +\fBuserdbctl\fR(1)\&. +.PP +Home directories managed by +systemd\-homed\&.service +are usually in one of two states, or in a transition state between them: when +"active" +they are unlocked and mounted, and thus accessible to the system and its programs; when +"inactive" +they are not mounted and thus not accessible\&. Activation happens automatically at login of the user and usually can only complete after a password (or other authentication token) has been supplied\&. Deactivation happens after the user fully logged out\&. A home directory remains active as long as the user is logged in at least once, i\&.e\&. has at least one login session\&. When the user logs in a second time simultaneously the home directory remains active\&. It is deactivated only after the last of the user\*(Aqs sessions ends\&. +.SH "OPTIONS" +.PP +The following general options are understood (further options that control the various properties of user records managed by +systemd\-homed\&.service +are documented further down): +.PP +\fB\-\-identity=\fR\fIFILE\fR +.RS 4 +Read the user\*(Aqs JSON record from the specified file\&. If passed as +"\-" +read the user record from standard input\&. The supplied JSON object must follow the structure documented in +\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2\&. This option may be used in conjunction with the +\fBcreate\fR +and +\fBupdate\fR +commands (see below), where it allows configuring the user record in JSON as\-is, instead of setting the individual user record properties (see below)\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-json=\fR\fIFORMAT\fR, \fB\-j\fR +.RS 4 +Controls whether to output the user record in JSON format, if the +\fBinspect\fR +command (see below) is used\&. Takes one of +"pretty", +"short" +or +"off"\&. If +"pretty" +human\-friendly whitespace and newlines are inserted in the output to make the JSON data more readable\&. If +"short" +all superfluous whitespace is suppressed\&. If +"off" +(the default) the user information is not shown in JSON format but in a friendly human readable formatting instead\&. The +\fB\-j\fR +option picks +"pretty" +when run interactively and +"short" +otherwise\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-export\-format=\fR\fIFORMAT\fR, \fB\-E\fR, \fB\-EE\fR +.RS 4 +When used with the +\fBinspect\fR +verb in JSON mode (see above) may be used to suppress certain aspects of the JSON user record on output\&. Specifically, if +"stripped" +format is used the binding and runtime fields of the record are removed\&. If +"minimal" +format is used the cryptographic signature is removed too\&. If +"full" +format is used the full JSON record is shown (this is the default)\&. This option is useful for copying an existing user record to a different system in order to create a similar user there with the same settings\&. Specifically: +\fBhomectl inspect \-EE | ssh root@othersystem homectl create \-i\-\fR +may be used as simple command line for replicating a user on another host\&. +\fB\-E\fR +is equivalent to +\fB\-j \-\-export\-format=stripped\fR, +\fB\-EE\fR +to +\fB\-j \-\-export\-format=minimal\fR\&. Note that when replicating user accounts user records acquired in +"stripped" +mode will retain the original cryptographic signatures and thus may only be modified when the private key to update them is available on the destination machine\&. When replicating users in +"minimal" +mode, the signature is removed during the replication and thus the record will be implicitly signed with the key of the destination machine and may be updated there without any private key replication\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-H\fR, \fB\-\-host=\fR +.RS 4 +Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by +"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by +":", and then a container name, separated by +"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with +\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&. +.RE +.PP +\fB\-M\fR, \fB\-\-machine=\fR +.RS 4 +Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating +"@" +character\&. If the special string +"\&.host" +is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus: +"\-\-user \-\-machine=lennart@\&.host")\&. If the +"@" +syntax is not used, the connection is made as root user\&. If the +"@" +syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and +"\&.host" +are implied\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +\fB\-\-no\-legend\fR +.RS 4 +Do not print the legend, i\&.e\&. column headers and the footer with hints\&. +.RE +.PP +\fB\-\-no\-ask\-password\fR +.RS 4 +Do not query the user for authentication for privileged operations\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.SH "USER RECORD PROPERTIES" +.PP +The following options control various properties of the user records/home directories that +systemd\-homed\&.service +manages\&. These switches may be used in conjunction with the +\fBcreate\fR +and +\fBupdate\fR +commands for configuring various aspects of the home directory and the user account: +.PP +\fB\-\-real\-name=\fR\fINAME\fR, \fB\-c\fR \fINAME\fR +.RS 4 +The real name for the user\&. This corresponds with the GECOS field on classic UNIX NSS records\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-realm=\fR\fIREALM\fR +.RS 4 +The realm for the user\&. The realm associates a user with a specific organization or installation, and allows distinguishing users of the same name defined in different contexts\&. The realm can be any string that also qualifies as valid DNS domain name, and it is recommended to use the organization\*(Aqs or installation\*(Aqs domain name for this purpose, but this is not enforced nor required\&. On each system only a single user of the same name may exist, and if a user with the same name and realm is seen it is assumed to refer to the same user while a user with the same name but different realm is considered a different user\&. Note that this means that two users sharing the same name but with distinct realms are not allowed on the same system\&. Assigning a realm to a user is optional\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-email\-address=\fR\fIEMAIL\fR +.RS 4 +Takes an electronic mail address to associate with the user\&. On log\-in the +\fI$EMAIL\fR +environment variable is initialized from this value\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-location=\fR\fITEXT\fR +.RS 4 +Takes location specification for this user\&. This is free\-form text, which might or might not be usable by geo\-location applications\&. Example: +\fB\-\-location="Berlin, Germany"\fR +or +\fB\-\-location="Basement, Room 3a"\fR +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-icon\-name=\fR\fIICON\fR +.RS 4 +Takes an icon name to associate with the user, following the scheme defined by the +\m[blue]\fBIcon Naming Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-home\-dir=\fR\fIPATH\fR, \fB\-d\fR\fIPATH\fR +.RS 4 +Takes a path to use as home directory for the user\&. Note that this is the directory the user\*(Aqs home directory is mounted to while the user is logged in\&. This is not where the user\*(Aqs data is actually stored, see +\fB\-\-image\-path=\fR +for that\&. If not specified defaults to +/home/$USER\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-uid=\fR\fIUID\fR +.RS 4 +Takes a preferred numeric UNIX UID to assign this user\&. If a user is to be created with the specified UID and it is already taken by a different user on the local system then creation of the home directory is refused\&. Note though, if after creating the home directory it is used on a different system and the configured UID is taken by another user there, then +\fBsystemd\-homed\fR +may assign the user a different UID on that system\&. The specified UID must be outside of the system user range\&. It is recommended to use the 60001\&...60513 UID range for this purpose\&. If not specified, the UID is automatically picked\&. If the home directory is found to be owned by a different UID when logging in, the home directory and everything underneath it will have its ownership changed automatically before login completes\&. +.sp +Note that changing this option for existing home directories generally has no effect on home directories that already have been registered locally (have a local +\fIbinding\fR), as the UID used for an account on the local system is determined when the home directory is first activated on it, and then remains in effect until the home directory is removed\&. +.sp +Note that users managed by +\fBsystemd\-homed\fR +always have a matching group associated with the same name as well as a GID matching the UID of the user\&. Thus, configuring the GID separately is not permitted\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-member\-of=\fR\fIGROUP\fR, \fB\-G\fR \fIGROUP\fR +.RS 4 +Takes a comma\-separated list of auxiliary UNIX groups this user shall belong to\&. Example: +\fB\-\-member\-of=wheel\fR +to provide the user with administrator privileges\&. Note that +\fBsystemd\-homed\fR +does not manage any groups besides a group matching the user in name and numeric UID/GID\&. Thus any groups listed here must be registered independently, for example with +\fBgroupadd\fR(8)\&. Any non\-existent groups are ignored\&. This option may be used more than once, in which case all specified group lists are combined\&. If the user is currently a member of a group which is not listed, the user will be removed from the group\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-capability\-bounding\-set=\fR\fICAPABILITIES\fR, \fB\-\-capability\-ambient\-set=\fR\fICAPABILITIES\fR +.RS 4 +These options take a space separated list of process capabilities (e\&.g\&. +\fBCAP_WAKE_ALARM\fR, +\fBCAP_BLOCK_SUSPEND\fR, \&...) that shall be set in the capability bounding and ambient sets for all the user\*(Aqs sessions\&. See +\fBcapabilities\fR(7) +for details on the capabilities concept\&. These options may be used more than once, in which case the specified lists are combined\&. If the parameter begins with a +"~" +character the effect is inverted: the specified capability is dropped from the specific set\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-skel=\fR\fIPATH\fR +.RS 4 +Takes a file system path to a directory\&. Specifies the skeleton directory to initialize the home directory with\&. All files and directories in the specified path are copied into any newly create home directory\&. If not specified defaults to +/etc/skel/\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-shell=\fR\fISHELL\fR +.RS 4 +Takes a file system path\&. Specifies the shell binary to execute on terminal logins\&. If not specified defaults to +/bin/bash\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-setenv=\fR\fIVARIABLE\fR[=\fIVALUE\fR] +.RS 4 +Takes an environment variable assignment to set for all user processes\&. May be used multiple times to set multiple environment variables\&. When +"=" +and +\fIVALUE\fR +are omitted, the value of the variable with the same name in the program environment will be used\&. +.sp +Note that a number of other settings also result in environment variables to be set for the user, including +\fB\-\-email=\fR, +\fB\-\-timezone=\fR +and +\fB\-\-language=\fR\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-timezone=\fR\fITIMEZONE\fR +.RS 4 +Takes a time zone location name that sets the timezone for the specified user\&. When the user logs in the +\fI$TZ\fR +environment variable is initialized from this setting\&. Example: +\fB\-\-timezone=Europe/Amsterdam\fR +will result in the environment variable +"TZ=:Europe/Amsterdam"\&. (":" +is used intentionally as part of the timezone specification, see +\fBtzset\fR(3)\&.) +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-language=\fR\fILANG\fR +.RS 4 +Takes a specifier indicating the preferred language of the user\&. The +\fI$LANG\fR +environment variable is initialized from this value on login, and thus a value suitable for this environment variable is accepted here, for example +\fB\-\-language=de_DE\&.UTF8\fR\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-ssh\-authorized\-keys=\fR\fIKEYS\fR +.RS 4 +Either takes a SSH authorized key line to associate with the user record or a +"@" +character followed by a path to a file to read one or more such lines from\&. SSH keys configured this way are made available to SSH to permit access to this home directory and user record\&. This option may be used more than once to configure multiple SSH keys\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-pkcs11\-token\-uri=\fR\fIURI\fR +.RS 4 +Takes an RFC 7512 PKCS#11 URI referencing a security token (e\&.g\&. YubiKey or PIV smartcard) that shall be able to unlock the user account\&. The security token URI should reference a security token with exactly one pair of X\&.509 certificate and private key\&. A random secret key is then generated, encrypted with the public key of the X\&.509 certificate, and stored as part of the user record\&. At login time it is decrypted with the PKCS#11 module and then used to unlock the account and associated resources\&. See below for an example how to set up authentication with a security token\&. +.sp +Instead of a valid PKCS#11 URI, the special strings +"list" +and +"auto" +may be specified\&. If +"list" +is passed, a brief table of suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs\&. If +"auto" +is passed, a suitable PKCS#11 hardware token is automatically selected (this operation will fail if there isn\*(Aqt exactly one suitable token discovered)\&. The latter is a useful shortcut for the most common case where a single PKCS#11 hardware token is plugged in\&. +.sp +Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the +"hmac\-secret" +extension (for example: the YubiKey 5 series), as supported with the +\fB\-\-fido2\-device=\fR +option below\&. Both mechanisms are similarly powerful, though FIDO2 is the more modern technology\&. PKCS#11/PIV tokens have the benefit of being recognizable before authentication and hence can be used for implying the user identity to use for logging in, which FIDO2 does not allow\&. PKCS#11/PIV devices generally require initialization (i\&.e\&. storing a private/public key pair on them, see example below) before they can be used; FIDO2 security tokens generally do not required that, and work out of the box\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-fido2\-credential\-algorithm=\fR\fISTRING\fR +.RS 4 +Specify COSE algorithm used in credential generation\&. The default value is +"es256"\&. Supported values are +"es256", +"rs256" +and +"eddsa"\&. +.sp +"es256" +denotes ECDSA over NIST P\-256 with SHA\-256\&. +"rs256" +denotes 2048\-bit RSA with PKCS#1\&.5 padding and SHA\-256\&. +"eddsa" +denotes EDDSA over Curve25519 with SHA\-512\&. +.sp +Note that your authenticator may not support some algorithms\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-fido2\-device=\fR\fIPATH\fR +.RS 4 +Takes a path to a Linux +"hidraw" +device (e\&.g\&. +/dev/hidraw1), referring to a FIDO2 security token implementing the +"hmac\-secret" +extension that shall be able to unlock the user account\&. A random salt value is generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the salt using an internal secret key\&. The result is then used as the key to unlock the user account\&. The random salt is included in the user record, so that whenever authentication is needed it can be passed to the FIDO2 token again\&. +.sp +Instead of a valid path to a FIDO2 +"hidraw" +device the special strings +"list" +and +"auto" +may be specified\&. If +"list" +is passed, a brief table of suitable discovered FIDO2 devices is shown\&. If +"auto" +is passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered\&. The latter is a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in\&. +.sp +Note that FIDO2 devices suitable for this option must implement the +"hmac\-secret" +extension\&. Most current devices (such as the YubiKey 5 series) do\&. If the extension is not implemented the device cannot be used for unlocking home directories\&. +.sp +The FIDO2 device may be subsequently removed by setting the device path to an empty string (e\&.g\&. +\fBhomectl update $USER \-\-fido2\-device=""\fR)\&. +.sp +Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be used with either +\fB\-\-fido2\-device=\fR +or +\fB\-\-pkcs11\-token\-uri=\fR), for a discussion see above\&. +.sp +Added in version 246\&. +.RE +.PP +\fB\-\-fido2\-with\-client\-pin=\fR\fIBOOL\fR +.RS 4 +When enrolling a FIDO2 security token, controls whether to require the user to enter a PIN when unlocking the account (the FIDO2 +"clientPin" +feature)\&. Defaults to +"yes"\&. (Note: this setting is without effect if the security token does not support the +"clientPin" +feature at all, or does not allow enabling or disabling it\&.) +.sp +Added in version 249\&. +.RE +.PP +\fB\-\-fido2\-with\-user\-presence=\fR\fIBOOL\fR +.RS 4 +When enrolling a FIDO2 security token, controls whether to require the user to verify presence (tap the token, the FIDO2 +"up" +feature) when unlocking the account\&. Defaults to +"yes"\&. (Note: this setting is without effect if the security token does not support the +"up" +feature at all, or does not allow enabling or disabling it\&.) +.sp +Added in version 249\&. +.RE +.PP +\fB\-\-fido2\-with\-user\-verification=\fR\fIBOOL\fR +.RS 4 +When enrolling a FIDO2 security token, controls whether to require user verification when unlocking the account (the FIDO2 +"uv" +feature)\&. Defaults to +"no"\&. (Note: this setting is without effect if the security token does not support the +"uv" +feature at all, or does not allow enabling or disabling it\&.) +.sp +Added in version 249\&. +.RE +.PP +\fB\-\-recovery\-key=\fR\fIBOOL\fR +.RS 4 +Accepts a boolean argument\&. If enabled a recovery key is configured for the account\&. A recovery key is a computer generated access key that may be used to regain access to an account if the password has been forgotten or the authentication token lost\&. The key is generated and shown on screen, and should be printed or otherwise transferred to a secure location\&. A recovery key may be entered instead of a regular password to unlock the account\&. +.sp +Added in version 247\&. +.RE +.PP +\fB\-\-locked=\fR\fIBOOLEAN\fR +.RS 4 +Takes a boolean argument\&. Specifies whether this user account shall be locked\&. If true logins into this account are prohibited, if false (the default) they are permitted (of course, only if authorization otherwise succeeds)\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-not\-before=\fR\fITIMESTAMP\fR, \fB\-\-not\-after=\fR\fITIMESTAMP\fR +.RS 4 +These options take a timestamp string, in the format documented in +\fBsystemd.time\fR(7) +and configures points in time before and after logins into this account are not permitted\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-rate\-limit\-interval=\fR\fISECS\fR, \fB\-\-rate\-limit\-burst=\fR\fINUMBER\fR +.RS 4 +Configures a rate limit on authentication attempts for this user\&. If the user attempts to authenticate more often than the specified number, on a specific system, within the specified time interval authentication is refused until the time interval passes\&. Defaults to 10 times per 1min\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-password\-hint=\fR\fITEXT\fR +.RS 4 +Takes a password hint to store alongside the user record\&. This string is stored accessible only to privileged users and the user itself and may not be queried by other users\&. Example: +\fB\-\-password\-hint="My first pet\*(Aqs name"\fR\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-enforce\-password\-policy=\fR\fIBOOL\fR, \fB\-P\fR +.RS 4 +Takes a boolean argument\&. Configures whether to enforce the system\*(Aqs password policy for this user, regarding quality and strength of selected passwords\&. Defaults to on\&. +\fB\-P\fR +is short for +\fB\-\-\-enforce\-password\-policy=no\fR\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-password\-change\-now=\fR\fIBOOL\fR +.RS 4 +Takes a boolean argument\&. If true the user is asked to change their password on next login\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-password\-change\-min=\fR\fITIME\fR, \fB\-\-password\-change\-max=\fR\fITIME\fR, \fB\-\-password\-change\-warn=\fR\fITIME\fR, \fB\-\-password\-change\-inactive=\fR\fITIME\fR +.RS 4 +Each of these options takes a time span specification as argument (in the syntax documented in +\fBsystemd.time\fR(7)) and configures various aspects of the user\*(Aqs password expiration policy\&. Specifically, +\fB\-\-password\-change\-min=\fR +configures how much time has to pass after changing the password of the user until the password may be changed again\&. If the user tries to change their password before this time passes the attempt is refused\&. +\fB\-\-password\-change\-max=\fR +configures how soon after it has been changed the password expires and needs to be changed again\&. After this time passes logging in may only proceed after the password is changed\&. +\fB\-\-password\-change\-warn=\fR +specifies how much earlier than then the time configured with +\fB\-\-password\-change\-max=\fR +the user is warned at login to change their password as it will expire soon\&. Finally +\fB\-\-password\-change\-inactive=\fR +configures the time which has to pass after the password as expired until the user is not permitted to log in or change the password anymore\&. Note that these options only apply to password authentication, and do not apply to other forms of authentication, for example PKCS#11\-based security token authentication\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-disk\-size=\fR\fIBYTES\fR +.RS 4 +Either takes a size in bytes as argument (possibly using the usual K, M, G, \&... suffixes for 1024 base values), a percentage value, or the special strings +"min" +or +"max", and configures the disk space to assign to the user\&. If a percentage value is specified (i\&.e\&. the argument suffixed with +"%") it is taken relative to the available disk space of the backing file system\&. If specified as +"min" +assigns the minimal disk space permitted by the constraints of the backing file system and other limits, when specified as +"max" +assigns the maximum disk space available\&. If the LUKS2 backend is used this configures the size of the loopback file and file system contained therein\&. For the other storage backends configures disk quota using the filesystem\*(Aqs native quota logic, if available\&. If not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for the others\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-access\-mode=\fR\fIMODE\fR +.RS 4 +Takes a UNIX file access mode written in octal\&. Configures the access mode of the home directory itself\&. Note that this is only used when the directory is first created, and the user may change this any time afterwards\&. Example: +\fB\-\-access\-mode=0700\fR +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-umask=\fR\fIMASK\fR +.RS 4 +Takes the access mode mask (in octal syntax) to apply to newly created files and directories of the user ("umask")\&. If set this controls the initial umask set for all login sessions of the user, possibly overriding the system\*(Aqs defaults\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-nice=\fR\fINICE\fR +.RS 4 +Takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login time\&. Takes a numeric value in the range \-20 (highest priority) to 19 (lowest priority)\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-rlimit=\fR\fILIMIT\fR=\fIVALUE\fR[:\fIVALUE\fR] +.RS 4 +Allows configuration of resource limits for processes of this user, see +\fBgetrlimit\fR(2) +for details\&. Takes a resource limit name (e\&.g\&. +"LIMIT_NOFILE") followed by an equal sign, followed by a numeric limit\&. Optionally, separated by colon a second numeric limit may be specified\&. If two are specified this refers to the soft and hard limits, respectively\&. If only one limit is specified the setting sets both limits in one\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-tasks\-max=\fR\fITASKS\fR +.RS 4 +Takes a non\-zero unsigned integer as argument\&. Configures the maximum number of tasks (i\&.e\&. threads, where each process is at least one thread) the user may have at any given time\&. This limit applies to all tasks forked off the user\*(Aqs sessions, even if they change user identity via +\fBsu\fR(1) +or a similar tool\&. Use +\fB\-\-rlimit=LIMIT_NPROC=\fR +to place a limit on the tasks actually running under the UID of the user, thus excluding any child processes that might have changed user identity\&. This controls the +\fITasksMax=\fR +setting of the per\-user systemd slice unit +user\-$UID\&.slice\&. See +\fBsystemd.resource-control\fR(5) +for further details\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-memory\-high=\fR\fIBYTES\fR, \fB\-\-memory\-max=\fR\fIBYTES\fR +.RS 4 +Set a limit on the memory a user may take up on a system at any given time in bytes (the usual K, M, G, \&... suffixes are supported, to the base of 1024)\&. This includes all memory used by the user itself and all processes they forked off that changed user credentials\&. This controls the +\fIMemoryHigh=\fR +and +\fIMemoryMax=\fR +settings of the per\-user systemd slice unit +user\-$UID\&.slice\&. See +\fBsystemd.resource-control\fR(5) +for further details\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-cpu\-weight=\fR\fIWEIGHT\fR, \fB\-\-io\-weight=\fR\fIWEIGHT\fR +.RS 4 +Set CPU and IO scheduling weights of the processes of the user, including those of processes forked off by the user that changed user credentials\&. Takes a numeric value in the range 1\&...10000\&. This controls the +\fICPUWeight=\fR +and +\fIIOWeight=\fR +settings of the per\-user systemd slice unit +user\-$UID\&.slice\&. See +\fBsystemd.resource-control\fR(5) +for further details\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-storage=\fR\fISTORAGE\fR +.RS 4 +Selects the storage mechanism to use for this home directory\&. Takes one of +"luks", +"fscrypt", +"directory", +"subvolume", +"cifs"\&. For details about these mechanisms, see above\&. If a new home directory is created and the storage type is not specifically specified, +\fBhomed.conf\fR(5) +defines which default storage to use\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-image\-path=\fR\fIPATH\fR +.RS 4 +Takes a file system path\&. Configures where to place the user\*(Aqs home directory\&. When LUKS2 storage is used refers to the path to the loopback file, otherwise to the path to the home directory (which may be in +/home/ +or any other accessible filesystem)\&. When unspecified defaults to +/home/$USER\&.home +when LUKS storage is used and +/home/$USER\&.homedir +for the other storage mechanisms\&. Not defined for the +"cifs" +storage mechanism\&. To use LUKS2 storage on a regular block device (for example a USB stick) pass the path to the block device here\&. Specifying the path to a directory here when using LUKS2 storage is not allowed\&. Similar, specifying the path to a regular file or device node is not allowed if any of the other storage backends are used\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-drop\-caches=\fR\fIBOOL\fR +.RS 4 +Automatically flush OS file system caches on logout\&. This is useful in combination with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and directories in memory (and accessible) after logout\&. This option is also supported on other backends, but should not bring any benefit there\&. Defaults to off, except if the selected storage backend is fscrypt, where it defaults to on\&. Note that flushing OS caches will negatively influence performance of the OS shortly after logout\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-\-fs\-type=\fR\fITYPE\fR +.RS 4 +When LUKS2 storage is used configures the file system type to use inside the home directory LUKS2 container\&. One of +"btrfs", +"ext4", +"xfs"\&. If not specified +\fBhomed.conf\fR(5) +defines which default file system type to use\&. Note that +"xfs" +is not recommended as its support for file system resizing is too limited\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-luks\-discard=\fR\fIBOOL\fR +.RS 4 +When LUKS2 storage is used configures whether to enable the +"discard" +feature of the file system\&. If enabled the file system on top of the LUKS2 volume will report empty block information to LUKS2 and the loopback file below, ensuring that empty space in the home directory is returned to the backing file system below the LUKS2 volume, resulting in a "sparse" loopback file\&. This option mostly defaults to off, since this permits over\-committing home directories which results in I/O errors if the underlying file system runs full while the upper file system wants to allocate a block\&. Such I/O errors are generally not handled well by file systems nor applications\&. When LUKS2 storage is used on top of regular block devices (instead of on top a loopback file) the discard logic defaults to on\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-luks\-offline\-discard=\fR\fIBOOL\fR +.RS 4 +Similar to +\fB\-\-luks\-discard=\fR, controls the trimming of the file system\&. However, while +\fB\-\-luks\-discard=\fR +controls what happens when the home directory is active, +\fB\-\-luks\-offline\-discard=\fR +controls what happens when it becomes inactive, i\&.e\&. whether to trim/allocate the storage when deactivating the home directory\&. This option defaults to on, to ensure disk space is minimized while a user is not logged in\&. +.sp +Added in version 246\&. +.RE +.PP +\fB\-\-luks\-extra\-mount\-options=\fR\fIOPTIONS\fR +.RS 4 +Takes a string containing additional mount options to use when mounting the LUKS volume\&. If specified, this string will be appended to the default, built\-in mount options\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-\-luks\-cipher=\fR\fICIPHER\fR, \fB\-\-luks\-cipher\-mode=\fR\fIMODE\fR, \fB\-\-luks\-volume\-key\-size=\fR\fIBYTES\fR, \fB\-\-luks\-pbkdf\-type=\fR\fITYPE\fR, \fB\-\-luks\-pbkdf\-hash\-algorithm=\fR\fIALGORITHM\fR, \fB\-\-luks\-pbkdf\-force\-iterations=\fR\fIITERATIONS\fR, \fB\-\-luks\-pbkdf\-time\-cost=\fR\fISECONDS\fR, \fB\-\-luks\-pbkdf\-memory\-cost=\fR\fIBYTES\fR, \fB\-\-luks\-pbkdf\-parallel\-threads=\fR\fITHREADS\fR, \fB\-\-luks\-sector\-size=\fR\fIBYTES\fR +.RS 4 +Configures various cryptographic parameters for the LUKS2 storage mechanism\&. See +\fBcryptsetup\fR(8) +for details on the specific attributes\&. +.sp +Note that +\fBhomectl\fR +uses bytes for key size, like +/proc/crypto, but +\fBcryptsetup\fR(8) +uses bits\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-auto\-resize\-mode=\fR +.RS 4 +Configures whether to automatically grow and/or shrink the backing file system on login and logout\&. Takes one of the strings +"off", +"grow", +"shrink\-and\-grow"\&. Only applies to the LUKS2 backend currently, and if the btrfs file system is used inside it (since only then online growing/shrinking of the file system is supported)\&. Defaults to +"shrink\-and\-grow", if LUKS2/btrfs is used, otherwise is off\&. If set to +"off" +no automatic shrinking/growing during login or logout is done\&. If set to +"grow" +the home area is grown to the size configured via +\fB\-\-disk\-size=\fR +should it currently be smaller\&. If it already matches the configured size or is larger no operation is executed\&. If set to +"shrink\-and\-grow" +the home area is also resized during logout to the minimal size the used disk space and file system constraints permit\&. This mode thus ensures that while a home area is activated it is sized to the configured size, but while deactivated it is compacted taking up only the minimal space possible\&. Note that if the system is powered off abnormally or if the user otherwise not logged out cleanly the shrinking operation will not take place, and the user has to re\-login/logout again before it is executed again\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-\-rebalance\-weight=\fR +.RS 4 +Configures the weight parameter for the free disk space rebalancing logic\&. Only applies to the LUKS2 backend (since for the LUKS2 backend disk space is allocated from a per\-user loopback file system instead of immediately from a common pool like the other backends do it)\&. In regular intervals free disk space in the active home areas and their backing storage is redistributed among them, taking the weight value configured here into account\&. Expects an integer in the range 1\&...10000, or the special string +"off"\&. If not specified defaults to 100\&. The weight is used to scale free space made available to the home areas: a home area with a weight of 200 will get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half of that\&. The backing file system will be assigned space for a weight of 20\&. If set to +"off" +no automatic free space distribution is done for this home area\&. Note that resizing the home area explicitly (with +\fBhomectl resize\fR +see below) will implicitly turn off the automatic rebalancing\&. To reenable the automatic rebalancing use +\fB\-\-rebalance\-weight=\fR +with an empty parameter\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-\-nosuid=\fR\fIBOOL\fR, \fB\-\-nodev=\fR\fIBOOL\fR, \fB\-\-noexec=\fR\fIBOOL\fR +.RS 4 +Configures the +"nosuid", +"nodev" +and +"noexec" +mount options for the home directories\&. By default +"nodev" +and +"nosuid" +are on, while +"noexec" +is off\&. For details about these mount options see +\fBmount\fR(8)\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-cifs\-domain=\fR\fIDOMAIN\fR, \fB\-\-cifs\-user\-name=\fR\fIUSER\fR, \fB\-\-cifs\-service=\fR\fISERVICE\fR, \fB\-\-cifs\-extra\-mount\-options=\fR\fIOPTIONS\fR +.RS 4 +Configures the Windows File Sharing (CIFS) domain and user to associate with the home directory/user account, as well as the file share ("service") to mount as directory\&. The latter is used when +"cifs" +storage is selected\&. The file share should be specified in format +"//\fIhost\fR/\fIshare\fR/\fIdirectory/\&...\fR"\&. The directory part is optional \(em if not specified the home directory will be placed in the top\-level directory of the share\&. The +\fB\-\-cifs\-extra\-mount\-options=\fR +setting allows specifying additional mount options when mounting the share, see +\fBmount.cifs\fR(8) +for details\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-stop\-delay=\fR\fISECS\fR +.RS 4 +Configures the time the per\-user service manager shall continue to run after the all sessions of the user ended\&. The default is configured in +\fBlogind.conf\fR(5) +(for home directories of LUKS2 storage located on removable media this defaults to 0 though)\&. A longer time makes sure quick, repetitive logins are more efficient as the user\*(Aqs service manager doesn\*(Aqt have to be started every time\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-kill\-processes=\fR\fIBOOL\fR +.RS 4 +Configures whether to kill all processes of the user on logout\&. The default is configured in +\fBlogind.conf\fR(5)\&. +.sp +Added in version 245\&. +.RE +.PP +\fB\-\-auto\-login=\fR\fIBOOL\fR +.RS 4 +Takes a boolean argument\&. Configures whether the graphical UI of the system should automatically log this user in if possible\&. Defaults to off\&. If less or more than one user is marked this way automatic login is disabled\&. +.sp +Added in version 245\&. +.RE +.SH "COMMANDS" +.PP +The following commands are understood: +.PP +\fBlist\fR +.RS 4 +List all home directories (along with brief details) currently managed by +systemd\-homed\&.service\&. This command is also executed if none is specified on the command line\&. (Note that the list of users shown by this command does not include users managed by other subsystems, such as system users or any traditional users listed in +/etc/passwd\&.) +.sp +Added in version 245\&. +.RE +.PP +\fBactivate\fR \fIUSER\fR [\fIUSER\&...\fR] +.RS 4 +Activate one or more home directories\&. The home directories of each listed user will be activated and made available under their mount points (typically in +/home/$USER)\&. Note that any home activated this way stays active indefinitely, until it is explicitly deactivated again (with +\fBdeactivate\fR, see below), or the user logs in and out again and it thus is deactivated due to the automatic deactivation\-on\-logout logic\&. +.sp +Activation of a home directory involves various operations that depend on the selected storage mechanism\&. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file system, mounting the file system, and potentially changing the ownership of all included files to the correct UID/GID\&. +.sp +Added in version 245\&. +.RE +.PP +\fBdeactivate\fR \fIUSER\fR [\fIUSER\&...\fR] +.RS 4 +Deactivate one or more home directories\&. This undoes the effect of +\fBactivate\fR\&. +.sp +Added in version 245\&. +.RE +.PP +\fBinspect\fR \fIUSER\fR [\fIUSER\&...\fR] +.RS 4 +Show various details about the specified home directories\&. This shows various information about the home directory and its user account, including runtime data such as current state, disk use and similar\&. Combine with +\fB\-\-json=\fR +to show the detailed JSON user record instead, possibly combined with +\fB\-\-export\-format=\fR +to suppress certain aspects of the output\&. +.sp +Added in version 245\&. +.RE +.PP +\fBauthenticate\fR \fIUSER\fR [\fIUSER\&...\fR] +.RS 4 +Validate authentication credentials of a home directory\&. This queries the caller for a password (or similar) and checks that it correctly unlocks the home directory\&. This leaves the home directory in the state it is in, i\&.e\&. it leaves the home directory in inactive state if it was inactive before, and in active state if it was active before\&. +.sp +Added in version 245\&. +.RE +.PP +\fBcreate\fR \fIUSER\fR, \fBcreate\fR \fB\-\-identity=\fR\fIPATH\fR [\fIUSER\fR] +.RS 4 +Create a new home directory/user account of the specified name\&. Use the various user record property options (as documented above) to control various aspects of the home directory and its user accounts\&. +.sp +The specified user name should follow the strict syntax described on +\m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +Added in version 245\&. +.RE +.PP +\fBremove\fR \fIUSER\fR +.RS 4 +Remove a home directory/user account\&. This will remove both the home directory\*(Aqs user record and the home directory itself, and thus delete all files and directories owned by the user\&. +.sp +Added in version 245\&. +.RE +.PP +\fBupdate\fR \fIUSER\fR, \fBupdate\fR \fB\-\-identity=\fR\fIPATH\fR [\fIUSER\fR] +.RS 4 +Update a home directory/user account\&. Use the various user record property options (as documented above) to make changes to the account, or alternatively provide a full, updated JSON user record via the +\fB\-\-identity=\fR +option\&. +.sp +Note that changes to user records not signed by a cryptographic private key available locally are not permitted, unless +\fB\-\-identity=\fR +is used with a user record that is already correctly signed by a recognized private key\&. +.sp +Added in version 245\&. +.RE +.PP +\fBpasswd\fR \fIUSER\fR +.RS 4 +Change the password of the specified home directory/user account\&. +.sp +Added in version 245\&. +.RE +.PP +\fBresize\fR \fIUSER\fR \fIBYTES\fR +.RS 4 +Change the disk space assigned to the specified home directory\&. If the LUKS2 storage mechanism is used this will automatically resize the loopback file and the file system contained within\&. Note that if +"ext4" +is used inside of the LUKS2 volume, it is necessary to deactivate the home directory before shrinking it (i\&.e the user has to log out)\&. Growing can be done while the home directory is active\&. If +"xfs" +is used inside of the LUKS2 volume the home directory may not be shrunk whatsoever\&. On all three of +"ext4", +"xfs" +and +"btrfs" +the home directory may be grown while the user is logged in, and on the latter also shrunk while the user is logged in\&. If the +"subvolume", +"directory", +"fscrypt" +storage mechanisms are used, resizing will change file system quota\&. The size parameter may make use of the usual suffixes B, K, M, G, T (to the base of 1024)\&. The special strings +"min" +and +"max" +may be specified in place of a numeric size value, for minimizing or maximizing disk space assigned to the home area, taking constraints of the file system, disk usage inside the home area and on the backing storage into account\&. +.sp +Added in version 245\&. +.RE +.PP +\fBlock\fR \fIUSER\fR +.RS 4 +Temporarily suspend access to the user\*(Aqs home directory and remove any associated cryptographic keys from memory\&. Any attempts to access the user\*(Aqs home directory will stall until the home directory is unlocked again (i\&.e\&. re\-authenticated)\&. This functionality is primarily intended to be used during system suspend to make sure the user\*(Aqs data cannot be accessed until the user re\-authenticates on resume\&. This operation is only defined for home directories that use the LUKS2 storage mechanism\&. +.sp +Added in version 245\&. +.RE +.PP +\fBunlock\fR \fIUSER\fR +.RS 4 +Resume access to the user\*(Aqs home directory again, undoing the effect of +\fBlock\fR +above\&. This requires authentication of the user, as the cryptographic keys required for access to the home directory need to be reacquired\&. +.sp +Added in version 245\&. +.RE +.PP +\fBlock\-all\fR +.RS 4 +Execute the +\fBlock\fR +command on all suitable home directories at once\&. This operation is generally executed on system suspend (i\&.e\&. by +\fBsystemctl suspend\fR +and related commands), to ensure all active user\*(Aqs cryptographic keys for accessing their home directories are removed from memory\&. +.sp +Added in version 245\&. +.RE +.PP +\fBdeactivate\-all\fR +.RS 4 +Execute the +\fBdeactivate\fR +command on all active home directories at once\&. This operation is generally executed on system shut down (i\&.e\&. by +\fBsystemctl poweroff\fR +and related commands), to ensure all active user\*(Aqs home directories are fully deactivated before +/home/ +and related file systems are unmounted\&. +.sp +Added in version 247\&. +.RE +.PP +\fBwith\fR \fIUSER\fR \fICOMMAND\&...\fR +.RS 4 +Activate the specified user\*(Aqs home directory, run the specified command (under the caller\*(Aqs identity, not the specified user\*(Aqs) and deactivate the home directory afterwards again (unless the user is logged in otherwise)\&. This command is useful for running privileged backup scripts and such, but requires authentication with the user\*(Aqs credentials in order to be able to unlock the user\*(Aqs home directory\&. +.sp +Added in version 245\&. +.RE +.PP +\fBrebalance\fR +.RS 4 +Rebalance free disk space between active home areas and the backing storage\&. See +\fB\-\-rebalance\-weight=\fR +above\&. This executes no operation unless there\*(Aqs at least one active LUKS2 home area that has disk space rebalancing enabled\&. This operation is synchronous: it will only complete once disk space is rebalanced according to the rebalancing weights\&. Note that rebalancing also takes place automatically in the background in regular intervals\&. Use this command to synchronously ensure disk space is properly redistributed before initiating an operation requiring large amounts of disk space\&. +.sp +Added in version 250\&. +.RE +.SH "EXIT STATUS" +.PP +On success, 0 is returned, a non\-zero failure code otherwise\&. +.PP +When a command is invoked with +\fBwith\fR, the exit status of the child is propagated\&. Effectively, +\fBhomectl\fR +will exit without error if the command is successfully invoked +\fIand\fR +finishes successfully\&. +.SH "ENVIRONMENT" +.PP +\fI$SYSTEMD_LOG_LEVEL\fR +.RS 4 +The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance) +\fBemerg\fR, +\fBalert\fR, +\fBcrit\fR, +\fBerr\fR, +\fBwarning\fR, +\fBnotice\fR, +\fBinfo\fR, +\fBdebug\fR, or an integer in the range 0\&...7\&. See +\fBsyslog\fR(3) +for more information\&. +.RE +.PP +\fI$SYSTEMD_LOG_COLOR\fR +.RS 4 +A boolean\&. If true, messages written to the tty will be colored according to priority\&. +.sp +This setting is only useful when messages are written directly to the terminal, because +\fBjournalctl\fR(1) +and other tools that display logs will color messages based on the log level on their own\&. +.RE +.PP +\fI$SYSTEMD_LOG_TIME\fR +.RS 4 +A boolean\&. If true, console log messages will be prefixed with a timestamp\&. +.sp +This setting is only useful when messages are written directly to the terminal or a file, because +\fBjournalctl\fR(1) +and other tools that display logs will attach timestamps based on the entry metadata on their own\&. +.RE +.PP +\fI$SYSTEMD_LOG_LOCATION\fR +.RS 4 +A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&. +.sp +Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&. +.RE +.PP +\fI$SYSTEMD_LOG_TID\fR +.RS 4 +A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&. +.sp +Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&. +.RE +.PP +\fI$SYSTEMD_LOG_TARGET\fR +.RS 4 +The destination for log messages\&. One of +\fBconsole\fR +(log to the attached tty), +\fBconsole\-prefixed\fR +(log to the attached tty but with prefixes encoding the log level and "facility", see +\fBsyslog\fR(3), +\fBkmsg\fR +(log to the kernel circular log buffer), +\fBjournal\fR +(log to the journal), +\fBjournal\-or\-kmsg\fR +(log to the journal if available, and to kmsg otherwise), +\fBauto\fR +(determine the appropriate log target automatically, the default), +\fBnull\fR +(disable log output)\&. +.RE +.PP +\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR +.RS 4 +Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to +"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&. +.RE +.PP +\fI$SYSTEMD_PAGER\fR +.RS 4 +Pager to use when +\fB\-\-no\-pager\fR +is not given; overrides +\fI$PAGER\fR\&. If neither +\fI$SYSTEMD_PAGER\fR +nor +\fI$PAGER\fR +are set, a set of well\-known pager implementations are tried in turn, including +\fBless\fR(1) +and +\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value +"cat" +is equivalent to passing +\fB\-\-no\-pager\fR\&. +.sp +Note: if +\fI$SYSTEMD_PAGERSECURE\fR +is not set, +\fI$SYSTEMD_PAGER\fR +(as well as +\fI$PAGER\fR) will be silently ignored\&. +.RE +.PP +\fI$SYSTEMD_LESS\fR +.RS 4 +Override the options passed to +\fBless\fR +(by default +"FRSXMK")\&. +.sp +Users might want to change two options in particular: +.PP +\fBK\fR +.RS 4 +This option instructs the pager to exit immediately when +Ctrl+C +is pressed\&. To allow +\fBless\fR +to handle +Ctrl+C +itself to switch back to the pager command prompt, unset this option\&. +.sp +If the value of +\fI$SYSTEMD_LESS\fR +does not include +"K", and the pager that is invoked is +\fBless\fR, +Ctrl+C +will be ignored by the executable, and needs to be handled by the pager\&. +.RE +.PP +\fBX\fR +.RS 4 +This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&. +.RE +.sp +See +\fBless\fR(1) +for more discussion\&. +.RE +.PP +\fI$SYSTEMD_LESSCHARSET\fR +.RS 4 +Override the charset passed to +\fBless\fR +(by default +"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&. +.RE +.PP +\fI$SYSTEMD_PAGERSECURE\fR +.RS 4 +Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If +\fI$SYSTEMD_PAGERSECURE\fR +is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see +\fBgeteuid\fR(2) +and +\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode, +\fBLESSSECURE=1\fR +will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When +\fI$SYSTEMD_PAGERSECURE\fR +is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only +\fBless\fR(1) +implements secure mode\&.) +.sp +Note: when commands are invoked with elevated privileges, for example under +\fBsudo\fR(8) +or +\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting +\fISYSTEMD_PAGERSECURE=0\fR +or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the +\fI$SYSTEMD_PAGER\fR +or +\fI$PAGER\fR +variables are to be honoured, +\fI$SYSTEMD_PAGERSECURE\fR +must be set too\&. It might be reasonable to completely disable the pager using +\fB\-\-no\-pager\fR +instead\&. +.RE +.PP +\fI$SYSTEMD_COLORS\fR +.RS 4 +Takes a boolean argument\&. When true, +\fBsystemd\fR +and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values: +"16", +"256" +to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on +\fI$TERM\fR +and what the console is connected to\&. +.RE +.PP +\fI$SYSTEMD_URLIFY\fR +.RS 4 +The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that +\fBsystemd\fR +makes based on +\fI$TERM\fR +and other conditions\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Create a user "waldo" in the administrator group "wheel", and assign 500 MiB disk space to them\&.\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +homectl create waldo \-\-real\-name="Waldo McWaldo" \-G wheel \-\-disk\-size=500M +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Create a user "wally" on a USB stick, and assign a maximum of 500 concurrent tasks to them\&.\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +homectl create wally \-\-real\-name="Wally McWally" \-\-image\-path=/dev/disk/by\-id/usb\-SanDisk_Ultra_Fit_476fff954b2b5c44\-0:0 \-\-tasks\-max=500 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Change nice level of user "odlaw" to +5 and make sure the environment variable \fI$SOME\fR is set to the string "THING" for them on login\&.\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +homectl update odlaw \-\-nice=5 \-\-setenv=SOME=THING +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Set up authentication with a YubiKey security token using PKCS#11/PIV:\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Clear the Yubikey from any old keys (careful!) +ykman piv reset + +# Generate a new private/public key pair on the device, store the public key in \*(Aqpubkey\&.pem\*(Aq\&. +ykman piv generate\-key \-a RSA2048 9d pubkey\&.pem + +# Create a self\-signed certificate from this public key, and store it on the device\&. +ykman piv generate\-certificate \-\-subject "Knobelei" 9d pubkey\&.pem + +# We don\*(Aqt need the public key on disk anymore +rm pubkey\&.pem + +# Allow the security token to unlock the account of user \*(Aqlafcadio\*(Aq\&. +homectl update lafcadio \-\-pkcs11\-token\-uri=auto +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&5.\ \&Set up authentication with a FIDO2 security token:\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Allow a FIDO2 security token to unlock the account of user \*(Aqnihilbaxter\*(Aq\&. +homectl update nihilbaxter \-\-fido2\-device=auto +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-homed.service\fR(8), +\fBhomed.conf\fR(5), +\fBuserdbctl\fR(1), +\fBuseradd\fR(8), +\fBcryptsetup\fR(8) +.SH "NOTES" +.IP " 1." 4 +JSON User Records +.RS 4 +\%https://systemd.io/USER_RECORD +.RE +.IP " 2." 4 +Icon Naming Specification +.RS 4 +\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html +.RE +.IP " 3." 4 +User/Group Name Syntax +.RS 4 +\%https://systemd.io/USER_NAMES +.RE diff --git a/upstream/fedora-40/man1/hostid.1 b/upstream/fedora-40/man1/hostid.1 new file mode 100644 index 00000000..994d0c4b --- /dev/null +++ b/upstream/fedora-40/man1/hostid.1 @@ -0,0 +1,36 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH HOSTID "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +hostid \- print the numeric identifier for the current host +.SH SYNOPSIS +.B hostid +[\fI\,OPTION\/\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print the numeric identifier (in hexadecimal) for the current host. +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.SH AUTHOR +Written by Jim Meyering. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBgethostid\fP(3) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) hostid invocation\(aq diff --git a/upstream/fedora-40/man1/hostname.1 b/upstream/fedora-40/man1/hostname.1 new file mode 100644 index 00000000..96d17f40 --- /dev/null +++ b/upstream/fedora-40/man1/hostname.1 @@ -0,0 +1,280 @@ +.TH HOSTNAME 1 "2009-09-16" "net-tools" "Linux Programmer's Manual" + +.SH NAME +hostname \- show or set the system's host name +.br +domainname \- show or set the system's NIS/YP domain name +.br +ypdomainname \- show or set the system's NIS/YP domain name +.br +nisdomainname \- show or set the system's NIS/YP domain name +.br +dnsdomainname \- show the system's DNS domain name +.br + +.SH SYNOPSIS +.B hostname +.RB [ \-a|\-\-alias ] +.RB [ \-d|\-\-domain ] +.RB [ \-f|\-\-fqdn|\-\-long ] +.RB [ \-A|\-\-all-fqdns ] +.RB [ \-i|\-\-ip-address ] +.RB [ \-I|\-\-all-ip-addresses ] +.RB [ \-s|\-\-short ] +.RB [ \-y|\-\-yp|\-\-nis ] +.br +.B hostname +.RB [ \-b|\-\-boot ] +.RB [ \-F|\-\-file\ filename ] +.RB [ hostname ] +.br +.B hostname +.RB [ \-h|\-\-help ] +.RB [ \-V|\-\-version ] +.PP +.B domainname +.RB [ nisdomain ] +.RB [ \-F\ file ] +.br +.B ypdomainname +.RB [ nisdomain ] +.RB [ \-F\ file ] +.br +.B nisdomainname +.RB [ nisdomain ] +.RB [ \-F\ file ] +.PP +.B dnsdomainname + +.SH DESCRIPTION +.B Hostname +is used to display the system's DNS name, and to display or set its hostname or +NIS domain name. + +.SS "GET NAME" +When called without any arguments, the program displays the current +names: +.LP +.B hostname +will print the name of the system as returned by the +.BR gethostname (2) +function. +.LP +.B domainname +will print the NIS domainname of the system. +.B domainname +uses the +.BR gethostname (2) +function, while +.B ypdomainname +and +.B nisdomainname +use the +.BR getdomainname (2). +.LP +.B dnsdomainname +will print the domain part of the FQDN (Fully Qualified Domain Name). The +complete FQDN of the system is returned with +.B hostname \-\-fqdn +(but see the warnings in section +.B THE FQDN +below). + +.LP +The function +.BR gethostname(2) +is used to get the hostname. When the +.BR "hostname \-a, \-d, \-f or \-i" +is called will +.BR gethostbyname(3) +be called. The difference in +.BR gethostname(2) +and +.BR gethostbyname(3) +is that +.BR gethostbyname(5) +is network aware, so it consults +.IR /etc/nsswitch.conf +and +.IR /etc/host.conf +to decide whether to read information in +.IR /etc/hostname +or +.IR /etc/hosts + +.SS "SET NAME" +When called with one argument or with the +.B \-\-file +option, the commands set the host name or the NIS/YP domain name. +.B hostname +uses the +.BR sethostname (2) +function, while all of the three +.BR domainname , +.B ypdomainname +and +.B nisdomainname +use +.BR setdomainname (2). +Note, that this is effective only until the next reboot. +Edit /etc/hostname for permanent change. +.LP +Note, that only the super-user can change the names. +.LP +It is not possible to set the FQDN or the DNS domain name with the +.B dnsdomainname +command (see +.B THE FQDN +below). +.LP +The host name is usually set once at system startup +(normally by reading the contents of a file which contains +the host name, e.g. +.IR /etc/hostname ). + +.SS THE FQDN +The FQDN (Fully Qualified Domain Name) of the system is the name that the +.BR resolver (3) +returns for the host name, such as, +.IR ursula.example.com . +It is usually the hostname followed by the DNS domain name (the part +after the first dot). You can check the FQDN using +.B hostname \-\-fqdn +or the domain name using +.BR "dnsdomainname" . +.LP +You cannot change the FQDN with +.B hostname +or +.BR dnsdomainname . +.LP +The recommended method of setting the FQDN is to make the hostname be +an alias for the fully qualified name using +.IR /etc/hosts , +DNS, or NIS. For example, if the hostname was "ursula", one might have a line in +.I /etc/hosts +which reads +.LP +.RS +127.0.1.1 ursula.example.com ursula +.RE +.LP +Technically: The FQDN is the name +.BR getaddrinfo (3) +returns for the host name returned by +.BR gethostname (2). +The DNS domain name is the part after the first dot. +.LP +Therefore it depends on the configuration of the resolver (usually in +.IR /etc/host.conf ) +how you can change it. Usually the hosts file is parsed before DNS or +NIS, so it is most common to change the FQDN in +.IR /etc/hosts . +.LP +If a machine has multiple network interfaces/addresses or is used in a +mobile environment, then it may either have multiple FQDNs/domain names +or none at all. Therefore avoid using +.BR "hostname \-\-fqdn" , +.B hostname \-\-domain +and +.BR "dnsdomainname" . +.B hostname \-\-ip-address +is subject to the same limitations so it should be avoided as well. + +.SH OPTIONS +.TP +.I "\-a, \-\-alias" +Display the alias name of the host (if used). This option is deprecated +and should not be used anymore. +.TP +.I "\-A, \-\-all-fqdns" +Displays all FQDNs of the machine. This option enumerates all configured +network addresses on all configured network interfaces, and translates +them to DNS domain names. Addresses that cannot be translated (i.e. because +they do not have an appropriate reverse IP entry) are skipped. Note that +different addresses may resolve to the same name, therefore the output may +contain duplicate entries. Do not make any assumptions about the order of the +output. +.TP +.I "\-b, \-\-boot" +Always set a hostname; this allows the file specified by \fI\-F\fR to be +non-existent or empty, in which case the default hostname \fIlocalhost\fR +will be used if none is yet set. +.TP +.I "\-d, \-\-domain" +Display the name of the DNS domain. Don't use the command +.B domainname +to get the DNS domain name because it will show the NIS domain name and +not the DNS domain name. Use +.B dnsdomainname +instead. See the warnings in section +.B THE FQDN +above, and avoid using this option. +.TP +.I "\-f, \-\-fqdn, \-\-long" +Display the FQDN (Fully Qualified Domain Name). A FQDN consists of a +short host name and the DNS domain name. Unless you are using bind or NIS +for host lookups you can change the FQDN and the DNS domain name (which is +part of the FQDN) in the \fI/etc/hosts\fR file. See the warnings in section +.B THE FQDN +above und use +.B hostname \-\-all-fqdns +instead wherever possible. +.TP +.I "\-F, \-\-file filename" +Read the host name from the specified file. Comments (lines starting with +a `#') are ignored. +.TP +.I "\-i, \-\-ip-address" +Display the network address(es) of the host name. Note that this works only +if the host name can be resolved. Avoid using this option; use +.B hostname \-\-all-ip-addresses +instead. +.TP +.I "\-I, \-\-all-ip-addresses" +Display all network addresses of the host. This option enumerates all +configured addresses on all network interfaces. The loopback interface and IPv6 +link-local addresses are omitted. Contrary to option \fI\-i\fR, this option +does not depend on name resolution. Do not make any assumptions about the +order of the output. +.TP +.I "\-s, \-\-short" +Display the short host name. This is the host name cut at the first dot. +.TP +.I "\-V, \-\-version" +Print version information on standard output and exit successfully. +.TP +.I "\-y, \-\-yp, \-\-nis" +Display the NIS domain name. If a parameter is given (or +.B \-\-file name +) then root can also set a new NIS domain. +.TP +.I "\-h, \-\-help" +Print a usage message and exit. +.SH NOTES +The address families +.B hostname +tries when looking up the FQDN, aliases and network addresses of the +host are determined by the configuration of your resolver. +For instance, on GNU Libc systems, the resolver can be instructed to +try IPv6 lookups first by using the +.B inet6 +option in +.BR /etc/resolv.conf . +.SH FILES +.B /etc/hostname +Historically this file was supposed to only contain the hostname and not the +full canonical FQDN. Nowadays most software is able to cope with a full FQDN +here. This file is read at boot time by the system initialization scripts to +set the hostname. +.LP +.B /etc/hosts +Usually, this is where one sets the domain name by aliasing the host name to +the FQDN. +.SH AUTHORS +Peter Tobias, +.br +Bernd Eckenfels, (NIS and manpage). +.br +Michael Meskes, +.br diff --git a/upstream/fedora-40/man1/hostnamectl.1 b/upstream/fedora-40/man1/hostnamectl.1 new file mode 100644 index 00000000..bba45a7e --- /dev/null +++ b/upstream/fedora-40/man1/hostnamectl.1 @@ -0,0 +1,217 @@ +'\" t +.TH "HOSTNAMECTL" "1" "" "systemd 255" "hostnamectl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +hostnamectl \- Control the system hostname +.SH "SYNOPSIS" +.HP \w'\fBhostnamectl\fR\ 'u +\fBhostnamectl\fR [OPTIONS...] {COMMAND} +.SH "DESCRIPTION" +.PP +\fBhostnamectl\fR +may be used to query and change the system hostname and related settings\&. +.PP +\fBsystemd-hostnamed.service\fR(8) +and this tool distinguish three different hostnames: the high\-level "pretty" hostname which might include all kinds of special characters (e\&.g\&. "Lennart\*(Aqs Laptop"), the "static" hostname which is the user\-configured hostname (e\&.g\&. "lennarts\-laptop"), and the transient hostname which is a fallback value received from network configuration (e\&.g\&. "node12345678")\&. If a static hostname is set to a valid value, then the transient hostname is not used\&. +.PP +Note that the pretty hostname has little restrictions on the characters and length used, while the static and transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at maximum (the latter being a Linux limitation)\&. +.PP +Use +\fBsystemd-firstboot\fR(1) +to initialize the system hostname for mounted (but not booted) system images\&. +.SH "COMMANDS" +.PP +The following commands are understood: +.PP +\fBstatus\fR +.RS 4 +Show system hostname and related information\&. If no command is specified, this is the implied default\&. +.sp +Added in version 195\&. +.RE +.PP +\fBhostname\fR [\fINAME\fR] +.RS 4 +If no argument is given, print the system hostname\&. If an optional argument +\fINAME\fR +is provided then the command changes the system hostname to +\fINAME\fR\&. By default, this will alter the pretty, the static, and the transient hostname alike; however, if one or more of +\fB\-\-static\fR, +\fB\-\-transient\fR, +\fB\-\-pretty\fR +are used, only the selected hostnames are changed\&. If the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be simplified in regards to the character set used before the latter are updated\&. This is done by removing special characters and spaces\&. This ensures that the pretty and the static hostname are always closely related while still following the validity rules of the specific name\&. This simplification of the hostname string is not done if only the transient and/or static hostnames are set, and the pretty hostname is left untouched\&. +.sp +The static and transient hostnames must each be either a single DNS label (a string composed of 7\-bit ASCII lower\-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN\&. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names)\&. +.sp +Added in version 249\&. +.RE +.PP +\fBicon\-name\fR [\fINAME\fR] +.RS 4 +If no argument is given, print the icon name of the system\&. If an optional argument +\fINAME\fR +is provided then the command changes the icon name to +\fINAME\fR\&. The icon name is used by some graphical applications to visualize this host\&. The icon name should follow the +\m[blue]\fBIcon Naming Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.sp +Added in version 249\&. +.RE +.PP +\fBchassis\fR [\fITYPE\fR] +.RS 4 +If no argument is given, print the chassis type\&. If an optional argument +\fITYPE\fR +is provided then the command changes the chassis type to +\fITYPE\fR\&. The chassis type is used by some graphical applications to visualize the host or alter user interaction\&. Currently, the following chassis types are defined: +"desktop", +"laptop", +"convertible", +"server", +"tablet", +"handset", +"watch", +"embedded", as well as the special chassis types +"vm" +and +"container" +for virtualized systems that lack an immediate physical chassis\&. +.sp +Added in version 249\&. +.RE +.PP +\fBdeployment\fR [\fIENVIRONMENT\fR] +.RS 4 +If no argument is given, print the deployment environment\&. If an optional argument +\fIENVIRONMENT\fR +is provided then the command changes the deployment environment to +\fIENVIRONMENT\fR\&. Argument +\fIENVIRONMENT\fR +must be a single word without any control characters\&. One of the following is suggested: +"development", +"integration", +"staging", +"production"\&. +.sp +Added in version 249\&. +.RE +.PP +\fBlocation\fR [\fILOCATION\fR] +.RS 4 +If no argument is given, print the location string for the system\&. If an optional argument +\fILOCATION\fR +is provided then the command changes the location string for the system to +\fILOCATION\fR\&. Argument +\fILOCATION\fR +should be a human\-friendly, free\-form string describing the physical location of the system, if it is known and applicable\&. This may be as generic as +"Berlin, Germany" +or as specific as +"Left Rack, 2nd Shelf"\&. +.sp +Added in version 249\&. +.RE +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fB\-\-no\-ask\-password\fR +.RS 4 +Do not query the user for authentication for privileged operations\&. +.sp +Added in version 195\&. +.RE +.PP +\fB\-\-static\fR, \fB\-\-transient\fR, \fB\-\-pretty\fR +.RS 4 +If +\fBstatus\fR +is invoked (or no explicit command is given) and one of these switches is specified, +\fBhostnamectl\fR +will print out just this selected hostname\&. +.sp +If used with +\fBhostname\fR, only the selected hostnames will be updated\&. When more than one of these switches are specified, all the specified hostnames will be updated\&. +.sp +Added in version 195\&. +.RE +.PP +\fB\-H\fR, \fB\-\-host=\fR +.RS 4 +Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by +"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by +":", and then a container name, separated by +"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with +\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&. +.RE +.PP +\fB\-M\fR, \fB\-\-machine=\fR +.RS 4 +Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating +"@" +character\&. If the special string +"\&.host" +is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus: +"\-\-user \-\-machine=lennart@\&.host")\&. If the +"@" +syntax is not used, the connection is made as root user\&. If the +"@" +syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and +"\&.host" +are implied\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +Shows output formatted as JSON\&. Expects one of +"short" +(for the shortest possible output without any redundant whitespace or line breaks), +"pretty" +(for a pretty version of the same, with indentation and line breaks) or +"off" +(to turn off JSON output, the default)\&. +.RE +.SH "EXIT STATUS" +.PP +On success, 0 is returned, a non\-zero failure code otherwise\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBhostname\fR(1), +\fBhostname\fR(5), +\fBmachine-info\fR(5), +\fBsystemctl\fR(1), +\fBsystemd-hostnamed.service\fR(8), +\fBsystemd-firstboot\fR(1) +.SH "NOTES" +.IP " 1." 4 +Icon Naming Specification +.RS 4 +\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html +.RE diff --git a/upstream/fedora-40/man1/hpftodit.1 b/upstream/fedora-40/man1/hpftodit.1 new file mode 100644 index 00000000..8059d8c6 --- /dev/null +++ b/upstream/fedora-40/man1/hpftodit.1 @@ -0,0 +1,476 @@ +.TH hpftodit 1 "24 January 2024" "groff 1.23.0" +.SH Name +hpftodit \- create font description files for use with +.I groff +and +.I grolj4 +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1994-2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_hpftodit_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY hpftodit +.RB [ \-aqs ] +.RB [ \-i\~\c +.IR n ] +.I tfm-file +.I map-file +.I font-description +.YS +. +. +.SY hpftodit +.B \-d +.I tfm-file +.RI [ map-file ] +.YS +. +. +.SY hpftodit +.B \-\-help +.YS +. +. +.SY hpftodit +.B \-v +. +.SY hpftodit +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I hpftodit +creates a font description file for use with a Hewlett-Packard +LaserJet\~4-\%series +(or newer) +printer with the +.MR grolj4 1 +output driver of +.MR groff 1 , +using data from an HP tagged font metric (TFM) file. +. +.I tfm-file +is the name of the font's TFM file; +Intellifont and TrueType TFM files are supported, +but symbol set TFM files are not. +. +.I map-file +is a file giving the +.I groff +special character identifiers for glyphs in the font; +this file should consist of a sequence of lines of the form +.RS +.EX +.IR "m u c1 c2 " "\&.\|.\|.\& [#" " comment" "]" +.EE +.RE +where +.I m +is a decimal integer giving the glyph's MSL +(Master Symbol List) +number, +.I u +is a hexadecimal integer giving its Unicode character code, +and +.IR c1 , +.IR c2 ", .\|.\|." +are its +.I groff +glyph names +(see +.MR groff_char 7 +for a list). +. +The values can be separated by any number of spaces and/or tabs. +. +The Unicode value must use uppercase hexadecimal digits A\^\[en]\^F, +and must lack a leading +.RB \[lq] 0x \[rq], +.RB \[lq] u \[rq], +or +.RB \[lq] U+ \[rq]. +. +Unicode values corresponding to composite glyphs are decomposed; +that is +.RB \[lq] u00C0 \[rq] +becomes +.RB \[lq] u0041_0300 \[rq]. +. +A glyph without a +.I groff +special character identifier may be named +.BI u XXXX +if the glyph corresponds to a Unicode value, +or as an unnamed glyph +.RB \[lq] \-\-\- \[rq]. +. +If the given Unicode value is in the Private Use Area (PUA) +(0xE000\^\[en]\^0xF8FF), +the glyph is included as an unnamed glyph. +. +Refer to +.MR groff_diff 1 +for additional information about unnamed glyphs and how to access them. +. +. +.P +Blank lines and lines beginning with +.RB \[lq] # \[rq] +are ignored. +. +A +.RB \[lq] # \[rq] +following one or more +.I groff +names begins a comment. +. +Because +.RB \[lq] # \[rq] +is a valid +.I groff +name, +it must appear first in a list of +.I groff +names if a comment is included, +as in +. +.RS +.EX +3 0023 # # number sign +.EE +.RE +. +or +. +.RS +.EX +3 0023 # sh # number sign +.EE +.RE +. +whereas in +. +.RS +.EX +3 0023 sh # # number sign +.EE +.RE +. +the first +.RB \[lq] # \[rq] +is interpreted as the beginning of the comment. +. +. +.P +Output is written in +.MR groff_font 5 +format to +.I font-description, +a file named for the intended +.I groff +font name; +if this operand is +.RB \[lq] \- \[rq], +the font description is written to the standard output stream. +. +. +.LP +If the +.B \-i +option is used, +.I hpftodit +automatically will generate an italic correction, +a left italic correction, +and a subscript correction for each glyph +(the significance of these parameters is explained in +.MR groff_font 5 ). +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-a +Include glyphs in the TFM file that are not included in +.IR map-file . +. +A glyph with corresponding Unicode value is given the name +.RI u XXXX ; +a glyph without a Unicode value is included as an unnamed glyph +\[lq]\-\^\-\^\-\[rq]. +. +A glyph with a Unicode value in the Private Use Area +(0xE000\^\[en]\^0xF8FF) +is also included as an unnamed glyph. +. +. +.IP +This option provides a simple means of adding Unicode-named and +unnamed glyphs to a font without including them in the map file, +but it affords little control over which glyphs are placed in a regular +font and which are placed in a special font. +. +The presence or absence of the +.B \-s +option has some effect on which glyphs are included: +without it, +only the \[lq]text\[rq] symbol sets are searched for matching glyphs; +with it, +only the \[lq]mathematical\[rq] symbol sets are searched. +. +Nonetheless, +restricting the symbol sets searched isn't very selective\[em]many +glyphs are placed in both regular and special fonts. +. +Normally, +.B \-a +should be used only as a last resort. +. +. +.TP +.B \-d +Dump information about the TFM file to the standard output stream; +use this to ensure that a TFM file is a proper match for a font, +and that its contents are suitable. +. +The information includes the values of important TFM tags and a listing +(by MSL number for Intellifont TFM files or by Unicode value for +TrueType TFM files) +of the glyphs included in the TFM file. +. +The unit of measure \[lq]DU\[rq] for some tags indicates design units; +there are 8782\~design units per em for Intellifont fonts, +and 2048\~design units per em for TrueType fonts. +. +Note that the accessibility of a glyph depends on its inclusion in a +symbol set; +some TFM files list many glyphs but only a few symbol sets. +. +. +.IP +The glyph listing includes the glyph index within the TFM file, +the MSL or Unicode value, +and the symbol set and character code that will be used to print the +glyph. +. +If +.I map-file +is given, +.I groff +names are given for matching glyphs. +. +If only the glyph index and MSL or Unicode value are given, +the glyph does not appear in any supported symbol set and cannot be +printed. +. +. +.IP +With the +.B \-d +option, +.I map-file +is optional, +and +.I output-font +is ignored if given. +. +. +.TP +.BI \-i\~ n +Generate an italic correction for each glyph so that its width plus its +italic correction is equal to +.I n +thousandths of an em plus the amount by which the right edge of the +glyphs's bounding box is to the right of its origin. +. +If a negative italic correction would result, +use a zero italic correction instead. +. +. +.IP +Also generate a subscript correction equal to the product of the tangent +of the slant of the font and four fifths of the x-height of the font. +. +If a subscript correction greater than the italic correction would +result, +use a subscript correction equal to the italic correction instead. +. +. +.IP +Also generate a left italic correction for each glyph equal to +.I n +thousandths of an em plus the amount by which the left edge of the +glyphs's bounding box is to the left of its origin. +. +The left italic correction may be negative. +. +. +.IP +This option normally is needed only with italic or oblique fonts; +a value of 50 +(0.05\~em) +usually is a reasonable choice. +. +. +.TP +.B \-q +Suppress warnings about glyphs in the map file that were not found in +the TFM file. +. +Warnings never are given for unnamed glyphs or by glyphs named by their +Unicode values. +. +This option is useful when sending the output of +.I hpftodit +to the standard output stream. +. +. +.TP +.B \-s +Add the +.B special +directive to the font description file, +affecting the order in which HP symbol sets are searched for each glyph. +. +Without this option, +the \[lq]text\[rq] sets are searched before the \[lq]mathematical\[rq] +symbol sets. +. +With it, +the search order is reversed. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:DESC +describes the +.B lj4 +output device. +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/ F +describes the font known +.RI as\~ F +on device +.BR lj4 . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:\%Makefile +is a +.MR make 1 +script that uses +.MR hpftodit 1 +to prepare the +.I groff +font description files above from HP TFM data; +in can be used to regenerate them in the event the TFM files are +updated. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:\%special\:.awk +is an +.MR awk 1 +script that corrects the Intellifont-based height metrics for several +glyphs in the +.B S +(special) font for TrueType CG Times used in the HP LaserJet\~4000 and +later. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:\%special\:.map +.TQ +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:\%symbol\:.map +.TQ +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:text\:.map +.TQ +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlj4/\:\%generate/\:\%wingdings.map +map MSL indices and HP Unicode PUA assignments to +.I groff +special character identifiers. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR groff 1 , +.MR groff_diff 1 , +.MR grolj4 1 , +.MR groff_font 5 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_hpftodit_1_man_C] +.do rr *groff_hpftodit_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/icedax.1 b/upstream/fedora-40/man1/icedax.1 new file mode 100644 index 00000000..d9daddbb --- /dev/null +++ b/upstream/fedora-40/man1/icedax.1 @@ -0,0 +1,1025 @@ +'\" t +.\" @(#)icedax.1 1.14 02/12/09 Copyright 1998,1999,2000 Heiko Eissfeldt +.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a +.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o +.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u +.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A +.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O +.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U +.if t .ds s \\(*b +.if t .ds S SS +.if n .ds a ae +.if n .ds o oe +.if n .ds u ue +.if n .ds s sz +.if t .ds m \\(*m +.if n .ds m micro +.TH ICEDAX 1 +.SH NAME +icedax \- a sampling utility that dumps CD audio data into wav sound +files +.SH SYNOPSIS +.B icedax +.RB [ -c +.IR chans ] +.RB [ -s ] +.RB [ -m ] +.RB [ -b +.IR bits ] +.RB [ -r +.IR rate ] +.RB [ -a +.IR divider ] +.RB [ -t +.IR track [ +endtrack ]] +.RB [ -i +.IR index ] +.RB [ -o +.IR offset ] +.RB [ -d +.IR duration ] +.RB [ -x ] +.RB [ -q ] +.RB [ -w ] +.RB [ -v +.IR optlist ] +.RB [ -V ] +.RB [ -Q ] +.RB [ -J ] +.RB [ -L +.IR cddbmode ] +.RB [ -R ] +.RB [ -P +.IR sectors ] +.RB [ -F ] +.RB [ -G ] +.RB [ -T ] +.RB [ -e ] +.RB [ -p +.IR percentage ] +.RB [ -n +.IR sectors ] +.RB [ -l +.IR buffers ] +.RB [ -N ] +.RB [ -J ] +.RB [ -H ] +.RB [ -g ] +.RB [ -B ] +.RB [ -D +.IR device ] +.RB [ -A +.IR auxdevice ] +.RB [ -I +.IR interface ] +.RB [ -O +.IR audiotype ] +.RB [ -C +.IR input-endianess ] +.RB [ -E +.IR output-endianess ] +.RB [ -M +.IR count ] +.RB [ -S +.IR speed ] +.RB [ -paranoia ] +.RB [ cddbp-server=servername ] +.RB [ cddbp-port=portnumber ] +.RI [ filename(s) +or +.IR directories ] +.SH DESCRIPTION +.B icedax +stands for InCrEdible Digital Audio eXtractor. It can retrieve audio tracks +.RB ( CDDA ) +from CDROM drives +that are +capable of reading audio data digitally to the host +(see README for a list of drives). + +.SH OPTIONS +.TP +.BI dev= device +.TP +.BI \-D " device +.TP +.BI \-device " device +uses +.B device +as the source for CDDA reading. For example +.B /dev/cdrom +or +.B Bus,ID,Lun. +The device specification can also have influence on the selection of the driver interface (eg. on Linux). +See the +.B \-I +option for details. +.sp +The setting of the environment variable +.B CDDA_DEVICE +is overridden by this option. +.TP +.BI \-A " auxdevice +.TP +.BI \-auxdevice " auxdevice +uses +.B auxdevice +as CDROM drive for ioctl usage. +.TP +.BI \-I " interface +.TP +.BI \-interface " interface +specifies the interface for CDROM access: +.B generic_scsi +or (on Linux, and FreeBSD systems) +.BR cooked_ioctl . +.sp +Using the +.B cooked_ioctl +is not recommended as this makes +.B icedax +mainly depend on the audio extraction quality of the operating system +which is usually extremely bad. +.TP +.BI \-c " channels --channels" +uses +.B 1 +for mono, or +.B 2 +for stereo recording, +or +.B s +for stereo recording with both channels swapped. +.TP +.B \-s " --stereo" +sets to stereo recording. +.TP +.B \-m " --mono" +sets to mono recording. +.TP +.B \-x " --max" +sets maximum (CD) quality. +.TP +.BI \-b " bits --bits-per-sample" +sets bits per sample per channel: +.BR 8 , +.B 12 +or +.BR 16 . +.TP +.BI \-r " rate --rate" +sets rate in samples per second. Possible values are listed with the +.B \-R +option. +.TP +.BI \-a " divider --divider" +sets rate to 44100Hz / divider. Possible values are listed with the +.B \-R +option. +.TP +.B \-R " --dump-rates" +shows a list of all sample rates and their dividers. +.TP +.B \-P " sectors --set-overlap" +sets the initial number of overlap +.I sectors +for jitter correction. +.TP +.BI \-n " sectors --sectors-per-request" +reads +.I sectors +per request. +.TP +.BI \-l " buffers --buffers-in-ring" +uses a ring buffer with +.I buffers +total. +.TP +.BI \-t " track+endtrack --track" +selects the start track and optionally the end track. +.TP +.BI \-i " index --index" +selects the start index. +.TP +.BI \-o " offset --offset" +starts +.I offset +sectors behind start track (one sector equivalents 1/75 seconds). +.TP +.B \-O " audiotype --output-format" +can be +.I wav +(for wav files) or +.I aiff +(for apple/sgi aiff files) or +.I aifc +(for apple/sgi aifc files) or +.I au +or +.I sun +(for sun .au PCM files) or +.I cdr +or +.I raw +(for headerless files to be used for cd writers). +.TP +.BI \-C " endianess --cdrom-endianess" +sets endianess of the input samples to 'little', 'big' or 'guess' to override defaults. +.TP +.BI \-E " endianess --output-endianess" +sets endianess of the output samples to 'little' or 'big' to override defaults. +.TP +.BI \-d " duration --duration" +sets recording time in seconds or frames. +Frames (sectors) are indicated by a 'f' suffix (like 75f for 75 sectors). +.B 0 +sets the time for whole track. +.TP +.B \-B " --bulk --alltracks" +copies each track into a separate file. +.TP +.B \-w " --wait" +waits for signal, then start recording. +.TP +.B \-F " --find-extremes" +finds extreme amplitudes in samples. +.TP +.B \-G " --find-mono" +finds if input samples are in mono. +.TP +.B \-T " --deemphasize" +undo the effect of pre-emphasis in the input samples. +.TP +.B \-e " --echo" +copies audio data to sound device e.g. +.BR /dev/dsp . +.TP +.B \-p " percentage --set-pitch" +changes pitch of audio data copied to sound device. +.TP +.B \-v " itemlist --verbose-level" +prints verbose information about the CD. +.B Level +is a list of comma separated suboptions. Each suboption controls the type of information to be reported. +.TS H +allbox; +c cw(1i) +r l. +Suboption Description +disable no information is given, warnings appear however +all all information is given +toc show table of contents +summary show a summary of the recording parameters +indices determine and display index offsets +catalog retrieve and display the media catalog number MCN +trackid T{ +.na +retrieve and display all International Standard Recording Codes ISRC +T} +sectors T{ +.na +show the table of contents in start sector notation +T} +titles T{ +.na +show the table of contents with track titles (when available) +T} +.TE +.TP +.B \-N " --no-write" +does not write to a file, it just reads (for debugging purposes). +.TP +.B \-J " --info-only" +does not write to a file, it just gives information about the disc. +.TP +.B \-L " cddb mode --cddb" +does a cddbp album- and track title lookup based on the cddb id. +The parameter cddb mode defines how multiple entries shall be handled. +.TS H +allbox; +c cw(4i) +r l. +Parameter Description +0 T{ +.na +interactive mode. The user selects the entry to use. +T} +1 T{ +.na +first fit mode. The first entry is taken unconditionally. +T} +.TE +.TP +.B " cddbp-server=servername" +sets the server to be contacted for title lookups. +.TP +.B " cddbp-port=portnumber" +sets the port number to be used for title lookups. +.TP +.B \-H " --no-infofile" +does not write an info file and a cddb file. +.TP +.B \-g " --gui" +formats the output to be better parsable by gui frontends. +.TP +.B \-M " count --md5" +enables calculation of MD-5 checksum for 'count' bytes from a beginning of a +track. +.TP +.B \-S " speed --speed" +sets the cdrom device to one of the selectable speeds for reading. +.TP +.B \-q " --quiet" +quiet operation, no screen output. +.TP +.B \-V " --verbose-SCSI" +enable SCSI command logging to the console. This is mainly used for debugging. +.TP +.B \-Q " --silent-SCSI" +suppress SCSI command error reports to the console. This is mainly used for guis. +.TP +.B \-scanbus +Scan all SCSI devices on all SCSI busses and print the inquiry +strings. This option may be used to find SCSI address of the +CD/DVD-Recorder on a system. +The numbers printed out as labels are computed by: +.B "bus * 100 + target +.TP +.B \-\-devices +Like \-scanbus but works in a more native way, respecting the device name +specification on the current operating system. See +.B wodim(1) +for details. +.TP +.B \-paranoia +use the paranoia library instead of icedax's routines for reading. +.TP +.B \-h " --help" +display version of icedax on standard output. +.TP +Defaults depend on the +.B Makefile +and +.B environment variable +settings (currently +.B CDDA_DEVICE +). +.SH "ENVIRONMENT VARIABLES" +.B CDDA_DEVICE +is used to set the device name. The device naming is compatible with the one +used by the wodim tool. +.TP +.B CDDBP_SERVER +is used for cddbp title lookups when supplied. +.TP +.B CDDBP_PORT +is used for cddbp title lookups when supplied. +.TP +.B RSH +If the +.B RSH +environment variable is present, the remote connection will not be created via +.BR rcmd (3) +but by calling the program pointed to by +.BR RSH . +Use e.g. +.BR RSH= /usr/bin/ssh +to create a secure shell connection. +.sp +Note that this forces +.B icedax +to create a pipe to the +.B rsh(1) +program and disallows +.B icedax +to directly access the network socket to the remote server. +This makes it impossible to set up performance parameters and slows down +the connection compared to a +.B root +initiated +.B rcmd(3) +connection. +.TP +.B RSCSI +If the +.B RSCSI +environment variable is present, the remote SCSI server will not be the program +.B /opt/schily/sbin/rscsi +but the program pointed to by +.BR RSCSI . +Note that the remote SCSI server program name will be ignored if you log in +using an account that has been created with a remote SCSI server program as +login shell. +.SH "RETURN VALUES" +.B icedax +uses the following exit codes to indicate various degrees of success: +.TS H +allbox; +c cw(1i) +r l. +Exitcode Description +0 no errors encountered, successful operation. +1 usage or syntax error. icedax got inconsistent arguments. +2 permission (un)set errors. permission changes failed. +3 read errors on the cdrom/burner device encountered. +4 T{ +.na +write errors while writing one of the output files encountered. +T} +5 errors with soundcard handling (initialization/write). +6 T{ +.na +errors with stat() system call on the read device (cooked ioctl). +T} +7 pipe communication errors encountered (in forked mode). +8 signal handler installation errors encountered. +9 allocation of shared memory failed (in forked mode). +10 dynamic heap memory allocation failed. +11 errors on the audio cd medium encountered. +12 device open error in ioctl handling detected. +13 race condition in ioctl interface handling detected. +14 error in ioctl() operation encountered. +15 internal error encountered. Please report back!!! +16 T{ +.na +error in semaphore operation encountered (install / request). +T} +17 could not get the scsi transfer buffer. +18 T{ +.na +could not create pipes for process communication (in forked mode). +T} +.TE +.SH "DISCUSSION" +.B icedax +is able to read parts of an +.B audio +CD or +.B multimedia +CDROM (containing audio parts) directly digitally. These parts can be +written to a file, a pipe, or to a sound device. +.PP +.B icedax +stands for +.B CDDA +to +.B WAV +(where +.B CDDA +stands for compact disc digital audio and +.B WAV +is a sound sample format introduced by MS Windows). It +allows copying +.B CDDA +audio data from the CDROM drive into a file in +.B WAV +or other formats. +.PP +The latest versions try to get higher real-time scheduling priorities to ensure +smooth (uninterrupted) operation. These priorities are available for super users +and are higher than those of 'normal' processes. Thus delays are minimized. +.PP +If your CDROM is on device +.B DEV +and it is loaded with an audio CD, you may simply invoke +.B icedax dev=DEV +and it will create the sound file +.B audio.wav +recording the whole track beginning with track 1 in stereo at 16 bit at 44100 +Hz sample rate, if your file system has enough space free. Otherwise +recording time will be limited. For details see files +.B README +and +.B README.INSTALL +. +.SH "HINTS ON OPTIONS" +.IP "Options" +Most of the options are used to control the format of the WAV file. In +the following text all of them are described. +.IP "Select Device" +.BI \-D " device" +selects the CDROM drive device to be used. +The specifier given should correspond to the selected interface (see below). +.B CHANGE! +For the cooked_ioctl interface this is the cdrom device descriptor as before. +.B The SCSI devices used with the generic SCSI interface however are now +.B addressed with their SCSI-Bus, SCSI-Id, and SCSI-Lun instead of the generic +.B SCSI device descriptor!!! +One example for a SCSI CDROM drive on bus 0 with SCSI ID 3 and lun 0 is -D0,3,0. +.IP "Select Auxiliary device" +.BI \-A " auxdevice" +is necessary for CD-Extra handling. For Non-SCSI-CDROM drives this is the +same device as given by -D (see above). For SCSI-CDROM drives it is the +CDROM drive (SCSI) device (i.e. +.B /dev/sr0 +) corresponding to the SCSI device (i.e. +.B 0,3,0 +). It has to match the device used for sampling. +.IP "Select Interface" +.BI \-I " interface" +selects the CDROM drive interface. For SCSI drives use generic_scsi +(cooked_ioctl may not yet be available for all devices): +.B generic_scsi +and +.BR cooked_ioctl . +The first uses the generic SCSI interface, the latter uses the ioctl of +the CDROM driver. The latter variant works only when the kernel driver supports +.B CDDA +reading. This entry has to match the selected CDROM device (see above). +.IP "Enable echo to soundcard" +.B \-e +copies audio data to the sound card while recording, so you hear it nearly +simultaneously. The soundcard gets the same data that is recorded. This +is time critical, so it works best with the +.B \-q +option. To use +.B icedax +as a pseudo CD player without recording in a file you could use +.B "icedax \-q \-e \-t2 \-d0 \-N" +to play the whole second track. This feature reduces the recording speed +to at most onefold speed. You cannot make better recordings than your sound card +can play (since the same data is used). +.IP "Change pitch of echoed audio" +.B "\-p percentage" +changes the pitch of all audio echoed to a sound card. Only the copy +to the soundcard is affected, the recorded audio samples in a file +remain the same. +Normal pitch, which is the default, is given by 100%. +Lower percentages correspond to lower pitches, i.e. +-p 50 transposes the audio output one octave lower. +See also the script +.B pitchplay +as an example. This option was contributed by Raul Sobon. +.IP "Select mono or stereo recording" +.B \-m +or +.B "\-c 1" +selects mono recording (both stereo channels are mixed), +.B \-s +or +.B "\-c 2" +or +.B "\-c s" +selects stereo recording. Parameter s +will swap both sound channels. +.IP "Select maximum quality" +.B \-x +will set stereo, 16 bits per sample at 44.1 KHz (full CD quality). Note +that other format options given later can change this setting. +.IP "Select sample quality" +.B "\-b 8" +specifies 8 bit (1 Byte) for each sample in each channel; +.B "\-b 12" +specifies 12 bit (2 Byte) for each sample in each channel; +.B "\-b 16" +specifies 16 bit (2 Byte) for each sample in each channel (Ensure that +your sample player or sound card is capable of playing 12-bit or 16-bit +samples). Selecting 12 or 16 bits doubles file size. 12-bit samples are +aligned to 16-bit samples, so they waste some disk space. +.IP "Select sample rate" +.BI \-r " samplerate" +selects a sample rate. +.I samplerate +can be in a range between 44100 and 900. Option +.B \-R +lists all available rates. +.IP "Select sample rate divider" +.BI \-a " divider" +selects a sample rate divider. +.I divider +can be minimally 1 and maximally 50.5 and everything between in steps of 0.5. +Option +.B \-R +lists all available rates. +.IP +To make the sound smoother at lower sampling rates, +.B icedax +sums over +.I n +samples (where +.I n +is the specific dividend). So for 22050 Hertz output we have to sum over +2 samples, for 900 Hertz we have to sum over 49 samples. This cancels +higher frequencies. Standard sector size of an audio CD (ignoring +additional information) is 2352 Bytes. In order to finish summing +for an output sample at sector boundaries the rates above have to be +chosen. Arbitrary sampling rates in high quality would require some +interpolation scheme, which needs much more sophisticated programming. +.IP "List a table of all sampling rates" +.BI \-R +shows a list of all sample rates and their dividers. Dividers can range +from 1 to 50.5 in steps of 0.5. +.IP "Select start track and optionally end track" +.BI \-t " n+m" +selects +.B n +as the start track and optionally +.B m +as the last track of a range to be recorded. +These tracks must be from the table of contents. This sets +the track where recording begins. Recording can advance through the +following tracks as well (limited by the optional end track or otherwise +depending on recording time). Whether one file or different files are +then created depends on the +.B \-B +option (see below). +.IP "Select start index" +.BI \-i " n" +selects the index to start recording with. Indices other than 1 will +invoke the index scanner, which will take some time to find the correct +start position. An offset may be given additionally (see below). +.IP "Set recording time" +.B \-d " n" +sets recording time to +.I n +seconds or set recording time for whole track if +.I n +is zero. In order to specify the duration in frames (sectors) also, the +argument can have an appended 'f'. Then the numerical argument is to be +taken as frames (sectors) rather than seconds. +Please note that if track ranges are being used they define the recording +time as well thus overriding any +.BR \-d " option" +specified times. +.IP +Recording time is defined as the time the generated sample will play (at +the defined sample rate). Since it's related to the amount of generated +samples, it's not the time of the sampling process itself (which can be +less or more). It's neither strictly coupled with the time information on +the audio CD (shown by your hifi CD player). +Differences can occur by the usage of the +.B \-o +option (see below). Notice that recording time will be shortened, unless +enough disk space exists. Recording can be aborted at anytime by +pressing the break character (signal SIGQUIT). + .IP "Record all tracks of a complete audio CD in separate files" +.B \-B +copies each track into a separate file. A base name can be given. File names +have an appended track number and an extension corresponding to the audio +format. To record all audio tracks of a CD, use a sufficient high duration +(i.e. -d99999). +.IP "Set start sector offset" +.BI \-o " sectors" +increments start sector of the track by +.IR sectors . +By this option you are able to skip a certain amount at the beginning of +a track so you can pick exactly the part you want. Each sector runs for 1/75 +seconds, so you have very fine control. If your offset is so high that +it would not fit into the current track, a warning message is issued +and the offset is ignored. Recording time is not reduced. (To skip +introductory quiet passages automagically, use the +.B \-w +option see below.) +.IP "Wait for signal option" +.B \-w +Turning on this option will suppress all silent output at startup, +reducing possibly file size. +.B icedax +will watch for any signal in the output signal and switches on writing +to file. +.IP "Find extreme samples" +.B \-F +Turning on this option will display the most negative and the most positive +sample value found during recording for both channels. This can be useful +for readjusting the volume. The values shown are not reset at track +boundaries, they cover the complete sampling process. They are taken from +the original samples and have the same format (i.e. they are independent +of the selected output format). +.IP "Find if input samples are in mono" +.B \-G +If this option is given, input samples for both channels will be compared. At +the end of the program the result is printed. Differences in the channels +indicate stereo, otherwise when both channels are equal it will indicate mono. +.IP "Undo the pre-emphasis in the input samples" +.B \-T +Some older audio CDs are recorded with a modified frequency response called +pre-emphasis. This is found mostly in classical recordings. The correction +can be seen in the flags of the Table Of Contents often. But there are +recordings, that show this setting only in the subchannels. If this option +is given, the index scanner will be started, which reads the q-subchannel +of each track. If pre-emphasis is indicated in the q-subchannel of a track, +but not in the TOC, pre-emphasis will be assumed to be present, and +subsequently a reverse filtering is done for this track before the samples +are written into the audio file. +.IP "Set audio format" +.B \-O " audiotype" +can be +.I wav +(for wav files) or +.I au +or +.I sun +(for sun PCM files) or +.I cdr +or +.I raw +(for headerless files to be used for cd writers). +All file samples are coded in linear pulse code modulation (as done +in the audio compact disc format). This holds for all audio formats. +Wav files are compatible to Wind*ws sound files, they have lsb,msb byte order +as being used on the audio cd. The default filename extension is '.wav'. +Sun type files are not like the older common logarithmically coded .au files, +but instead as mentioned above linear PCM is used. The byte order is msb,lsb +to be compatible. The default filename extension is '.au'. +The AIFF and the newer variant AIFC from the Apple/SGI world store their samples +in bigendian format (msb,lsb). In AIFC no compression is used. +Finally the easiest 'format', +the cdr aka raw format. It is done per default in msb,lsb byte order to satisfy +the order wanted by most cd writers. Since there is no header information in this +format, the sample parameters can only be identified by playing the samples +on a soundcard or similar. The default filename extension is '.cdr' or '.raw'. +.IP "Select cdrom drive reading speed" +.B \-S " speed" +allows to switch the cdrom drive to a certain level of speed in order to +reduce read errors. The argument is transfered verbatim to the drive. +Details depend very much on the cdrom drives. +An argument of 0 for example is often the default speed of the drive, +a value of 1 often selects single speed. +.IP "Enable MD5 checksums" +.B \-M " count" +enables calculation of MD-5 checksum for 'count' bytes from the beginning of a +track. This was introduced for quick comparisons of tracks. +.IP "Use Monty's libparanoia for reading of sectors" +.B \-paranoia +selects an alternate way of extracting audio sectors. Monty's library is used +with the following default options: +.sp +PARANOIA_MODE_FULL, but without PARANOIA_MODE_NEVERSKIP +.sp +for details see Monty's libparanoia documentation. +In this case the option +.B \-P +has no effect. +.IP "Do linear or overlapping reading of sectors" +(This applies unless option +.B \-paranoia +is used.) +.B \-P " sectors" +sets the given number of sectors for initial overlap sampling for jitter +correction. Two cases are to be distinguished. For nonzero values, +some sectors are read twice to enable icedax's jitter correction. +If an argument of zero is given, no overlap sampling will be used. +For nonzero overlap sectors icedax dynamically adjusts the setting during +sampling (like cdparanoia does). +If no match can be found, icedax retries the read with an increased overlap. +If the amount of jitter is lower than the current overlapped samples, icedax +reduces the overlap setting, resulting in a higher reading speed. +The argument given has to be lower than the total number of sectors per request +(see option +.I -n +below). +Icedax will check this setting and issues a error message otherwise. +The case of zero sectors is nice on low load situations or errorfree (perfect) +cdrom drives and perfect (not scratched) audio cds. +.IP "Set the transfer size" +.B \-n " sectors" +will set the transfer size to the specified sectors per request. +.IP "Set number of ring buffer elements" +.B \-l " buffers" +will allocate the specified number of ring buffer elements. +.IP "Set endianess of input samples" +.B \-C " endianess" +will override the default settings of the input format. +Endianess can be set explicitly to "little" or "big" or to the automatic +endianess detection based on voting with "guess". +.IP "Set endianess of output samples" +.B \-E " endianess" +(endianess can be "little" or "big") will override the default settings +of the output format. +.IP "Verbose option" +.B \-v " itemlist" +prints more information. A list allows selection of different +information items. +.sp +.B "disable" +keeps quiet +.sp +.B "toc" +displays the table of contents +.sp +.B "summary" +displays a summary of recording parameters +.sp +.B "indices" +invokes the index scanner and displays start positions of indices +.sp +.B "catalog" +retrieves and displays a media catalog number +.sp +.B "trackid" +retrieves and displays international standard recording codes +.sp +.B "sectors" +displays track start positions in absolute sector notation +.sp +To combine several requests just list the suboptions separated with commas. +.IP "The table of contents" +The display will show the table of contents with number of tracks and +total time (displayed in +.IR mm : ss . hh +format, +.IR mm =minutes, +.IR ss =seconds, +.IR hh "=rounded 1/100 seconds)." +The following list displays track number and track time for each entry. +The summary gives a line per track describing the type of the track. +.sp +.ce 1 +.B "track preemphasis copypermitted tracktype chans" +.sp +The +.B track +column holds the track number. +.B preemphasis +shows if that track has been given a non linear frequency response. +NOTE: You can undo this effect with the +.B \-T +option. +.B "copy-permitted" +indicates if this track is allowed to copy. +.B "tracktype" +can be data or audio. On multimedia CDs (except hidden track CDs) +both of them should be present. +.B "channels" +is defined for audio tracks only. There can be two or four channels. +.IP "No file output" +.B \-N +this debugging option switches off writing to a file. +.IP "No infofile generation" +.B \-H +this option switches off creation of an info file and a cddb file. +.IP "Generation of simple output for gui frontends" +.B \-g +this option switches on simple line formatting, which is needed to support +gui frontends (like xcd-roast). +.IP "Verbose SCSI logging" +.B \-V +this option switches on logging of SCSI commands. This will produce +a lot of output (when SCSI devices are being used). +This is needed for debugging purposes. The format +is the same as being used with the cdrecord program from J\*org Schilling or +the wodim tool. See there for details. +.IP "Quiet option" +.B \-q +suppresses all screen output except error messages. +That reduces cpu time resources. +.IP "Just show information option" +.B \-J +does not write a file, it only prints information about the disc (depending +on the +.B \-v +option). This is just for information purposes. +.SH "CDDBP support" +.IP "Lookup album and track titles option" +.B \-L " cddbp mode" +Icedax tries to retrieve performer, album-, and track titles from a cddbp +server. The default server right now is 'freedb.freedb.org'. +It is planned to have more control over the server handling later. +The parameter defines how multiple entries are handled: +.PP +0 interactive mode, the user chooses one of the entries. +.PP +1 take the first entry without asking. +.IP "Set server for title lookups" +.B cddbp-server " servername" +When using \-L or --cddb, the server being contacted can be set with +this option. +.IP "Set portnumber for title lookups" +.B cddbp-port " portnumber" +When using \-L or --cddb, the server port being contacted can be set with +this option. +.SH "HINTS ON USAGE" +Don't create samples you cannot read. First check your sample player +software and sound card hardware. I experienced problems with very low +sample rates (stereo <= 1575 Hz, mono <= 3675 Hz) when trying to play +them with standard WAV players for sound blaster (maybe they are not +legal in +.B WAV +format). Most CD-Writers insist on audio samples in a bigendian format. +Now icedax supports the +.B \-E " endianess" +option to control the endianess of the written samples. +.PP +If your hardware is fast enough to run icedax +uninterrupted and your CD drive is one of the 'perfect' ones, you will +gain speed when switching all overlap sampling off with the +.B \-P " 0" +option. Further fine tuning can be done with the +.B \-n " sectors" +option. You can specify how much sectors should be requested in one go. +.PP +Icedax supports +.B pipes +now. Use a filename of +.B \- +to let icedax output its samples to standard output. +.PP +Conversion to other sound formats can be done using the +.B sox +program package (although the use of +.B sox -x +to change the byte order of samples should be no more necessary; see option +.B \-E +to change the output byteorder). +.PP +If you want to sample more than one track into +different files in one run, this is currently possible with the +.B \-B +option. When recording time exceeds the track limit a new file will +be opened for the next track. +.SH FILES +Icedax can generate a lot of files for various purposes. +.sp +Audio files: +.sp +There are audio files containing samples with default extensions +.wav, .au, .aifc, .aiff, and .cdr according to the selected sound format. +These files are not generated when option (-N) is given. Multiple files may +be written when the bulk copy option (-B) is used. Individual file names +can be given as arguments. If the number of file names given is sufficient +to cover all included audio tracks, the file names will be used verbatim. +Otherwise, if there are less file names than files needed to write the +included tracks, the part of the file name before the extension is extended +with '_dd' where dd represents the current track number. +.sp +Cddb and Cdindex files: +.sp +If icedax detects cd-extra or cd-text (album/track) title information, +then .cddb and .cdindex files are generated unless suppressed by the +option -H. They contain suitable formatted entries for submission to +audio cd track title databases in the internet. The CDINDEX and CDDB(tm) +systems are currently supported. For more information please visit +www.musicbrainz.org and www.freedb.com. +.sp +Inf files: +.sp +The inf files are describing the sample files and the part from the audio cd, +it was taken from. They are a means to transfer information to a cd burning +program like wodim. For example, if the original audio cd had pre-emphasis +enabled, and icedax -T did remove the pre-emphasis, then the inf file has +pre-emphasis not set (since the audio file does not have it anymore), while +the .cddb and the .cdindex have pre-emphasis set as the original does. +.SH WARNING +.B IMPORTANT: +it is prohibited to sell copies of copyrighted material by noncopyright +holders. This program may not be used to circumvent copyrights. +The user acknowledges this constraint when using the software. +.SH BUGS +Generation of md5 checksums is currently broken. +.sp +Performance may not be optimal on slower systems. +.sp +The index scanner may give timeouts. +.sp +The resampling (rate conversion code) uses polynomial interpolation, which +is not optimal. +.sp +Icedax should use threads. +.sp +Icedax currently cannot sample hidden audio tracks (track 1 index 0). +.SH ACKNOWLEDGEMENTS +Thanks goto Project MODE (http://www.mode.net/) and Fraunhofer Institut f\*ur +integrierte Schaltungen (FhG-IIS) (http://www.iis.fhg.de/) for financial +support. +Plextor Europe and Ricoh Japan provided cdrom disk drives and cd burners +which helped a lot to develop this software. +Rammi has helped a lot with the debugging and showed a lot of stamina when +hearing 100 times the first 16 seconds of the first track of the Krupps CD. +Libparanoia contributed by Monty (Christopher Montgomery) xiphmont@mit.edu. +.SH AUTHOR +Heiko Eissfeldt heiko@colossus.escape.de +.PP +This manpage describes the program implementation of +.B +icedax +as shipped by the cdrkit distribution. See +.B +http://alioth.debian.org/projects/debburn/ +for details. It is a spinoff from the original program cdda2wav as distributed +in the cdrtools package [1]. However, the cdrtools developers are not involved +in the development of this spinoff and therefore shall not be made responsible +for any problem caused by it. Do not try to get support for this program by +contacting the original authors. +.PP +If you have support questions, send them to +.PP +.B +debburn-devel@lists.alioth.debian.org +.br +.PP +If you have definitely found a bug, send a mail to this list or to +.PP +.B +submit@bugs.debian.org +.br +.PP +writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body. + +.SH DATE +26 Sep 2006 + +.SH SOURCES +.PP +.br +[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de + diff --git a/upstream/fedora-40/man1/icehelp.1 b/upstream/fedora-40/man1/icehelp.1 new file mode 100644 index 00000000..32ec235b --- /dev/null +++ b/upstream/fedora-40/man1/icehelp.1 @@ -0,0 +1,149 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEHELP 1" +.TH ICEHELP 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icehelp \- a very simple HTML browser +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicehelp\fR [\fIOPTIONS\fR] \fIFILENAME\fR +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicehelp\fR is a very simple HTML browser, which is used by \fBicewm\fR\|(1) +to display the IceWM Manual and the manpages. +.PP +The document can be navigated by cursor keys, navigation keys and +a scrollbar. To find text, hit \f(CW\*(C`Ctrl+F\*(C'\fR for a search window. +Hit the \f(CW\*(C`F3\*(C'\fR function key to repeat a search. +.PP +The top right corner shows a button, which opens a menu. This menu +can also be opened by a right mouse button click. +.SS ARGUMENTS +.IX Subsection "ARGUMENTS" +.IP \fIFILENAME\fR 4 +.IX Item "FILENAME" +Specifies the file to browse. It can also be the URL of a website. +.SS OPTIONS +.IX Subsection "OPTIONS" +.SS "SPECIFIC OPTIONS" +.IX Subsection "SPECIFIC OPTIONS" +.IP \fB\-B\fR 4 +.IX Item "-B" +Display the IceWM icewmbg manpage. +.IP "\fB\-b\fR, \fB\-\-bugs\fR" 4 +.IX Item "-b, --bugs" +Display the IceWM bug reports (primitively). +.IP "\fB\-f\fR, \fB\-\-faq\fR" 4 +.IX Item "-f, --faq" +Display the IceWM FAQ and Howto. +.IP \fB\-g\fR 4 +.IX Item "-g" +Display the IceWM Github website. +.IP "\fB\-i\fR, \fB\-\-icewm\fR" 4 +.IX Item "-i, --icewm" +Display the IceWM icewm manpage. +.IP "\fB\-m\fR, \fB\-\-manual\fR" 4 +.IX Item "-m, --manual" +Display the IceWM Manual (default). +.IP \fB\-s\fR 4 +.IX Item "-s" +Display the IceWM icesound manpage. +.IP "\fB\-t\fR, \fB\-\-theme\fR" 4 +.IX Item "-t, --theme" +Display the IceWM themes Howto. +.IP "\fB\-w\fR, \fB\-\-website\fR" 4 +.IX Item "-w, --website" +Display the IceWM website. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +Use \fIDISPLAY\fR to connect to the X server. +If this option is missing then \fIDISPLAY\fR +is read from the environment variable \f(CW\*(C`DISPLAY\*(C'\fR. +.IP \fB\-\-sync\fR 4 +.IX Item "--sync" +Use a slower synchronous mode communication with \fIX11\fR server. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icesh.1 b/upstream/fedora-40/man1/icesh.1 new file mode 100644 index 00000000..9ad67659 --- /dev/null +++ b/upstream/fedora-40/man1/icesh.1 @@ -0,0 +1,952 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICESH 1" +.TH ICESH 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icesh \- control window properties and the IceWM window manager +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.IP "\fBicesh\fR \fIOPTIONS|ACTIONS\fR+" 4 +.IX Item "icesh OPTIONS|ACTIONS+" +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicesh\fR provides two types of commands: +.IP "1. Commands to directly interact with icewm:" 4 +.IX Item "1. Commands to directly interact with icewm:" +These are listed in the section "MANAGER ACTIONS" below. +They are easy to use, because they don't require to select one +or more windows. For example, \f(CW\*(C`icesh restart\*(C'\fR will restart +icewm and \f(CW\*(C`icesh clients\*(C'\fR lists the applications that +are managed by icewm. +.IP "2. Commands that operate on a selection of windows:" 4 +.IX Item "2. Commands that operate on a selection of windows:" +See the section \f(CW\*(C`WINDOW ACTIONS\*(C'\fR below. For example, \f(CW\*(C`icesh close\*(C'\fR +is a request to close a window, but which window? Now icesh +will turn the mouse pointer into a crosshair. Click on a window +and a close request will be sent to that application. +.Sp +The power of icesh lies in its ability to programmatically +select one or more windows and operate on that selection. +This can be used in scripts and in \fBicewm\-keys\fR\|(5) +to define your own window management hotkeys. For example, to +immediately close all xterm windows do \f(CW\*(C`icesh \-c xterm close\*(C'\fR. +.Sp +There are a dozen \f(CW\*(C`SELECT OPTIONS\*(C'\fR to select windows. They start +with a '\-' or a '+'. The '\-' starts a new selection, while the '+' +adds more windows to an existing selection. +.Sp +This selection of windows can be reduced by \f(CW\*(C`FILTER OPTIONS\*(C'\fR. +These remove unwanted windows from the current selection. +Multiple filter options can be given. For example, +\&\f(CW\*(C`icesh \-c xterm \-W this close\*(C'\fR will close only those xterms +that are shown on the current workspace. The xterms on other +workspaces are filtered out by the \f(CW\*(C`\-W this\*(C'\fR filter option. +.PP +There is no limit to the number of commands, selections, filters +and actions that you can give to a single icesh command. +They are processed and evaluated one by one from left to right. +This makes icesh a small declarative programming language. +Have a look at some examples near the end of this document. +.SS OPTIONS +.IX Subsection "OPTIONS" +\&\fBicesh\fR recognizes the following options: +.SS "SELECT OPTIONS" +.IX Subsection "SELECT OPTIONS" +Select options specify the window or windows to which subsequent +actions apply. If none is given, but an action does require a window, +then a selection crosshair is shown to select the desired window +interactively. The manager actions do not require window options. +.PP +The following options \fIselect\fR one or more client windows. +If needed, they can be repeated for successive actions. +.IP "\fB\-a\fR, \fB\-all\fR" 4 +.IX Item "-a, -all" +Selects all client windows of the window manager. +.IP "\fB\-f\fR, \fB\-focus\fR, \fB+f\fR, \fB+focus\fR" 4 +.IX Item "-f, -focus, +f, +focus" +Selects the application window that is currently focused. +The option with minus sign replaces the existing selection with +the focused window. With a plus sign the focused window is added to +an existing selection. +.IP "\fB+g\fR, \fB+group\fR" 4 +.IX Item "+g, +group" +Extend the current selection with client windows that +belong to the same application window group. +.IP "\fB\-r\fR, \fB\-root\fR, \fB+r\fR, \fB+root\fR" 4 +.IX Item "-r, -root, +r, +root" +Selects the root window. +The option with minus sign replaces the existing selection with +the root window. With a plus sign the root window is added to +an existing selection. +.IP "\fB\-s\fR, \fB\-shown\fR" 4 +.IX Item "-s, -shown" +Selects all client windows that are on the current workspace. +.IP "\fB\-t\fR, \fB\-top\fR" 4 +.IX Item "-t, -top" +Selects all toplevel windows from the display unconditionally. +This includes windows that have never been mapped and windows +with the override redirect bit set to evade management. +.IP "\fB\-w\fR, \fB\-window\fR, \fB+w\fR, \fB+window\fR \fIWINDOW_ID\fR" 4 +.IX Item "-w, -window, +w, +window WINDOW_ID" +Specifies the identifier of the window, \fIWINDOW_ID\fR, for which the +action applies. Special identifiers are \fBroot\fR for the root window +and \fBfocus\fR for the currently focused window. +The option with minus sign replaces the existing selection. +With a plus sign the window is added to an existing selection. +.IP "\fB\-x\fR, \fB\-xembed\fR" 4 +.IX Item "-x, -xembed" +Selects all windows that are embedded using the \fIXEMBED\fR protocol. +.IP "\fB+c\fR, \fB+class\fR \fICLASS\fR" 4 +.IX Item "+c, +class CLASS" +Extend the current selection with client windows that have a +\&\fIWM_CLASS\fR property equal to \fICLASS\fR. This is the resource +instance and class name. If \fICLASS\fR contains a period, only +windows with exactly the same \fIWM_CLASS\fR property are matched. +If there is no period, windows of the same class and windows +of the same instance are selected. +.IP "\fB+C\fR, \fB+Class\fR" 4 +.IX Item "+C, +Class" +Extend the current selection with client windows that +have a \fIWM_CLASS\fR property \fIsimilar\fR to the already +selected set of windows. +.IP "\fB\-D\fR, \fB\-Dockapps\fR" 4 +.IX Item "-D, -Dockapps" +Selects all Dockapp applications that are managed by icewm. +.IP "\fB+P\fR, \fB+Pid\fR" 4 +.IX Item "+P, +Pid" +Extend the current selection with client windows that have +the same process identifier as one of the selected windows. +.IP \fB\-T\fR 4 +.IX Item "-T" +Selects the IceWM taskbar. +.SS "FILTER OPTIONS" +.IX Subsection "FILTER OPTIONS" +The following options \fIfilter\fR the currently selected set of windows. +If no previous \fIselect\fR option was given then a \fB\-all\fR option is +implicitly assumed to filter all client windows. +.IP "\fB\-c\fR, \fB\-class\fR \fICLASS\fR" 4 +.IX Item "-c, -class CLASS" +Filters the set of windows on their \fIWM_CLASS\fR property. This is +the resource instance and class name. If \fICLASS\fR contains a period, +only windows with exactly the same \fIWM_CLASS\fR property are matched. +If there is no period, windows of the same class and windows of the +same instance (aka. \fI\-name\fR) are selected. +.IP "\fB\-l\fR, \fB\-last\fR" 4 +.IX Item "-l, -last" +Filter clients and keep only the most recent client. +.IP "\fB\-m\fR, \fB\-machine\fR \fIHOST\fR" 4 +.IX Item "-m, -machine HOST" +Filters clients by host name. Clients with a WM_CLIENT_MACHINE property +equal to \fIHOST\fR are selected. +.IP "\fB\-n\fR, \fB\-name\fR \fINAME\fR" 4 +.IX Item "-n, -name NAME" +Filters clients by _NET_WM_NAME or WM_NAME. +\&\fINAME\fR matches any part of the property value. +To match at the beginning use a \f(CW\*(C`^\*(C'\fR prefix. +To match at the end use a \f(CW\*(C`$\*(C'\fR suffix. +.IP "\fB\-p\fR, \fB\-pid\fR \fIPID\fR" 4 +.IX Item "-p, -pid PID" +Filters clients by process ID. Clients with a _NET_WM_PID property equal +to \fIPID\fR are selected. +.IP "\fB\-u\fR, \fB\-unmapped\fR" 4 +.IX Item "-u, -unmapped" +Filter clients and keep those that are currently not viewable. +These are hidden, minimized, rolled-up, or on another workspace. +.IP "\fB\-v\fR, \fB\-viewable\fR" 4 +.IX Item "-v, -viewable" +Filter clients and keep only those that are currently viewable. +These clients are mapped on the current workspace. +.IP "\fB\-G\fR, \fB\-Gravity\fR \fIGRAVITY\fR" 4 +.IX Item "-G, -Gravity GRAVITY" +Filters clients by the window gravity field of the WM_NORMAL_HINTS +property. Clients with a gravity equal to \fIGRAVITY\fR are selected. +If \fIGRAVITY\fR starts with an exclamation mark then the filtering is +inverted. +.IP "\fB\-L\fR, \fB\-Layer\fR \fILAYER\fR" 4 +.IX Item "-L, -Layer LAYER" +Filters clients by \fIGNOME window layer\fR, which can either be a layer +name or a layer number. See EXPRESSIONS below. If \fILAYER\fR starts with +an exclamation mark then the filtering is inverted. +.IP "\fB\-N\fR, \fB\-Netstate\fR \fISTATE\fR" 4 +.IX Item "-N, -Netstate STATE" +Filters clients by \fIEWMH window state\fR. Clients that have at +least an EWMH window state of \fISTATE\fR are selected. This state +refers to details like \fBMINIZED\fR or \fBMAXIMIZED\fR. See EXPRESSIONS +below. If \fISTATE\fR starts with an exclamation mark then the filtering +is inverted. A question mark \f(CW\*(C`?\*(C'\fR filters clients with any bit set +in \fISTATE\fR. +.IP "\fB\-P\fR, \fB\-Property\fR \fIPROP[=value]\fR" 4 +.IX Item "-P, -Property PROP[=value]" +Filters clients by property. Clients that have a property \fIPROP\fR +are selected. If the optional \fIvalue\fR is given, the match succeeds +only if \fIPROP\fR is a string, window, cardinal, or atom, with a value +equal to \fIvalue\fR. The filtering is inverted if \fIPROP\fR starts with +an exclamation mark. +.IP "\fB\-R\fR, \fB\-Role\fR \fIROLE\fR" 4 +.IX Item "-R, -Role ROLE" +Filters clients by WM_WINDOW_ROLE. Clients that have a WM_WINDOW_ROLE +property value equal to \fIROLE\fR are selected. The filtering is inverted +if \fIROLE\fR starts with an exclamation mark. +.IP "\fB\-W\fR, \fB\-Workspace\fR \fIWORKSPACE\fR" 4 +.IX Item "-W, -Workspace WORKSPACE" +Filter clients by workspace. Workspace \fIWORKSPACE\fR is either a +workspace name, or a workspace number counting from zero, or the word +\&\f(CW\*(C`this\*(C'\fR for the current workspace, or the word \f(CW\*(C`All\*(C'\fR for all workspaces. +If \fIWORKSPACE\fR starts with an exclamation mark then the filtering is +inverted. +.IP "\fB\-X\fR, \fB\-Xinerama\fR \fIMONITOR\fR" 4 +.IX Item "-X, -Xinerama MONITOR" +Limit clients by \fIRandR\fR/\fIXinerama\fR monitor. Only operate on +clients that are displayed on \fIMONITOR\fR, where \fIMONITOR\fR can +be \f(CW\*(C`All\*(C'\fR for all monitors, \f(CW\*(C`this\*(C'\fR for the monitor where the +active window is displayed, or a monitor number starting from zero. +See the output of \f(CW\*(C`randr\*(C'\fR or \f(CW\*(C`xinerama\*(C'\fR below. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +The following options are identical for every IceWM command. +.IP "\fB\-d\fR, \fB\-display\fR \fIDISPLAY\fR" 4 +.IX Item "-d, -display DISPLAY" +Specifies the X11 DISPLAY. If unspecified, defaults to \fR\f(CB$DISPLAY\fR\fB\fR. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4 +.IX Item "-q, --quiet" +Don't complain if no matching windows could be found. +.SS ACTIONS +.IX Subsection "ACTIONS" +\&\fBicesh\fR expects one or more action arguments. There are two kinds of +actions: \fIwindow actions\fR and \fImanager actions\fR. The first operates on +the selected windows. The second directly interacts with the \fBicewm\fR +window manager. +.SS "WINDOW ACTIONS" +.IX Subsection "WINDOW ACTIONS" +The following actions affect the selected window or windows. +.IP \fBactivate\fR 4 +.IX Item "activate" +Activate the window, aka. \fIto focus\fR. +.IP \fBclose\fR 4 +.IX Item "close" +Send a close request to the client that created the window. +.IP \fBkill\fR 4 +.IX Item "kill" +Force an immediate close down of the client that created the window. +.IP \fBid\fR 4 +.IX Item "id" +Print window identifiers for the selected windows. +.IP \fBpid\fR 4 +.IX Item "pid" +Print process identifiers for the selected windows. +.IP \fBlist\fR 4 +.IX Item "list" +Show window details, like geometry and names. +.IP \fBlower\fR 4 +.IX Item "lower" +Lower the window. +.IP \fBraise\fR 4 +.IX Item "raise" +Raise the window. +.IP \fBabove\fR 4 +.IX Item "above" +Stack the window above others. +.IP \fBbelow\fR 4 +.IX Item "below" +Stack the window below others. +.IP \fBrollup\fR 4 +.IX Item "rollup" +Rollup the specified window. +.IP \fBfullscreen\fR 4 +.IX Item "fullscreen" +Set the window to fullscreen. +.IP \fBmaximize\fR 4 +.IX Item "maximize" +Maximize the window. +.IP \fBhorizontal\fR 4 +.IX Item "horizontal" +Maximize the window only horizontally. +.IP \fBvertical\fR 4 +.IX Item "vertical" +Maximize the window only vertically. +.IP \fBminimize\fR 4 +.IX Item "minimize" +Minimize the window. +.IP \fBrestore\fR 4 +.IX Item "restore" +Restore the window to normal. +.IP \fBhide\fR 4 +.IX Item "hide" +Hide the window. +.IP \fBunhide\fR 4 +.IX Item "unhide" +Reveal the window. +.IP \fBskip\fR 4 +.IX Item "skip" +Don't show the window on the taskbar. +.IP \fBunskip\fR 4 +.IX Item "unskip" +Do show the window on the taskbar. +.IP \fBsticky\fR 4 +.IX Item "sticky" +Show the window on all workspaces. +.IP \fBunsticky\fR 4 +.IX Item "unsticky" +Show the window on just one workspace. +.IP \fBurgent\fR 4 +.IX Item "urgent" +Set the urgent flag to flash the task button. +.IP "\fBresize\fR \fIWIDTH\fR \fIHEIGHT\fR" 4 +.IX Item "resize WIDTH HEIGHT" +Resize window to \fIWIDTH\fR by \fIHEIGHT\fR window units. For text based +applications like terminals, a window unit is the size of a single +character cell. +.IP "\fBsizeto\fR \fIWIDTH\fR \fIHEIGHT\fR" 4 +.IX Item "sizeto WIDTH HEIGHT" +Resize window to \fIWIDTH\fR by \fIHEIGHT\fR pixels. If \fIWIDTH\fR or \fIHEIGHT\fR +ends with a percent sign \f(CW\*(C`%\*(C'\fR, then they refer to a percentage of the +desktop work area. For instance, \f(CW\*(C`sizeto 50% 100%\*(C'\fR resizes to half +the desktop width and whatever height is available above or below the +taskbar. +.IP "\fBsizeby\fR \fIWIDTH\fR \fIHEIGHT\fR" 4 +.IX Item "sizeby WIDTH HEIGHT" +Resize window by \fIWIDTH\fR by \fIHEIGHT\fR pixels. If \fIWIDTH\fR or \fIHEIGHT\fR +ends with a percent sign \f(CW\*(C`%\*(C'\fR, then they refer to a percentage of the +current window size. For instance, \f(CW\*(C`sizeby 50% 200\*(C'\fR increases the width +by 50% and increases the height by 200 pixels. +.IP "\fBmove\fR \fIX\fR \fIY\fR" 4 +.IX Item "move X Y" +Move the selected window or windows to the screen position \fIX\fR \fIY\fR. +To specify \fIX\fR or \fIY\fR values relative to the right side or bottom side +precede the value with an extra minus sign, like in \f(CW\*(C`move \-+10 \-\-20\*(C'\fR. +.IP "\fBmoveby\fR \fIX\fR \fIY\fR" 4 +.IX Item "moveby X Y" +Displace window by \fIX\fR \fIY\fR pixels. +.IP \fBcenter\fR 4 +.IX Item "center" +Position the window in the center of the desktop work area. +.IP \fBleft\fR 4 +.IX Item "left" +Position the window against the left side of the desktop work area. +.IP \fBright\fR 4 +.IX Item "right" +Position the window against the right side of the desktop work area. +.IP \fBtop\fR 4 +.IX Item "top" +Position the window against the top side of the desktop work area. +.IP \fBbottom\fR 4 +.IX Item "bottom" +Position the window against the bottom side of the desktop work area. +.IP "\fBsetIconTitle\fR \fITITLE\fR" 4 +.IX Item "setIconTitle TITLE" +Set the icon title to \fITITLE\fR. +.IP \fBgetIconTitle\fR 4 +.IX Item "getIconTitle" +Print the icon title. +.IP "\fBsetWindowTitle\fR \fITITLE\fR" 4 +.IX Item "setWindowTitle TITLE" +Set the window title to \fITITLE\fR. +.IP \fBgetWindowTitle\fR 4 +.IX Item "getWindowTitle" +Print the window title. +.IP "\fBsetGeometry\fR \fIGEOMETRY\fR" 4 +.IX Item "setGeometry GEOMETRY" +Set the window geometry to \fIGEOMETRY\fR. This geometry should be +specified in a format that can be parsed by \fBXParseGeometry\fR\|(3). +Negative offsets are with respect to the bottom or right side of +the screen. Use \f(CW\*(C`+\-\*(C'\fR for a truly negative position. +.IP \fBgetGeometry\fR 4 +.IX Item "getGeometry" +Print the window geometry. +.IP "\fBsetClass\fR \fICLASS\fR" 4 +.IX Item "setClass CLASS" +Set the resource name and class to \fICLASS\fR, which should be a resource +name and a resource class connected by a dot. To preserve either the +existing name or class, use a percentage sign for that part. +.IP \fBgetClass\fR 4 +.IX Item "getClass" +Print the resource name and class. +.IP "\fBnetState\fR \fI[STATE]\fR" 4 +.IX Item "netState [STATE]" +If \fISTATE\fR is omitted then it shows the \fIEWMH window state\fR. +If \fISTATE\fR starts with a \f(CW\*(C`+\*(C'\fR then flags in \fISTATE\fR are appended to +the existing \fIEWMH window state\fR. If \fISTATE\fR starts with a \f(CW\*(C`\-\*(C'\fR +then flags in \fISTATE\fR are removed from the existing \fIEWMH window +state\fR. If \fISTATE\fR starts with a \f(CW\*(C`^\*(C'\fR then flags in \fISTATE\fR are +toggled with respect to the existing \fIEWMH window state\fR. +If \fISTATE\fR starts with a \f(CW\*(C`=\*(C'\fR then the \fIEWMH window state\fR +is set to \fISTATE\fR. See EXPRESSIONS below. A list of \fIEWMH flags\fR +can be found in the output of \f(CW\*(C`icesh symbols\*(C'\fR. +.IP "\fBsetLayer\fR \fILAYER\fR" 4 +.IX Item "setLayer LAYER" +Move the specified window to another \fIwindow layer\fR. +See EXPRESSIONS below for a list of \fILAYER\fR symbols. +.IP \fBgetLayer\fR 4 +.IX Item "getLayer" +Print the \fIwindow layer\fR for the specified window. +.IP "\fBsetWorkspace\fR \fIWORKSPACE\fR" 4 +.IX Item "setWorkspace WORKSPACE" +Move the specified window to another workspace. Select the root +window to change the current workspace. If \fIWORKSPACE\fR is \f(CW\*(C`All\*(C'\fR +then the specified window becomes visible on all workspaces. +Specify \f(CW\*(C`this\*(C'\fR for the current workspace, \f(CW\*(C`next\*(C'\fR for the subsequent +workspace or \f(CW\*(C`prev\*(C'\fR for the preceding workspace. +.IP \fBgetWorkspace\fR 4 +.IX Item "getWorkspace" +Print the workspace for the specified window. +.IP "\fBopacity\fR [\fIOPACITY\fR]" 4 +.IX Item "opacity [OPACITY]" +Print the window opacity if \fIOPACITY\fR is not given, +otherwise set the window opacity to \fIOPACITY\fR. +.IP "\fBsetTrayOption\fR \fITRAYOPTION\fR" 4 +.IX Item "setTrayOption TRAYOPTION" +Set the \fIIceWM tray option\fR for the specified window to \fITRAYOPTION\fR. +See \fIIceWM tray options\fR, below, for \fITRAYOPTION\fR symbols. +.IP \fBgetTrayOption\fR 4 +.IX Item "getTrayOption" +Print the \fIIceWM tray option\fR for the specified window. +.IP "\fBsetNormalGravity\fR \fIGRAVITY\fR" 4 +.IX Item "setNormalGravity GRAVITY" +Set the window gravity field in the WM_NORMAL_HINTS property for the +specified window to \fIGRAVITY\fR. See below for \fIGRAVITY\fR symbols. +.IP \fBgetNormalGravity\fR 4 +.IX Item "getNormalGravity" +Print the window gravity from the WM_NORMAL_HINTS property for the +specified window. +.IP "\fBsetWindowGravity\fR \fIGRAVITY\fR" 4 +.IX Item "setWindowGravity GRAVITY" +Set the window gravity for the specified window to \fIGRAVITY\fR. +See below for \fIGRAVITY\fR symbols. +.IP \fBgetWindowGravity\fR 4 +.IX Item "getWindowGravity" +Print the window gravity for the specified window. +.IP "\fBsetBitGravity\fR \fIGRAVITY\fR" 4 +.IX Item "setBitGravity GRAVITY" +Set the bit gravity> for the specified window to \fIGRAVITY\fR. +See below for \fIGRAVITY\fR symbols. +.IP \fBgetBitGravity\fR 4 +.IX Item "getBitGravity" +Print the bit gravity for the specified window. +.IP "\fBmotif\fR [\fBfuncs\fR \fIFUNCTIONS\fR | \fBdecor\fR \fIDECORATIONS\fR | \fBremove\fR]" 4 +.IX Item "motif [funcs FUNCTIONS | decor DECORATIONS | remove]" +Query, set or modify the \f(CW\*(C`_MOTIF_WM_HINTS\*(C'\fR property for the specified +window. Without arguments \fBmotif\fR will show the current value, but +only if the window has such a property. The property can be removed or +reset with the \fBremove\fR argument. With \fBfuncs\fR and \fBdecor\fR individual +fields of this property can be enabled or disabled. If \fIFUNCTIONS\fR or +\&\fIDECORATIONS\fR starts with a minus or plus sign then the existing value +is modified, otherwise it is set to the new value. Note that if \f(CW\*(C`All\*(C'\fR +is set, other set fields are disabled and cleared fields are enabled. +.IP \fBborderless\fR 4 +.IX Item "borderless" +Hide the frame borders and title. +.IP \fBbordered\fR 4 +.IX Item "bordered" +Show the frame borders and title. +.IP \fBdenormal\fR 4 +.IX Item "denormal" +Remove the WM_NORMAL_HINTS property, if it exists. This lifts +font-size restrictions on resizing, especially for terminals. +.IP "\fBprop\fR \fIPROPERTY\fR" 4 +.IX Item "prop PROPERTY" +Print the value of property \fIPROPERTY\fR, if it is present. +.IP \fBproperties\fR 4 +.IX Item "properties" +Print all properties and their values. +.IP \fBframe\fR 4 +.IX Item "frame" +Print the identifier of the window frame. +.IP \fBextents\fR 4 +.IX Item "extents" +Print the window identifier and the frame border sizes: left, right, +top and bottom. +.IP \fBfocusmodel\fR 4 +.IX Item "focusmodel" +Print the ICCCM focus model as advertised by the client window. +This is either Locally, Passive, Globally or NoInput. +.IP "\fBoverride\fR [\fI0|1\fR]" 4 +.IX Item "override [0|1]" +Print the override redirect status for the window, or if either 0 or 1 +is given, then disable or enable the override redirect status. +.IP "\fBtabto\fR \fIlabel\fR" 4 +.IX Item "tabto label" +Move the windows as tabs to a frame that has \f(CW\*(C`frame\*(C'\fR label \fIlabel\fR. +Such a frame is created if needed. +.IP \fBuntab\fR 4 +.IX Item "untab" +Move each window to its own frame, if it is currently tabbed. +.IP "\fBloadicon\fR \fIimage.pam\fR" 4 +.IX Item "loadicon image.pam" +Load an icon from file, which must be in the PAM image format, +with dimensions at most 256, a depth of 4, and type \fIRGB_ALPHA\fR. +.IP "\fBsaveicon\fR \fIfile000.pam\fR" 4 +.IX Item "saveicon file000.pam" +Save an icon to a new file in the PAM image format. Digits are +increased to generate a unique new filename for each window. +.IP "\fBclick\fR \fIwindow-x\fR \fIwindow-y\fR \fIbutton\fR" 4 +.IX Item "click window-x window-y button" +Send a button press and release event at position (\fIwindow-x\fR, +\&\fIwindow-y\fR). A negative position is relative to the bottom right +corner. The mouse pointer is warped to the position before sending +the events. The button number should be between 1 and 5 inclusive. +.IP "\fBmonitors\fR \fItop\fR \fIbottom\fR \fIleft\fR \fIright\fR" 4 +.IX Item "monitors top bottom left right" +This sets the monitors to use for fullscreen. +Top, bottom, left, and right are indices of the \fIicesh xinerama\fR command. +.IP \fBspy\fR 4 +.IX Item "spy" +Observe the selected windows and report any changes. This includes +focus, visibility, position, size and all window properties. +To monitor all of the protocol request messages that client applications +may send to icewm, also spy on the root window. +.IP \fBstacking\fR 4 +.IX Item "stacking" +Sort the list of windows from topmost to bottom-most. +.IP \fBreverse\fR 4 +.IX Item "reverse" +Reverse the order of the list of windows. +.SS "MANAGER ACTIONS" +.IX Subsection "MANAGER ACTIONS" +The following actions control the IceWM window manager and therefore +do not require a window \fIselect\fR or \fIfilter\fR option: +.IP \fBlistWorkspaces\fR 4 +.IX Item "listWorkspaces" +List the names of all workspaces. +.IP \fBcurrent\fR 4 +.IX Item "current" +Show the number and name of the current workspace. +.IP "\fBgoto\fR \fIWORKSPACE\fR" 4 +.IX Item "goto WORKSPACE" +Change the current workspace to \fIWORKSPACE\fR. Specify \f(CW\*(C`next\*(C'\fR for the +subsequent workspace or \f(CW\*(C`prev\*(C'\fR for the preceding workspace. +.IP "\fBworkspaces\fR [\fICOUNT\fR]" 4 +.IX Item "workspaces [COUNT]" +Print the number of workspaces if \fICOUNT\fR is not given, +otherwise set the number of workspaces to \fICOUNT\fR. +.IP "\fBsetWorkspaceName\fR \fIINDEX\fR \fINAME\fR" 4 +.IX Item "setWorkspaceName INDEX NAME" +Change the name of the workspace \fIINDEX\fR to \fINAME\fR, where \fIINDEX\fR is +a workspace number starting from zero. +.IP "\fBsetWorkspaceNames\fR \fINAME\fR [\fINAME\fR]*" 4 +.IX Item "setWorkspaceNames NAME [NAME]*" +Change the workspace names to the list of \fINAME\fRs. +.IP "\fBaddWorkspace\fR \fINAME\fR" 4 +.IX Item "addWorkspace NAME" +Create a new workspace with name \fINAME\fR. +.IP "\fBdesktop\fR [\fISHOWING\fR]" 4 +.IX Item "desktop [SHOWING]" +If \fISHOWING\fR is \f(CW1\fR then set \f(CW\*(C`showing the desktop\*(C'\fR mode. +If \fISHOWING\fR is \f(CW0\fR then turn off \f(CW\*(C`showing the desktop\*(C'\fR. +Print the current mode if \fISHOWING\fR is not given. +.IP \fBworkarea\fR 4 +.IX Item "workarea" +Print the dimensions of the work area for the current workspace. +This is the desktop, but minus space occupied by dock and panel windows. +.IP \fBrandr\fR 4 +.IX Item "randr" +Summarize the \fIRandR\fR configuration. +.IP \fBxinerama\fR 4 +.IX Item "xinerama" +Summarize the \fIXinerama\fR configuration. +.IP \fBcheck\fR 4 +.IX Item "check" +Print information about the current window manager, like name, +version, class, locale, command, host name and pid. +.IP \fBclients\fR 4 +.IX Item "clients" +List all managed client windows, their titles and geometries. +.IP \fBshown\fR 4 +.IX Item "shown" +List all mapped client windows for the current desktop, +their titles and geometries. +.IP \fBwindows\fR 4 +.IX Item "windows" +List all toplevel windows, their titles and geometries. +.IP \fBsystray\fR 4 +.IX Item "systray" +List applications that are managed by the IceWM system tray. +.IP \fBxembed\fR 4 +.IX Item "xembed" +List application windows that are embedded using the \fIXEMBED\fR protocol. +This is another way to discover system tray applications. +.IP \fBlogout\fR 4 +.IX Item "logout" +Let icewm execute the \f(CW\*(C`LogoutCommand\*(C'\fR. +.IP \fBreboot\fR 4 +.IX Item "reboot" +Let icewm execute the \f(CW\*(C`RebootCommand\*(C'\fR. +.IP \fBshutdown\fR 4 +.IX Item "shutdown" +Let icewm execute the \f(CW\*(C`ShutdownCommand\*(C'\fR. +.IP \fBcancel\fR 4 +.IX Item "cancel" +Let icewm cancel the logout/reboot/shutdown. +.IP \fBabout\fR 4 +.IX Item "about" +Let icewm show the about window. +.IP \fBwindowlist\fR 4 +.IX Item "windowlist" +Let icewm show the window list window. +.IP \fBrestart\fR 4 +.IX Item "restart" +Let icewm restart itself. +.IP \fBsuspend\fR 4 +.IX Item "suspend" +Let icewm execute the \f(CW\*(C`SuspendCommand\*(C'\fR. +.IP \fBhibernate\fR 4 +.IX Item "hibernate" +Let icewm execute the \f(CW\*(C`HibernateCommand\*(C'\fR. +.IP \fBwinoptions\fR 4 +.IX Item "winoptions" +Let icewm reload the \f(CW\*(C`winoptions\*(C'\fR. +.IP \fBkeys\fR 4 +.IX Item "keys" +Let icewm reload the \f(CW\*(C`keys\*(C'\fR file. +.IP \fBrefresh\fR 4 +.IX Item "refresh" +Let icewm refresh the desktop background. +.IP \fBguievents\fR 4 +.IX Item "guievents" +Monitor the \fBICEWM_GUI_EVENT\fR property and report all changes. +Hit \f(CW\*(C`Ctrl+C\*(C'\fR to abort this and continue with the next command. +.IP "\fBdelay\fR [\fItime\fR]" 4 +.IX Item "delay [time]" +Stop execution for \fItime\fR or 0.1 seconds. +.IP "\fBrunonce\fR \fIprogram\fR [\fIarguments...\fR]" 4 +.IX Item "runonce program [arguments...]" +This action is meant to be used together with the \fB\-class\fR option. +Only if no window is matched by \fIWM_CLASS\fR then +\&\fIprogram\fR [\fIarguments...\fR] is executed. +.IP "\fBloop\fR [\fIcount\fR]" 4 +.IX Item "loop [count]" +Loop back to the beginning of the command and repeat. The optional +\&\fIcount\fR limits the number of repetitions. +.IP \fBpick\fR 4 +.IX Item "pick" +Choose a window by a mouse button click. +.IP \fBsync\fR 4 +.IX Item "sync" +Synchronize with the IceWM window manager. That is, wait for icewm to +process all previous actions. +.IP \fBsymbols\fR 4 +.IX Item "symbols" +List all named symbols. +.SS CONDITIONALS +.IX Subsection "CONDITIONALS" +Icesh supports \f(CW\*(C`if\-then\-else\*(C'\fR expressions. The full syntax is: +.PP +.Vb 9 +\& if selection +\& then +\& actions +\& elif selection +\& then +\& actions +\& else +\& actions +\& end +.Ve +.PP +Where \f(CW\*(C`selection\*(C'\fR is a sequence of selection and filtering options, +which evaluates to \fBtrue\fR when it is non-empty. That is, if one or more +windows fulfilled the condition. If it is empty, then its \f(CW\*(C`actions\*(C'\fR +clause is ignored and the subsequent \f(CW\*(C`elif\*(C'\fR or \f(CW\*(C`else\*(C'\fR clause is tried +or taken. Each clause is optional. +.PP +Whenever a selection condition evaluates to \fBfalse\fR, the window selection +that existed before the \f(CW\*(C`if\*(C'\fR clause is immediately restored. This also +happens after an \f(CW\*(C`end\*(C'\fR clause. +.SS EXPRESSIONS +.IX Subsection "EXPRESSIONS" +Some of the window actions require one or two \fIEXPRESSION\fR arguments. +.ie n .IP "\fBEXPRESSION\fR ::= \fISYMBOL\fR | \fIEXPRESSION\fR { ""+"" | ""|"" } \fISYMBOL\fR" 4 +.el .IP "\fBEXPRESSION\fR ::= \fISYMBOL\fR | \fIEXPRESSION\fR { \f(CW+\fR | \f(CW|\fR } \fISYMBOL\fR" 4 +.IX Item "EXPRESSION ::= SYMBOL | EXPRESSION { + | | } SYMBOL" +.PP +Each \fISYMBOL\fR may be from one of the following applicable domains: +.IP "\fIWindow layer\fR" 4 +.IX Item "Window layer" +Named symbols of the domain \fIWindow layer\fR (numeric range: 0\-15): +.Sp +.Vb 9 +\& Desktop (0) +\& Below (2) +\& Normal (4) +\& OnTop (6) +\& Dock (8) +\& AboveDock (10) +\& Menu (12) +\& Fullscreen (14) +\& AboveAll (15) +.Ve +.Sp +These symbols are used with the \fILAYER\fR argument to the \f(CW\*(C`setLayer\*(C'\fR +action. +.IP "\fIIceWM tray option\fR" 4 +.IX Item "IceWM tray option" +Named symbols of the domain \fIIceWM tray option\fR (numeric range: 0\-2): +.Sp +.Vb 3 +\& Ignore (0) +\& Minimized (1) +\& Exclusive (2) +.Ve +.Sp +These symbols are used with the \fITRAYOPTION\fR argument to the +\&\f(CW\*(C`setTrayOption\*(C'\fR action. +.IP "\fIGravity symbols\fR" 4 +.IX Item "Gravity symbols" +Named symbols for window and bit gravity (numeric range: 0\-10): +.Sp +.Vb 11 +\& ForgetGravity (0) +\& NorthWestGravity (1) +\& NorthGravity (2) +\& NorthEastGravity (3) +\& WestGravity (4) +\& CenterGravity (5) +\& EastGravity (6) +\& SouthWestGravity (7) +\& SouthGravity (8) +\& SouthEastGravity (9) +\& StaticGravity (10) +.Ve +.IP "\fIMotif functions\fR" 4 +.IX Item "Motif functions" +.Vb 6 +\& All (1) +\& Resize (2) +\& Move (4) +\& Minimize (8) +\& Maximize (16) +\& Close (32) +.Ve +.IP "\fIMotif decorations\fR" 4 +.IX Item "Motif decorations" +.Vb 7 +\& All (1) +\& Border (2) +\& Resize (4) +\& Title (8) +\& Menu (16) +\& Minimize (32) +\& Maximize (64) +.Ve +.IP "\fIEWMH window state symbols\fR" 4 +.IX Item "EWMH window state symbols" +Named symbols of the domain \fIEWMH state\fR (numeric range: +0\-8191): +.Sp +.Vb 10 +\& ABOVE (1) +\& BELOW (2) +\& DEMANDS_ATTENTION (4) +\& FOCUSED (8) +\& FULLSCREEN (16) +\& HIDDEN (32) +\& MAXIMIZED_HORZ (64) +\& MAXIMIZED_VERT (128) +\& MODAL (256) +\& SHADED (512) +\& SKIP_PAGER (1024) +\& SKIP_TASKBAR (2048) +\& STICKY (4096) +.Ve +.SS EXAMPLES +.IX Subsection "EXAMPLES" +List all workspace names: +.PP +.Vb 1 +\& icesh listWorkspaces +.Ve +.PP +Example output: +.PP +.Vb 4 +\& workspace #0: \`main\*(Aq +\& workspace #1: \`web\*(Aq +\& workspace #2: \`doc\*(Aq +\& workspace #3: \`dev\*(Aq +.Ve +.PP +Close terminal work and activate terminal fun. +.PP +.Vb 1 +\& icesh \-c work.XTerm close \-a \-c fun.XTerm activate +.Ve +.PP +Print opacity for all xterms. +.PP +.Vb 1 +\& icesh \-c XTerm opacity +.Ve +.PP +Change opacity for all xterms. +.PP +.Vb 1 +\& icesh \-c XTerm opacity 84 +.Ve +.PP +Move all windows on workspace "Top" to the current workspace. +.PP +.Vb 1 +\& icesh \-W "Top" setWorkspace "this" +.Ve +.PP +Restore all hidden clients, minimize all clients on the current +workspace and activate Firefox. +.PP +.Vb 1 +\& icesh \-N HIDDEN restore \-a \-W "this" minimize \-a \-c Firefox activate +.Ve +.PP +Resize the focused window to occupy the right half of the desktop area. +.PP +.Vb 1 +\& icesh \-f sizeto 49% 100% top right raise +.Ve +.PP +Toggle the frame border of the focused window. +.PP +.Vb 2 +\& if icesh \-f motif | grep \-q \*(Aqdecor:$\*(Aq; then \e +\& icesh \-f motif decor All; else icesh \-f motif decor ""; fi +.Ve +.PP +Here is a different solution using conditionals. +.PP +.Vb 1 +\& icesh \-f if \-P _NET_FRAME_EXTENTS=0 then bordered else borderless +.Ve +.PP +Here is a conditional to either toggle the visibility of a roxterm +that has a WM_ROLE value of \f(CW\*(C`special\*(C'\fR or start it with \fBrunonce\fR. +.PP +.Vb 4 +\& icesh if \-c roxterm.Roxterm \-R special then \e +\& if \-v then hide \e +\& elif \-u then setWorkspace this activate end \e +\& else runonce roxterm \-\-role=special +.Ve +.PP +Collect all urxvt terminals from the fourth workspace in a single frame +on the current workspace. +.PP +.Vb 1 +\& icesh \-W 3 \-c urxvt tabto myfunnyname +.Ve +.PP +Use the loop construct conditionally to wait for a certain window to +appear. +.PP +.Vb 1 +\& icesh \-t if \-n Tooltip then list else delay 0.05 loop end +.Ve +.SS ENVIRONMENT +.IX Subsection "ENVIRONMENT" +.IP \fBDISPLAY\fR 4 +.IX Item "DISPLAY" +The default display. +.SS "EXIT STATUS" +.IX Subsection "EXIT STATUS" +.IP \fB0\fR 4 +.IX Item "0" +The last action completed successfully. +.IP \fB1\fR 4 +.IX Item "1" +The last action completed unsuccessfully, or no window met the condition. +.IP \fB2\fR 4 +.IX Item "2" +A conditional has invalid syntax. +.IP \fB3\fR 4 +.IX Item "3" +The display could not be opened. +.IP \fB4\fR 4 +.IX Item "4" +The X server reports an error while processing a request. +.SS COMPLIANCE +.IX Subsection "COMPLIANCE" +\&\fBicesh\fR is largely compliant with the EWMH and ICCCM specifications. +Some commands, like manager actions, are specific to IceWM. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), \fBwmctrl\fR\|(1), \fBxdotool\fR\|(1), \fBxprop\fR\|(1), +\&\fBxwininfo\fR\|(1), \fBXParseGeometry\fR\|(3). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icesound.1 b/upstream/fedora-40/man1/icesound.1 new file mode 100644 index 00000000..928a7460 --- /dev/null +++ b/upstream/fedora-40/man1/icesound.1 @@ -0,0 +1,199 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICESOUND 1" +.TH ICESOUND 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icesound \- play audio files when interesting GUI events happen +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicesound\fR [\fIOPTIONS\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fBicewm\fR\|(1) window manager generates so-called GUI events in +response to interesting actions, like opening or closing of application +windows, switching of workspace, etc. GUI events are a property of the +X root window. \fBicewm\fR\|(1) updates this property whenever a new GUI +event occurs. Interested applications can listen for changes to this +property. There are nearly twenty GUI events defined. +.PP +\&\fBicesound\fR responds to these GUI events by playing audio files. +These sound files are \fI.wav\fR files located in a \fIsounds\fR sub-directory +in one of the \fBicewm\fR\|(1) configuration directories. +.PP +\&\fBicesound\fR supports several common audio interfaces. These are: ALSA, +OSS and libAO. These must be enabled during configuration. +ALSA, OSS and libAO all require support for libsndfile, which is a +very common library to read audio files. +.IP \fBALSA\fR 4 +.IX Item "ALSA" +\&\fBALSA\fR is rather involved to program and it works, but this could use +more testing. It plays at most one sound at a time. +.IP \fBLibAO\fR 4 +.IX Item "LibAO" +\&\fBLibAO\fR is a cross-platform audio output library which is a convenient +wrapper around a significant number of common audio interfaces. It has +a simple configuration file which is documented in the \fBlibao.conf\fR\|(5) +manual page. +.IP \fBOSS\fR 4 +.IX Item "OSS" +The \fIOpen Sound System (OSS)\fR is a cross-platform sound interface, +which is fully supported by \fBicesound\fR. +.PP +When multiple audio interfaces are available \fBicesound\fR will examine +them all until it finds one which it can connect to and then use that +one. By default it prefers them in the order of: \fBAO\fR, \fBALSA\fR, \fBOSS\fR. +.SS OPTIONS +.IX Subsection "OPTIONS" +.SS "SPECIFIC OPTIONS" +.IX Subsection "SPECIFIC OPTIONS" +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +X11 display used by \fBicewm\fR\|(1) (default: \f(CW$DISPLAY\fR). +.IP "\fB\-s\fR, \fB\-\-sample\-dir\fR=\fIDIRECTORY\fR" 4 +.IX Item "-s, --sample-dir=DIRECTORY" +Specifies a directory with sound files. The default is: +\&\fR\f(CI$HOME\fR\fI/.config/icewm/sounds\fR, \fI\fR\f(CI$HOME\fR\fI/.icewm/sounds\fR, \fICFGDIR/sounds\fR +and \fILIBDIR/sounds\fR. See the output of \f(CW\*(C`icewm \-\-directories\*(C'\fR. +.IP "\fB\-i\fR, \fB\-\-interface\fR={\fBAO\fR|\fBALSA\fR|\fBOSS\fR}[,{\fBAO\fR|\fBALSA\fR|\fBOSS\fR}]*" 4 +.IX Item "-i, --interface={AO|ALSA|OSS}[,{AO|ALSA|OSS}]*" +Specifies the audio output interfaces. One or more of: \fBAO\fR, +\&\fBALSA\fR, \fBOSS\fR separated by comma's (\f(CW\*(C`,\*(C'\fR). +.IP "\fB\-D\fR, \fB\-\-device\fR=\fIDEVICE\fR" 4 +.IX Item "-D, --device=DEVICE" +Backwards compatibility only: the default device. +Please prefer one of the \fB\-A\fR, \fB\-O\fR or \fB\-S\fR options. +.IP "\fB\-O\fR, \fB\-\-oss\fR=\fIDEVICE\fR" 4 +.IX Item "-O, --oss=DEVICE" +Specifies the OSS device (default: \fI/dev/dsp\fR). +.IP "\fB\-A\fR, \fB\-\-alsa\fR=\fIDEVICE\fR" 4 +.IX Item "-A, --alsa=DEVICE" +Specifies the ALSA device (default: \f(CW\*(C`default\*(C'\fR). +.IP "\fB\-z\fR, \fB\-\-snooze\fR=\fIMILLISECONDS\fR" 4 +.IX Item "-z, --snooze=MILLISECONDS" +Specifies the snooze interval between sound events +in milliseconds. Default is 500 milliseconds. +.IP "\fB\-p\fR, \fB\-\-play\fR=\fISOUND\fR" 4 +.IX Item "-p, --play=SOUND" +Plays the given sound (name or number) and exits. +.IP "\fB\-l\fR, \fB\-\-list\-files\fR" 4 +.IX Item "-l, --list-files" +Lists the available sound file paths and exits. +.IP \fB\-\-list\-sounds\fR 4 +.IX Item "--list-sounds" +Lists the supported sound file names and exits. +.IP \fB\-\-list\-interfaces\fR 4 +.IX Item "--list-interfaces" +Lists the supported audio interfaces and exits. +.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4 +.IX Item "-o, --output=FILE" +Redirect all output to \fIFILE\fR. +A leading tilde or environment variable is expanded. +.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 +.IX Item "-v, --verbose" +Be verbose and print some information when sound events occur. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.SS "EXIT STATUS" +.IX Subsection "EXIT STATUS" +.IP \fB0\fR 4 +.IX Item "0" +Success. +.IP \fB1\fR 4 +.IX Item "1" +General error. +.IP \fB2\fR 4 +.IX Item "2" +Command line error. +.IP \fB3\fR 4 +.IX Item "3" +Subsystems error (i.e cannot connect to server). +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBlibao.conf\fR\|(5), +\&\fBpadsp\fR\|(1), +\&\fBaplay\fR\|(1), +\&\fBalsamixer\fR\|(1). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewm-menu-fdo.1 b/upstream/fedora-40/man1/icewm-menu-fdo.1 new file mode 100644 index 00000000..aad397d6 --- /dev/null +++ b/upstream/fedora-40/man1/icewm-menu-fdo.1 @@ -0,0 +1,190 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-MENU-FDO 1" +.TH ICEWM-MENU-FDO 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-menu\-fdo \- menu generator for .desktop files +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewm-menu-fdo\fR [\fIOPTIONS\fR] [\fIFILENAME\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewm-menu-fdo\fR generates a menu for the \fBIceWM\fR window manager +from XDG menu descriptors (aka FreeDesktop.Org \fI.desktop\fR files). +By including this in the \fBicewm\-menu\fR\|(1), the system applications +become available in the icewm start menu. +.SS ARGUMENTS +.IX Subsection "ARGUMENTS" +.IP [\fIFILENAME\fR] 4 +.IX Item "[FILENAME]" +The optional \fIFILENAME\fR argument is the location of a \fI.desktop\fR file. +When given, \fBicewm-menu-fdo\fR launches the application using the \f(CW\*(C`Exec\*(C'\fR +line from the desktop file. +.SS OPTIONS +.IX Subsection "OPTIONS" +.IP "\fB\-g\fR, \fB\-\-generic\fR" 4 +.IX Item "-g, --generic" +Include the generic name in parentheses in the title of \fBprog\fR entries. +.IP \fB\-\-seps\fR 4 +.IX Item "--seps" +Print a leading and a trailing separator. +.IP \fB\-\-sep\-before\fR 4 +.IX Item "--sep-before" +Print a leading separator. +.IP \fB\-\-sep\-after\fR 4 +.IX Item "--sep-after" +Print a trailing separator. +.IP \fB\-\-no\-sep\-others\fR 4 +.IX Item "--no-sep-others" +Don't print the \f(CW\*(C`Other\*(C'\fR category last. +.IP \fB\-\-no\-sub\-cats\fR 4 +.IX Item "--no-sub-cats" +Don't nest subcategories in submenus. +.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4 +.IX Item "-o, --output=FILE" +Write the output to \fIFILE\fR. +.IP "\fB\-t\fR, \fB\-\-terminal=NAME\fR" 4 +.IX Item "-t, --terminal=NAME" +Use \fINAME\fR to start a terminal emulator that supports the '\-e' option. +.IP \fB\-\-flat\fR 4 +.IX Item "--flat" +Display apps from all categories in one level with the title containing +the category information as prefix. +.IP "\fB\-F sep\fR, \fB\-\-flat\-sep=sep\fR" 4 +.IX Item "-F sep, --flat-sep=sep" +When used with \f(CW\*(C`\-\-flat\*(C'\fR, the specified character sequence is used as +separator between the section titles. +.IP "\fB\-m filter\fR, \fB\-\-match=filter\fR" 4 +.IX Item "-m filter, --match=filter" +Specifies a filter to show only apps that contain this as substring +within their title. +.IP "\fB\-M filter\fR, \fB\-\-imatch=filter\fR" 4 +.IX Item "-M filter, --imatch=filter" +Like \f(CW\*(C`\-\-match\*(C'\fR but applied with any letter case. +.IP \fB\-\-match\-sec\fR 4 +.IX Item "--match-sec" +Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to both, apps and +section titles. +.IP \fB\-\-match\-osec\fR 4 +.IX Item "--match-osec" +Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to only to section titles. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.SS USAGE +.IX Subsection "USAGE" +This utility is not normally used directly. It is used as the +executable in a \fBmenuprog\fR entry in a \fBicewm\-menu\fR\|(5). +.SS EXAMPLES +.IX Subsection "EXAMPLES" +The following line in a \fBicewm\-menu\fR\|(5) file will dynamically generate +a comprehensive set of menus for easy access to \fI.desktop\fR files. +.PP +.Vb 1 +\& menuprog "Desktop Apps" folder icewm\-menu\-fdo +.Ve +.SS ENVIRONMENT +.IX Subsection "ENVIRONMENT" +\&\fBXDG_DATA_HOME\fR or \fBXDG_DATA_DIRS\fR are considered as suggested by XDG +Base Directory Specification. +.PP +\&\fBTERMINAL\fR may define a terminal emulator that supports the '\-e' option. +.SS "CONFORMING TO" +.IX Subsection "CONFORMING TO" +\&\fBicewm-menu-fdo\fR complies roughly to the XDG \fI.desktop\fR file and menu +specification, see "Desktop Entry Specification", Version 1.2alpha, +2015\-03\-06 and "Desktop Menu Specification", Version 1.1\-draft, 31 +March 2011. +.SS CAVEATS +.IX Subsection "CAVEATS" +The \fBicewm-menu-fdo\fR program is only built when the \fBicewm\fR\|(1) package +is configured with the \fB\-\-enable\-menus\-fdo\fR option, which requires the +\&\fBglib2\-dev\fR package dependency. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +"Desktop Entry Specification", +"Desktop Menu Specification", +\&\fBicewm\fR\|(1), +\&\fBicewm\-menu\fR\|(5), +\&\fBicewm\-preferences\fR\|(5), +\&\fBicewm\-programs\fR\|(5). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Eduard Bloch . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewm-menu-xrandr.1 b/upstream/fedora-40/man1/icewm-menu-xrandr.1 new file mode 100644 index 00000000..d588ac90 --- /dev/null +++ b/upstream/fedora-40/man1/icewm-menu-xrandr.1 @@ -0,0 +1,141 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-MENU-XRANDR 1" +.TH ICEWM-MENU-XRANDR 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-menu\-xrandr \- IceWM menu provider for multi\-monitor setup shortcuts +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewm-menu-xrandr\fR +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewm-menu-xrandr\fR is a helper to manage multi-screen configurations +in a semi-automated way. It is a regular icewm menu generator that +detects the available xrandr screens (i.e. connected monitors) and +creates menu entries that call the xrandr command to setup this +configuration. +.PP +Optionally, the contents of the generated configurations can be accessed +on-the-fly through a "quick-switch" style menu which pops up upon +pressing Super-P key binding (or a manually configured key, see +\&\fBicewm\-keys\fR\|(5) for the configuration of \fBswitchkey\fR directive). +.PP +The tool does not examine the exact monitor resolutions, refresh rates +or screen orientation. For this matters it uses auto selected mode by +default. However, it is possible to replace the custom option selection +for each output using \fIxrandr\fR options in a custom configuration file +(see \fICONFIGURATION\fR below). Also tuning specific options like +\&\-\-brightness and \-\-gamma is possible there. +.PP +The displayed name of the monitors is constructed using the output name +and the monitor information from its EDID data. Either from its "Display +Name" field or from the "Unspecified ASCII text" fields (concatenated). +.SS OPTIONS +.IX Subsection "OPTIONS" +.IP \fB\-\-max\fR 4 +.IX Item "--max" +Obsolete and ineffective option. Used to select the \fIxrandr\fR mode with the +highest detected refresh rate. However, the maximum rate might cause +problems, therefore the explicit configuration in the \fIINI file\fR should be +used now, see \fICONFIGURATION\fR. +.IP "\fB\-\-auto\-number [ init value ]\fR" 4 +.IX Item "--auto-number [ init value ]" +Adding a auto-incremented numbered prefix to each display name, +optionally started at the specified value. This mostly useful for menu +creation. +.IP "\fB\-\-xrandr command\fR" 4 +.IX Item "--xrandr command" +Replacement for \fIxrandr\fR command that should deliver equivalent data +and accept the same options as \fIxrandr\fR. +.IP "\fB\-\-activate combo-name\fR" 4 +.IX Item "--activate combo-name" +A shortcut to run the activation command of the specified combo, just +like \fIIceWM\fR would run the commmand when selected from the menu or +quick-switch dialog. The \fIcombo-name\fR parameter needs to match the +displayed name exactly. +.SS CONFIGURATION +.IX Subsection "CONFIGURATION" +Optionally, a local configuration can specify command line options to +\&\fIxrandr\fR calls, and further commands to run after mode switching. +.PP +Refer to configuration examples (\fIxrandr_menu\fR) in \fIicewm\fR +documentation or its contrib folder for the syntax and rules of that +file. It can be placed into \fR\f(CI$HOME\fR\fI/.config/icewm\fR or into +\&\fI\fR\f(CI$HOME\fR\fI/.icewm\fR or wherever \fI\fR\f(CI$XDG_CONFIG_HOME\fR\fI/.config/icewm\fR might +resolve to. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBxrandr\fR\|(1). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Eduard Bloch . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBicewm-menu-xrandr\fR is licensed under the Simplified BSD License. +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man1/icewm-session.1 b/upstream/fedora-40/man1/icewm-session.1 new file mode 100644 index 00000000..ea9023c2 --- /dev/null +++ b/upstream/fedora-40/man1/icewm-session.1 @@ -0,0 +1,185 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-SESSION 1" +.TH ICEWM-SESSION 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-session \- X.Org session manager provider with IceWM +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewm-session\fR [\fIOPTIONS\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +icewm-session is an implementation of a X.Org session manager and can be +run from a X11 session setup. It runs \fBicewm\fR as default window manager +and controls the life cycle of related support applications. +.SS OPTIONS +.IX Subsection "OPTIONS" +.SS "SPECIFIC OPTIONS" +.IX Subsection "SPECIFIC OPTIONS" +.IP "\fB\-c\fR, \fB\-\-config=FILE\fR" 4 +.IX Item "-c, --config=FILE" +Let IceWM load preferences from \fIFILE\fR. +.IP "\fB\-t\fR, \fB\-\-theme=FILE\fR" 4 +.IX Item "-t, --theme=FILE" +Let IceWM load the theme \fIFILE\fR. +.IP "\fB\-i\fR, \fB\-\-icewm=FILE\fR" 4 +.IX Item "-i, --icewm=FILE" +Use \fIFILE\fR as the IceWM window manager. +.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4 +.IX Item "-o, --output=FILE" +Redirect all output to \fIFILE\fR. +A leading tilde or environment variable is expanded. +.IP "\fB\-a\fR, \fB\-\-alpha\fR" 4 +.IX Item "-a, --alpha" +Use a 32\-bit visual for translucency. +.IP "\fB\-b\fR, \fB\-\-nobg\fR" 4 +.IX Item "-b, --nobg" +Do not start icewmbg. +.IP "\fB\-n\fR, \fB\-\-notray\fR" 4 +.IX Item "-n, --notray" +Do not start icewmtray. +This is only applicable if IceWM was explicitly configured +to use an external icewmtray process. +.IP "\fB\-s\fR, \fB\-\-sound\fR" 4 +.IX Item "-s, --sound" +Also start icesound. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +Use \fIDISPLAY\fR to connect to the X server. +If this option is missing then \fIDISPLAY\fR +is read from the environment variable \f(CW\*(C`DISPLAY\*(C'\fR. +.IP \fB\-\-sync\fR 4 +.IX Item "--sync" +Use a slower synchronous mode communication with the \fIX11\fR server. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Give a list of all supported options and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions and exit. +.SS "DEBUGGING OPTIONS" +.IX Subsection "DEBUGGING OPTIONS" +.IP "\fB\-v\fR, \fB\-\-\-valgrind\fR" 4 +.IX Item "-v, ---valgrind" +Let \f(CW\*(C`/usr/bin/valgrind\*(C'\fR run icewm. +Thoroughly examines the execution of icewm. +.IP "\fB\-g\fR, \fB\-\-\-catchsegv\fR" 4 +.IX Item "-g, ---catchsegv" +Let \f(CW\*(C`/usr/bin/catchsegv\*(C'\fR run icewm. +Gives a backtrace if icewm segfaults. +.SS USAGE +.IX Subsection "USAGE" +On startup icewm-session executes the following steps. +From the file \fIenv\fR in the configuration directory +it loads additional environment variables, if that file exists. +Then it will start \fIicewmbg\fR to manage root background colors and images. +It may also start \fIicesound\fR, if this was enabled at configuration time. +Then \fIicewm\fR is started. +.PP +If there exists an executable script \fIstartup\fR in the configuration +directory, it will be executed. It may contain commands to initialize X11 +settings with \fIxset\fR, load keyboard configuration, start a compositing +manager like \fIcompton\fR and load system tray applications. +.PP +When icewm exits, icewm-session will execute a \fIshutdown\fR script, +if it exists in the configuration directory. +When this finishes, icewm-session will terminate icewm, icewmbg +and icesound. Finally, icewm-session will exit. +.PP +If the icewm process crashes then icewm-session will attempt to restart +it. If two such crashes occur in a short period, then icewm-session will +attempt to popup a dialog using either \fIyad\fR, \fIxmessage\fR, \fIkdialog\fR +or \fIzenity\fR. This dialog presents a choice between restarting icewm, +starting a terminal, or abort execution of icewm-session. +.SS ENVIRONMENT +.IX Subsection "ENVIRONMENT" +.IP \fBICEWM_OPTIONS\fR 4 +.IX Item "ICEWM_OPTIONS" +A space separated list of options that will be added to the command +line invocation of \fIicewm\fR. This can be set in the \fIenv\fR file. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-env\fR\|(5), +\&\fBicewm\-shutdown\fR\|(5), +\&\fBicewm\-startup\fR\|(5), +\&\fBicewmbg\fR\|(1). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewm-set-gnomewm.1 b/upstream/fedora-40/man1/icewm-set-gnomewm.1 new file mode 100644 index 00000000..b0059a6f --- /dev/null +++ b/upstream/fedora-40/man1/icewm-set-gnomewm.1 @@ -0,0 +1,97 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-SET-GNOMEWM 1" +.TH ICEWM-SET-GNOMEWM 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-set\-gnomewm \- modify GNOME settings to use IceWM +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewm-set-gnomewm\fR [\fIOPTIONS\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewm-set-gnomewm\fR is a helper script that instruments GNOME to +replace its own WM with icewm. +.SS OPTIONS +.IX Subsection "OPTIONS" +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewm.1 b/upstream/fedora-40/man1/icewm.1 new file mode 100644 index 00000000..67ee974f --- /dev/null +++ b/upstream/fedora-40/man1/icewm.1 @@ -0,0 +1,1418 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM 1" +.TH ICEWM 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm \- lightweight X11 window manager +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewm\fR [\fIOPTIONS\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewm\fR is a window manager for the X11 window system. +It aims to be small, fast and familiar to new users. +.PP +\&\fBicewm\fR is called a re-parenting window manager, +because it draws small frames around application windows. +By dragging this frame with the mouse, windows are resized or moved. +.PP +Because windows may overlap, \fBicewm\fR is also a stacking window manager. +Many windows may exist, some hidden behind others. +.PP +\&\fBicewm\fR supports a configurable number of virtual desktops. These are +called workspaces. Related windows are grouped on a dedicated workspace. +By switching between workspaces, the user can attend to different tasks, +while keeping oversight. This is supported by a task bar and a pager. +.PP +The installation comes with several themes. Choose a theme via a menu. +.PP +\&\fBicewm\fR is compliant with the ICCCM and EWMH window manager specifications. +.SS PROGRAMS +.IX Subsection "PROGRAMS" +The \fBicewm\fR package includes several programs: +.IP \fBicewm\fR\|(1) 4 +.IX Item "icewm" +The actual window manager. It positions application windows on screen +and decorates them with borders. It gives input focus to the current +active application. \fBicewm\fR supports different focus modes, which are +explained below. It draws a small task bar at the bottom of the screen, +that gives easy access to programs, to virtual desktops, to active +applications, and to a small set of monitoring applets. +.IP \fBicewmbg\fR\|(1) 4 +.IX Item "icewmbg" +The background setting application. It can assign plain background color +or images in different formats to the X background. Each workspace can +have its own background. It supports semitransparency. Semitransparent +background image and colour can be configured. When the background image +has changed then \fBicewmbg\fR\|(1) can be notified to update the background. +Multi-head monitor setups are fully supported. See the \fBicewmbg\fR\|(1). +.IP \fBicewm\-session\fR\|(1) 4 +.IX Item "icewm-session" +\&\fBicewm\-session\fR\|(1) is the preferred program to start the IceWM system. +It first loads additional environment variables from the optional +\&\fIenv\fR file. Then it starts \fBicewmbg\fR\|(1) and \fBicewm\fR. It also runs +the \fIstartup\fR script and implements basic session management. +On termination the \fIshutdown\fR script will be run first, then +\&\fBicewm\-session\fR\|(1) will terminate \fBicewm\fR and \fBicewmbg\fR\|(1). +\&\fBicewm\-session\fR\|(1) will also start the optional \fBicesound\fR\|(1) +if you give it the \fB\-\-sound\fR option. See \fBicewm\-session\fR\|(1). +.IP \fBicesh\fR\|(1) 4 +.IX Item "icesh" +A powerful tool to control window properties and to interact with the +window manager. It is typically used in shell scripts. See \fBicesh\fR\|(1). +.IP \fBicehelp\fR\|(1) 4 +.IX Item "icehelp" +A small document browser that is used by \fBicewm\fR to display the +\&'IceWM manual' and some man pages. +.IP \fBicewmhint\fR\|(1) 4 +.IX Item "icewmhint" +A utility for passing IceWM-specific window options to \fBicewm\fR. +The options are used to configure the first application that is started +subsequently. See \fBicewmhint\fR\|(1). +.IP \fBicesound\fR\|(1) 4 +.IX Item "icesound" +Plays audio files on GUI events that are raised by \fBicewm\fR. +It supports ALSA, AO and OSS. See the \fBicesound\fR\|(1) man page. +.IP \fBicewm\-menu\-fdo\fR\|(1) 4 +.IX Item "icewm-menu-fdo" +Generate an \fBicewm\fR menu with executable desktop applications +according to XDG specifications. See the \fBicewm\-menu\-fdo\fR\|(1) man page. +.IP \fBicewm\-set\-gnomewm\fR\|(1) 4 +.IX Item "icewm-set-gnomewm" +Configures GNOME to start IceWM instead of its own WM. +.SS OPTIONS +.IX Subsection "OPTIONS" +.SS "COMMON OPTIONS" +.IX Subsection "COMMON OPTIONS" +Each of the IceWM executables supports the following options: +.IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4 +.IX Item "-c, --config=FILE" +Use \fIFILE\fR as the source of configuration options. By default \fBicewm\fR +looks for a file named \fIpreferences\fR. This is a readable text file +that can be modified with the help of a text editor. +.IP "\fB\-t\fR, \fB\-\-theme\fR=\fINAME\fR" 4 +.IX Item "-t, --theme=NAME" +Use \fINAME\fR as the name of the \fBicewm\fR theme to use. A theme defines +the look and feel of \fBicewm\fR, like colors, fonts and buttons. +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +Connect to the X11 server on \fIDISPLAY\fR. By default +the environment variable \f(CW\*(C`DISPLAY\*(C'\fR is used. +.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4 +.IX Item "-o, --output=FILE" +Redirect all output to \fIFILE\fR. +A leading tilde or environment variable is expanded. +.IP \fB\-\-sync\fR 4 +.IX Item "--sync" +This option specifies to use a slower synchronous communication mode +with the X11 server. This is irrelevant for normal use. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Gives a complete list of all the available command-line options with +some very brief explanation. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Shows the software release version for this program. +.SS "ICEWM OPTIONS" +.IX Subsection "ICEWM OPTIONS" +The \fBicewm\fR program supports some additional options: +.IP "\fB\-a\fR, \fB\-\-alpha\fR" 4 +.IX Item "-a, --alpha" +Use a 32\-bit visual for translucency. This can also be set in +the preferences file as \f(CW\*(C`Alpha=1\*(C'\fR. +.IP \fB\-\-replace\fR 4 +.IX Item "--replace" +Instructs \fBicewm\fR to replace an existing window manager. Provided that +the window manager being replaced is ICCCM 2.0 compliant, once it +notices that it is to be replaced it will cease operations and typically +stop execution. This allows \fBicewm\fR to establish itself as the only +active window manager. +.IP "\fB\-r\fR, \fB\-\-restart\fR" 4 +.IX Item "-r, --restart" +Tell \fBicewm\fR to restart itself. This reloads the configuration from +file. If no window manager is active, then it starts one. +.IP "\fB\-s\fR, \fB\-\-splash\fR=\fIIMAGE\fR" 4 +.IX Item "-s, --splash=IMAGE" +Briefly show \fIIMAGE\fR on startup in the center of the screen. +This can also be set in the preferences file as Splash=\f(CW\*(C`image.jpg\*(C'\fR. +.IP \fB\-\-configured\fR 4 +.IX Item "--configured" +Shows a list of configuration options that were enabled when \fBicewm\fR +was compiled from source code. This can be helpful if one suspects some +functionality may be missing. +.IP \fB\-\-directories\fR 4 +.IX Item "--directories" +Gives a list of directories where \fBicewm\fR will look for configuration +data. This list is printed in the actual order in which \fBicewm\fR uses +it to search for configuration files. +.IP "\fB\-l\fR, \fB\-\-list\-themes\fR" 4 +.IX Item "-l, --list-themes" +\&\fBicewm\fR will search all the configuration directories for theme files +and print a list of all found themes. +.IP "\fB\-p\fR, \fB\-\-postpreferences\fR" 4 +.IX Item "-p, --postpreferences" +This gives a long list of all the internal \fBicewm\fR options with their +actual values after \fBicewm\fR has processed all of the configuration and +theme files. In some advanced scenarios this can be helpful to inspect +which configuration was chosen or whether option formatting was correct. +.IP \fB\-\-rewrite\-preferences\fR 4 +.IX Item "--rewrite-preferences" +Overwrite an existing preferences file with an icewm default preferences, +but preserve all modifications insofar they deviate from the defaults. +.IP \fB\-\-extensions\fR 4 +.IX Item "--extensions" +Give a list of the current X extensions, their versions and status. +.IP \fB\-\-trace\fR=\fIconf\fR,\fIfont\fR,\fIicon\fR,\fIprog\fR,\fIsystray\fR 4 +.IX Item "--trace=conf,font,icon,prog,systray" +Enable tracing of the paths that are used to load configuration, +fonts, icons, executed programs, and/or system tray applets. +.SS USAGE +.IX Subsection "USAGE" +.SS TASKBAR +.IX Subsection "TASKBAR" +On startup \fBicewm\fR launches the task bar at the bottom of the screen. +The task bar consists from left to right of the following components: +.PP +The \fIMenu\fR button in the lower left corner gives access to the \fBicewm\fR +root menu. This menu has sub-menus to start applications, to control +\&\fBicewm\fR settings, and the \fBicewm\fR \fILogout\fR menu. +.PP +The \fIShow Desktop\fR button unmaps all application windows to fully +uncover the desktop. +.PP +The \fIWindow List Menu\fR button gives access to a menu with a list of +active windows for the current workspace and a list of workspaces +with sub-menus for their active application windows. +.PP +The \fIToolbar\fR is a list of icons for applications that are defined in +the toolbar configuration file. +.PP +The \fIWorkspace Pane\fR shows one button for each workspace. The current +workspace is indicated by a pressed button. Clicking another workspace +switches to that workspace. Press left mouse, then the Shift key, then +release the left mouse, takes the current window to that workspace. +Press left, then Alt, then release left, moves only the focused window +to other workspace, without changing the current workspace. +.PP +The workspaces are defined in the \fIpreferences\fR file. To change a name +for only this session, double click, edit the name and hit Enter. +When \f(CW\*(C`PagerShowPreview\*(C'\fR is turned on, a small graphical window summary +for each workspace is shown. They support drag-and-drop: dragging a +Firefox tab to a workspace button changes the current workspace. +Then releasing it moves that tab to a new window in that workspace. +.PP +The \fITask Pane\fR consists of a list of wide buttons for each application +that is running on the current workspace, or all workspaces if +\&\f(CW\*(C`TaskBarShowAllWindows=1\*(C'\fR. Each task button shows the +application icon and the application title. The active application is +indicated by a pressed button. This is the application that has input +focus. Pressing another button activates that application: it is +brought to the foreground and receives input focus. Other mouse +controlled activities on the window buttons are: dragging window buttons +with the left mouse button to rearrange the order, closing the application +window with \f(CW\*(C`Alt\*(C'\fR + middle button, lowering the application window with +\&\f(CW\*(C`Ctrl\*(C'\fR + middle button, or bringing the application window to the current +workspace with \f(CW\*(C`Shift\*(C'\fR + middle button if \f(CW\*(C`TaskBarShowAllWindows=1\*(C'\fR. +.PP +If there are not many application buttons then a stretch of plain task +bar is visible. Clicking on it with the right mouse button gives the +task bar menu. Even with a full task pane, this menu can be usually +accessed by right-clicking the bottom right corner of the taskbar. +.PP +The \fITray Applet\fR shows system tray objects. +.PP +The \fIAPM Applet\fR shows battery power status. +.PP +The \fINet Applet\fR shows network activity. Network devices to monitor +are given by the \f(CW\*(C`NetworkStatusDevice\*(C'\fR option. +.PP +The \fIMemory Applet\fR monitors memory usage. +.PP +The \fICPU Applet\fR monitors processor utilization. +.PP +The \fIMailbox Applet\fR monitors mailbox status changes. +See the section MAILBOX MONITORING below. +.PP +The \fIClock Applet\fR shows the current time and date. It is configured +by the \f(CW\*(C`TimeFormat\*(C'\fR option. +.PP +The \fITask Bar Collapse\fR button collapses the task bar and hides it. +.PP +Not all \fBicewm\fR applets may show up on the task bar. They must have +been enabled during configuration of the \fBicewm\fR software. Their +appearance is also controlled by options in the \fIpreferences\fR file. +.SS "INPUT FOCUS" +.IX Subsection "INPUT FOCUS" +Of all visible windows only one can be the active window. This is the +window that has input focus. It is the primary receiver of keyboard +and mouse events and hence one can interact with the application that +created that window. A primary task of a window manager is to allow the +user to switch input focus between different windows. The primary means +to do this is the mouse pointer. By moving the mouse pointer over the +screen to another window, and perhaps also by clicking on a window, +input focus can be directed. +.PP +The \f(CW\*(C`FocusMode\*(C'\fR option controls the way \fBicewm\fR gives input focus to +applications. It is initialized by the \fIfocus_mode\fR configuration +file. The focus mode is set via the \fIFocus\fR menu. \fBicewm\fR supports +six focus models: +.IP "\fB1. Click-to-focus\fR" 4 +.IX Item "1. Click-to-focus" +The default focus mode. In this mode changing input focus requires to +click a window with the left mouse button. The window is raised if +needed. When an application requests focus its task pane button +flashes. This gives the option to honor this request or to ignore it. +When a new application window appears it automatically receives focus. +Also when a hidden application raises to the front it receives focus. +.IP "\fB2. Sloppy-mouse-focus\fR" 4 +.IX Item "2. Sloppy-mouse-focus" +Sets input focus merely by moving the mouse pointer over a window. It +is called sloppy, because if the mouse then leaves the window and moves +to the desktop background the input focus remains with the last active +window. When a window receives focus it is raised. When an application +requests focus its task pane button flashes. A new application or an +application that raises to the front automatically receives focus. +.IP "\fB3. Explicit-focus\fR" 4 +.IX Item "3. Explicit-focus" +Focus is even more user-controlled than \fBClick-to-focus\fR. When a +window receives focus it is not raised by default, unless the frame +border is clicked. No flashing occurs when an application requests +focus. When a new application window appears it does not receive focus. +Only by explicit clicking on a window is focus directed. +.IP "\fB4. Strict-mouse-focus\fR" 4 +.IX Item "4. Strict-mouse-focus" +Like \fBSloppy\fR but focus remains with the last window. New applications +don't receive focus and are mapped behind other windows. When an +application raises to the front it still does not get focus. +.IP "\fB5. Quiet-sloppy-focus\fR" 4 +.IX Item "5. Quiet-sloppy-focus" +Like \fBSloppy\fR but no disturbing flashing occurs on the task bar when an +application requests focus. +.IP "\fB6. Custom-mode\fR" 4 +.IX Item "6. Custom-mode" +A focus mode that is defined by the following ten options: +\&\f(CW\*(C`ClickToFocus\*(C'\fR, +\&\f(CW\*(C`FocusOnAppRaise\*(C'\fR, +\&\f(CW\*(C`RequestFocusOnAppRaise\*(C'\fR, +\&\f(CW\*(C`RaiseOnFocus\*(C'\fR, +\&\f(CW\*(C`RaiseOnClickClient\*(C'\fR, +\&\f(CW\*(C`FocusChangesWorkspace\*(C'\fR, +\&\f(CW\*(C`FocusOnMap\*(C'\fR, +\&\f(CW\*(C`FocusOnMapTransient\*(C'\fR, +\&\f(CW\*(C`FocusOnMapTransientActive\*(C'\fR, +\&\f(CW\*(C`MapInactiveOnTop\*(C'\fR. +.Sp +All non-Custom focus modes override these ten options. +.PP +Apart from the mouse, \fBicewm\fR supports changing input focus in two +ways by keyboard. By pressing \f(CW\*(C`Alt+Esc\*(C'\fR or \f(CW\*(C`Alt+Shift+Esc\*(C'\fR, +input focus is immediately changed to the next or previous window, +which will be raised to make it fully visible. The other method +involves the quick switch. +.SS "QUICK SWITCH" +.IX Subsection "QUICK SWITCH" +The \fBQuickSwitch\fR is a means to quickly and interactively change +the input focus to another window. It is activated by pressing the +\&\f(CW\*(C`Alt+Tab\*(C'\fR or \f(CW\*(C`Alt+Shift+Tab\*(C'\fR key combination. A window pops up +in the centre of the screen with a list of windows to choose from. +A narrow band indicates a selection: the candidate window that will +be activated to receive input focus when the Alt key is released. +.PP +The selection can be changed by repeatedly pressing the Tab key, while +keeping the Alt key down. If a Shift key is also down, the direction of +traversal is reversed. Or use the scroll wheel of the mouse. Or use +one of the digit keys to select the corresponding window from the list. +Arrow keys are also supported, as well as the Home and End key. +.PP +To make a selected window the active window, just release the Alt key, +or hit the Return key, or click on it. To cancel the QuickSwitch, +press Escape or click outside of the QuickSwitch window. +.PP +A selected window can be closed by Delete, \f(CW\*(C`Alt+F4\*(C'\fR, or the middle +mouse button. While the QuickSwitch window is up, one can still change +workspace with the usual workspace hotkeys. +.PP +The QuickSwitch has two distinct modes: vertical and horizontal. +The window list can include all windows or be limited to the current +workspace. There is an option to raise the selected candidate. +See the many preferences available for the QuickSwitch. +.SS "WINDOW PLACEMENT" +.IX Subsection "WINDOW PLACEMENT" +A second important task of a window manager is to place new windows on +the screen. By default \fBicewm\fR chooses a placement with minimal +overlap, but this is determined by the \f(CW\*(C`SmartPlacement\*(C'\fR option in the +\&\fIpreferences\fR file. If \f(CW\*(C`SmartPlacement\*(C'\fR is turned off then windows +are placed in sequence from left to right and top to bottom. One can +also turn on \f(CW\*(C`ManualPlacement\*(C'\fR. Then new windows appear initially in +the top left corner and the mouse cursor changes into a fist. By moving +the fist cursor to a suitable location and clicking the new window will +appear at the mouse click location. +.SS "WINDOW LAYERS" +.IX Subsection "WINDOW LAYERS" +Windows can overlap. Which window appears on top is determined by three +features. Newer windows appear over older windows. By clicking on a +window it is raised to the top. But both are overruled by the window +layer. Windows can be placed in different layers via the \fILayers\fR +menu. Click with the right mouse button on the window frame and select +\&\fILayer\fR. From there choose one of seven window layers. These are +ordered from higher to lower. Windows in higher layers appear over +windows in lower layers. +.SS "TABBED WINDOWS" +.IX Subsection "TABBED WINDOWS" +A window frame may contain multiple client windows. Only one client can +be visible, while the others are hidden. This is called tabbing. This +can be helpful to reduce the number of visible windows. To create a tab, +drag the title bar with the middle mouse button, while holding down a +shift key, onto the title bar of another frame. The two title bars will +start to flash to indicate that they can merge. Release the mouse button +to merge the client of the upper window to the lower frame. Now the +lower frame will have multiple clients, called tabs. The title bar will +show a vertical bar with triple dots to indicate this. +To change the current tab either: +.IP \(bu 4 +Click on the triple dots next to the vertical bar. +.IP \(bu 4 +Use \f(CW\*(C`KeyWinNext=Alt+F6\*(C'\fR to select the next tab. +.IP \(bu 4 +Use \f(CW\*(C`KeyWinPrev=Alt+Shift+F6\*(C'\fR for the previous tab. +.IP \(bu 4 +Use the QuickSwitch. +.IP \(bu 4 +Use the window list window. +.IP \(bu 4 +Use a submenu in the window menu. +.PP +To change the mouse binding for creating tabs, modify +\&\fBMouseWinTabbing\fR=\f(CW\*(C`Shift+Pointer_Button2\*(C'\fR. Another +useful setting is \fBMouseWinTabbing\fR=\f(CW\*(C`Pointer_Button1\*(C'\fR. +.PP +\&\f(CW\*(C`Alt+F4\*(C'\fR closes all tabs. To close just the active tab add to \f(CW\*(C`keys\*(C'\fR: +.PP +.Vb 1 +\& key "Ctrl+Shift+F4" icesh \-f close +.Ve +.PP +To move the active tab to its own window frame by key, add to \f(CW\*(C`keys\*(C'\fR: +.PP +.Vb 1 +\& key "Alt+u" icesh \-f untab +.Ve +.PP +To open all chrome windows in the same frame add this to \f(CW\*(C`winoptions\*(C'\fR: +.PP +.Vb 1 +\& google\-chrome.frame: chrome +.Ve +.SS WORKSPACES +.IX Subsection "WORKSPACES" +\&\fBicewm\fR supports multiple virtual desktops called workspaces. A +workspace is like a screen where a subset of all application windows are +mapped. Thanks to multiple workspaces we can more easily manage a +large number of applications. The number of workspaces and their names +are configurable in the \fIpreferences\fR file through the +\&\f(CW\*(C`WorkspaceNames\*(C'\fR option. By default four workspaces are created +with the names 1, 2, 3 and 4 thus: +.PP +.Vb 1 +\& WorkspaceNames=" 1 ", " 2 ", " 3 ", " 4 " +.Ve +.PP +This syntax is typical for \fBicewm\fR options that receive multiple +values. It is a list of comma-separated values each of which can be +quoted. +.PP +The workspaces are visible on the toolbar. One can switch to a +different workspace by pressing the workspace button in the toolbar, +but after becoming familiar with the 'keyboard shortcuts' below one will +want to use a hotkey to choose a workspace. If the \f(CW\*(C`EdgeSwitch\*(C'\fR +options is enabled in the \fIpreferences\fR file (with sub-options +\&\f(CW\*(C`HorizontalEdgeSwitch\*(C'\fR and \f(CW\*(C`VerticalEdgeSwitch\*(C'\fR) then one can move to +the next or previous workspace by moving the mouse to the edge of the +screen. The \f(CW\*(C`ContinuousEdgeSwitch\*(C'\fR option enables continuous movement +to subsequent workspaces. The \f(CW\*(C`EdgeSwitchDelay\*(C'\fR option says how long +to wait before a change of workspace occurs. +.PP +To move an application window to a different workspace one can use a +keyboard shortcut. Another option is to select the \fIMove To\fR submenu +in the window menu of the window frame. +.SS "DRAG AND DROP" +.IX Subsection "DRAG AND DROP" +The task bar supports drag and drop operations. When a drag +is in progress, the destination window can be activated by +hovering the drag icon over the task button for that window. +Alternatively, the current workspace can be changed by +hovering the drag icon over the desired workspace button. +When edge switching is enabled, the current workspace can +also be changed by bringing the drag icon to the screen edge. +.SS "ADDRESS BAR" +.IX Subsection "ADDRESS BAR" +If \fBEnableAddressBar\fR=1 then \fBKeySysAddressBar\fR=\f(CW\*(C`Alt+Ctrl+Space\*(C'\fR +activates the address bar in the task bar. +If \fBShowAddressBar\fR=1 it is always shown. This is a command-line in +the task bar where a shell command can be typed. +Pressing \f(CW\*(C`Enter\*(C'\fR will execute the command. +\&\fBAddressBarCommand\fR=\f(CW\*(C`/bin/sh\*(C'\fR will be used to execute the command. +On \f(CW\*(C`Control+Enter\*(C'\fR the command is executed in a terminal +as given by \fBTerminalCommand\fR. +The address bar maintains a history that is navigable by the \fIUp\fR +and \fIDown\fR keys. +It supports command completion using \f(CW\*(C`Tab\*(C'\fR or \f(CW\*(C`Ctrl+I\*(C'\fR. +A rich set of editing operations is supported, +including cut\-/copy\-/paste\-operations. +.SS "WINDOW LIST" +.IX Subsection "WINDOW LIST" +The window list window shows a list of all workspaces. For each +workspace it shows the window titles of the windows that are mapped +on it. The bottom entry reads \f(CW\*(C`All Workspaces\*(C'\fR. It holds the sticky +windows. These windows are mapped in all workspaces. +.PP +The window list window is normally hidden. Choose one of the following +four methods to make it visible: +.IP \(bu 4 +Select the bottom window list menu entry. +.IP \(bu 4 +Press the \f(CW\*(C`KeySysWindowList=Ctrl+Alt+Esc\*(C'\fR key. +.IP \(bu 4 +Press the right Windows key if \f(CW\*(C`Win95Keys=1\*(C'\fR +.IP \(bu 4 +Press the \f(CW\*(C`DesktopWinListButton=2\*(C'\fR mouse button in the root window. +.IP \(bu 4 +Press the middle mouse button in a workspace button on the task bar. +.PP +A single-click on a window entry selects it. A group of windows can +be selected by \f(CW\*(C`Shift+Pointer_Button1\*(C'\fR or by dragging with the left +mouse button. Use \f(CW\*(C`Ctrl+Pointer_Button1\*(C'\fR to individually select +windows in a multi-selection. A right mouse click over a selection +will popup the system menu for this selection. To close the selected +windows, press \f(CW\*(C`Delete\*(C'\fR. Press \f(CW\*(C`Shift+Delete\*(C'\fR to forcefully kill them. +Right mouse click below the sticky windows for a menu with window +arranging actions. +.PP +Double-click on a workspace to switch to it. Double-click on a window +to activate it. Or navigate by arrow keys and press Enter. +The space bar toggles a selection of a window. \f(CW\*(C`Ctrl+a\*(C'\fR and \f(CW\*(C`Ctrl+/\*(C'\fR +will select the entire list of windows. \f(CW\*(C`Ctrl+\e\e\*(C'\fR deselects everything. +Press the first letter of a window title to navigate to it and select +it. If titles of multiple windows start with the same letter then +repeatedly pressing the first letter cycles over those windows. +\&\f(CW\*(C`Home\*(C'\fR selects the first entry and \f(CW\*(C`End\*(C'\fR the last. \f(CW\*(C`PageUp\*(C'\fR and +\&\f(CW\*(C`PageDown\*(C'\fR move up or down by ten entries. Combine this with the +\&\f(CW\*(C`Shift\*(C'\fR key to extend a selection over the range of motion. +.SS "SYSTEM DIALOG" +.IX Subsection "SYSTEM DIALOG" +The system dialog offers quick access to a set of general controls. +It can lock the screen, suspend the system, logout or cancel a pending +logout, reboot the system, shutdown the system, show the window list, +restart icewm, show the about dialog, reload the winoptions file or +the keys file. It is activated by \fBKeySysDialog\fR=\f(CW\*(C`Ctrl+Alt+Del\*(C'\fR. +To cancel it, hit the Escape key. +.SS "MAILBOX MONITORING" +.IX Subsection "MAILBOX MONITORING" +The task bar can show one or more icons to reflect the status of a +mailbox. The mailbox can be a local file or a remote POP or IMAP +account. For this a couple of options must be set. First, +\&\fITaskBarShowMailboxStatus\fR must be enabled, which it is by default. +Then the location of the mailbox must be set. Icewm first looks for +\&\fIMailBoxPath\fR in preferences. If this is unset, it looks at the +environment variables \f(CW\*(C`MAILPATH\*(C'\fR and \f(CW\*(C`MAIL\*(C'\fR. \fIMailBoxPath\fR may +contain a space-separated list of mailboxes, while \f(CW\*(C`MAILPATH\*(C'\fR may +contain a colon-separated list of mailboxes. If a mailbox starts +with a slash \f(CW\*(C`/\*(C'\fR, then it is a local file, otherwise a URL. +These are six examples of possible mailboxes: +.PP +.Vb 6 +\& file:///var/spool/mail/captnmark +\& file:///home/captnmark/Maildir/ +\& pop3://markus:%2f%40%3a@maol.ch/ +\& pop3s://markus:password@pop.gmail.com/ +\& imap://mathias@localhost/INBOX.Maillisten.icewm\-user +\& imaps://mathias:password@imap.gmail.com/INBOX +.Ve +.PP +The POP3S and IMAPS schemes use \f(CW\*(C`openssl\*(C'\fR for TLS/SSL encryption. +Note that for IceWM to access Gmail you must first configure +your Gmail account to enable POP3 or IMAP access. +Make sure you have secure file permissions on your IceWM +preferences file and the directory that contains it. +.PP +Reserved characters in the password, like \fIslash\fR, \fIat\fR and \fIcolon\fR +can be specified using escape sequences with a hexadecimal encoding +like \f(CW%2f\fR for the slash or \f(CW%40\fR for the at sign. +For example, to hex-encode \f(CW\*(C`!p@a%s&s~\*(C'\fR use this Perl snippet: +.PP +.Vb 2 +\& perl \-e \*(Aqforeach(split("", $ARGV[0])) { printf "%%%02x", ord($_); }; +\& print "\en";\*(Aq \*(Aq!p@a%s&s~\*(Aq +.Ve +.PP +Which will print: +.PP +.Vb 1 +\& %21%40%23%24%25%5e%26%2a%7e +.Ve +.PP +This is the hex-encoded password. However, it is unwise to store a +password in your preferences. Consider a wallet extension for IceWM. +.PP +IceWM will check a mailbox periodically. The period in seconds can +be set by the \fIMailCheckDelay\fR option, which is 30 seconds by default. +.PP +Whenever new mail arrives, the mailbox icon will be highlighted. +The color will indicate if the mail has been read or not. Hovering +the mouse over the mailbox icon will show a tooltip with more details. +A command can be also be run on new mail. Set the \fINewMailCommand\fR +option. Its environment will have these variables set by IceWM: +.IP ICEWM_MAILBOX 4 +.IX Item "ICEWM_MAILBOX" +The mailbox index number of \fIMailBoxPath\fR starting from 1. +.IP ICEWM_COUNT 4 +.IX Item "ICEWM_COUNT" +The total number of messages in this mailbox. +.IP ICEWM_UNREAD 4 +.IX Item "ICEWM_UNREAD" +The number of unread messages in this mailbox. +.SS "KEYBOARD LAYOUT SWITCHING" +.IX Subsection "KEYBOARD LAYOUT SWITCHING" +To control keyboard layouts on the task bar, define in \fIpreferences\fR +the option \fBKeyboardLayouts\fR to a comma-separated list of your +preferred keyboard layouts. For example: +.PP +.Vb 1 +\& KeyboardLayouts="de","fr","jp" +.Ve +.PP +A keyboard layout can simply be a name. Usually this is a two-letter +country code. See the directory \fI/usr/share/X11/xkb/symbols\fR for +a list of available keyboard layouts for your system. If it is +enclosed in double quotes, it can also be a space-separated list of +command-line arguments to an invocation of the \f(CW\*(C`setxkbmap\*(C'\fR program. +.PP +The first layout is the default. It will be installed when icewm starts. +The task bar will show the current keyboard layout. If an icon can +be found for the first two letters of the layout, then that icon +will be shown. Otherwise the first two letters of the name of the +layout will be shown. +.PP +Click on the current keyboard layout to cycle through all the +available keyboard layouts, or use the \fBKeySysKeyboardNext\fR key. +Click with the right mouse button to open a menu of all available +keyboard layouts. +.PP +It is also possible to configure a default keyboard layout for +each program individually in the \fBicewm\-winoptions\fR\|(5) file. +Whenever such a program receives input focus, icewm will install +this configured keyboard layout automatically. The keyboard status +on the task bar will be updated to reflect this. +.PP +Please note that for keyboard layout switching to work, the +\&\f(CW\*(C`setxkbmap\*(C'\fR program must be installed. To see your current +keyboard layout settings, do \f(CW\*(C`setxkbmap \-query\*(C'\fR. +.SS "KEYBOARD SHORTCUTS" +.IX Subsection "KEYBOARD SHORTCUTS" +\&\fBicewm\fR supports a large number of hotkeys to activate some behaviour +with a single key combination. These are all configurable in the +\&\fIpreferences\fR file. Here we give their preferences name, followed by +their default value in double quotes, and a short descriptions of their +effect. +.PP +Note that all use one or more key modifiers. Icewm supports the +following modifiers: Alt, AltGr, Ctrl, Hyper, Meta, Shift, Super. +Setting \fBModSuperIsCtrlAlt=1\fR makes the Super modifier an alias +for Ctrl+Alt. +.ie n .IP "\fBKeyWinRaise\fR=""Alt+F1""" 4 +.el .IP \fBKeyWinRaise\fR=\f(CWAlt+F1\fR 4 +.IX Item "KeyWinRaise=Alt+F1" +Raises the window that currently has input focus. +.ie n .IP "\fBKeyWinOccupyAll\fR=""Alt+F2""" 4 +.el .IP \fBKeyWinOccupyAll\fR=\f(CWAlt+F2\fR 4 +.IX Item "KeyWinOccupyAll=Alt+F2" +Makes the active window occupy all workspaces. +.ie n .IP "\fBKeyWinLower\fR=""Alt+F3""" 4 +.el .IP \fBKeyWinLower\fR=\f(CWAlt+F3\fR 4 +.IX Item "KeyWinLower=Alt+F3" +Lowers the window that currently has input focus. +.ie n .IP "\fBKeyWinClose\fR=""Alt+F4""" 4 +.el .IP \fBKeyWinClose\fR=\f(CWAlt+F4\fR 4 +.IX Item "KeyWinClose=Alt+F4" +Closes the active window. +.ie n .IP "\fBKeyWinRestore\fR=""Alt+F5""" 4 +.el .IP \fBKeyWinRestore\fR=\f(CWAlt+F5\fR 4 +.IX Item "KeyWinRestore=Alt+F5" +Restores the active window to its visible state. +.ie n .IP "\fBKeyWinNext\fR=""Alt+F6""" 4 +.el .IP \fBKeyWinNext\fR=\f(CWAlt+F6\fR 4 +.IX Item "KeyWinNext=Alt+F6" +Switches focus to the next window. +.ie n .IP "\fBKeyWinPrev\fR=""Alt+Shift+F6""" 4 +.el .IP \fBKeyWinPrev\fR=\f(CWAlt+Shift+F6\fR 4 +.IX Item "KeyWinPrev=Alt+Shift+F6" +Switches focus to the previous window. +.ie n .IP "\fBKeyWinMove\fR=""Alt+F7""" 4 +.el .IP \fBKeyWinMove\fR=\f(CWAlt+F7\fR 4 +.IX Item "KeyWinMove=Alt+F7" +Starts movement of the active window. +.ie n .IP "\fBKeyWinSize\fR=""Alt+F8""" 4 +.el .IP \fBKeyWinSize\fR=\f(CWAlt+F8\fR 4 +.IX Item "KeyWinSize=Alt+F8" +Starts resizing of the active window. +.ie n .IP "\fBKeyWinMinimize\fR=""Alt+F9""" 4 +.el .IP \fBKeyWinMinimize\fR=\f(CWAlt+F9\fR 4 +.IX Item "KeyWinMinimize=Alt+F9" +Iconifies the active window. +.ie n .IP "\fBKeyWinMaximize\fR=""Alt+F10""" 4 +.el .IP \fBKeyWinMaximize\fR=\f(CWAlt+F10\fR 4 +.IX Item "KeyWinMaximize=Alt+F10" +Maximizes the active window with borders. +.ie n .IP "\fBKeyWinMaximizeVert\fR=""Alt+Shift+F10""" 4 +.el .IP \fBKeyWinMaximizeVert\fR=\f(CWAlt+Shift+F10\fR 4 +.IX Item "KeyWinMaximizeVert=Alt+Shift+F10" +Maximizes the active window vertically. +.ie n .IP "\fBKeyWinMaximizeHoriz\fR=""undefined""" 4 +.el .IP \fBKeyWinMaximizeHoriz\fR=\f(CWundefined\fR 4 +.IX Item "KeyWinMaximizeHoriz=undefined" +Maximizes the active window horizontally. +.ie n .IP "\fBKeyWinFullscreen\fR=""Alt+F11""" 4 +.el .IP \fBKeyWinFullscreen\fR=\f(CWAlt+F11\fR 4 +.IX Item "KeyWinFullscreen=Alt+F11" +Maximizes the active window without borders. +.ie n .IP "\fBKeyWinRollup\fR=""Alt+F12""" 4 +.el .IP \fBKeyWinRollup\fR=\f(CWAlt+F12\fR 4 +.IX Item "KeyWinRollup=Alt+F12" +Rolls up the active window. +.ie n .IP "\fBKeyWinHide\fR=""Alt+Shift+F12""" 4 +.el .IP \fBKeyWinHide\fR=\f(CWAlt+Shift+F12\fR 4 +.IX Item "KeyWinHide=Alt+Shift+F12" +Hides the active window. +.ie n .IP "\fBKeyWinMenu\fR=""Alt+Space""" 4 +.el .IP \fBKeyWinMenu\fR=\f(CWAlt+Space\fR 4 +.IX Item "KeyWinMenu=Alt+Space" +Posts the window menu. +.ie n .IP "\fBKeyWinArrangeNW\fR=""Ctrl+Alt+KP_7""" 4 +.el .IP \fBKeyWinArrangeNW\fR=\f(CWCtrl+Alt+KP_7\fR 4 +.IX Item "KeyWinArrangeNW=Ctrl+Alt+KP_7" +Moves the active window to the top left corner of the screen. +.ie n .IP "\fBKeyWinArrangeN\fR=""Ctrl+Alt+KP_8""" 4 +.el .IP \fBKeyWinArrangeN\fR=\f(CWCtrl+Alt+KP_8\fR 4 +.IX Item "KeyWinArrangeN=Ctrl+Alt+KP_8" +Moves the active window to the top middle of the screen. +.ie n .IP "\fBKeyWinArrangeNE\fR=""Ctrl+Alt+KP_9""" 4 +.el .IP \fBKeyWinArrangeNE\fR=\f(CWCtrl+Alt+KP_9\fR 4 +.IX Item "KeyWinArrangeNE=Ctrl+Alt+KP_9" +Moves the active window to the top right of the screen. +.ie n .IP "\fBKeyWinArrangeE\fR=""Ctrl+Alt+KP_6""" 4 +.el .IP \fBKeyWinArrangeE\fR=\f(CWCtrl+Alt+KP_6\fR 4 +.IX Item "KeyWinArrangeE=Ctrl+Alt+KP_6" +Moves the active window to the middle right of the screen. +.ie n .IP "\fBKeyWinArrangeSE\fR=""Ctrl+Alt+KP_3""" 4 +.el .IP \fBKeyWinArrangeSE\fR=\f(CWCtrl+Alt+KP_3\fR 4 +.IX Item "KeyWinArrangeSE=Ctrl+Alt+KP_3" +Moves the active window to the bottom right of the screen. +.ie n .IP "\fBKeyWinArrangeS\fR=""Ctrl+Alt+KP_2""" 4 +.el .IP \fBKeyWinArrangeS\fR=\f(CWCtrl+Alt+KP_2\fR 4 +.IX Item "KeyWinArrangeS=Ctrl+Alt+KP_2" +Moves the active window to the bottom middle of the screen. +.ie n .IP "\fBKeyWinArrangeSW\fR=""Ctrl+Alt+KP_1""" 4 +.el .IP \fBKeyWinArrangeSW\fR=\f(CWCtrl+Alt+KP_1\fR 4 +.IX Item "KeyWinArrangeSW=Ctrl+Alt+KP_1" +Moves the active window to the bottom left of the screen. +.ie n .IP "\fBKeyWinArrangeW\fR=""Ctrl+Alt+KP_4""" 4 +.el .IP \fBKeyWinArrangeW\fR=\f(CWCtrl+Alt+KP_4\fR 4 +.IX Item "KeyWinArrangeW=Ctrl+Alt+KP_4" +Moves the active window to the middle left of the screen. +.ie n .IP "\fBKeyWinArrangeC\fR=""Ctrl+Alt+KP_5""" 4 +.el .IP \fBKeyWinArrangeC\fR=\f(CWCtrl+Alt+KP_5\fR 4 +.IX Item "KeyWinArrangeC=Ctrl+Alt+KP_5" +Moves the active window to the center of the screen. +.IP "\fBKeyWinTileLeft\fR=""""" 4 +.IX Item "KeyWinTileLeft=""""" +Let the active window occupy the left half of the screen. +.IP "\fBKeyWinTileRight\fR=""""" 4 +.IX Item "KeyWinTileRight=""""" +Let the active window occupy the right half of the screen. +.IP "\fBKeyWinTileTop\fR=""""" 4 +.IX Item "KeyWinTileTop=""""" +Let the active window occupy the top half of the screen. +.IP "\fBKeyWinTileBottom\fR=""""" 4 +.IX Item "KeyWinTileBottom=""""" +Let the active window occupy the bottom half of the screen. +.IP "\fBKeyWinTileTopLeft\fR=""""" 4 +.IX Item "KeyWinTileTopLeft=""""" +Let the active window occupy the top left quarter of the screen. +.IP "\fBKeyWinTileTopRight\fR=""""" 4 +.IX Item "KeyWinTileTopRight=""""" +Let the active window occupy the top right quarter of the screen. +.IP "\fBKeyWinTileBottomLeft\fR=""""" 4 +.IX Item "KeyWinTileBottomLeft=""""" +Let the active window occupy the bottom left quarter of the screen. +.IP "\fBKeyWinTileBottomRight\fR=""""" 4 +.IX Item "KeyWinTileBottomRight=""""" +Let the active window occupy the bottom right quarter of the screen. +.IP "\fBKeyWinTileCenter\fR=""""" 4 +.IX Item "KeyWinTileCenter=""""" +Let the active window occupy the center quarter of the screen. +.ie n .IP "\fBKeyWinSmartPlace\fR=""Ctrl+Alt+Shift+KP_5""" 4 +.el .IP \fBKeyWinSmartPlace\fR=\f(CWCtrl+Alt+Shift+KP_5\fR 4 +.IX Item "KeyWinSmartPlace=Ctrl+Alt+Shift+KP_5" +Smart place the active window. +.ie n .IP "\fBKeySysWinMenu\fR=""Shift+Esc""" 4 +.el .IP \fBKeySysWinMenu\fR=\f(CWShift+Esc\fR 4 +.IX Item "KeySysWinMenu=Shift+Esc" +Posts the system window menu. +.ie n .IP "\fBKeySysWinNext\fR=""Alt+Esc""" 4 +.el .IP \fBKeySysWinNext\fR=\f(CWAlt+Esc\fR 4 +.IX Item "KeySysWinNext=Alt+Esc" +Give focus to the next window and raise it. +.ie n .IP "\fBKeySysWinPrev\fR=""Alt+Shift+Esc""" 4 +.el .IP \fBKeySysWinPrev\fR=\f(CWAlt+Shift+Esc\fR 4 +.IX Item "KeySysWinPrev=Alt+Shift+Esc" +Give focus to the previous window and raise it. +.ie n .IP "\fBKeySysDialog\fR=""Ctrl+Alt+Del""" 4 +.el .IP \fBKeySysDialog\fR=\f(CWCtrl+Alt+Del\fR 4 +.IX Item "KeySysDialog=Ctrl+Alt+Del" +Opens the IceWM system dialog in the center of the screen. +.ie n .IP "\fBKeySysMenu\fR=""Ctrl+Esc""" 4 +.el .IP \fBKeySysMenu\fR=\f(CWCtrl+Esc\fR 4 +.IX Item "KeySysMenu=Ctrl+Esc" +Activates the IceWM root menu in the lower left corner. +.ie n .IP "\fBKeySysWindowList\fR=""Alt+Ctrl+Esc""" 4 +.el .IP \fBKeySysWindowList\fR=\f(CWAlt+Ctrl+Esc\fR 4 +.IX Item "KeySysWindowList=Alt+Ctrl+Esc" +Opens the IceWM system window list in the center of the screen. +.ie n .IP "\fBKeySysAddressBar\fR=""Alt+Ctrl+Space""" 4 +.el .IP \fBKeySysAddressBar\fR=\f(CWAlt+Ctrl+Space\fR 4 +.IX Item "KeySysAddressBar=Alt+Ctrl+Space" +Opens the address bar in the task bar where a command can be typed. +.ie n .IP "\fBKeySysWorkspacePrev\fR=""Alt+Ctrl+Left""" 4 +.el .IP \fBKeySysWorkspacePrev\fR=\f(CWAlt+Ctrl+Left\fR 4 +.IX Item "KeySysWorkspacePrev=Alt+Ctrl+Left" +Goes one workspace to the left. +.ie n .IP "\fBKeySysWorkspaceNext\fR=""Alt+Ctrl+Right""" 4 +.el .IP \fBKeySysWorkspaceNext\fR=\f(CWAlt+Ctrl+Right\fR 4 +.IX Item "KeySysWorkspaceNext=Alt+Ctrl+Right" +Goes one workspace to the right. +.ie n .IP "\fBKeySysWorkspaceLast\fR=""Alt+Ctrl+Down""" 4 +.el .IP \fBKeySysWorkspaceLast\fR=\f(CWAlt+Ctrl+Down\fR 4 +.IX Item "KeySysWorkspaceLast=Alt+Ctrl+Down" +Goes to the previous workspace. +.ie n .IP "\fBKeySysWorkspacePrevTakeWin\fR=""Alt+Ctrl+Shift+Left""" 4 +.el .IP \fBKeySysWorkspacePrevTakeWin\fR=\f(CWAlt+Ctrl+Shift+Left\fR 4 +.IX Item "KeySysWorkspacePrevTakeWin=Alt+Ctrl+Shift+Left" +Takes the active window one workspace to the left. +.ie n .IP "\fBKeySysWorkspaceNextTakeWin\fR=""Alt+Ctrl+Shift+Right""" 4 +.el .IP \fBKeySysWorkspaceNextTakeWin\fR=\f(CWAlt+Ctrl+Shift+Right\fR 4 +.IX Item "KeySysWorkspaceNextTakeWin=Alt+Ctrl+Shift+Right" +Takes the active window one workspace to the right. +.ie n .IP "\fBKeySysWorkspaceLastTakeWin\fR=""Alt+Ctrl+Shift+Down""" 4 +.el .IP \fBKeySysWorkspaceLastTakeWin\fR=\f(CWAlt+Ctrl+Shift+Down\fR 4 +.IX Item "KeySysWorkspaceLastTakeWin=Alt+Ctrl+Shift+Down" +Takes the active window to the previous workspace. +.ie n .IP "\fBKeySysWorkspace1\fR=""Alt+Ctrl+1""" 4 +.el .IP \fBKeySysWorkspace1\fR=\f(CWAlt+Ctrl+1\fR 4 +.IX Item "KeySysWorkspace1=Alt+Ctrl+1" +Goes to workspace 1. +.ie n .IP "\fBKeySysWorkspace2\fR=""Alt+Ctrl+2""" 4 +.el .IP \fBKeySysWorkspace2\fR=\f(CWAlt+Ctrl+2\fR 4 +.IX Item "KeySysWorkspace2=Alt+Ctrl+2" +Goes to workspace 2. +.ie n .IP "\fBKeySysWorkspace3\fR=""Alt+Ctrl+3""" 4 +.el .IP \fBKeySysWorkspace3\fR=\f(CWAlt+Ctrl+3\fR 4 +.IX Item "KeySysWorkspace3=Alt+Ctrl+3" +Goes to workspace 3. +.ie n .IP "\fBKeySysWorkspace4\fR=""Alt+Ctrl+4""" 4 +.el .IP \fBKeySysWorkspace4\fR=\f(CWAlt+Ctrl+4\fR 4 +.IX Item "KeySysWorkspace4=Alt+Ctrl+4" +Goes to workspace 4. +.ie n .IP "\fBKeySysWorkspace5\fR=""Alt+Ctrl+5""" 4 +.el .IP \fBKeySysWorkspace5\fR=\f(CWAlt+Ctrl+5\fR 4 +.IX Item "KeySysWorkspace5=Alt+Ctrl+5" +Goes to workspace 5. +.ie n .IP "\fBKeySysWorkspace6\fR=""Alt+Ctrl+6""" 4 +.el .IP \fBKeySysWorkspace6\fR=\f(CWAlt+Ctrl+6\fR 4 +.IX Item "KeySysWorkspace6=Alt+Ctrl+6" +Goes to workspace 6. +.ie n .IP "\fBKeySysWorkspace7\fR=""Alt+Ctrl+7""" 4 +.el .IP \fBKeySysWorkspace7\fR=\f(CWAlt+Ctrl+7\fR 4 +.IX Item "KeySysWorkspace7=Alt+Ctrl+7" +Goes to workspace 7. +.ie n .IP "\fBKeySysWorkspace8\fR=""Alt+Ctrl+8""" 4 +.el .IP \fBKeySysWorkspace8\fR=\f(CWAlt+Ctrl+8\fR 4 +.IX Item "KeySysWorkspace8=Alt+Ctrl+8" +Goes to workspace 8. +.ie n .IP "\fBKeySysWorkspace9\fR=""Alt+Ctrl+9""" 4 +.el .IP \fBKeySysWorkspace9\fR=\f(CWAlt+Ctrl+9\fR 4 +.IX Item "KeySysWorkspace9=Alt+Ctrl+9" +Goes to workspace 9. +.ie n .IP "\fBKeySysWorkspace10\fR=""Alt+Ctrl+0""" 4 +.el .IP \fBKeySysWorkspace10\fR=\f(CWAlt+Ctrl+0\fR 4 +.IX Item "KeySysWorkspace10=Alt+Ctrl+0" +Goes to workspace 10. +.ie n .IP "\fBKeySysWorkspace11\fR=""Alt+Ctrl+minus""" 4 +.el .IP \fBKeySysWorkspace11\fR=\f(CWAlt+Ctrl+minus\fR 4 +.IX Item "KeySysWorkspace11=Alt+Ctrl+minus" +Goes to workspace 11. +.ie n .IP "\fBKeySysWorkspace12\fR=""Alt+Ctrl+equal""" 4 +.el .IP \fBKeySysWorkspace12\fR=\f(CWAlt+Ctrl+equal\fR 4 +.IX Item "KeySysWorkspace12=Alt+Ctrl+equal" +Goes to workspace 12. +.ie n .IP "\fBKeySysWorkspace1TakeWin\fR=""Alt+Ctrl+Shift+1""" 4 +.el .IP \fBKeySysWorkspace1TakeWin\fR=\f(CWAlt+Ctrl+Shift+1\fR 4 +.IX Item "KeySysWorkspace1TakeWin=Alt+Ctrl+Shift+1" +Takes the active window to workspace 1. +.ie n .IP "\fBKeySysWorkspace2TakeWin\fR=""Alt+Ctrl+Shift+2""" 4 +.el .IP \fBKeySysWorkspace2TakeWin\fR=\f(CWAlt+Ctrl+Shift+2\fR 4 +.IX Item "KeySysWorkspace2TakeWin=Alt+Ctrl+Shift+2" +Takes the active window to workspace 2. +.ie n .IP "\fBKeySysWorkspace3TakeWin\fR=""Alt+Ctrl+Shift+3""" 4 +.el .IP \fBKeySysWorkspace3TakeWin\fR=\f(CWAlt+Ctrl+Shift+3\fR 4 +.IX Item "KeySysWorkspace3TakeWin=Alt+Ctrl+Shift+3" +Takes the active window to workspace 3. +.ie n .IP "\fBKeySysWorkspace4TakeWin\fR=""Alt+Ctrl+Shift+4""" 4 +.el .IP \fBKeySysWorkspace4TakeWin\fR=\f(CWAlt+Ctrl+Shift+4\fR 4 +.IX Item "KeySysWorkspace4TakeWin=Alt+Ctrl+Shift+4" +Takes the active window to workspace 4. +.ie n .IP "\fBKeySysWorkspace5TakeWin\fR=""Alt+Ctrl+Shift+5""" 4 +.el .IP \fBKeySysWorkspace5TakeWin\fR=\f(CWAlt+Ctrl+Shift+5\fR 4 +.IX Item "KeySysWorkspace5TakeWin=Alt+Ctrl+Shift+5" +Takes the active window to workspace 5. +.ie n .IP "\fBKeySysWorkspace6TakeWin\fR=""Alt+Ctrl+Shift+6""" 4 +.el .IP \fBKeySysWorkspace6TakeWin\fR=\f(CWAlt+Ctrl+Shift+6\fR 4 +.IX Item "KeySysWorkspace6TakeWin=Alt+Ctrl+Shift+6" +Takes the active window to workspace 6. +.ie n .IP "\fBKeySysWorkspace7TakeWin\fR=""Alt+Ctrl+Shift+7""" 4 +.el .IP \fBKeySysWorkspace7TakeWin\fR=\f(CWAlt+Ctrl+Shift+7\fR 4 +.IX Item "KeySysWorkspace7TakeWin=Alt+Ctrl+Shift+7" +Takes the active window to workspace 7. +.ie n .IP "\fBKeySysWorkspace8TakeWin\fR=""Alt+Ctrl+Shift+8""" 4 +.el .IP \fBKeySysWorkspace8TakeWin\fR=\f(CWAlt+Ctrl+Shift+8\fR 4 +.IX Item "KeySysWorkspace8TakeWin=Alt+Ctrl+Shift+8" +Takes the active window to workspace 8. +.ie n .IP "\fBKeySysWorkspace9TakeWin\fR=""Alt+Ctrl+Shift+9""" 4 +.el .IP \fBKeySysWorkspace9TakeWin\fR=\f(CWAlt+Ctrl+Shift+9\fR 4 +.IX Item "KeySysWorkspace9TakeWin=Alt+Ctrl+Shift+9" +Takes the active window to workspace 9. +.ie n .IP "\fBKeySysWorkspace10TakeWin\fR=""Alt+Ctrl+Shift+0""" 4 +.el .IP \fBKeySysWorkspace10TakeWin\fR=\f(CWAlt+Ctrl+Shift+0\fR 4 +.IX Item "KeySysWorkspace10TakeWin=Alt+Ctrl+Shift+0" +Takes the active window to workspace 10. +.ie n .IP "\fBKeySysWorkspace11TakeWin\fR=""Alt+Ctrl+Shift+minus""" 4 +.el .IP \fBKeySysWorkspace11TakeWin\fR=\f(CWAlt+Ctrl+Shift+minus\fR 4 +.IX Item "KeySysWorkspace11TakeWin=Alt+Ctrl+Shift+minus" +Takes the active window to workspace 11. +.ie n .IP "\fBKeySysWorkspace12TakeWin\fR=""Alt+Ctrl+Shift+equal""" 4 +.el .IP \fBKeySysWorkspace12TakeWin\fR=\f(CWAlt+Ctrl+Shift+equal\fR 4 +.IX Item "KeySysWorkspace12TakeWin=Alt+Ctrl+Shift+equal" +Takes the active window to workspace 12. +.ie n .IP "\fBKeySysTileVertical\fR=""Alt+Shift+F2""" 4 +.el .IP \fBKeySysTileVertical\fR=\f(CWAlt+Shift+F2\fR 4 +.IX Item "KeySysTileVertical=Alt+Shift+F2" +Tiles all windows from left to right maximized vertically. +.ie n .IP "\fBKeySysTileHorizontal\fR=""Alt+Shift+F3""" 4 +.el .IP \fBKeySysTileHorizontal\fR=\f(CWAlt+Shift+F3\fR 4 +.IX Item "KeySysTileHorizontal=Alt+Shift+F3" +Tiles all windows from top to bottom maximized horizontally. +.ie n .IP "\fBKeySysCascade\fR=""Alt+Shift+F4""" 4 +.el .IP \fBKeySysCascade\fR=\f(CWAlt+Shift+F4\fR 4 +.IX Item "KeySysCascade=Alt+Shift+F4" +Makes a horizontal cascade of all windows which are maximized vertically. +.ie n .IP "\fBKeySysArrange\fR=""Alt+Shift+F5""" 4 +.el .IP \fBKeySysArrange\fR=\f(CWAlt+Shift+F5\fR 4 +.IX Item "KeySysArrange=Alt+Shift+F5" +Rearranges the windows. +.ie n .IP "\fBKeySysUndoArrange\fR=""Alt+Shift+F7""" 4 +.el .IP \fBKeySysUndoArrange\fR=\f(CWAlt+Shift+F7\fR 4 +.IX Item "KeySysUndoArrange=Alt+Shift+F7" +Undoes arrangement. +.ie n .IP "\fBKeySysArrangeIcons\fR=""Alt+Shift+F8""" 4 +.el .IP \fBKeySysArrangeIcons\fR=\f(CWAlt+Shift+F8\fR 4 +.IX Item "KeySysArrangeIcons=Alt+Shift+F8" +Rearranges icons. +.ie n .IP "\fBKeySysMinimizeAll\fR=""Alt+Shift+F9""" 4 +.el .IP \fBKeySysMinimizeAll\fR=\f(CWAlt+Shift+F9\fR 4 +.IX Item "KeySysMinimizeAll=Alt+Shift+F9" +Minimizes all windows. +.ie n .IP "\fBKeySysHideAll\fR=""Alt+Shift+F11""" 4 +.el .IP \fBKeySysHideAll\fR=\f(CWAlt+Shift+F11\fR 4 +.IX Item "KeySysHideAll=Alt+Shift+F11" +Hides all windows. +.ie n .IP "\fBKeySysShowDesktop\fR=""Alt+Ctrl+d""" 4 +.el .IP \fBKeySysShowDesktop\fR=\f(CWAlt+Ctrl+d\fR 4 +.IX Item "KeySysShowDesktop=Alt+Ctrl+d" +Unmaps all windows to show the desktop. +.ie n .IP "\fBKeySysCollapseTaskBar\fR=""Alt+Ctrl+h""" 4 +.el .IP \fBKeySysCollapseTaskBar\fR=\f(CWAlt+Ctrl+h\fR 4 +.IX Item "KeySysCollapseTaskBar=Alt+Ctrl+h" +Hides the task bar. +.ie n .IP "\fBKeyTaskBarSwitchNext\fR=""undefined""" 4 +.el .IP \fBKeyTaskBarSwitchNext\fR=\f(CWundefined\fR 4 +.IX Item "KeyTaskBarSwitchNext=undefined" +Switches to the next window in the task bar. +.ie n .IP "\fBKeyTaskBarSwitchPrev\fR=""undefined""" 4 +.el .IP \fBKeyTaskBarSwitchPrev\fR=\f(CWundefined\fR 4 +.IX Item "KeyTaskBarSwitchPrev=undefined" +Switches to the previous window in the task bar. +.ie n .IP "\fBKeyTaskBarMoveNext\fR=""undefined""" 4 +.el .IP \fBKeyTaskBarMoveNext\fR=\f(CWundefined\fR 4 +.IX Item "KeyTaskBarMoveNext=undefined" +Moves the task bar button of the current window +right. +.ie n .IP "\fBKeyTaskBarMovePrev\fR=""undefined""" 4 +.el .IP \fBKeyTaskBarMovePrev\fR=\f(CWundefined\fR 4 +.IX Item "KeyTaskBarMovePrev=undefined" +Moves the task bar button of the current window +left. +.ie n .IP "\fBKeySysWinListMenu\fR=""undefined""" 4 +.el .IP \fBKeySysWinListMenu\fR=\f(CWundefined\fR 4 +.IX Item "KeySysWinListMenu=undefined" +Shows the window list menu. +.ie n .IP "\fBKeySysKeyboardNext\fR=""undefined""" 4 +.el .IP \fBKeySysKeyboardNext\fR=\f(CWundefined\fR 4 +.IX Item "KeySysKeyboardNext=undefined" +Switch to the next keyboard layout in the KeyboardLayouts list. +.ie n .IP "\fBKeySysSwitchNext\fR=""Alt+Tab""" 4 +.el .IP \fBKeySysSwitchNext\fR=\f(CWAlt+Tab\fR 4 +.IX Item "KeySysSwitchNext=Alt+Tab" +Opens the \f(CW\*(C`QuickSwitch\*(C'\fR popup (see "INPUT FOCUS") +and/or moves the selector in the \f(CW\*(C`QuickSwitch\*(C'\fR popup. +.ie n .IP "\fBKeySysSwitchLast\fR=""Alt+Shift+Tab""" 4 +.el .IP \fBKeySysSwitchLast\fR=\f(CWAlt+Shift+Tab\fR 4 +.IX Item "KeySysSwitchLast=Alt+Shift+Tab" +Works like \f(CW\*(C`KeySysSwitchNext\*(C'\fR but moving in the +opposite direction. +.ie n .IP "\fBKeySysSwitchClass\fR=""Alt+grave""" 4 +.el .IP \fBKeySysSwitchClass\fR=\f(CWAlt+grave\fR 4 +.IX Item "KeySysSwitchClass=Alt+grave" +Is like \f(CW\*(C`KeySysSwitchNext\*(C'\fR but only for windows +with the same WM_CLASS property as the currently focused window. +.SS "MOUSE BINDINGS" +.IX Subsection "MOUSE BINDINGS" +You can control windows by a modified mouse button press: +.ie n .IP "\fBMouseWinMove\fR=""Alt+Pointer_Button1""" 4 +.el .IP \fBMouseWinMove\fR=\f(CWAlt+Pointer_Button1\fR 4 +.IX Item "MouseWinMove=Alt+Pointer_Button1" +Moves the window under the mouse over the screen. +.ie n .IP "\fBMouseWinSize\fR=""Alt+Pointer_Button3""" 4 +.el .IP \fBMouseWinSize\fR=\f(CWAlt+Pointer_Button3\fR 4 +.IX Item "MouseWinSize=Alt+Pointer_Button3" +Resizes the window. Keep the key and button pressed. +To enlarge the window move the mouse button away from the center. To +shrink it move towards the centre. +.ie n .IP "\fBMouseWinRaise\fR=""Ctrl+Alt+Pointer_Button1""" 4 +.el .IP \fBMouseWinRaise\fR=\f(CWCtrl+Alt+Pointer_Button1\fR 4 +.IX Item "MouseWinRaise=Ctrl+Alt+Pointer_Button1" +Raises the window under the mouse. +.ie n .IP "\fBMouseWinLower\fR=""Ctrl+Alt+Pointer_Button1""" 4 +.el .IP \fBMouseWinLower\fR=\f(CWCtrl+Alt+Pointer_Button1\fR 4 +.IX Item "MouseWinLower=Ctrl+Alt+Pointer_Button1" +Lowers the window under the mouse. +If this is equal to \f(CW\*(C`MouseWinRaise\*(C'\fR and the window can be raised +then \f(CW\*(C`MouseWinRaise\*(C'\fR takes preference over \f(CW\*(C`MouseWinLower\*(C'\fR. +.IP "\fBMouseWinTabbing\fR=""Shift+Pointer_Button2""" 4 +.IX Item "MouseWinTabbing=""Shift+Pointer_Button2""" +Mouse binding to create tabs. +Drag the title bar with this button over another title bar. +When they start to flash, release the button to merge the frame tabs. +.PP +The title frame of a window also listens for mouse clicks. Left double +clicking maximizes the window (\f(CW\*(C`TitleBarMaximizeButton=1\*(C'\fR). Press +Shift to only maximize vertically. Press Alt+Shift for horizontally. +Middle double clicking rolls up the window (\f(CW\*(C`TitleBarRollupButton=2\*(C'\fR). +Also press Shift to maximize horizontally. If \fBTitleBarRollupButton\fR +is either 4 or 5 then the scroll wheel controls rolling up or down. +Pressing a mouse button and moving it will move the window. +\&\f(CW\*(C`Alt+Pointer_Button1\*(C'\fR lowers the window. +.PP +When the mouse is on the window frame then a left click raises the +window. Dragging with the left button down resizes the window. +Clicking the right button pops up the context menu. Dragging with the +right button moves the window. +.PP +Clicking on the desktop activates a menu. The middle button shows the +window list (\f(CW\*(C`DesktopWinListButton=2\*(C'\fR). The right button shows the +root menu (\f(CW\*(C`DesktopMenuButton=3\*(C'\fR). If you press \f(CW\*(C`Ctrl+Alt\*(C'\fR then +the mouse wheel will focus all applications in turn. +.SS SIGNALS +.IX Subsection "SIGNALS" +\&\fBicewm\fR supports the following signals: +.IP \fBSIGHUP\fR 4 +.IX Item "SIGHUP" +\&\fBicewm\fR will restart itself. It is a way to reload the configuration. +.IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4 +.IX Item "SIGINT, SIGTERM" +\&\fBicewm\fR will cease to manage application windows and terminate. +.IP \fBSIGQUIT\fR 4 +.IX Item "SIGQUIT" +\&\fBicewm\fR will initiate the logout procedure. If a \f(CW\*(C`LogoutCommand\*(C'\fR +preferences option was configured it will be executed. +.IP \fBSIGUSR2\fR 4 +.IX Item "SIGUSR2" +Toggle the logging of X11 events, if \f(CW\*(C`logevents\*(C'\fR was configured. +.SS "ENVIRONMENT VARIABLES" +.IX Subsection "ENVIRONMENT VARIABLES" +.IP \fBICEWM_PRIVCFG\fR 4 +.IX Item "ICEWM_PRIVCFG" +The directory for user private configuration files. When this +environment variable is not specified, the default directory is +\&\fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm\fR when that directory exists, otherwise the +default value is \fI\fR\f(CI$HOME\fR\fI/.icewm\fR. +.IP \fBDISPLAY\fR 4 +.IX Item "DISPLAY" +The name of the X11 server. See \fBXorg\fR\|(1) or \fBXserver\fR\|(1). This +value can be overridden by the \fB\-\-display\fR option. +.IP "\fBMAILPATH\fR, \fBMAIL\fR" 4 +.IX Item "MAILPATH, MAIL" +Gives the location of your mailbox. If the schema is omitted the local +"file" schema is assumed. This is used by the mailbox applet in the +task bar to show the status of your mailbox. If the \f(CW\*(C`MailBoxPath\*(C'\fR +option in the \fIpreferences\fR file is set, then that one takes +precedence. +.SS FILES +.IX Subsection "FILES" +.SS "CONFIGURATION DIRECTORIES" +.IX Subsection "CONFIGURATION DIRECTORIES" +\&\fBicewm\fR looks for configuration files in the following directories, in +the given order, until it finds one: +.ie n .IP \fR\fI$ICEWM_PRIVCFG\fR\fI/\fR 4 +.el .IP \fR\f(CI$ICEWM_PRIVCFG\fR\fI/\fR 4 +.IX Item "$ICEWM_PRIVCFG/" +Contains user-specific configurations. When \fBICEWM_PRIVCFG\fR is +specified, this directory takes precedence over +\&\fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm\fR and \fI\fR\f(CI$HOME\fR\fI/.icewm\fR. +.ie n .IP \fR\fI$XDG_CONFIG_HOME\fR\fI/icewm/\fR 4 +.el .IP \fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm/\fR 4 +.IX Item "$XDG_CONFIG_HOME/icewm/" +Contains user-specific configurations. When this directory exists it +take precedence over \fR\f(CI$HOME\fR\fI/.icewm\fR. +.ie n .IP \fR\fI$HOME\fR\fI/.icewm/\fR 4 +.el .IP \fR\f(CI$HOME\fR\fI/.icewm/\fR 4 +.IX Item "$HOME/.icewm/" +Contains user-specific configurations. This is the historical default +directory. +.IP \fI/etc/icewm/\fR 4 +.IX Item "/etc/icewm/" +Contains system-wide customized defaults. Please note that your local +installation may have been configured to use a different system +location. The output of \f(CW\*(C`icewm \-\-directories\*(C'\fR will show this location. +.IP \fI/usr/share/icewm/\fR 4 +.IX Item "/usr/share/icewm/" +Default local installation settings. +.SS "CONFIGURATION FILES" +.IX Subsection "CONFIGURATION FILES" +.IP \fIenv\fR 4 +.IX Item "env" +\&\fBicewm\-session\fR\|(1) loads additional environment variables from the file +\&\fIenv\fR. Each line is subjected to POSIX shell expansion by +\&\fBwordexp\fR\|(3). Comment lines starting by a hash-sign (\f(CW\*(C`#\*(C'\fR) are ignored. +\&\fBicewm\-session\fR\|(1) will load those expanded lines that contain a name, +followed by an equals sign, followed by the value (which may be empty). +.Sp +See \fBicewm\-env\fR\|(5). +.IP \fIfocus_mode\fR 4 +.IX Item "focus_mode" +Defines the initial value for \f(CW\*(C`FocusMode\*(C'\fR. Its default value is +\&\f(CW\*(C`FocusMode=1\*(C'\fR (Click-to-focus). This can be changed via the menu. +\&\fBicewm\fR will save the Focus menu choice in this file. +.Sp +See \fBicewm\-focus_mode\fR\|(5). +.IP \fIkeys\fR 4 +.IX Item "keys" +Global keybindings to launch applications, which need not be window +manager related. Each non-empty line starts with the word \f(CW\*(C`key\*(C'\fR. +After one or more spaces follows a double-quoted string of the bound X11 +key combination like \f(CW\*(C`Alt+Ctrl+Shift+X\*(C'\fR. Then after at least one space +follows a shell command-line that will be executed by \fBicewm\fR whenever +this key combination is pressed. For example, the following line +creates a hotkey to reload the \fBicewm\fR configuration: +.Sp +.Vb 1 +\& key "Ctrl+Shift+r" icesh restart +.Ve +.Sp +See \fBicewm\-keys\fR\|(5). +.IP \fImenu\fR 4 +.IX Item "menu" +A menu of applications; usually customized by the user. \fBicewm\fR +provides the \fBicewm\-menu\-fdo\fR\|(1) program to generate a default menu. +Similar programs are \fBxdg_menu\fR\|(1), \fBmmaker\fR\|(1) (MenuMaker), +\&\fBxde\-menu\fR\|(1), \fBxdgmenumaker\fR\|(1). +.Sp +See \fBicewm\-menu\fR\|(5). +.IP \fIpreferences\fR 4 +.IX Item "preferences" +Contains general settings like paths, colors and fonts, but also options +to control the \fBicewm\fR focus behaviour and the applets that are +started in the task bar. The \fBicewm\fR installation will provide a +default \fIpreferences\fR file, which can be copied to the \fBicewm\fR user +configuration directory and modified. +.Sp +See \fBicewm\-preferences\fR\|(5). +.IP \fIprefoverride\fR 4 +.IX Item "prefoverride" +Settings which override the settings from a theme. Some of the \fBicewm\fR +configuration options from the preferences file that control the +look-and-feel may be overridden by the theme, if the theme designer +thinks this is desirable. However, this \fIprefoverride\fR file will again +override this for a few specific options of your choosing. It is safe +to leave this file empty initially. +.Sp +See \fBicewm\-prefoverride\fR\|(5). +.IP \fIprograms\fR 4 +.IX Item "programs" +An automatically generated menu of applications. This could be used by +\&\fBwmconfig\fR\|(1), menu or similar programs to give easy access to all the +desktop applications that are installed on the system. +.Sp +See \fBicewm\-programs\fR\|(5). +.IP \fItheme\fR 4 +.IX Item "theme" +This file contains the name of the default theme. On startup \fBicewm\fR +reads this file to obtain the theme name, unless \fBicewm\fR was started +with the \fB\-\-theme\fR option. Whenever a different theme is selected from +the \fBicewm\fR Menu then the theme file is overwritten with the name of +the selected theme. This theme file contains the keyword \f(CW\*(C`Theme\*(C'\fR, +followed by an equals sign, followed by a double-quoted string with the +theme name. The theme name is the name of the theme directory, followed +by a slash, followed by the theme file. Usually the theme file is just +\&\fIdefault.theme\fR, but a theme may have alternatives. Alternatives are +small tweaks of a theme. These are specified in their own \fI.theme\fR +file, which replaces \fIdefault.theme\fR. If no theme file exists then +\&\fBicewm\fR will use the default setting of +\&\f(CW\*(C`Theme="default/default.theme"\*(C'\fR. +.Sp +See \fBicewm\-theme\fR\|(5). +.IP \fItoolbar\fR 4 +.IX Item "toolbar" +Contains names of quick to launch applications with icons for the task +bar. Each non-empty non-comment line starts with the keyword \fBprog\fR. +After one or more spaces follows a name, which is displayed in a tool +tip whenever the mouse cursor hovers over the toolbar icon. This name +may be a double quoted string. Then follows the bare name of the icon +to use without extensions. This icon will be shown in the toolbar. The +last component is a shell command-line that will be executed whenever +the user presses the icon in the toolbar. For example, the following +line in toolbar will create a button with tool tip \f(CW\*(C`Mozilla Firefox\*(C'\fR +with the \fIfirefox\fR icon that launches \fBfirefox\fR\|(1) when clicked: +.Sp +.Vb 1 +\& prog "Mozilla Firefox" firefox /usr/bin/firefox \-\-private\-window +.Ve +.Sp +See \fBicewm\-toolbar\fR\|(5). +.IP \fIwinoptions\fR 4 +.IX Item "winoptions" +Contains settings to control window appearance and behaviour that are +specific to applications or groups of applications. Options can control +the border, whether it appears on the task bar, the window list, the +system tray and the workspaces. Also its layer, geometry, whether it +can be moved, resized and closed. +.Sp +See \fBicewm\-winoptions\fR\|(5). +.IP \fIstartup\fR 4 +.IX Item "startup" +Contains commands to be executed on \fBicewm\fR startup. This is an +executable script with commands to tweak X11 settings and launch some +applications that need to be active whenever \fBicewm\fR is started. +It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR starts. +.Sp +See \fBicewm\-startup\fR\|(5). +.IP \fIshutdown\fR 4 +.IX Item "shutdown" +Contains commands to be executed on \fBicewm\fR shutdown. This is an +executable script with commands to be executed in the last stage of +\&\fBicewm\fR termination. Typically they may undo some of the effects of +the \fIstartup\fR script. It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR +terminates. +.Sp +See \fBicewm\-shutdown\fR\|(5). +.SS "CONFIGURATION SUBDIRECTORIES" +.IX Subsection "CONFIGURATION SUBDIRECTORIES" +.IP \fIcursors\fR 4 +.IX Item "cursors" +May contain cursor icons in the XPM image format. These overrule cursors +provided by a theme. There are 3 direction cursors: \fIleft.xpm\fR, +\&\fIright.xpm\fR, \fImove.xpm\fR, 8 resize cursors: \fIsizeR.xpm\fR, \fIsizeTR.xpm\fR, +\&\fIsizeT.xpm\fR, \fIsizeTL.xpm\fR, \fIsizeL.xpm\fR, \fIsizeBL.xpm\fR, \fIsizeB.xpm\fR, +\&\fIsizeBR.xpm\fR, and 4 scroll cursors: \fIscrollL.xpm\fR, \fIscrollR.xpm\fR, +\&\fIscrollU.xpm\fR, and \fIscrollD.xpm\fR. +By default an XPM header defines four dimensions: width, height, colors +and chars-per-pixel. For cursors this must be extended to six. The last +two are the \fIx\-hotspot\fR and the \fIy\-hotspot\fR. These define which point +in the XPM image is the sensitive point for the mouse pointer. +.IP \fIicons\fR 4 +.IX Item "icons" +Contains icons that are used to identify applications. Usually these +files are in the XPM format, but the PNG and SVG image formats are also +supported. The names of icon files may follow a specific naming +pattern, like \fIapp_32x32.xpm\fR. They start with a base name, usually +this is just a single word. Then follows an underscore, followed by a +size specification in the format \f(CW\*(C`SIZExSIZE\*(C'\fR. This is followed by a +dot and the file extension, where the extension denotes the icon image +format. Common sizes are 16, 32 and 48 for small, large and huge icons. +This depends on the respective \f(CW\*(C`IconSize\*(C'\fR preferences options. +.IP \fIledclock\fR 4 +.IX Item "ledclock" +Pictures of digits for the LED clock which is displayed in the +bottom-right corner of the task bar. These can be seen when the +\&\f(CW\*(C`TaskBarShowClock\*(C'\fR and \f(CW\*(C`TaskBarClockLeds\*(C'\fR options are both set to 1. +.IP \fImailbox\fR 4 +.IX Item "mailbox" +Icons that are used to display different states of the mailbox applet +in the task bar. There are five states and each has its own icon: +\&\fImail.xpm\fR, \fInewmail.xpm\fR, \fIunreadmail.xpm\fR, \fInomail.xpm\fR, +\&\fIerrmail.xpm\fR. +.IP \fIsounds\fR 4 +.IX Item "sounds" +Audio files that are played by \fBicesound\fR\|(1) on GUI events. These +are: \fIstartup.wav\fR, \fIshutdown.wav\fR, \fIrestart.wav\fR, \fIlaunchApp.wav\fR, +\&\fIworkspaceChange.wav\fR, \fIwindowOpen.wav\fR, \fIwindowClose.wav\fR, +\&\fIdialogOpen.wav\fR, \fIdialogClose.wav\fR, \fIwindowMax.wav\fR, +\&\fIwindowRestore.wav\fR, \fIwindowMin.wav\fR, \fIwindowHide.wav\fR, +\&\fIwindowRollup.wav\fR, \fIwindowMoved.wav\fR, \fIwindowSized.wav\fR, +\&\fIwindowLower.wav\fR. +.IP \fItaskbar\fR 4 +.IX Item "taskbar" +Pictures to customize the look of the task bar. These include: +\&\fItaskbarbg.xpm\fR, \fItaskbuttonactive.xpm\fR, \fItaskbuttonbg.xpm\fR, +\&\fItaskbuttonminimized.xpm\fR, \fItoolbuttonbg.xpm\fR, +\&\fIworkspacebuttonactive.xpm\fR, \fIworkspacebuttonbg.xpm\fR. +.IP \fIthemes\fR 4 +.IX Item "themes" +A directory to store themes. Each theme is stored in its own +sub-directory in the \fIthemes\fR directory. A theme contains at least a +\&\fIdefault.theme\fR file, and optionally theme alternatives which are +additional files that have a \fI.theme\fR file name extension and that +contain tweaks of the \fIdefault.theme\fR file. +How to create a theme is explained in the +IceWM Theme Creation Howto. +.IP \fIworkspace\fR 4 +.IX Item "workspace" +If \f(CW\*(C`PagerShowPreview\*(C'\fR is disabled, icewm looks in the \f(CW\*(C`workspace\*(C'\fR +directory for images to draw on a workspace button. The image filename +should have the name of the workspace. The image extension is optional. +.SS OPACITY +.IX Subsection "OPACITY" +IceWM supports window opacity and transparency in connection with an +external compositor like \fBcompton\fR\|(1) or \fBpicom\fR\|(1). +If a client window sets the \f(CW\*(C`_NET_WM_WINDOW_OPACITY\*(C'\fR property on +its window, then \fBicewm\fR will copy this to the outer frame window, +where the compositor will read it and adjust the opacity accordingly. +.PP +The opacity can also be set in the \fBicewm\-winoptions\fR\|(5) file. +\&\fBicesh\fR\|(1) can control the opacity level of running applications. +.PP +The _NET_WM_WINDOW_TYPE properties that \fBicewm\fR sets on its windows +are \fIDIALOG\fR, \fINOTIFICATION\fR, \fIPOPUP_MENU\fR and \fITOOLTIP\fR. The output +of \f(CW\*(C`icesh windows\*(C'\fR shows their WM_CLASS values. These can be helpful +to configure compton. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Examples of the above configuration files can be found in the default +installation path or in the system-wide defaults. See the output of +\&\f(CW\*(C`icewm \-\-directories\*(C'\fR for their locations. +.SS "CONFORMING TO" +.IX Subsection "CONFORMING TO" +ICCCM 2.0: partial. NetWM/EWMH: extensive. +See the file \fICOMPLIANCE\fR in the distribution for full details. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicehelp\fR\|(1), +\&\fBicesh\fR\|(1), +\&\fBicesound\fR\|(1), +\&\fBicewm\-env\fR\|(5), +\&\fBicewm\-focus_mode\fR\|(5), +\&\fBicewm\-keys\fR\|(5), +\&\fBicewm\-menu\fR\|(5), +\&\fBicewm\-menu\-fdo\fR\|(1), +\&\fBicewm\-menu\-xrandr\fR\|(1), +\&\fBicewm\-preferences\fR\|(5), +\&\fBicewm\-prefoverride\fR\|(5), +\&\fBicewm\-programs\fR\|(5), +\&\fBicewm\-session\fR\|(1), +\&\fBicewm\-set\-gnomewm\fR\|(1), +\&\fBicewm\-shutdown\fR\|(5), +\&\fBicewm\-startup\fR\|(5), +\&\fBicewm\-theme\fR\|(5), +\&\fBicewm\-toolbar\fR\|(5), +\&\fBicewm\-winoptions\fR\|(5), +\&\fBicewmbg\fR\|(1), +\&\fBicewmhint\fR\|(1), +\&\fBsetxkbmap\fR\|(1), +\&\fBXorg\fR\|(1), +\&\fBXserver\fR\|(1), +\&\fBxinit\fR\|(1), +\&\fBxprop\fR\|(1), +\&\fBxwininfo\fR\|(1), +\&\fBwmctrl\fR\|(1). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewmbg.1 b/upstream/fedora-40/man1/icewmbg.1 new file mode 100644 index 00000000..8cfafc70 --- /dev/null +++ b/upstream/fedora-40/man1/icewmbg.1 @@ -0,0 +1,298 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWMBG 1" +.TH ICEWMBG 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewmbg \- a background settings manager for the IceWM window manager +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewmbg\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR] +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewmbg\fR can assign a colour or image to the \fIX11\fR desktop background. +Common image formats are supported. Each \fBicewm\fR\|(1) workspace can have +its own background. +.PP +When the background image changes, \fBicewmbg\fR can be notified to +update the background. When switching workspaces, it checks the image +file modification time. If the file has changed, it reloads the +image from file. +.PP +\&\fBicewmbg\fR supports semitransparency. Semitransparent background +images and colours can be configured. +.PP +It uses RandR or Xinerama to support backgrounds on all connected +monitors. When monitors appear/disappear, or change their resolution, +\&\fBicewmbg\fR will adjust. It supports an option for one large background +over all monitors. +.PP +It will update the \f(CW\*(C`_ICEWMBG_IMAGE\*(C'\fR property of the root window to the +path of the background image whenever it changes the desktop background. +.PP +\&\fBicewmbg\fR is started automatically by \fBicewm\-session\fR\|(1). +If there is just a single background for all workspaces, icewmbg may +conclude that it can safely exit after setting the desktop background, +to free its system memory. If the screen size changes, icewm will then +attempt to restart icewmbg, preferably via icewm-session. +.SS ARGUMENTS +.IX Subsection "ARGUMENTS" +.SS "SPECIFIC OPTIONS" +.IX Subsection "SPECIFIC OPTIONS" +Where multiple values can be given for images +or colours, they are separated by comma's. +Each such value may be enclosed in double quotes. +If \fIFILE\fR is a directory, all images +from that directory are used in sorted order. +If the value starts with an exclamation mark, as in \fI!FILE\fR, +the images from the directory \fIFILE\fR are permuted randomly. +Image file names or directory names may have \fBglob\fR\|(7) wildcards, +or they may start with a tilde or environment variable. +.IP "\fB\-f\fR, \fB\-\-fork\fR" 4 +.IX Item "-f, --fork" +Fork into the background and detach from the terminal. +.IP "\fB\-p\fR, \fB\-\-replace\fR" 4 +.IX Item "-p, --replace" +Replace an existing \fBicewmbg\fR. If there is a running \fBicewmbg\fR, +it is instructed to quit. The new \fBicewmbg\fR will take over. +.IP "\fB\-q\fR, \fB\-\-quit\fR" 4 +.IX Item "-q, --quit" +Tell the running \fBicewmbg\fR to quit. This option is used by +\&\fBicewm\-session\fR\|(1) when \fBicewm\fR\|(1) exits. +.IP "\fB\-r\fR, \fB\-\-restart\fR" 4 +.IX Item "-r, --restart" +Tell the running \fBicewmbg\fR to restart itself. This is useful when +settings in have changed. If no icewmbg is active, it starts one. +.IP "\fB\-u\fR, \fB\-\-shuffle\fR" 4 +.IX Item "-u, --shuffle" +Shuffle the list of background images randomly. +This option may be given again whenever the running +\&\fBicewmbg\fR should reshuffle its list of background images. +.IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4 +.IX Item "-c, --config=FILE" +Load preferences from \fIFILE\fR. +.IP "\fB\-t\fR, \fB\-\-theme\fR=\fITHEME\fR" 4 +.IX Item "-t, --theme=THEME" +Use the theme named \fITHEME\fR. +.IP "\fB\-i\fR, \fB\-\-image\fR=\fIFILE\fR[,\fIFILE\fR]*" 4 +.IX Item "-i, --image=FILE[,FILE]*" +Load background images from each \fIFILE\fR. +This overrules the \f(CW\*(C`DesktopBackgroundImage\*(C'\fR preference. +When more than one image is given, they are assigned +to each workspace in the given order. +.IP "\fB\-k\fR, \fB\-\-color\fR=\fICOLOR\fR[,\fICOLOR\fR]*" 4 +.IX Item "-k, --color=COLOR[,COLOR]*" +Use background colours from each \fICOLOR\fR. +This overrules the \f(CW\*(C`DesktopBackgroundColor\*(C'\fR preference. +.IP "\fB\-s\fR, \fB\-\-semis\fR=\fIFILE\fR[,\fIFILE\fR]*" 4 +.IX Item "-s, --semis=FILE[,FILE]*" +Load transparency images from each \fIFILE\fR. +This overrules the \f(CW\*(C`DesktopTransparencyImage\*(C'\fR preference. +.IP "\fB\-x\fR, \fB\-\-trans\fR=\fINAME\fR[,\fINAME\fR]" 4 +.IX Item "-x, --trans=NAME[,NAME]" +Use transparency colours for each \fINAME\fR. +This overrules the \f(CW\*(C`DesktopTransparencyColor\*(C'\fR preference. +.IP "\fB\-e\fR, \fB\-\-center\fR={\fI0\fR|\fI1\fR}" 4 +.IX Item "-e, --center={0|1}" +Disable/Enable centring background. +This overrules the \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR preference. +.IP "\fB\-a\fR, \fB\-\-scaled\fR={\fI0\fR|\fI1\fR}" 4 +.IX Item "-a, --scaled={0|1}" +Disable/Enable scaling background. +This overrules the \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR preference. +.IP "\fB\-m\fR, \fB\-\-multi\fR={\fI0\fR|\fI1\fR}" 4 +.IX Item "-m, --multi={0|1}" +Disable or enable a single background over all monitors. +This overrules the \f(CW\*(C`DesktopBackgroundMultihead\*(C'\fR preference. +.IP "\fB\-y\fR, \fB\-\-cycle\fR=\fISECONDS\fR" 4 +.IX Item "-y, --cycle=SECONDS" +Cycle over the list of background images every \fISECONDS\fR. +This overrules the \f(CW\*(C`CycleBackgroundsPeriod\*(C'\fR preference. +.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4 +.IX Item "-o, --output=FILE" +Redirect all output to \fIFILE\fR. +A leading tilde or environment variable is expanded. +.IP \fB\-\-postpreferences\fR 4 +.IX Item "--postpreferences" +Print a list of all preference values that \fBicewmbg\fR will use. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +Use \fIDISPLAY\fR to connect to the X server. +Otherwise use DISPLAY from the environment. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.IP \fB\-\-sync\fR 4 +.IX Item "--sync" +Use a slow synchronous mode to communicate with the \fIX11\fR server. +.IP \fB\-\-verbose\fR 4 +.IX Item "--verbose" +Report on some of the activities. +.SS FILES +.IX Subsection "FILES" +Additional arguments, which either are a path or which have an image +extension, are assumed to be background image files or directories. +.SS PREFERENCES +.IX Subsection "PREFERENCES" +By default \fBicewmbg\fR loads settings from the \fBicewm\fR\|(1) +preferences file. See \fBicewm\-preferences\fR\|(5) for details. +The settings read are: +.PP +.Vb 10 +\& DesktopBackgroundCenter \- Display desktop background centered +\& DesktopBackgroundScaled \- Display desktop background scaled +\& DesktopBackgroundColor \- Desktop background color(s) +\& DesktopBackgroundImage \- Desktop background image(s) +\& ShuffleBackgroundImages \- Shuffle the list of background images +\& SupportSemitransparency \- Support for semitransparent terminals +\& DesktopTransparencyColor \- Semitransparency background color(s) +\& DesktopTransparencyImage \- Semitransparency background image(s) +\& DesktopBackgroundMultihead \- One background over all monitors +\& CycleBackgroundsPeriod \- Seconds between cycling over backgrounds +.Ve +.PP +If these settings are set in the \fIpreferences\fR file, they can +be overridden by the theme in the theme defaults file. +To enforce a certain setting, set it in the \fIprefoverride\fR file instead. +See \fBicewm\-prefoverride\fR\|(5). +.SS WORKSPACES +.IX Subsection "WORKSPACES" +Each workspace can have a unique image. Specify multiple images to +\&\fBDesktopBackgroundImage\fR separated by comma's. Or give at least one +directory with images. The images are assigned to each workspace in +the order given. When icewm changes workspace, the running icewmbg +will adapt the desktop background to the assigned image. +.PP +If you specify more images then there are workspaces, then +\&\fBCycleBackgroundsPeriod\fR can set a period. When the period expires, +icewmbg will switch to the next set of images. If you give less images +than there are workspaces, then icewmbg will reuse previous images +for the remaining workspaces. +.SS "IMAGE SCALING" +.IX Subsection "IMAGE SCALING" +Often a background image has a different width or height than the screen. +The image can then be replicated (tiled), centered or scaled. This is +controlled by \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR and \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR. +What happens for their combination is given by the following table: +.PP +.Vb 4 +\& center:0 scaled:0 = The background is replicated in both directions. +\& center:1 scaled:0 = The background is centered, but not scaled. +\& center:1 scaled:1 = Fill one dimension and preserve the aspect ratio. +\& center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio. +.Ve +.SS EXAMPLES +.IX Subsection "EXAMPLES" +.Vb 1 +\& # For four unique desktop backgrounds for four workspaces do: +\& +\& icewmbg \-f \-p \-i image0,image1,image2,image3 +\& +\& # Or create a directory with the four images and do: +\& +\& icewmbg \-f \-p \-i /path/to/directory +\& +\& # The images should have proper image filename extensions. +.Ve +.SS SIGNALS +.IX Subsection "SIGNALS" +\&\fBicewmbg\fR supports the following signals: +.IP \fBSIGHUP\fR 4 +.IX Item "SIGHUP" +\&\fBicewmbg\fR will restart itself. +.IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4 +.IX Item "SIGINT, SIGTERM" +\&\fBicewmbg\fR will terminate. +.IP \fBSIGUSR1\fR 4 +.IX Item "SIGUSR1" +\&\fBicewmbg\fR will reshuffle the list of background images and +update the backgrounds of all workspaces. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-preferences\fR\|(5), +\&\fBicewm\-prefoverride\fR\|(5), +\&\fBwmsetbg\fR\|(1), +\&\fBxsetbg\fR\|(1), +\&\fBxwallpaper\fR\|(1). +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icewmhint.1 b/upstream/fedora-40/man1/icewmhint.1 new file mode 100644 index 00000000..ef5387ae --- /dev/null +++ b/upstream/fedora-40/man1/icewmhint.1 @@ -0,0 +1,281 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWMHINT 1" +.TH ICEWMHINT 1 2024-01-24 "icewm\ 3.4.5" "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +icewmhint \- set IceWM hints by window class and instance +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +\&\fBicewmhint\fR \fICLASS\fR\fB.\fR\fIINSTANCE\fR \fIOPTION\fR \fIVALUE\fR ... +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewmhint\fR is a utility for passing IceWM hints to \fBicewm\fR\|(1). +\&\fBicewm\fR uses these hints for the first \fIX11 client\fR which is +subsequently started. They take precedence over hints from +the \fBicewm\-winoptions\fR\|(1) file. +.PP +A hint is a triplet consisting of a \fIclass.instance\fR, an +\&\fIIceWM winoption\fR and its value. Multiple hints can be given per +invocation of \fBicewmhint\fR. +.PP +The hints are communicated over the \f(CW\*(C`_ICEWM_WINOPTHINT\*(C'\fR property on +the root window. \fBicewmhint\fR appends hints to this property, while +\&\fBicewm\fR removes the property after reading it. +.SS OPTIONS +.IX Subsection "OPTIONS" +\&\fBicewmhint\fR recognizes the following options: +.SS "COMMAND OPTIONS" +.IX Subsection "COMMAND OPTIONS" +Only one command option can be specified per invocation. If no command +option is specified, argument parsing and processing is performed. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +Print a brief usage statement to \fIstdout\fR and exit. +.IP "\fB\-V\fR, \fB\-\-version\fR" 4 +.IX Item "-V, --version" +Print the program version to \fIstdout\fR and exit. +.IP "\fB\-C\fR, \fB\-\-copying\fR" 4 +.IX Item "-C, --copying" +Print copying permissions to \fIstdout\fR for the program and exit. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4 +.IX Item "-d, --display=DISPLAY" +Specifies the X11 DISPLAY. If unspecified, defaults to \fR\f(CB$DISPLAY\fR\fB\fR. +.SS ARGUMENTS +.IX Subsection "ARGUMENTS" +The following three arguments are required for each hint. +.IP \fICLASS\fR\fB.\fR\fIINSTANCE\fR 4 +.IX Item "CLASS.INSTANCE" +Specifies the ICCCM 2.0 \fBWM_CLASS\fR property in terms of resource class +and resource name separated by a period (\f(CW\*(C`.\*(C'\fR). For example: +\&\f(CW\*(C`XTerm.xterm\*(C'\fR. Just the resource class or resource name without a dot +is also acceptable, like \f(CW\*(C`XTerm\*(C'\fR or \f(CW\*(C`xterm\*(C'\fR. +.IP \fIOPTION\fR 4 +.IX Item "OPTION" +Specifies the \fIOPTION\fR to affect. +.IP \fIVALUE\fR 4 +.IX Item "VALUE" +Gives the \fIVALUE\fR for the option. +.PP +Multiple hints can be given. +.SS "GENERAL OPTION ARGUMENTS" +.IX Subsection "GENERAL OPTION ARGUMENTS" +.IP "\fBicon\fR \fINAME\fR" 4 +.IX Item "icon NAME" +Specifies the icon name for windows of \fICLASS\fR\fB.\fR\fIINSTANCE\fR. +\&\fINAME\fR should be the name of the icon. \fBicewm\fR\|(1) will use its +usual method to locate the icon. The default is the name provided +by window manager hints. +.IP "\fBworkspace\fR \fIWORKSPACE\fR" 4 +.IX Item "workspace WORKSPACE" +Specifies the workspace on which a window of \fICLASS\fR\fB.\fR\fIINSTANCE\fR +will be initially placed. The default is the current workspace. +\&\fIWORKSPACE\fR should be a workspace number counting from 0. +.IP "\fBgeometry\fR \fIGEOMETRY\fR" 4 +.IX Item "geometry GEOMETRY" +Specifies the initial geometry for windows of the given +\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR. \fIGEOMETRY\fR must be a geometry that can be +parsed by \fBXParseGeometry\fR\|(3). The default is the geometry provided by +window manager hints. +.IP "\fBorder\fR \fINUMBER\fR" 4 +.IX Item "order NUMBER" +The sorting order of task buttons and tray icons. The default value is +zero. Increasing positive values go farther right, while decreasing +negative values go farther left. The order option applies to the task +pane, the tray pane and the system tray. +.IP "\fBopacity\fR \fINUMBER\fR" 4 +.IX Item "opacity NUMBER" +Set the _NET_WM_WINDOW_OPACITY property if \fINUMBER\fR is a value between +1 and 100. \fINUMBER\fR is interpreted as percentage of maximum opaqueness. +.IP "\fBlayer\fR {\fILAYER\fR|\fINUMBER\fR}" 4 +.IX Item "layer {LAYER|NUMBER}" +This command option specifies the layer to be associated with a +\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR. The default is the \f(CW\*(C`Normal\*(C'\fR layer. \fIVALUE\fR +is either a layer number or a symbolic layer name. Symbolic +layer names are: +.Sp +.Vb 9 +\& Desktop (0) Desktop window. +\& Below (2) Below the default layer. +\& Normal (4) Default layer for windows. +\& OnTop (6) Above the default layer. +\& Dock (8) Docked windows at edge of screen. +\& AboveDock (10) Windows above the dock. +\& Menu (12) The layer for menu\*(Aqs. +\& Fullscreen (14) When fullscreen and focused. +\& AboveAll (15) Always above anything. +.Ve +.IP "\fBtray\fR {\fBIgnore\fR|\fBMinimized\fR|\fBExclusive\fR|\fINUMBER\fR}" 4 +.IX Item "tray {Ignore|Minimized|Exclusive|NUMBER}" +Specifies the tray handling to be applied to windows with +\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR. This option is specific to \fBicewm\fR\|(1) and +sets the \f(CW\*(C`_ICEWM_TRAY\*(C'\fR property associated with the window. +The default is \f(CW\*(C`Ignore\*(C'\fR. \fIVALUE\fR can be an option number +or a symbolic name as follows: +.Sp +.Vb 3 +\& Ignore (0) only in task list. +\& Minimized (1) icon in tray, task list unminimized. +\& Exclusive (2) only in tray, not in task list. +.Ve +.IP "\fBframe\fR \fIlabel\fR (default: none)" 4 +.IX Item "frame label (default: none)" +All windows with the same frame label become tabs in a single frame. +.SS "FUNCTION OPTION ARGUMENTS" +.IX Subsection "FUNCTION OPTION ARGUMENTS" +Specifies which functions are disabled or enabled (0/1) for windows with +\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR. All functions have a default value of enabled +(1) unless overridden by the application. The Motif-like functions are +as follows: +.PP +.Vb 7 +\& fClose can be closed: (default: 1). +\& fHide can be hidden: (default: 1). +\& fMaximize can be maximized: (default: 1). +\& fMinimize can be minimized: (default: 1). +\& fMove can be moved: (default: 1). +\& fResize can be resized: (default: 1). +\& fRollup can be shaded: (default: 1). +.Ve +.SS "DECOR OPTION ARGUMENTS" +.IX Subsection "DECOR OPTION ARGUMENTS" +Specifies which decorations are disabled or enabled (0/1) for windows +with \fICLASS\fR\fB.\fR\fIINSTANCE\fR. All decor options have a default value +of enabled (1) unless overridden by the application. The Motif-like +decorations are as follows: +.PP +.Vb 10 +\& dBorder has border: (default: 1). +\& dClose has close button: (default: 1). +\& dDepth has depth button: (default: 1). +\& dHide has hide button: (default: 1). +\& dMaximize has maximize button: (default: 1). +\& dMinimize has minimize button: (default: 1). +\& dResize has resize grips: (default: 1). +\& dRollup has shade button: (default: 1). +\& dSysMenu has window menu: (default: 1). +\& dTitleBar has title bar: (default: 1). +.Ve +.SS "FEATURE OPTION ARGUMENTS" +.IX Subsection "FEATURE OPTION ARGUMENTS" +Specifies which advanced features to be enabled/disabled (1/0) for +windows with \fICLASS\fR\fB.\fR\fIINSTANCE\fR. All advanced features have a +default value of disabled (0) unless overridden by the application. The +advanced features are as follows: +.PP +.Vb 10 +\& allWorkspaces on all workspaces. +\& appTakesFocus let application take focus. +\& doNotCover limits workspace if sticky. +\& doNotFocus do not focus. +\& doNotManage do not manage. +\& forcedClose no close dialog. +\& fullKeys provided more keys. +\& ignoreNoFocusHint focus even no\-input. +\& ignorePagerPreview do not show in pager preview. +\& ignorePositionHint place automatically. +\& ignoreQuickSwitch not on quick switch. +\& ignoreTaskBar not on task bar. +\& ignoreUrgentHint ignore urgent hints. +\& ignoreWinList not on window list. +\& ignoreActivationMessages only user can focus window. +\& ignoreOverrideRedirect ignore the override redirect flag. +\& noFocusOnAppRaise no focus on raise. +\& noFocusOnMap do not focus when mapped. +\& noIgnoreTaskBar on task bar. +\& startClose close the window immediately. +\& startFullscreen start full screen. +\& startMaximized start maximized. +\& startMaximizedHorz start maximized horizontal. +\& startMaximizedVert start maximized vertical. +\& startMinimized start minimized. +.Ve +.SS EXAMPLE +.IX Subsection "EXAMPLE" +.Vb 2 +\& # Here is how to preload an invisible background process of chromium +\& # on the fourth workspace which is only visible on the Window List. +\& +\& icewmhint Chromium\-browser startMinimized 1 \e +\& Chromium\-browser workspace 3 \e +\& Chromium\-browser ignorePagerPreview 1 \e +\& Chromium\-browser ignorePositionHint 1 \e +\& Chromium\-browser ignoreTaskBar 1 \e +\& Chromium\-browser ignoreQuickSwitch 1 \e +\& Chromium\-browser ignoreUrgentHint 1 \e +\& Chromium\-browser noFocusOnAppRaise 1 +\& chromium +.Ve +.SS BUGS +.IX Subsection "BUGS" +Please report bugs at . +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.PP +See \fB\-\-copying\fR for full copyright notice and copying permissions. +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag +to display copying permissions. diff --git a/upstream/fedora-40/man1/icontopbm.1 b/upstream/fedora-40/man1/icontopbm.1 new file mode 100644 index 00000000..419f86cc --- /dev/null +++ b/upstream/fedora-40/man1/icontopbm.1 @@ -0,0 +1,48 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Icontopbm User Manual" 0 "" "netpbm documentation" + +.SH NAME + +icontopbm - replaced by sunicontopnm + +.UN synopsis +.SH SYNOPSIS + +\fBicontopbm\fP +[\fIiconfile\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBicontopbm\fP was obsoleted by +.BR "\fBsunicontopnm\fP" (1)\c +\&, introduced with Netpbm 10.53 +(December 2010). \fBsunicontopnm\fP is backward compatible with +\fBicontopbm\fP, plus adds additional functions, including the +ability to convert a Depth=8 Sun icon, producing a PGM image. +.PP +Starting in Release 10.53, \fBicontopbm\fP is just an alias for +\fBsunicontopnm\fP. +.PP +The point of the name change is that there are many kinds of icons in the +world besides Sun icons, and in 2010, the Sun variety isn't even common. +.PP +In releases before 10.53, you can use the \fBsunicontopnm\fP documentation +for \fBicontopbm\fP, as long as you recognize that any change the +\fBsunicontopnm\fP manual says happened in or after Netpbm 10.53 doesn't +apply to \fBicontopbm\fP. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/icontopbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/iconv.1 b/upstream/fedora-40/man1/iconv.1 new file mode 100644 index 00000000..ffa84516 --- /dev/null +++ b/upstream/fedora-40/man1/iconv.1 @@ -0,0 +1,204 @@ +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH iconv 1 2024-01-28 "Linux man-pages 6.06" +.SH NAME +iconv \- convert text from one character encoding to another +.SH SYNOPSIS +.B iconv +.RI [ options ] +.RI "[\-f " from-encoding "]" +.RI "[\-t " to-encoding "]" +.RI [ inputfile ]... +.SH DESCRIPTION +The +.B iconv +program reads in text in one encoding and outputs the text in another +encoding. +If no input files are given, or if it is given as a dash (\-), +.B iconv +reads from standard input. +If no output file is given, +.B iconv +writes to standard output. +.P +If no +.I from-encoding +is given, the default is derived +from the current locale's character encoding. +If no +.I to-encoding +is given, the default is derived +from the current locale's character +encoding. +.SH OPTIONS +.TP +.BI \-\-from\-code= from-encoding +.TQ +.BI \-f\~ from-encoding +Use +.I from-encoding +for input characters. +.TP +.BI \-\-to\-code= to-encoding +.TQ +.BI \-t\~ to-encoding +Use +.I to-encoding +for output characters. +.IP +If the string +.B //IGNORE +is appended to +.IR to-encoding , +characters that cannot be converted are discarded and an error is +printed after conversion. +.IP +If the string +.B //TRANSLIT +is appended to +.IR to-encoding , +characters being converted are transliterated when needed and possible. +This means that when a character cannot be represented in the target +character set, it can be approximated through one or several similar +looking characters. +Characters that are outside of the target character set and cannot be +transliterated are replaced with a question mark (?) in the output. +.TP +.B \-\-list +.TQ +.B \-l +List all known character set encodings. +.TP +.B \-c +Silently discard characters that cannot be converted instead of +terminating when encountering such characters. +.TP +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile +Use +.I outputfile +for output. +.TP +.B \-\-silent +.TQ +.B \-s +This option is ignored; it is provided only for compatibility. +.TP +.B \-\-verbose +Print progress information on standard error when processing +multiple files. +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH ENVIRONMENT +Internally, the +.B iconv +program uses the +.BR iconv (3) +function which in turn uses +.I gconv +modules (dynamically loaded shared libraries) +to convert to and from a character set. +Before calling +.BR iconv (3), +the +.B iconv +program must first allocate a conversion descriptor using +.BR iconv_open (3). +The operation of the latter function is influenced by the setting of the +.B GCONV_PATH +environment variable: +.IP \[bu] 3 +If +.B GCONV_PATH +is not set, +.BR iconv_open (3) +loads the system gconv module configuration cache file created by +.BR iconvconfig (8) +and then, based on the configuration, +loads the gconv modules needed to perform the conversion. +If the system gconv module configuration cache file is not available +then the system gconv module configuration file is used. +.IP \[bu] +If +.B GCONV_PATH +is defined (as a colon-separated list of pathnames), +the system gconv module configuration cache is not used. +Instead, +.BR iconv_open (3) +first tries to load the configuration files by searching the directories in +.B GCONV_PATH +in order, +followed by the system default gconv module configuration file. +If a directory does not contain a gconv module configuration file, +any gconv modules that it may contain are ignored. +If a directory contains a gconv module configuration file +and it is determined that a module needed for this conversion is +available in the directory, +then the needed module is loaded from that directory, +the order being such that the first suitable module found in +.B GCONV_PATH +is used. +This allows users to use custom modules and even replace system-provided +modules by providing such modules in +.B GCONV_PATH +directories. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.P +Depending on the architecture, +the above files may instead be located at directories with the path prefix +.IR /usr/lib64 . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8: +.P +.in +4n +.EX +$ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP +.EE +.in +.P +The next example converts from UTF-8 to ASCII, transliterating when +possible: +.P +.in +4n +.EX +$ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP +abc ss ? EUR abc +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR uconv (1), +.BR iconv (3), +.BR nl_langinfo (3), +.BR charsets (7), +.BR iconvconfig (8) diff --git a/upstream/fedora-40/man1/id.1 b/upstream/fedora-40/man1/id.1 new file mode 100644 index 00000000..0d2fcbe0 --- /dev/null +++ b/upstream/fedora-40/man1/id.1 @@ -0,0 +1,62 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH ID "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +id \- print real and effective user and group IDs +.SH SYNOPSIS +.B id +[\fI\,OPTION\/\fR]... [\fI\,USER\/\fR]... +.SH DESCRIPTION +.\" Add any additional description here +.PP +Print user and group information for each specified USER, +or (when USER omitted) for the current process. +.TP +\fB\-a\fR +ignore, for compatibility with other versions +.TP +\fB\-Z\fR, \fB\-\-context\fR +print only the security context of the process +.TP +\fB\-g\fR, \fB\-\-group\fR +print only the effective group ID +.TP +\fB\-G\fR, \fB\-\-groups\fR +print all group IDs +.TP +\fB\-n\fR, \fB\-\-name\fR +print a name instead of a number, for \fB\-ugG\fR +.TP +\fB\-r\fR, \fB\-\-real\fR +print the real ID instead of the effective ID, with \fB\-ugG\fR +.TP +\fB\-u\fR, \fB\-\-user\fR +print only the effective user ID +.TP +\fB\-z\fR, \fB\-\-zero\fR +delimit entries with NUL characters, not whitespace; +.IP +not permitted in default format +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +Without any OPTION, print some useful set of identified information. +.SH AUTHOR +Written by Arnold Robbins and David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +Full documentation +.br +or available locally via: info \(aq(coreutils) id invocation\(aq diff --git a/upstream/fedora-40/man1/ident.1 b/upstream/fedora-40/man1/ident.1 new file mode 100644 index 00000000..78728dd0 --- /dev/null +++ b/upstream/fedora-40/man1/ident.1 @@ -0,0 +1,224 @@ +.ds Rv 5.10.1 +.ds Dt 2024-01-26 +.ds i \&\s-1ISO\s0 +.ds r \&\s-1RCS\s0 +.ds u \&\s-1UTC\s0 +.ds o \*r file +.ds iD 5.4 1993/11/09 17:40:15 eggert Exp +.if n .ds - \%-- +.if t .ds - \(em +.TH IDENT 1 "\*(Dt" "GNU RCS \*(Rv" +.SH NAME +ident \- identify RCS keyword strings in files +.SH SYNOPSIS +.B ident +[ +.B \-q +] [ +.B \-V +] [ +.I file +\&.\|.\|. ] +.SH DESCRIPTION +.B ident +searches for all instances of the pattern +.BI $ keyword : "\ text\ " $ +in the named files or, if no files are named, the standard input. +.PP +These patterns are normally inserted automatically by the \*r command +.BR co (1), +but can also be inserted manually. +The option +.B \-q +suppresses +the warning given if there are no patterns in a file. +The option +.B \-V +prints \*r's version number. +.PP +.B ident +works on text files as well as object files and dumps. +For example, if the C program in +.B f.c +contains +.IP +.ft 3 +#include +.br +static char const rcsid[] = +.br + \&"$\&Id: f.c,v \*(iD $\&"; +.br +int main() { return printf(\&"%s\en\&", rcsid) == EOF; } +.ft P +.LP +and +.B f.c +is compiled into +.BR f.o , +then the command +.IP +.B "ident f.c f.o" +.LP +will output +.nf +.IP +.ft 3 +f.c: + $\&Id: f.c,v \*(iD $ +f.o: + $\&Id: f.c,v \*(iD $ +.ft +.fi +.PP +If a C program defines a string like +.B rcsid +above but does not use it, +.BR lint (1) +may complain, and some C compilers will optimize away the string. +The most reliable solution is to have the program use the +.B rcsid +string, as shown in the example above. +.PP +.B ident +finds all instances of the +.BI $ keyword : "\ text\ " $ +pattern, even if +.I keyword +is not actually an \*r-supported keyword. +This gives you information about nonstandard keywords like +.BR $\&XConsortium$ . +.PP +The pattern normally requires a colon and a space immediately +after the keyword and a space immediately before the terminating +.BR $ , +but for Subversion 1.2 (and later) compatibility, +.B ident +will also recognize the pattern +.BI $ keyword :: "\ text\ " $ +(i.e., two colons and a space) +and the pattern +.BI $ keyword :: "\ text\ #" $ +(likewise, with a hash before the terminating +.BR $ ). +These are the fixed-width keyword syntax. +To summarize, the three recognized patterns are: +.IP +.BI $ keyword : "\ text\ " $ +.br +.BI $ keyword :: "\ text\ " $ +.br +.BI $ keyword :: "\ text\ #" $ +.br +.SH KEYWORDS +Here is the list of keywords currently maintained by +.BR co (1). +All times are given in Coordinated Universal Time (\*u, +sometimes called \&\s-1GMT\s0) by default, but if the files +were checked out with +.BR co 's +.BI \-z zone +option, times are given with a numeric time zone indication appended. +.TP +.B $\&Author$ +The login name of the user who checked in the revision. +.TP +.B $\&Date$ +The date and time the revision was checked in. +.TP +.B $\&Header$ +A standard header containing the full \*o name, the +revision number, the date and time, the author, the state, +and the locker (if locked). +.TP +.B $\&Id$ +Same as +.BR $\&Header$ , +except that the \*o name is without directory components. +.TP +.B $\&Locker$ +The login name of the user who locked the revision (empty if not locked). +.TP +.B $\&Log$ +The log message supplied during checkin. +For +.BR ident 's +purposes, this is equivalent to +.BR $\&RCSfile$ . +.TP +.B $\&Name$ +The symbolic name used to check out the revision, if any. +.TP +.B $\&RCSfile$ +The \*o name without directory components. +.TP +.B $\&Revision$ +The revision number assigned to the revision. +.TP +.B $\&Source$ +The full \*o name. +.TP +.B $\&State$ +The state assigned to the revision with the +.B \-s +option of +.BR rcs (1) +or +.BR ci (1). +.PP +.BR co (1) +represents the following characters in keyword values by escape sequences +to keep keyword strings well-formed. +.LP +.RS +.nf +.ne 6 +.ta \w'newline 'u +\f2char escape sequence\fP +tab \f3\et\fP +newline \f3\en\fP +space \f3\e040 +$ \e044 +\e \e\e\fP +.fi +.RE +.ds EY 1990, 1992, 1993 +.SH IDENTIFICATION +Author: Walter F. Tichy. +.br +Manual Page Revision: \*(Rv; Release Date: \*(Dt. +.br +Copyright \(co 2010-2022 Thien-Thi Nguyen. +.br +Copyright \(co \*(EY Paul Eggert. +.br +Copyright \(co 1982, 1988, 1989 Walter F. Tichy. +.br +.SH "SEE ALSO" +.BR ci (1), +.BR co (1), +.BR rcs (1), +.BR rcsdiff (1), +.BR rcsmerge (1), +.BR rlog (1), +.BR rcsfile (5). +.PP +Walter F. Tichy, +\*r\*-A System for Version Control, +.I "Software\*-Practice & Experience" +.BR 15 , +7 (July 1985), 637-654. +.PP +The full documentation for \*r is maintained as a Texinfo manual. +If the +.BR info (1) +and \*r programs are properly installed at your site, the command +.IP +.B info rcs +.PP +should give you access to the complete manual. +Additionally, the \*r homepage: +.IP +.B http://www.gnu.org/software/rcs/ +.PP +has news and links to the latest release, development site, etc. diff --git a/upstream/fedora-40/man1/ifnames.1 b/upstream/fedora-40/man1/ifnames.1 new file mode 100644 index 00000000..0bb65d87 --- /dev/null +++ b/upstream/fedora-40/man1/ifnames.1 @@ -0,0 +1,57 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.17. +.TH IFNAMES "1" "January 2021" "GNU Autoconf 2.71" "User Commands" +.SH NAME +ifnames \- Extract CPP conditionals from a set of files +.SH SYNOPSIS +.B ifnames +[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.SH DESCRIPTION +Scan all of the C source FILES (or the standard input, if none are +given) and write to the standard output a sorted list of all the +identifiers that appear in those files in '#if', '#elif', '#ifdef', or +\&'#ifndef' directives. Print each identifier on a line, followed by a +space\-separated list of the files in which that identifier occurs. +.TP +\fB\-h\fR, \fB\-\-help\fR +print this help, then exit +.TP +\fB\-V\fR, \fB\-\-version\fR +print version number, then exit +.SH AUTHOR +Written by David J. MacKenzie and Paul Eggert. +.SH "REPORTING BUGS" +Report bugs to . +.br +GNU Autoconf home page: . +.br +General help using GNU software: . +.SH COPYRIGHT +Copyright \(co 2021 Free Software Foundation, Inc. +License GPLv3+/Autoconf: GNU GPL version 3 or later +, +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +.BR autoconf (1), +.BR automake (1), +.BR autoreconf (1), +.BR autoupdate (1), +.BR autoheader (1), +.BR autoscan (1), +.BR config.guess (1), +.BR config.sub (1), +.BR ifnames (1), +.BR libtool (1). +.PP +The full documentation for +.B ifnames +is maintained as a Texinfo manual. If the +.B info +and +.B ifnames +programs are properly installed at your site, the command +.IP +.B info ifnames +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/ilbmtoppm.1 b/upstream/fedora-40/man1/ilbmtoppm.1 new file mode 100644 index 00000000..ac8d4f83 --- /dev/null +++ b/upstream/fedora-40/man1/ilbmtoppm.1 @@ -0,0 +1,160 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Ilbmtoppm User Manual" 0 "12 November 2014" "netpbm documentation" + +.SH NAME +ilbmtoppm - convert an ILBM file into a PPM image + +.UN synopsis +.SH SYNOPSIS + +\fBilbmtoppm\fP +[\fB-ignore\fP\fB]\fP +[ +\fB-isham\fP | \fB-isnotham\fP | +\fB-isehb\fP | \fB-isnotehb\fP | +\fB-isdeep\fP | \fB-isnotdeep\fP +] +[\fB-cmaponly\fP] +[\fB-adjustcolors\fP] +[\fB-transparent \fP\fIcolor\fP] +[\fB-maskfile\fP \fIfilename\fP +[\fB-verbose\fP] +[\fIILBMfile\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBilbmtoppm\fP reads an IFF ILBM file as input and produces a PPM +image as output. \fBilbmtoppm\fP can handle the following ILBM types: + + +.IP \(bu +Normal ILBMs with 1-16 planes. +.IP \(bu +Amiga Extra_Halfbrite (EHB) +.IP \(bu +Amiga HAM with 3-16 planes. +.IP \(bu +24 bit. +.IP \(bu +Multiplatte (normal or HAM) pictures. +.IP \(bu +Color map (BMHD + CMAP chunk only, nPlanes = 0). +.IP \(bu +Unofficial direct color. 1-16 planes for each color component. + +.PP +\fBilbmtoppm\fP uses these ILBM chunks: BMHD, CMAP, CAMG (only HAM +& EHB flags used), PCHG, BODY unofficial DCOL chunk to identify +direct color ILBM. It ignores these chunks: GRAB, DEST, SPRT, CRNG, +CCRT, CLUT, DPPV, DRNG, EPSF. It ignores, but displays in verbose +mode, these: NAME, AUTH, (c), ANNO, DPI. It skips chunks whose type +it doesn't recognize. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBilbmtoppm\fP recognizes the following +command line options: + + + +.TP +\fB-transparent \fP\fIcolor\fP +This is the color that should "show through" in places where +the image is transparent. +.sp +\fIcolor\fP is like the +.UR libnetpbm_image.html#colorname +argument of the \fBpnm_parsecolor()\fP library routine +.UE +\&. + +.TP +\fB-verbose\fP +Give some information about the ILBM file. + +.TP +\fB-ignore\fP \fIchunkID\fP +Skip a chunk. \fIchunkID\fP is the 4-letter IFF chunk identifier +of the chunk to be skipped. + +.TP +\fB-isham\fP | \fB-isehb\fP +Treat the input file as a HAM or Extra_Halfbrite picture, even if +these flags are not set in the CAMG chunk (or if there is no CAMG +chunk). + +.TP +\fB-maskfile\fP \fIfilename\fP +This names a file for \fBilbmtoppm\fP to create with the image's +transparency mask. The mask file is a PBM image which maps to the input image +with white pixels representing transparent pixels in the image and black +pixels representing opaque pixels. +.sp +If you don't specfy this, or the image does not contain transparency +information, \fBilbmtoppm\fP does not create a mask file. + +.TP +\fB-cmaponly\fP +With this option, \fBilbmtoppm\fP generates a PPM of the ILBM's \fIcolor +map\fP, not the image itself. +.sp +\fBilbmtoppm\fP does the same thing even without \fB-cmaponly\fP if the +ILBM is a pure color map stream (it has a bitmap header with an \fInplanes\fP +value of zero or has no BODY chunk. + +.TP +\fB-adjustcolors\fP +If all colors in the CMAP have a value of less then 16, ilbmtoppm +assumes a 4-bit colormap and gives a warning. With this option the +colormap is scaled to 8 bits. + + + + +.UN limitations +.SH LIMITATIONS +.PP +The multipalette PCHG BigLineChanges and Huffman decompression code +is untested. + +.UN references +.SH REFERENCES + +Amiga ROM Kernel Reference Manual - Devices (3rd Ed.) +Addison Wesley, ISBN 0-201-56775-X + +.UN seealso +.SH SEE ALSO +.BR "ppmtoilbm" (1)\c +\&, +.BR "ppm" (1)\c +\& + +.UN authors +.SH AUTHORS + +Copyright (C) 1989 by Jef Poskanzer. +.PP +Modified October 1993 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP) +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/ilbmtoppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/imgtoppm.1 b/upstream/fedora-40/man1/imgtoppm.1 new file mode 100644 index 00000000..92d0d280 --- /dev/null +++ b/upstream/fedora-40/man1/imgtoppm.1 @@ -0,0 +1,55 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Imgtoppm User Manual" 0 "05 September 1989" "netpbm documentation" + +.SH NAME +imgtoppm - convert an Img-whatnot file into a PPM image + +.UN synopsis +.SH SYNOPSIS + +\fBimgtoppm\fP +[\fIimgfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBimgtoppm\fPreads an Img-whatnot file as input and produces a +PPM image as output. The Img-whatnot toolkit is available for FTP on +venera.isi.edu, along with numerous images in this format. + +.UN options +.SH OPTIONS +.PP +There are no command line options defined specifically +for \fBimgtoppm\fP, but it recognizes the options common to all +programs based on libnetpbm (See +.UR index.html#commonoptions + Common Options +.UE +\&.) + +.UN seealso +.SH SEE ALSO +.BR "ppm" (1)\c +\& + +.UN author +.SH AUTHOR + +Based on a simple conversion program posted to comp.graphics by Ed Falk. +.PP +Copyright (C) 1989 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/imgtoppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/includeres.1 b/upstream/fedora-40/man1/includeres.1 new file mode 100644 index 00000000..b8a0940a --- /dev/null +++ b/upstream/fedora-40/man1/includeres.1 @@ -0,0 +1,65 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.1. +.TH INCLUDERES "1" "February 2023" "includeres 2.10" "User Commands" +.SH NAME +includeres - include resources in a PostScript document +.SH SYNOPSIS +.B includeres +[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]] +.SH DESCRIPTION +Include resources in a PostScript document. +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-v\fR, \fB\-\-version\fR +display version information and exit +.PP +.B includeres +includes resources (fonts, procsets, patterns, files, etc.) in place of +.B %%IncludeResource +comments in a PostScript document. +The resources are searched for under the resource name, and with an +appropriate extension. +The pipeline +.sp +.RS +extractres file.ps | includeres >out.ps +.RE +.sp +will move all resources appearing in a document to the document prologue, +removing redundant copies. +The output file can then be put through page re-arrangement filters such as +.B psnup +or +.B pstops +safely. + +.SS "Exit status:" +.TP +0 +if OK, +.TP +1 +if arguments or options are incorrect, or there is some other problem +starting up, +.TP +2 +if there is some problem during processing, typically an error reading or +writing an input or output file. +.SH AUTHOR +Written by Angus J. C. Duggan and Reuben Thomas. +.SH BUGS +.B includeres +does not alter the +.B %%DocumentNeededResources +comments. +.SH COPYRIGHT +Copyright \(co Reuben Thomas 2012\-2022. +.br +Copyright \(co Angus J. C. Duggan 1991\-1997. +.SH TRADEMARKS +.B PostScript +is a trademark of Adobe Systems Incorporated. +.SH "SEE ALSO" +.BR psutils (1), +.BR paper (1) diff --git a/upstream/fedora-40/man1/indent.1 b/upstream/fedora-40/man1/indent.1 new file mode 100644 index 00000000..c5307b67 --- /dev/null +++ b/upstream/fedora-40/man1/indent.1 @@ -0,0 +1,2185 @@ +.TH INDENT 1 +.SH "NAME" +indent \- changes the appearance of a C program by inserting or deleting whitespace. +.SH "SYNOPSIS" +.B "indent " +[options] [input\-files] +.sp +.B "indent " +[options] [single\-input\-file] [\-o output\-file] +.sp +.B "indent " +\-\-version +.SH "DESCRIPTION" +This man page is generated from the file \fIindent.texinfo\fR. +This is Edition of "The \fBindent\fR Manual", +for Indent Version , last updated . + +The \fBindent\fR program +can be used to make code easier to read. It can also convert from one +style of writing C to another. + +.B indent\fR understands a substantial amount about the syntax of C, +but it also attempts to cope with incomplete and misformed syntax. + +In version 1.2 and more recent versions, the GNU style of indenting is +the default. +.SH "OPTIONS" + +.TP 4 +.B -as\fR, \fB--align-with-spaces\fR +If using tabs for indentation, use spaces for alignment. +.br +See \fB\ INDENTATION\fR. +.TP +.B -bad\fR, \fB--blank-lines-after-declarations\fR +Force blank lines after the declarations. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bap\fR, \fB--blank-lines-after-procedures\fR +Force blank lines after procedure bodies. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bbb\fR, \fB--blank-lines-before-block-comments\fR +Force blank lines before block comments. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bbo\fR, \fB--break-before-boolean-operator\fR +Prefer to break long lines before boolean operators. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -bc\fR, \fB--blank-lines-after-commas\fR +Force newline after comma in declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bl\fR, \fB--braces-after-if-line\fR +Put braces on line after \fBif\fR, etc. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -blf\fR, \fB--braces-after-func-def-line\fR +Put braces on line following function definition line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bli\fIn\fB\fR, \fB--brace-indent\fIn\fB\fR +Indent braces \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -bls\fR, \fB--braces-after-struct-decl-line\fR +Put braces on the line after \fBstruct\fR declaration lines. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -br\fR, \fB--braces-on-if-line\fR +Put braces on line with \fBif\fR, etc. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -brf\fR, \fB--braces-on-func-def-line\fR +Put braces on function definition line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -brs\fR, \fB--braces-on-struct-decl-line\fR +Put braces on \fBstruct\fR declaration line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bs\fR, \fB--Bill-Shannon\fR, \fB--blank-before-sizeof\fR +Put a space between \fBsizeof\fR and its argument. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -c\fIn\fB\fR, \fB--comment-indentation\fIn\fB\fR +Put comments to the right of code in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cbi\fIn\fB\fR, \fB--case-brace-indentation\fIn\fB\fR +Indent braces after a case label N spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cd\fIn\fB\fR, \fB--declaration-comment-column\fIn\fB\fR +Put comments to the right of the declarations in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cdb\fR, \fB--comment-delimiters-on-blank-lines\fR +Put comment delimiters on blank lines. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cdw\fR, \fB--cuddle-do-while\fR +Cuddle while of \fBdo {} while;\fR and preceding \(oq}\(cq. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ce\fR, \fB--cuddle-else\fR +Cuddle else and preceding \(oq}\(cq. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ci\fIn\fB\fR, \fB--continuation-indentation\fIn\fB\fR +Continuation indent of \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cli\fIn\fB\fR, \fB--case-indentation\fIn\fB\fR +Case label indent of \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cp\fIn\fB\fR, \fB--else-endif-column\fIn\fB\fR +Put comments to the right of \fB#else\fR and \fB +#endif\fR statements in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cs\fR, \fB--space-after-cast\fR +Put a space after a cast operator. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -d\fIn\fB\fR, \fB--line-comments-indentation\fIn\fB\fR +Set indentation of comments not to the right +of code to \fIn\fR spaces. +.br +See \fB\ COMMENTS\fR. +.TP +.B -bfda\fR, \fB--break-function-decl-args\fR +Break the line before all arguments in a declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bfde\fR, \fB--break-function-decl-args-end\fR +Break the line after the last argument in a declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -dj\fR, \fB--left-justify-declarations\fR +If -cd 0 is used then comments after declarations are left justified +behind the declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -di\fIn\fB\fR, \fB--declaration-indentation\fIn\fB\fR +Put variables in column \fIn\fR. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -fc1\fR, \fB--format-first-column-comments\fR +Format comments in the first column. +.br +See \fB\ COMMENTS\fR. +.TP +.B -fca\fR, \fB--format-all-comments\fR +Do not disable all formatting of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -fnc\fR, \fB--fix-nested-comments\fR +Fix nested comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -gnu\fR, \fB--gnu-style\fR +Use GNU coding style. This is the default. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -gts\fR, \fB--gettext-strings\fR +Treat gettext \fB_("...")\fR and \fBN_("...")\fR as strings rather than as functions. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -hnl\fR, \fB--honour-newlines\fR +Prefer to break long lines at the position of newlines in the input. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -i\fIn\fB\fR, \fB--indent-level\fIn\fB\fR +Set indentation level to \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -il\fIn\fB\fR, \fB--indent-label\fIn\fB\fR +Set offset for labels to column \fIn\fR. +.br +See \fB\ INDENTATION\fR. +.TP +.B -ip\fIn\fB\fR, \fB--parameter-indentation\fIn\fB\fR +Indent parameter types in old-style function +definitions by \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -kr\fR, \fB--k-and-r-style\fR +Use Kernighan & Ritchie coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -l\fIn\fB\fR, \fB--line-length\fIn\fB\fR +Set maximum line length for non-comment lines to \fIn\fR. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -lc\fIn\fB\fR, \fB--comment-line-length\fIn\fB\fR +Set maximum line length for comment formatting to \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -linux\fR, \fB--linux-style\fR +Use Linux coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -lp\fR, \fB--continue-at-parentheses\fR +Line up continued lines at parentheses. +.br +See \fB\ INDENTATION\fR. +.TP +.B -lps\fR, \fB--leave-preprocessor-space\fR +Leave space between \(oq#\(cq and preprocessor directive. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nlps\fR, \fB--remove-preprocessor-space\fR +Remove space between \(oq#\(cq and preprocessor directive. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nbad\fR, \fB--no-blank-lines-after-declarations\fR +Do not force blank lines after declarations. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nbap\fR, \fB--no-blank-lines-after-procedures\fR +Do not force blank lines after procedure bodies. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nbbo\fR, \fB--break-after-boolean-operator\fR +Do not prefer to break long lines before boolean operators. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nbc\fR, \fB--no-blank-lines-after-commas\fR +Do not force newlines after commas in declarations. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nbfda\fR, \fB--dont-break-function-decl-args\fR +Don\(cqt put each argument in a function declaration on a separate line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -ncdb\fR, \fB--no-comment-delimiters-on-blank-lines\fR +Do not put comment delimiters on blank lines. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ncdw\fR, \fB--dont-cuddle-do-while\fR +Do not cuddle \fB}\fR and the \fBwhile\fR of a \fBdo {} while;\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nce\fR, \fB--dont-cuddle-else\fR +Do not cuddle \fB}\fR and \fBelse\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ncs\fR, \fB--no-space-after-casts\fR +Do not put a space after cast operators. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ndj\fIn\fB\fR, \fB--dont-left-justify-declarations\fR +Comments after declarations are treated the same as +comments after other statements. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nfc1\fR, \fB--dont-format-first-column-comments\fR +Do not format comments in the first column as normal. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nfca\fR, \fB--dont-format-comments\fR +Do not format any comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ngts\fR, \fB--no-gettext-strings\fR +Treat gettext \fB_("...")\fR and \fBN_("...")\fR as normal functions. This is the default. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nhnl\fR, \fB--ignore-newlines\fR +Do not prefer to break long lines at the position of newlines in the input. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nip\fR, \fB--no-parameter-indentation\fR +Zero width indentation for parameters. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nlp\fR, \fB--dont-line-up-parentheses\fR +Do not line up parentheses. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -npcs\fR, \fB--no-space-after-function-call-names\fR +Do not put space after the function in function calls. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nprs\fR, \fB--no-space-after-parentheses\fR +Do not put a space after every \(cq(\(cq and before every \(cq)\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -npsl\fR, \fB--dont-break-procedure-type\fR +Put the type of a procedure on the same line as its name. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nsaf\fR, \fB--no-space-after-for\fR +Do not put a space after every \fBfor\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsai\fR, \fB--no-space-after-if\fR +Do not put a space after every \fBif\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsaw\fR, \fB--no-space-after-while\fR +Do not put a space after every \fBwhile\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsc\fR, \fB--dont-star-comments\fR +Do not put the \(oq*\(cq character at the left of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nsob\fR, \fB--leave-optional-blank-lines\fR +Do not swallow optional blank lines. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nss\fR, \fB--dont-space-special-semicolon\fR +Do not force a space before the semicolon after certain statements. +Disables \(oq-ss\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ntac\fR, \fB--dont-tab-align-comments\fR +Do not pad comments out to the nearest tabstop. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nut\fR, \fB--no-tabs\fR +Use spaces instead of tabs. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nv\fR, \fB--no-verbosity\fR +Disable verbose mode. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -orig\fR, \fB--original\fR +Use the original Berkeley coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -npro\fR, \fB--ignore-profile\fR +Do not read \(oq.indent.pro\(cq files. +.br +See \fB\ INVOKING\ INDENT\fR. +.TP +.B -pal\fR, \fB--pointer-align-left\fR +Put asterisks in pointer declarations on the left of spaces, next to +types: \(oq\(oqchar* p\(cq\(cq. +.TP +.B -par\fR, \fB--pointer-align-right\fR +Put asterisks in pointer declarations on the right of spaces, next to +variable names: \(oq\(oqchar *p\(cq\(cq. This is the default behavior. +.TP +.B -pcs\fR, \fB--space-after-procedure-calls\fR +Insert a space between the name of the +procedure being called and the \(oq(\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -pi\fIn\fB\fR, \fB--paren-indentation\fIn\fB\fR +Specify the extra indentation per open parentheses \(cq(\(cq when a +statement is broken.See \fB\ STATEMENTS\fR. +.TP +.B -pmt\fR, \fB--preserve-mtime\fR +Preserve access and modification times on output files.See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -ppi\fIn\fB\fR, \fB--preprocessor-indentation\fIn\fB\fR +Specify the indentation for preprocessor conditional statements.See \fB\ INDENTATION\fR. +.TP +.B -prs\fR, \fB--space-after-parentheses\fR +Put a space after every \(cq(\(cq and before every \(cq)\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -psl\fR, \fB--procnames-start-lines\fR +Put the type of a procedure on the line before its name. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -saf\fR, \fB--space-after-for\fR +Put a space after each \fBfor\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sai\fR, \fB--space-after-if\fR +Put a space after each \fBif\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sar\fR, \fB--spaces-around-initializers\fR +Put a space after the \(oq{\(cq and before the \(oq}\(cq in initializers. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -saw\fR, \fB--space-after-while\fR +Put a space after each \fBwhile\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sbi\fIn\fB\fR, \fB--struct-brace-indentation\fIn\fB\fR +Indent braces of a struct, union or enum N spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sc\fR, \fB--start-left-side-of-comments\fR +Put the \(oq*\(cq character at the left of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -slc\fR, \fB--single-line-conditionals\fR +Allow for unbraced conditionals (\fBif\fR, \fBelse\fR, etc.) to have +their inner statement on the same line. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sob\fR, \fB--swallow-optional-blank-lines\fR +Swallow optional blank lines. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -ss\fR, \fB--space-special-semicolon\fR +On one-line \fBfor\fR and \fBwhile\fR statements, +force a blank before the semicolon. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -st\fR, \fB--standard-output\fR +Write to standard output. +.br +See \fB\ INVOKING\ INDENT\fR. +.TP +.B -T\fR +Tell \fBindent\fR the name of typenames. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -ts\fIn\fB\fR, \fB--tab-size\fIn\fB\fR +Set tab size to \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -ut\fR, \fB--use-tabs\fR +Use tabs. This is the default. +.br +See \fB\ INDENTATION\fR. +.TP +.B -v\fR, \fB--verbose\fR +Enable verbose mode. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -version\fR +Output the version number of \fBindent\fR. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. + +.SH "INVOKING INDENT" + +As of version 1.3, the format of the \fBindent\fR command is: + +.in +5 +.nf +.na + +indent [\fIoptions\fR] [\fIinput-files\fR] + +indent [\fIoptions\fR] [\fIsingle-input-file\fR] [-o \fIoutput-file\fR] + +.in -5 +.ad +.fi + +This format is different from earlier versions and other versions of +.B indent\fR. + +In the first form, one or more input files are specified. \fBindent\fR +makes a backup copy of each file, and the original file is replaced with +its indented version. See \fBBACKUP\ FILES\fR, for an explanation of how +backups are made. + +In the second form, only one input file is specified. In this case, or +when the standard input is used, you may specify an output file after +the \(oq-o\(cq option. + +To cause \fBindent\fR to write to standard output, use the \(oq-st\(cq +option. This is only allowed when there is only one input file, or when +the standard input is used. + +If no input files are named, the standard input is read for input. +Also, if a filename named \(oq-\(cq is specified, then the standard input +is read. + +As an example, each of the following commands will input the program +\(oqslithy_toves.c\(cq and write its indented text to +\(oqslithy_toves.out\(cq: + +.in +5 +.nf +.na + +indent slithy_toves.c -o slithy_toves.out + +indent -st slithy_toves.c > slithy_toves.out + +cat slithy_toves.c | indent -o slithy_toves.out + +.in -5 +.ad +.fi + +Most other options to \fBindent\fR control how programs are formatted. +As of version 1.2, \fBindent\fR also recognizes a long name for each +option name. Long options are prefixed by either \(oq--\(cq or +\(oq+\(cq. +[ \(oq+\(cq is being superseded by \(oq--\(cq to +maintain consistency with the POSIX standard.] + In most of this document, +the traditional, short names are used for the sake of brevity. +See \fBOPTION\ SUMMARY\fR, for a list of options, including both long and +short names. + +Here is another example: + +.in +5 +.nf +.na +indent -br test/metabolism.c -l85 +.in -5 +.ad +.fi + +This will indent the program \(oqtest/metabolism.c\(cq using the +\(oq-br\(cq and \(oq-l85\(cq options, write the output back to +\(oqtest/metabolism.c\(cq, and write the original contents of +\(oqtest/metabolism.c\(cq to a backup file in the directory \(oqtest\(cq. + +Equivalent invocations using long option names for this example would +be: + +.in +5 +.nf +.na + +indent --braces-on-if-line --line-length185 test/metabolism.c + +indent +braces-on-if-line +line-length185 test/metabolism.c + +.in -5 +.ad +.fi + +If you find that you often use \fBindent\fR with the same options, you +may put those options into a file named \(oq.indent.pro\(cq. +.B indent\fR will look for a profile file in three places. First it will check +the environment variable \fBINDENT_PROFILE\fR. If that exists its value +is expected to name the file that is to be used. If the environment variable does +not exist, indent looks for \(oq.indent.pro\(cq in the current directory + and use that if found. Finally \fBindent\fR will search +your home directory for \(oq.indent.pro\(cq and use that file if it is +found. This behaviour is different from that of other versions of +.B indent\fR, which load both files if they both exist. + +The format of \(oq.indent.pro\(cq is simply a list of options, just as +they would appear on the command line, separated by white space (tabs, +spaces, and newlines). Options in \(oq.indent.pro\(cq may be surrounded by C +or C++ comments, in which case they are ignored. + +Command line switches are handled \fIafter\fR processing +\(oq .indent.pro\(cq. Options specified later override arguments +specified earlier, with one exception: Explicitly specified options +always override background options (See \fBCOMMON\ STYLES\fR). You can +prevent \fBindent\fR from reading an \(oq.indent.pro\(cq file by +specifying the \(oq-npro\(cq option. + +.SH "BACKUP FILES" + +As of version 1.3, GNU \fBindent\fR makes GNU-style backup files, the +same way GNU Emacs does. This means that either \fIsimple\fR or +.I numbered\fR backup filenames may be made. + +Simple backup file names are generated by appending a suffix to the +original file name. The default for this suffix is the +one-character string \(oq~\(cq (tilde). Thus, the backup file for +\(oqpython.c\(cq would be \(oqpython.c~\(cq. + +Instead of the default, you may specify any string as a suffix by +setting the environment variable \fBSIMPLE_BACKUP_SUFFIX\fR to +your preferred suffix. + +Numbered backup versions of a file \(oqmomeraths.c\(cq look like +\(oqmomeraths.c.~23~\(cq, where 23 is the version of this particular +backup. When making a numbered backup of the file \(oqsrc/momeraths.c\(cq, +the backup file will be named \(oqsrc/momeraths.c.~\fIV\fR~\(cq, where +.I V\fR is one greater than the highest version currently existing in +the directory \(oqsrc\(cq. The environment variable \fBVERSION_WIDTH\fR +controls the number of digits, using left zero padding when necessary. +For instance, setting this variable to "2" will lead to the backup +file being named \(oqmomeraths.c.~04~\(cq. + +The type of backup file made is controlled by the value of the +environment variable \fBVERSION_CONTROL\fR. If it is the string +\(oqsimple\(cq, then only simple backups will be made. If its value is +the string \(oqnumbered\(cq, then numbered backups will be made. If its +value is \(oqnumbered-existing\(cq, then numbered backups will be made if +there \fIalready exist\fR numbered backups for the file being indented; +otherwise, a simple backup is made. If \fBVERSION_CONTROL\fR is not +set, then \fBindent\fR assumes the behaviour of +\(oqnumbered-existing\(cq. + +Other versions of \fBindent\fR use the suffix \(oq.BAK\(cq in naming +backup files. This behaviour can be emulated by setting +.B SIMPLE_BACKUP_SUFFIX\fR to \(oq.BAK\(cq. + +Note also that other versions of \fBindent\fR make backups in the +current directory, rather than in the directory of the source file as +GNU \fBindent\fR now does. + +.SH "COMMON STYLES" + +There are several common styles of C code, including the GNU style, the +Kernighan & Ritchie style, and the original Berkeley style. A style may +be selected with a single \fIbackground\fR option, which specifies a set +of values for all other options. However, explicitly specified options +always override options implied by a background option. + +As of version 1.2, the default style of GNU \fBindent\fR is the GNU +style. Thus, it is no longer necessary to specify the option +\(oq-gnu\(cq to obtain this format, although doing so will not cause an +error. Option settings which correspond to the GNU style are: + +.in +5 +.nf +.na +-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 +-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -nprs -psl -saf -sai +-saw -nsc -nsob +.in -5 +.ad +.fi + +The GNU coding style is that preferred by the GNU project. It is the +style that the GNU Emacs C mode encourages and which is used in the C +portions of GNU Emacs. (People interested in writing programs for +Project GNU should get a copy of "The GNU Coding Standards", which +also covers semantic and portability issues such as memory usage, the +size of integers, etc.) + +The Kernighan & Ritchie style is used throughout their well-known book +"The C Programming Language". It is enabled with the \(oq-kr\(cq +option. The Kernighan & Ritchie style corresponds to the following set +of options: + +.in +5 +.nf +.na +-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0 +-cp33 -cs -d0 -di1 -nfc1 -nfca -hnl -i4 -ip0 -l75 -lp -npcs +-nprs -npsl -saf -sai -saw -nsc -nsob -nss -par +.in -5 +.ad +.fi + +Kernighan & Ritchie style does not put comments to the right of code in +the same column at all times (nor does it use only one space to the +right of the code), so for this style \fBindent\fR has arbitrarily +chosen column 33. + +The style of the original Berkeley \fBindent\fR may be obtained by +specifying \(oq-orig\(cq (or by specifying \(oq--original\(cq, using the +long option name). This style is equivalent to the following settings: + +.in +5 +.nf +.na +-nbad -nbap -bbo -bc -br -brs -c33 -cd33 -cdb -ce -ci4 -cli0 +-cp33 -di16 -fc1 -fca -hnl -i4 -ip4 -l75 -lp -npcs -nprs -psl +-saf -sai -saw -sc -nsob -nss -ts8 +.in -5 +.ad +.fi + +The Linux style is used in the linux kernel code and drivers. Code +generally has to follow the Linux coding style to be accepted. +This style is equivalent to the following settings: + +.in +5 +.nf +.na +-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 +-cli0 -d0 -di1 -nfc1 -i8 -ip0 -l80 -lp -npcs -nprs -npsl -sai +-saf -saw -ncs -nsc -sob -nfca -cp33 -ss -ts8 -il1 +.in -5 +.ad +.fi + +.SH "BLANK LINES" + +Various programming styles use blank lines in different places. +.B indent\fR has a number of options to insert or delete blank lines in +specific places. + +The \(oq-bad\(cq option causes \fBindent\fR to force a blank line after +every block of declarations. The \(oq-nbad\(cq option causes +.B indent\fR not to force such blank lines. + +The \(oq-bap\(cq option forces a blank line after every procedure body. +The \(oq-nbap\(cq option forces no such blank line. + +The \(oq-bbb\(cq option forces a blank line before every boxed comment +(See \fBCOMMENTS\fR.) +The \(oq-nbbb\(cq option does not force such blank lines. + +The \(oq-sob\(cq option causes \fBindent\fR to swallow optional blank +lines (that is, any optional blank lines present in the input will be +removed from the output). If the \(oq-nsob\(cq is specified, any blank +lines present in the input file will be copied to the output file. + + +.SH "--blank-lines-after-declarations" + +The \(oq-bad\(cq option forces a blank line after every block of +declarations. The \(oq-nbad\(cq option does not add any such blank +lines. + +For example, given the input +.in +5 +.nf +.na +char *foo; +char *bar; +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +.B indent -bad\fR produces + +.in +5 +.nf +.na +char *foo; +char *bar; + +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +and \fBindent -nbad\fR produces + +.in +5 +.nf +.na +char *foo; +char *bar; +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +.SH "--blank-lines-after-procedures" + +The \(oq-bap\(cq option forces a blank line after every procedure body. + +For example, given the input + +.in +5 +.nf +.na +int +foo () +{ + puts("Hi"); +} +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts("Hello"); +} +.in -5 +.ad +.fi + +.B indent -bap\fR produces + +.in +5 +.nf +.na +int +foo () +{ + puts ("Hi"); +} + +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts ("Hello"); +} +.in -5 +.ad +.fi + +and \fBindent -nbap\fR produces + +.in +5 +.nf +.na +int +foo () +{ + puts ("Hi"); +} +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts ("Hello"); +} +.in -5 +.ad +.fi + +No blank line will be added after the procedure \fBfoo\fR. + +.SH "COMMENTS" + +.B indent\fR formats both C and C++ comments. C comments are begun with +\(oq/*\(cq, terminated with \(oq*/\(cq and may contain newline characters. +C++ comments begin with the delimiter \(oq//\(cq and end at the newline. + +.B indent\fR handles comments differently depending upon their context. +.B indent\fR attempts to distinguish between comments which follow +statements, comments which follow declarations, comments following +preprocessor directives, and comments which are not preceded by code of +any sort, i.e., they begin the text of the line (although not +necessarily in column 1). + +.B indent\fR further distinguishes between comments found outside of +procedures and aggregates, and those found within them. In particular, +comments beginning a line found within a procedure will be indented to +the column at which code is currently indented. The exception to this +is a comment beginning in the leftmost column; such a comment is output +at that column. + +.B indent\fR attempts to leave \fIboxed comments\fR unmodified. The +general idea of such a comment is that it is enclosed in a rectangle or +\(oq\(oqbox\(cq\(cq of stars or dashes to visually set it apart. More precisely, +boxed comments are defined as those in which the initial \(oq/*\(cq is +followed immediately by the character \(oq*\(cq, \(oq=\(cq, \(oq_\(cq, or +\(oq-\(cq, or those in which the beginning comment delimiter (\(oq/*\(cq) +is on a line by itself, and the following line begins with a \(oq*\(cq in +the same column as the star of the opening delimiter. + +Examples of boxed comments are: + +.in +5 +.nf +.na +/********************** + * Comment in a box!! * + **********************/ + + /* + * A different kind of scent, + * for a different kind of comment. + */ +.in -5 +.ad +.fi + +.B indent\fR attempts to leave boxed comments exactly as they are found +in the source file. Thus the indentation of the comment is unchanged, +and its length is not checked in any way. The only alteration made is +that an embedded tab character may be converted into the appropriate +number of spaces. + +If the \(oq-bbb\(cq option is specified, all such boxed comments will be +preceded by a blank line, unless such a comment is preceded by code. + +Comments which are not boxed comments may be formatted, which means that +the line is broken to fit within a right margin and left-filled with +whitespace. Single newlines are equivalent to a space, but blank lines +(two or more newlines in a row) are taken to mean a paragraph break. +Formatting of comments which begin after the first column is enabled +with the \(oq-fca\(cq option. To format those beginning in column one, +specify \(oq-fc1\(cq. Such formatting is disabled by default. + +The right margin for formatting defaults to 78, but may be changed with +the \(oq-lc\(cq option. If the margin specified does not allow the +comment to be printed, the margin will be automatically extended for the +duration of that comment. The margin is not respected if the comment is +not being formatted. + +If the \(oq-fnc\(cq option is specified, all comments with \(oq/*\(cq +embedded will have that character sequence replaced by a space followed +by the character \(oq*\(cq thus eliminating nesting. + +If the comment begins a line (i.e., there is no program text to its +left), it will be indented to the column it was found in unless the +comment is within a block of code. In that case, such a comment will be +aligned with the indented code of that block (unless the comment began +in the first column). This alignment may be affected by the \(oq-d\(cq +option, which specifies an amount by which such comments are moved to +the \fIleft\fR, or unindented. For example, \(oq-d2\(cq places comments +two spaces to the left of code. By default, comments are aligned with +code, unless they begin in the first column, in which case they are left +there by default --- to get them aligned with the code, specify \(oq-fc1\(cq. + +Comments to the right of code will appear by default in column 33. +This may be changed with one of three options. \(oq-c\(cq will specify +the column for comments following code, \(oq-cd\(cq specifies the +column for comments following declarations, and \(oq-cp\(cq specifies +the column for comments following preprocessor directives \fB#else\fR +and \fB#endif\fR. \(oq-dj\(cq together with \(oq-cd0\(cq can be used +to suppress alignment of comments to the right of declarations, causing the +comment to follow one tabstop from the end of the declaration. Normally \(oq-cd0\(cq +causes \(oq-c\(cq to become effective. + +If the code to the left of the comment exceeds the beginning column, +the comment column will be extended to the next tabstop column past +the end of the code, unless the \(oq-ntac\(cq option is specified. +In the case of preprocessor directives,comments are extended to to one +space past the end of the directive. This extension lasts only for +the output of that particular comment. + +The \(oq-cdb\(cq option places the comment delimiters on blank lines. +Thus, a single line comment like \fB/* Loving hug */\fR can be +transformed into: + +.in +5 +.nf +.na +/* + Loving hug + */ +.in -5 +.ad +.fi + +Stars can be placed at the beginning of multi-line comments with the +\(oq-sc\(cq option. Thus, the single-line comment above can be +transformed (with \(oq-cdb -sc\(cq) into: + +.in +5 +.nf +.na +/* + * Loving hug + */ +.in -5 +.ad +.fi + +.SH "STATEMENTS" + +The \(oq-br\(cq or \(oq-bl\(cq option specifies how to format braces. + +The \(oq-br\(cq option formats statement braces like this: + +.in +5 +.nf +.na +if (x > 0) { + x--; +} +.in -5 +.ad +.fi + +The \(oq-bl\(cq option formats them like this: + +.in +5 +.nf +.na +if (x > 0) + { + x--; + } +.in -5 +.ad +.fi + +If you use the \(oq-bl\(cq option, you may also want to specify the +\(oq-bli\(cq option. This option specifies the number of spaces by +which braces are indented. \(oq-bli2\(cq, the default, gives the +result shown above. \(oq-bli0\(cq results in the following: + +.in +5 +.nf +.na +if (x > 0) +{ + x--; +} +.in -5 +.ad +.fi + +If you are using the \(oq-br\(cq option, you probably want to also use +the \(oq-ce\(cq option. This causes the \fBelse\fR in an if-then-else +construct to cuddle up to the immediately preceding \(oq}\(cq. For +example, with \(oq-br -ce\(cq you get the following: + +.in +5 +.nf +.na +if (x > 0) { + x--; +} else { + fprintf (stderr, "...something wrong?\\n"); +} +.in -5 +.ad +.fi + +With \(oq-br -nce\(cq that code would appear as + +.in +5 +.nf +.na +if (x > 0) { + x--; +} +else { + fprintf (stderr, "...something wrong?\\n"); +} +.in -5 +.ad +.fi + +An exception to the behavior occurs when there is a comment between the +right brace and the subsequent else statement. While the \(oq-br\(cq +option will cause a left brace to jump over the comment, the else does +not jump over the comment to cuddle because it has a strong likelihood +of changing the meaning of the comment. + +The \(oq-cdw\(cq option causes the \fBwhile\fR in a do-while +loop to cuddle up to the immediately preceding \(oq}\(cq. For +example, with \(oq-cdw\(cq you get the following: + +.in +5 +.nf +.na +do { + x--; +} while (x); +.in -5 +.ad +.fi + +With \(oq-ncdw\(cq that code would appear as + +.in +5 +.nf +.na +do { + x--; +} +while (x); +.in -5 +.ad +.fi + +The \(oq-slc\(cq option allows for an unbraced conditional and its inner +statement to appear on the same line. For example: + +.in +5 +.nf +.na +if (x) x--; +else x++; +.in -5 +.ad +.fi + +Without \(oq-slc\(cq that code would appear as + +.in +5 +.nf +.na +if (x) + x--; +else + x++; +.in -5 +.ad +.fi + +The \(oq-cli\(cq option specifies the number of spaces that case labels +should be indented to the right of the containing \fBswitch\fR +statement. + +The default gives code like: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +Using the \(oq-cli2\(cq that would become: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +The indentation of the braces below a case statement can be +controlled with the \(oq-cbi\fIn\fR\(cq option. For example, +using \(oq-cli2 -cbi0\(cq results in: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +If a semicolon is on the same line as a \fBfor\fR or \fBwhile\fR +statement, the \(oq-ss\(cq option will cause a space to be placed before +the semicolon. This emphasizes the semicolon, making it clear that the +body of the \fBfor\fR or \fBwhile\fR statement is an empty statement. +\(oq-nss\(cq disables this feature. + +The \(oq-pcs\(cq option causes a space to be placed between the name of +the procedure being called and the \(oq(\(cq (for example, \fBputs\ ("Hi");\fR. The \(oq-npcs\(cq option would give \fBputs("Hi");\fR). + + +If the \(oq-cs\(cq option is specified, \fBindent\fR puts a space between +a cast operator and the object to be cast. The \(oq-ncs\(cq ensures that there +is no space between the cast operator and the object. Remember that \fBindent\fR +only knows about the standard C data types and so cannot recognise user-defined types +in casts. Thus \fB(mytype)thing\fR is not treated as a cast. + +The \(oq-bs\(cq option ensures that there is a space between the +keyword \fBsizeof\fR and its argument. In some versions, this is +known as the \(oqBill_Shannon\(cq option. + +The \(oq-saf\(cq option forces a space between a \fBfor\fR +and the following parenthesis. This is the default. + +The \(oq-sai\(cq option forces a space between a \fBif\fR +and the following parenthesis. This is the default. + +The \(oq-saw\(cq option forces a space between a \fBwhile\fR +and the following parenthesis. This is the default. + +The \(oq-prs\(cq option causes all parentheses to be separated with +a space from whatever is between them. For example, using \(oq-prs\(cq +results in code like: + +.in +5 +.nf +.na + while ( ( e_code - s_code ) < ( dec_ind - 1 ) ) + { + set_buf_break ( bb_dec_ind ); + *e_code++ = \(cq \(cq; + } +.in -5 +.ad +.fi + +.SH "DECLARATIONS" + +By default \fBindent\fR will line up identifiers, in the column +specified by the \(oq-di\(cq option. For example, \(oq-di16\(cq makes +things look like: + +.in +5 +.nf +.na +int foo; +char *bar; +.in -5 +.ad +.fi + +Using a small value (such as one or two) for the \(oq-di\(cq option can +be used to cause the identifiers to be placed in the first available +position; for example: + +.in +5 +.nf +.na +int foo; +char *bar; +.in -5 +.ad +.fi + +The value given to the \(oq-di\(cq option will still affect variables +which are put on separate lines from their types, for example +\(oq-di2\(cq will lead to: + +.in +5 +.nf +.na +int + foo; +.in -5 +.ad +.fi + +If the \(oq-bc\(cq option is specified, a newline is forced after each +comma in a declaration. For example, + +.in +5 +.nf +.na +int a, + b, + c; +.in -5 +.ad +.fi + +With the \(oq-nbc\(cq option this would look like + +.in +5 +.nf +.na +int a, b, c; +.in -5 +.ad +.fi + +The \(oq-bfda\(cq option causes a newline to be forced after the comma +separating the arguments of a function declaration. The arguments will +appear at one indention level deeper than the function declaration. This +is particularly helpful for functions with long argument lists. +The option \(oq-bfde\(cq causes a newline to be forced before the closing +bracket of the function declaration. For both options the \(cqn\(cq setting is the default: +-nbfda and -nbfde. + + +For +example, + +.in +5 +.nf +.na +void foo (int arg1, char arg2, int *arg3, long arg4, char arg5); +.in -5 +.ad +.fi +With the \(oq-bfda\(cq option this would look like + +.in +5 +.nf +.na +void foo ( + int arg1, + char arg2, + int *arg3, + long arg4, + char arg5); +.in -5 +.ad +.fi + +With, in addition, the \(oq-bfde\(cq option this would look like + +.in +5 +.nf +.na +void foo ( + int arg1, + char arg2, + int *arg3, + long arg4, + char arg5 + ); +.in -5 +.ad +.fi + +The \(oq-psl\(cq option causes the type of a procedure being defined to +be placed on the line before the name of the procedure. This style is +required for the \fBetags\fR program to work correctly, as well as some +of the \fBc-mode\fR functions of Emacs. + +You must use the \(oq-T\(cq +option to tell \fBindent\fR the name of all the typenames in your +program that are defined by \fBtypedef\fR. \(oq-T\(cq can be specified +more than once, and all names specified are used. For example, if your +program contains + +.in +5 +.nf +.na +typedef unsigned long CODE_ADDR; +typedef enum {red, blue, green} COLOR; +.in -5 +.ad +.fi + +you would use the options \(oq-T CODE_ADDR -T COLOR\(cq. + + +The \(oq-brs\(cq or \(oq-bls\(cq option specifies how to format braces +in struct declarations. The \(oq-brs\(cq option formats braces like +this: + +.in +5 +.nf +.na +struct foo { + int x; +}; +.in -5 +.ad +.fi + +The \(oq-bls\(cq option formats them like this: + +.in +5 +.nf +.na +struct foo +{ + int x; +}; +.in -5 +.ad +.fi + + +Similarly to the structure brace \(oq-brs\(cq and \(oq-bls\(cq options, + the function brace options \(oq-brf\(cq or \(oq-blf\(cq specify how to format the braces +in function definitions. The \(oq-brf\(cq option formats braces like +this: + +.in +5 +.nf +.na +int one(void) { + return 1; +}; +.in -5 +.ad +.fi + +The \(oq-blf\(cq option formats them like this: + +.in +5 +.nf +.na +int one(void) +{ + return 1; +}; +.in -5 +.ad +.fi + + +The \(oq-sar\(cq option affects how \fBindent\fR will render initializer +lists. Without \(oq-sar\(cq they are formatted like this: + +.in +5 +.nf +.na +int a[] = {1, 2, 3, 4}; + +struct s { + const char *name; + int x; +} a[] = { + {"name", 0}, + {"a", 1} +}; +.in -5 +.ad +.fi + +With \(oq-sar\(cq they are formatted like this, with spaces inside the +braces: + +.in +5 +.nf +.na +int a[] = { 1, 2, 3, 4 }; + +struct s { + const char *name; + int x; +} a[] = { + { "name", 0 }, + { "a", 1 } +}; +.in -5 +.ad +.fi + +.SH "INDENTATION" + +The most basic, and most controversial issues with regard to code +formatting is precisely how indentation should be acoomplished. +Fortunately, \fBindent\fR supports several different styles of +identation. The default is to use tabs for indentation, which is +specified by the \(oq-ut\(cq option. Assuming the default tab size of +8, the code would look like this: + +.in +5 +.nf +.na +int a(int b) +{ + return b; +|------| + 1 tab +} +.in -5 +.ad +.fi + +For those that prefer spaces to tabs, \(oqindent\(cq provides the +\(oq-nut\(cq option. The same code would look like this: + +.in +5 +.nf +.na +int a(int b) +{ + return b; +|------| +8 spaces +} +.in -5 +.ad +.fi + +Another issue in the formatting of code is how far each line should be +indented from the left margin. When the beginning of a statement such +as \fBif\fR or \fBfor\fR is encountered, the indentation level is +increased by the value specified by the \(oq-i\(cq option. For example, +use \(oq-i8\(cq to specify an eight character indentation for each +level. When a statement is broken across two lines, the second line is +indented by a number of additional spaces specified by the \(oq-ci\(cq +option. \(oq-ci\(cq defaults to 0. However, if the \(oq-lp\(cq option is +specified, and a line has a left parenthesis which is not closed on that +line, then continuation lines will be lined up to start at the character +position just after the left parenthesis. This processing also applies +to \(oq[\(cq and applies to \(oq{\(cq when it occurs in initialization +lists. For example, a piece of continued code might look like this with +\(oq-nlp -ci3\(cq in effect: + +.in +5 +.nf +.na + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +.in -5 +.ad +.fi + +With \(oq-lp\(cq in effect the code looks somewhat clearer: + +.in +5 +.nf +.na + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +.in -5 +.ad +.fi + +When a statement is broken in between two or more paren pairs (...), +each extra pair causes the indentation level extra indentation: + +.in +5 +.nf +.na +if ((((i < 2 && + k > 0) || p == 0) && + q == 1) || + n = 0) +.in -5 +.ad +.fi + +The option \(oq-ip\fIN\fR\(cq can be used to set the extra offset per paren. +For instance, \(oq-ip0\(cq would format the above as: + +.in +5 +.nf +.na +if ((((i < 2 && + k > 0) || p == 0) && + q == 1) || + n = 0) +.in -5 +.ad +.fi + +.B indent\fR assumes that tabs are placed at regular intervals of both +input and output character streams. These intervals are by default 8 +columns wide, but (as of version 1.2) may be changed by the \(oq-ts\(cq +option. Tabs are treated as the equivalent number of spaces. + +By default, \fBindent\fR will use tabs to indent as far as possible, +and then pad with spaces until the desired position is reached. However, +with the \(oq-as\(cq option, spaces will be used for alignment beyond +the current indentation level. By default, assuming \(oq-lp\(cq is +enabled, the code would be indented like so (\(oqt\(cq represents tabs, +\(oqs\(cq represents spaces): + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +|------||-------||------||-------|__ + t t t t ss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|------||------||------|_____ + t t t sssss +} +.in -5 +.ad +.fi + +This is fine, if you assume that whoever is reading the code will honor +your assumption of 8-space tabs. If the reader was using 4-space tabs, +it would look like this: + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +|---||---||---||---|__ + t t t t ss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|---||---||---|______ + t t t ssssss +} +.in -5 +.ad +.fi + +The \(oq-as\(cq option fixes this so that the code will appear consistent +regardless of what tab size the user users to read the code. This looks +like: + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +____________________________________ +ssssssssssssssssssssssssssssssssssss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|------|______________________ + t ssssssssssssssssssssss +} +.in -5 +.ad +.fi + +The indentation of type declarations in old-style function definitions +is controlled by the \(oq-ip\(cq parameter. This is a numeric parameter +specifying how many spaces to indent type declarations. For example, +the default \(oq-ip5\(cq makes definitions look like this: + +.in +5 +.nf +.na +char * +create_world (x, y, scale) + int x; + int y; + float scale; +{ + . . . +} +.in -5 +.ad +.fi + +For compatibility with other versions of indent, the option \(oq-nip\(cq +is provided, which is equivalent to \(oq-ip0\(cq. + +ANSI C allows white space to be placed on preprocessor command lines +between the character \(oq#\(cq and the command name. By default, +.B indent\fR removes this space, but specifying the \(oq-lps\(cq option +directs \fBindent\fR to leave this space unmodified. The option \(oq-ppi\(cq +overrides \(oq-nlps\(cq and \(oq-lps\(cq. + +This option can be used to request that preprocessor conditional statements can +be indented by to given number of spaces, for example with the option \(oq-ppi 3\(cq + +.in +5 +.nf +.na +#if X +#if Y +#define Z 1 +#else +#define Z 0 +#endif +#endif +.in -5 +.ad +.fi +becomes +.in +5 +.nf +.na +#if X +# if Y +# define Z 1 +# else +# define Z 0 +# endif +#endif +.in -5 +.ad +.fi + +This option sets the offset at which a label (except case labels) +will be positioned. If it is set to zero or a positive number, this indicates how +far from the left margin to indent a label. If it is set to a negative number, +this indicates how far back from the current indent level to place the label. +The default setting is -2 which matches the behaviour of earlier versions of indent. +Note that this parameter does not affect the placing of case labels; see the +\(oq-cli\(cq parameter for that. For example with the option \(oq-il 1\(cq + +.in +5 +.nf +.na +group +function() +{ + if (do_stuff1() == ERROR) + goto cleanup1; + + if (do_stuff2() == ERROR) + goto cleanup2; + + return SUCCESS; + + cleanup2: + do_cleanup2(); + + cleanup1: + do_cleanup1(); + + return ERROR; +} +.in -5 +.ad +.fi +becomes +.in +5 +.nf +.na +group +function() +{ + if (do_stuff1() == ERROR) + goto cleanup1; + + if (do_stuff2() == ERROR) + goto cleanup2; + + return SUCCESS; + + cleanup2: + do_cleanup2(); + + cleanup1: + do_cleanup1(); + + return ERROR; +} +.in -5 +.ad +.fi + +.SH "BREAKING LONG LINES" + +With the option \(oq-l\fIn\fR\(cq, or \(oq--line-length\fIn\fR\(cq, it is +possible to specify the maximum length of a line of C code, not including +possible comments that follow it. + +When lines become longer than the specified line length, GNU \fBindent\fR +tries to break the line at a logical place. This is new as of version 2.1 +however and not very intelligent or flexible yet. + +Currently there are three options that allow one to interfere with the +algorithm that determines where to break a line. + +The \(oq-bbo\(cq option causes GNU \fBindent\fR to prefer to break +long lines before the boolean operators \fB&&\fR and \fB||\fR. The +\(oq-nbbo\(cq option causes GNU \fBindent\fR not have that +preference. For example, the default option \(oq-bbo\(cq (together +with \(oq--line-length60\(cq and \(oq--ignore-newlines\(cq) makes code +look like this: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq + && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +Using the option \(oq-nbbo\(cq will make it look like this: + +.in +5 +.nf +.na + if (mask && + ((mask[0] == \(cq\\0\(cq) || + (mask[1] == \(cq\\0\(cq && + ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +The default \(oq-hnl\(cq, however, honours newlines in the input file by +giving them the highest possible priority to break lines at. For example, +when the input file looks like this: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +then using the option \(oq-hnl\(cq, or \(oq--honour-newlines\(cq, +together with the previously mentioned \(oq-nbbo\(cq and +\(oq--line-length60\(cq, will cause the output not to be what is given +in the last example but instead will prefer to break at the positions +where the code was broken in the input file: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq && + ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +The idea behind this option is that lines which are too long, but are already +broken up, will not be touched by GNU \fBindent\fR. Really messy code +should be run through \fBindent\fR at least once using the +\(oq--ignore-newlines\(cq option though. + +The \(oq-gts\(cq option affects how the gettext standard macros \fB_()\fR and \fBN_()\fR +are treated. The default behavior (or the use of \(oq-ngts\(cq) causes indent to +treat them as it does other functions, so that a long string is broken like the following +example. + +.in +5 +.nf +.na + if (mask) + { + warning (_ + ("This is a long string that stays together.")); + } +.in -5 +.ad +.fi + +With the \(oq-gts\(cq option, the underscore is treated as a part of the string, keeping +it tied to the string, and respecting the fact that gettext is unobtrusively providing +a localized string. This only works if \fB_("\fR is together as a unit at the beginning +of the string and \fB")\fR is together as a unit at the end. + +.in +5 +.nf +.na + if (mask) + { + warning + (_("This is a long string that stays together.")); + } +.in -5 +.ad +.fi + +.SH "DISABLING FORMATTING" + +Formatting of C code may be disabled for portions of a program by +embedding special \fIcontrol comments\fR in the program. To turn off +formatting for a section of a program, place the disabling control +comment \fB/* *INDENT-OFF* */\fR on a line by itself just before that +section. Program text scanned after this control comment is output +precisely as input with no modifications until the corresponding +enabling comment is scanned on a line by itself. The enabling control +comment is \fB/* *INDENT-ON* */\fR, and any text following the comment +on the line is also output unformatted. Formatting begins again with +the input line following the enabling control comment. + +More precisely, \fBindent\fR does not attempt to verify the closing +delimiter (\fB*/\fR) for these C comments, and any whitespace on the +line is totally transparent. + +These control comments also function in their C++ formats, namely +.B // *INDENT-OFF*\fR and \fB// *INDENT-ON*\fR. + +It should be noted that the internal state of \fBindent\fR remains +unchanged over the course of the unformatted section. Thus, for +example, turning off formatting in the middle of a function and +continuing it after the end of the function may lead to bizarre +results. It is therefore wise to be somewhat modular in selecting code +to be left unformatted. + +As a historical note, some earlier versions of \fBindent\fR produced +error messages beginning with \fB*INDENT**\fR. These versions of +.B indent\fR were written to ignore any input text lines which began +with such error messages. I have removed this incestuous feature from +GNU \fBindent\fR. + +.SH "MISCELLANEOUS OPTIONS" + +To find out what version of \fBindent\fR you have, use the command +.B indent -version\fR. This will report the version number of +.B indent\fR, without doing any of the normal processing. + +The \(oq-v\(cq option can be used to turn on verbose mode. When in +verbose mode, \fBindent\fR reports when it splits one line of input +into two more more lines of output, and gives some size statistics at +completion. + +The \(oq-pmt\(cq option causes \fBindent\fR to preserve the access +and modification times on the output files. Using this option +has the advantage that running indent on all source and header +files in a project won\(cqt cause \fBmake\fR to rebuild all targets. +This option is only available on Operating Systems that have the +POSIX \fButime(2)\fR function. + +.SH "BUGS" + +Please report any bugs to bug-indent@gnu.org. + +When \fBindent\fR is run twice on a file, with the same profile, +it should \fInever\fR change that file the second time. With the +current design of \fBindent\fR, this can not be guaranteed, +and it has not been extensively tested. + +.B indent\fR does not understand C. In some cases this leads to +the inability to join lines. The result is that running a file +through \fBindent\fR is \fIirreversible\fR, even if the used input +file was the result of running \fBindent\fR with a given profile +(\(oq.indent.pro\(cq). + +While an attempt was made to get \fBindent\fR working for C++, it +will not do a good job on any C++ source except the very simplest. + +.B indent\fR does not look at the given \(oq--line-length\(cq option +when writing comments to the output file. This results often in comments +being put far to the right. In order to prohibit \fBindent\fR from +joining a broken line that has a comment at the end, make sure that the +comments start on the first line of the break. + +.B indent\fR does not count lines and comments (see the \(oq-v\(cq +option) when \fBindent\fR is turned off with +.B /* *INDENT-OFF* */\fR. + +Comments of the form \fB/*UPPERCASE*/\fR are not treated as comment but as an +identifier, causing them to be joined with the next line. This renders +comments of this type useless, unless they are embedded in the code to +begin with. + +.SH "COPYRIGHT" + +The following copyright notice applies to the \fBindent\fR program. +The copyright and copying permissions for this manual appear near the +beginning of \(oqindent.texinfo\(cq and \(oqindent.info\(cq, and near the +end of \(oqindent.1\(cq. + +.nf +.na +Copyright (c) 2015 Tim Hentenaar. +Copyright (c) 2001 David Ingamells. +Copyright (c) 1999 Carlo Wood. +Copyright (c) 1995, 1996 Joseph Arceneaux. +Copyright (c) 1989, 1992, 1993, 1994, 1995, 1996, 2014 Free Software Foundation +Copyright (c) 1985 Sun Microsystems, Inc. +Copyright (c) 1980 The Regents of the University of California. +Copyright (c) 1976 Board of Trustees of the University of Illinois. +All rights reserved. + +Redistribution and use in source and binary forms are permitted +provided that the above copyright notice and this paragraph are +duplicated in all such forms and that any documentation, +advertising materials, and other materials related to such +distribution and use acknowledge that the software was developed +by the University of California, Berkeley, the University of Illinois, +Urbana, and Sun Microsystems, Inc. The name of either University +or Sun Microsystems may not be used to endorse or promote products +derived from this software without specific prior written permission. +THIS SOFTWARE IS PROVIDED \(oq\(oqAS IS\(cq\(cq AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR +PURPOSE. +.ad +.fi + +.SH "Options\(cq Cross Key" + +Here is a list of options alphabetized by long option, to help you find +the corresponding short option. + + +.in +5 +.nf +.na +--align-with-spaces -as +--blank-lines-after-commas -bc +--blank-lines-after-declarations -bad +--blank-lines-after-procedures -bap +--blank-lines-before-block-comments -bbb +--braces-after-if-line -bl +--braces-after-func-def-line -blf +--brace-indent -bli +--braces-after-struct-decl-line -bls +--braces-on-if-line -br +--braces-on-func-def-line -brf +--braces-on-struct-decl-line -brs +--break-after-boolean-operator -nbbo +--break-before-boolean-operator -bbo +--break-function-decl-args -bfda +--break-function-decl-args-end -bfde +--case-indentation -cli\fIn\fR +--case-brace-indentation -cbi\fIn\fR +--comment-delimiters-on-blank-lines -cdb +--comment-indentation -c\fIn\fR +--continuation-indentation -ci\fIn\fR +--continue-at-parentheses -lp +--cuddle-do-while -cdw +--cuddle-else -ce +--declaration-comment-column -cd\fIn\fR +--declaration-indentation -di\fIn\fR +--dont-break-function-decl-args -nbfda +--dont-break-function-decl-args-end -nbfde +--dont-break-procedure-type -npsl +--dont-cuddle-do-while -ncdw +--dont-cuddle-else -nce +--dont-format-comments -nfca +--dont-format-first-column-comments -nfc1 +--dont-line-up-parentheses -nlp +--dont-left-justify-declarations -ndj +--dont-space-special-semicolon -nss +--dont-star-comments -nsc +--dont-tab-align-comments -ntac +--else-endif-column -cp\fIn\fR +--format-all-comments -fca +--format-first-column-comments -fc1 +--gnu-style -gnu +--honour-newlines -hnl +--ignore-newlines -nhnl +--ignore-profile -npro +--indent-label -il\fIn\fR +--indent-level -i\fIn\fR +--k-and-r-style -kr +--leave-optional-blank-lines -nsob +--leave-preprocessor-space -lps +--left-justify-declarations -dj +--line-comments-indentation -d\fIn\fR +--line-length -l\fIn\fR +--linux-style -linux +--no-blank-lines-after-commas -nbc +--no-blank-lines-after-declarations -nbad +--no-blank-lines-after-procedures -nbap +--no-blank-lines-before-block-comments -nbbb +--no-comment-delimiters-on-blank-lines -ncdb +--no-space-after-casts -ncs +--no-parameter-indentation -nip +--no-space-after-for -nsaf +--no-space-after-function-call-names -npcs +--no-space-after-if -nsai +--no-space-after-parentheses -nprs +--no-space-after-while -nsaw +--no-tabs -nut +--no-verbosity -nv +--original -orig +--parameter-indentation -ip\fIn\fR +--paren-indentation -pi\fIn\fR +--preserve-mtime -pmt +--preprocessor-indentation -ppi\fIn\fR +--procnames-start-lines -psl +--remove-preprocessor-space -nlps +--single-line-conditionals -slc +--space-after-cast -cs +--space-after-for -saf +--space-after-if -sai +--space-after-parentheses -prs +--space-after-procedure-calls -pcs +--space-after-while -saw +--space-special-semicolon -ss +--spaces-around-initializers -sar +--standard-output -st +--start-left-side-of-comments -sc +--struct-brace-indentation -sbi\fIn\fR +--swallow-optional-blank-lines -sob +--tab-size -ts\fIn\fR +--use-tabs -ut +--verbose -v +.in -5 +.ad +.fi + +.SH "RETURN VALUE" +.IP \(bu 2 +0 means no errors or warnings were found during a successful invocation of +the program. +.br +.IP \(bu 2 +2 is returned if errors occur during formatting which do not prevent completion +of the formatting, but which appear to be manifested by incorrect code (i.e. code +which wouldn't compile). +.br +.IP \(bu 2 +3 is returned if formatting of a file is halted because of an error with the file +which prevents completion of formatting. If more than one input file was specified, +indent continues to the next file. +.br +.IP \(bu 2 +4 is returned if a serious internal problem occurs and the entire indent process +is terminated, even if all specified files have not been processed. +.br +.IP \(bu 2 +64 is returned if an invocation problem (like an incorrect option) prevents +any formatting to occur. +.SH FILES +.br +.nf +.\" set tabstop to longest possible filename, plus a wee bit +.ta \w'$HOME/.indent.pro 'u +\fI$HOME/.indent.pro\fR holds default options for indent. +.SH "AUTHORS" +.br +Tim Hentenaar +.br +Carlo Wood +.br +Joseph Arceneaux +.br +Jim Kingdon +.br +David Ingamells +.SH "HISTORY" +Derived from the UCB program "indent". +.SH "COPYING" +Copyright (C) 1989, 1992, 1993, 1994, 1995, 1996, 2014, 2015 Free Software Foundation, Inc. +Copyright (C) 1995, 1996 Joseph Arceneaux. +Copyright (C) 1999 Carlo Wood. +Copyright (C) 2001 David Ingamells. +Copyright (C) 2013 Łukasz Stelmach. +Copyright (C) 2015 Tim Hentenaar. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + + diff --git a/upstream/fedora-40/man1/indxbib.1 b/upstream/fedora-40/man1/indxbib.1 new file mode 100644 index 00000000..10dd88b6 --- /dev/null +++ b/upstream/fedora-40/man1/indxbib.1 @@ -0,0 +1,347 @@ +.TH \%indxbib 1 "24 January 2024" "groff 1.23.0" +.SH Name +\%indxbib \- make inverted index for bibliographic databases +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2020 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_indxbib_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY \%indxbib +.RB [ \-w ] +.RB [ \-c\~\c +.IR \%common-words-file ] +.RB [ \-d\~\c +.IR dir ] +.RB [ \-f\~\c +.IR \%list-file ] +.RB [ \-h\~\c +.IR \%min-hash-table-size ] +.RB [ \-i\~\c +.IR \%excluded-fields ] +.RB [ \-k\~\c +.IR \%max-keys-per-record ] +.RB [ \-l\~\c +.IR \%min-key-length ] +.RB [ \-n\~\c +.IR \%threshold ] +.RB [ \-o\~\c +.IR file ] +.RB [ \-t\~\c +.IR \%max-key-length ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY \%indxbib +.B \-\-help +.YS +. +. +.SY \%indxbib +.B \-v +. +.SY \%indxbib +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I \%indxbib +makes an inverted index for the bibliographic databases in each +.I file +for use with +.MR \%refer 1 , +.MR \%lookbib 1 , +and +.MR lkbib 1 . +. +Each created index is named +.RI file \%.i ; +writing is done to a temporary file which is then renamed to this. +. +If no +.I file +operands are given on the command line because the +.B \-f +option has been used, +and no +.B \-o +option is given, +the index will be named +.IR \%Ind\%.i . +. +. +.LP +Bibliographic databases are divided into records by blank lines. +. +Within a record, +each field starts with a +.B % +character at the beginning of a line. +. +Fields have a one letter name that follows the +.B % +character. +. +. +.LP +The values set by the +.BR \-c , +.BR \-l , +.BR \-n , +and +.B \-t +options are stored in the index: +when the index is searched, +keys will be discarded and truncated in a +manner appropriate to these options; +the original keys will be used for verifying that any record +found using the index actually contains the keys. +. +This means that a user of an index need not know whether these +options were used in the creation of the index, +provided that not all the keys to be searched for +would have been discarded during indexing +and that the user supplies at least the part of each key +that would have remained after being truncated during indexing. +. +The value set by the +.B \-i +option is also stored in the index +and will be used in verifying records found using the index. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-\-help +displays a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.BI \-c\~ common-words-file +Read the list of common words from +.I common-words-file +instead of +.IR \%/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%eign . +. +. +.TP +.BI \-d\~ dir +Use +.I dir +as the name of the directory to store in the index, +instead of that returned by +.MR getcwd 2 . +. +Typically, +.I dir +will be a symbolic link whose target is the current working directory. +. +. +.TP +.BI \-f\~ list-file +Read the files to be indexed from +.IR list-file . +. +If +.I list-file +is +.BR \- , +files will be read from the standard input stream. +. +The +.B \-f +option can be given at most once. +. +. +.TP +.BI \-h\~ min-hash-table-size +Use the first prime number greater than or equal to +the argument for the size of the hash table. +. +Larger values +will usually make searching faster, +but will make the index file larger +and cause +.I \%indxbib +to use more memory. +. +The default hash table size is 997. +. +. +.TP +.BI \-i\~ excluded-fields +Don't index the contents of fields whose names are in +.IR excluded-fields . +. +Field names are one character each. +. +If this option is not present, +.I \%indxbib +excludes fields +.BR X , +.BR Y , +and +.BR Z . +. +. +.TP +.BI \-k\~ max-keys-per-record +Use no more keys per input record than specified in the argument. +. +If this option is not present, +the maximum is 100. +. +. +.TP +.BI \-l\~ min-key-length +Discard any key whose length in characters is shorter than the value of +the argument. +. +If this option is not present, +the minimum key length +is 3. +. +. +.TP +.BI \-n\~ threshold +Discard the +.I threshold +most common words from the common words file. +. +If this option is not present, +the 100 most common words are discarded. +. +. +.TP +.BI \-o\~ basename +Name the index +.RI basename \%.i . +. +. +.TP +.BI \-t\~ max-key-length +Truncate keys to +.I max-key-length +in characters. +. +If this option is not present, +keys are truncated to 6 characters. +. +. +.TP +.B \-w +Index whole files. +. +Each file is a separate record. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.RI \%file \%.i +index for +.I file +. +. +.TP +.I \%Ind\%.i +default index name +. +. +.TP +.I \%/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%eign +contains the list of common words. +. +The traditional name, +.RI \[lq] eign \[rq], +is an abbreviation of \[lq]English ignored [word list]\[rq]. +. +. +.TP +.IR \%indxbib XXXXXX +temporary file +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +\[lq]Some Applications of Inverted Indexes on the Unix System\[rq], +by M.\& E.\& Lesk, +1978, +AT&T Bell Laboratories Computing Science Technical Report No.\& 69. +. +. +.LP +.MR \%refer 1 , +.MR lkbib 1 , +.MR \%lookbib 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_indxbib_1_man_C] +.do rr *groff_indxbib_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man1/info.1 b/upstream/fedora-40/man1/info.1 new file mode 100644 index 00000000..3801a1fc --- /dev/null +++ b/upstream/fedora-40/man1/info.1 @@ -0,0 +1,101 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.1. +.TH INFO "1" "October 2023" "GNU texinfo 7.1" "User Commands" +.SH NAME +info \- read Info documents +.SH SYNOPSIS +.B info +[\fI\,OPTION\/\fR]... [\fI\,MENU-ITEM\/\fR...] +.SH DESCRIPTION +Read documentation in Info format. +.SS "Frequently-used options:" +.TP +\fB\-a\fR, \fB\-\-all\fR +use all matching manuals +.TP +\fB\-k\fR, \fB\-\-apropos\fR=\fI\,STRING\/\fR +look up STRING in all indices of all manuals +.TP +\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR +add DIR to INFOPATH +.TP +\fB\-f\fR, \fB\-\-file\fR=\fI\,MANUAL\/\fR +specify Info manual to visit +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help and exit +.TP +\fB\-\-index\-search\fR=\fI\,STRING\/\fR +go to node pointed by index entry STRING +.TP +\fB\-n\fR, \fB\-\-node\fR=\fI\,NODENAME\/\fR +specify nodes in first visited Info file +.TP +\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR +output selected nodes to FILE +.TP +\fB\-\-subnodes\fR +recursively output menu items +.TP +\fB\-v\fR, \fB\-\-variable\fR VAR=VALUE +assign VALUE to Info variable VAR +.TP +\fB\-\-version\fR +display version information and exit +.TP +\fB\-w\fR, \fB\-\-where\fR, \fB\-\-location\fR +print physical location of Info file +.PP +The first non\-option argument, if present, is the menu entry to start from; +it is searched for in all 'dir' files along INFOPATH. +If it is not present, info merges all 'dir' files and shows the result. +Any remaining arguments are treated as the names of menu +items relative to the initial node visited. +.PP +For a summary of key bindings, type H within Info. +.SH EXAMPLES +.TP +info +show top\-level dir menu +.TP +info info\-stnd +show the manual for this Info program +.TP +info emacs +start at emacs node from top\-level dir +.TP +info emacs buffers +select buffers menu entry in emacs manual +.TP +info emacs \-n Files +start at Files node within emacs manual +.TP +info '(emacs)Files' +alternative way to start at Files node +.TP +info \-\-subnodes \-o out.txt emacs +dump entire emacs manual to out.txt +.TP +info \-f ./foo.info +show file ./foo.info, not searching dir +.SH "REPORTING BUGS" +Email bug reports to bug\-texinfo@gnu.org, +general questions and discussion to help\-texinfo@gnu.org. +.br +Texinfo home page: http://www.gnu.org/software/texinfo/ +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B info +is maintained as a Texinfo manual. If the +.B info +program is properly installed at your site, the command +.IP +.B info info +.PP +should give you access to the complete manual. +(Or, if you have Emacs, M-x info will lead to the manual.) diff --git a/upstream/fedora-40/man1/infocmp.1m b/upstream/fedora-40/man1/infocmp.1m new file mode 100644 index 00000000..b18a5a67 --- /dev/null +++ b/upstream/fedora-40/man1/infocmp.1m @@ -0,0 +1,667 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2017,2018 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: infocmp.1m,v 1.107 2024/01/13 22:05:39 tom Exp $ +.TH infocmp 1M 2024-01-13 "ncurses 6.4" "User commands" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ie t .ds ' \(aq +.el .ds ' ' +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. +.ds d /usr/share/terminfo +.SH NAME +\fBinfocmp\fP \- +compare or print out \fIterminfo\fP descriptions +.SH SYNOPSIS +\fBinfocmp\fP [\fB\-\ +1\ +c\ +C\ +d\ +D\ +e\ +E\ +F\ +g\ +G\ +i\ +I\ +K\ +l\ +L\ +n\ +p\ +q\ +r\ +t\ +T\ +u\ +U\ +V\ +W\ +x\ +\fP] + [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fBsubset\fR] + [\fB\-w\fP\ \fIwidth\fP] [\fB\-A\fP\ \fIdirectory\fP] [\fB\-B\fP\ \fIdirectory\fP] + [\fIterminal-type\fP ...] +.SH DESCRIPTION +\fBinfocmp\fP can be used to compare a binary \fBterminfo\fP entry with other +terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the +\fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the +binary file (\fBterm\fP) in a variety of formats. +In all cases, the Boolean +fields will be printed first, followed by the numeric fields, followed by the +string fields. +.SS "Default Options" +If no options are specified and zero or one \fIterminal-types\fP are +specified, +the +\fB\-I\fP option will be assumed. +If more than one \fIterminal-type\fP is specified, +the \fB\-d\fP option will be assumed. +.SS "Comparison Options [\-d] [\-c] [\-n]" +\fBinfocmp\fP compares the \fBterminfo\fP description of the first terminal +\fIterminal-type\fP with each of the descriptions given by the entries +for the other terminal's \fIterminal-types\fP. +If a capability is defined for only one of the +terminals, the value returned depends on the type of the capability: +.bP +\fBF\fP for missing Boolean variables +.bP +\fBNULL\fP for missing integer or string variables +.PP +Use the \fB\-q\fP option to show the distinction between +\fIabsent\fP and \fIcancelled\fP capabilities. +.PP +These options produce a list which you can use to compare two +or more terminal descriptions: +.TP 5 +\fB\-d\fP +produces a list of each capability that is \fIdifferent\fP +between two entries. +Each item in the list shows \*(``:\*('' after the capability name, +followed by the capability values, separated by a comma. +.TP +\fB\-c\fP +produces a list of each capability that is \fIcommon\fP between +two or more entries. +Missing capabilities are ignored. +Each item in the list shows \*(``=\*('' after the capability name, +followed by the capability value. +.IP +The \fB\-u\fP option provides a related output, +showing the first terminal description rewritten to use the second +as a building block via the \*(``use=\*('' clause. +.TP +\fB\-n\fP +produces a list of each capability that is in \fInone\fP of the given entries. +Each item in the list shows \*(``!\*('' before the capability name. +.IP +Normally only the conventional capabilities are shown. +Use the \fB\-x\fP option to add the BSD-compatibility +capabilities (names prefixed with \*(``OT\*(''). +.IP +If no \fIterminal-types\fP are given, +\fBinfocmp\fP uses the environment variable \fITERM\fP +for each of the \fIterminal-types\fP. +.SS "Source Listing Options [\-I] [\-L] [\-C] [\-r]" +The \fB\-I\fP, \fB\-L\fP, and \fB\-C\fP options will produce +a source listing for each terminal named. +.PP +.TS +center; +Lb L. +\-I use \fIterminfo\fP capability codes +\-L use \*(``long\*('' capability names +\-C use \fItermcap\fP capability codes +\-r with \fB\-C\fP, include nonstandard capabilities +\-K with \fB\-C\fP, improve BSD compatibility +.TE +.PP +If no \fIterminal-types\fP are given, +the environment variable \fITERM\fP will be used for the terminal name. +.PP +The source produced by the \fB\-C\fP option may be used directly as a +\fBtermcap\fP entry, but not all parameterized strings can be changed to +the \fBtermcap\fP format. +\fBinfocmp\fP will attempt to convert most of the +parameterized information, and anything not converted will be plainly marked in +the output and commented out. +These should be edited by hand. +.PP +For best results when converting to \fBtermcap\fP format, +you should use both \fB\-C\fP and \fB\-r\fP. +Normally a termcap description is limited to 1023 bytes. +\fBinfocmp\fP trims away less essential parts to make it fit. +If you are converting to one of the (rare) termcap implementations +which accept an unlimited size of termcap, +you may want to add the \fB\-T\fP option. +More often however, you must help the termcap implementation, +and trim excess whitespace (use the \fB\-0\fP option for that). +.PP +All padding information for strings will be collected together and placed +at the beginning of the string where \fBtermcap\fP expects it. +Mandatory +padding (padding information with a trailing \*(``/\*('') will become optional. +.PP +All \fBtermcap\fP variables no longer supported by \fBterminfo\fP, but which +are derivable from other \fBterminfo\fP variables, will be output. +Not all +\fBterminfo\fP capabilities will be translated; only those variables which were +part of \fBtermcap\fP will normally be output. +Specifying the \fB\-r\fP option +will take off this restriction, allowing all capabilities to be output in +\fItermcap\fP form. +Normally you would use both the \fB\-C\fP and \fB\-r\fP options. +The actual format used incorporates some improvements for escaped characters +from terminfo format. +For a stricter BSD-compatible translation, use the \fB\-K\fP option +rather than \fB\-C\fP. +.PP +Note that because padding is collected to the beginning of the capability, not +all capabilities are output. +Mandatory padding is not supported. +Because +\fBtermcap\fP strings are not as flexible, it is not always possible to convert +a \fBterminfo\fP string capability into an equivalent \fBtermcap\fP format. +A subsequent conversion of the \fBtermcap\fP file +back into \fBterminfo\fP format +will not necessarily reproduce the original \fBterminfo\fP source. +.PP +Some common \fBterminfo\fP parameter sequences, their \fBtermcap\fP +equivalents, and some terminal types which commonly have such sequences, are: +.PP +.TS +center; +Lf(BI) Lf(BI) L +Lb Lb L. +terminfo termcap Terminal Types +_ +.\" ansi-m cup (adm3a has other stuff in between, more like concept) +%p1%c %. ansi\-m +.\" ansi cub, vt100 cub +%p1%d %d ansi, vt100 +.\" vt52 cup (via vt52-basic) +%p1%\*' \*'%+%c %+x vt52 +.\" ansi cup, vt100 cup +%i %iq ansi, vt100 +.\" annarbor4080 cup +%p1%?%\*'x\*'%>%t%p1%\*'y\*'%+%; %>xy annarbor4080 +.\" hpgeneric cup +%p2\fR\|.\|.\|.\|\fP%p1 %r hpgeneric +.TE +.SS "Use= Option [\-u]" +The \fB\-u\fP option produces a \fBterminfo\fP source description of the first +terminal \fIterminal-type\fP which is relative to the sum of the +descriptions given by the entries for the other \fIterminal-types\fP. +It does this by +analyzing the differences between the first \fIterminal-types\fP and the +other \fIterminal-types\fP and producing a description with \fBuse=\fP +fields for the other terminals. +In this manner, it is possible to retrofit generic terminfo +entries into a terminal's description. +Or, if two similar terminals exist, but +were coded at different times or by different people so that each description +is a full description, using \fBinfocmp\fP +will show what can be done to change +one description to be relative to the other. +.PP +A capability will be printed with an at-sign (@) if it no longer exists in the +first \fIterminal-type\fP, +but one of the other \fIterminal-type\fP entries contains a value for +it. +A capability's value will be printed if the value in the first +\fIterminal-type\fP is not found in any of the other \fIterminal-type\fP +entries, +or if the first of the other \fIterminal-type\fP entries that has this +capability gives a different value for the capability than that in the +first \fIterminal-type\fP. +.PP +The order of the other \fIterminal-type\fP entries is significant. +Since the +terminfo compiler \fBtic\fP does a left-to-right scan of the capabilities, +specifying two \fBuse=\fP entries that contain differing entries for the same +capabilities will produce different results depending on the order that the +entries are given in. +\fBinfocmp\fP will flag any such inconsistencies between +the other \fIterminal-type\fP entries as they are found. +.PP +Alternatively, specifying a capability \fIafter\fP a \fBuse=\fP entry that +contains that capability will cause the second specification to be ignored. +Using \fBinfocmp\fP to recreate a description can be a useful check to make +sure that everything was specified correctly in the original source +description. +.PP +Another error that does not cause incorrect compiled files, but will slow down +the compilation time, is specifying extra \fBuse=\fP fields that are +superfluous. +\fBinfocmp\fP will flag any other \fIterminal-type use=\fP fields that +were not needed. +.SS "Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]" +Like other \fI\%ncurses\fP utilities, +\fBinfocmp\fP looks for the terminal descriptions in several places. +You can use the \fI\%TERMINFO\fP and \fI\%TERMINFO_DIRS\fP environment +variables to override the compiled-in default list of places to search. +See \fBcurses\fP(3X), as well as +the \fIFetching Compiled Descriptions\fP section in \fBterminfo\fR(5). +.PP +You can also use the options \fB\-A\fP +and \fB\-B\fP to override the list of places to search +when comparing terminal descriptions: +.bP +The \fB\-A\fP option sets the location for the first \fIterminal-type\fP +.bP +The \fB\-B\fP option sets the location for the other +\fIterminal-types\fP. +.PP +Using these options, it is possible to +compare descriptions for a terminal with the same name located in two different +databases. +For instance, +you can use this feature for comparing descriptions for the same terminal +created by different people. +.SS "Other Options" +.TP 5 +\fB\-0\fP +causes the fields to be printed on one line, without wrapping. +.TP 5 +\fB\-1\fP +causes the fields to be printed out one to a line. +Otherwise, +the fields will be printed several to a line to a maximum width +of 60 characters. +.TP +\fB\-a\fP +tells \fBinfocmp\fP to retain commented-out capabilities +rather than discarding them. +Capabilities are commented by prefixing them with a period. +.TP +\fB\-D\fP +tells \fBinfocmp\fP to print the database locations that it knows about, +and exit. +.TP 5 +\fB\-E\fP +Dump the capabilities of the given terminal as tables, needed in +the C initializer for a +TERMTYPE structure (the terminal capability structure in the \fB\fP). +This option is useful for preparing versions of the curses library hardwired +for a given terminal type. +The tables are all declared static, and are named according to the type +and the name of the corresponding terminal entry. +.sp +Before \fI\%ncurses\fP 5.0, +the split between the \fB\-e\fP and \fB\-E\fP options was not needed; +but support for extended names required making the arrays of terminal +capabilities separate from the TERMTYPE structure. +.TP 5 +\fB\-e\fP +Dump the capabilities of the given terminal as a C initializer for a +TERMTYPE structure (the terminal capability structure in the \fB\fP). +This option is useful for preparing versions of the curses library hardwired +for a given terminal type. +.TP 5 +\fB\-F\fP +compare terminfo files. +This assumes that two following arguments are filenames. +The files are searched for pairwise matches between +entries, with two entries considered to match if any of their names do. +The report printed to standard output lists entries with no matches in +the other file, and entries with more than one match. +For entries +with exactly one match it includes a difference report. +Normally, +to reduce the volume of the report, use references are +not resolved before looking for differences, but resolution can be forced +by also specifying \fB\-r\fP. +.TP 5 +\fB\-f\fP +Display complex terminfo strings which contain if/then/else/endif expressions +indented for readability. +.TP 5 +\fB\-G\fP +Display constant literals in decimal form +rather than their character equivalents. +.TP 5 +\fB\-g\fP +Display constant character literals in quoted form +rather than their decimal equivalents. +.TP 5 +\fB\-i\fP +Analyze the initialization (\fBis1\fP, \fBis2\fP, \fBis3\fP), and reset +(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP), strings in the entry, +as well as those used for starting/stopping cursor-positioning mode +(\fBsmcup\fP, \fBrmcup\fP) as well as starting/stopping keymap mode +(\fBsmkx\fP, \fBrmkx\fP). +.IP +For each string, the +code tries to analyze it into actions in terms of the other capabilities in the +entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series +private modes (the set of recognized special sequences has been selected for +completeness over the existing terminfo database). +Each report line consists +of the capability name, followed by a colon and space, followed by a printable +expansion of the capability string with sections matching recognized actions +translated into {}-bracketed descriptions. +.IP +Here is a list of the DEC/ANSI +special sequences recognized: +.PP +.TS +center; +L L. +Action Meaning +_ +RIS full reset +SC save cursor +RC restore cursor +LL home-down +RSR reset scroll region +_ +DECSTR soft reset (VT320) +S7C1T 7-bit controls (VT220) +_ +ISO DEC G0 enable DEC graphics for G0 +ISO UK G0 enable UK chars for G0 +ISO US G0 enable US chars for G0 +ISO DEC G1 enable DEC graphics for G1 +ISO UK G1 enable UK chars for G1 +ISO US G1 enable US chars for G1 +_ +DECPAM application keypad mode +DECPNM normal keypad mode +DECANSI enter ANSI mode +_ +ECMA[+\-]AM keyboard action mode +ECMA[+\-]IRM insert replace mode +ECMA[+\-]SRM send receive mode +ECMA[+\-]LNM linefeed mode +_ +DEC[+\-]CKM application cursor keys +DEC[+\-]ANM set VT52 mode +DEC[+\-]COLM 132-column mode +DEC[+\-]SCLM smooth scroll +DEC[+\-]SCNM reverse video mode +DEC[+\-]OM origin mode +DEC[+\-]AWM wraparound mode +DEC[+\-]ARM auto-repeat mode +.TE +.sp +It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set +Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and +REVERSE. +All but NORMAL may be prefixed with +.RS +.bP +\*(``+\*('' (turn on) or +.bP +\*(``\-\*('' (turn off). +.RE +.IP +An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}). +.TP 5 +\fB\-l\fP +Set output format to terminfo. +.TP 5 +\fB\-p\fP +Ignore padding specifications when comparing strings. +.TP 5 +\fB\-Q\fP \fIn\fP +Rather than show source in terminfo (text) format, +print the compiled (binary) format in hexadecimal or base64 form, +depending on the option's value: +.RS 8 +.TP 3 +1 +hexadecimal +.TP 3 +2 +base64 +.TP 3 +3 +hexadecimal and base64 +.RE +.IP +For example, this prints the compiled terminfo value as a string +which could be assigned to the \fI\%TERMINFO\fP environment variable: +.PP +.RS 9 +.EX +infocmp \-0 \-q \-Q2 +.EE +.RE +.TP 5 +\fB\-q\fP +This makes the output a little shorter: +.RS +.bP +Make the comparison listing shorter by omitting subheadings, and using +\*(``\-\*('' for absent capabilities, \*(``@\*('' +for canceled rather than \*(``NULL\*(''. +.bP +However, show differences between absent and cancelled capabilities. +.bP +Omit the \*(``Reconstructed from\*('' comment for source listings. +.RE +.TP 5 +\fB\-R\fIsubset\fR +Restrict output to a given subset. +This option is for use with archaic +versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support +the full set of SVR4/XSI Curses terminfo; and variants such as AIX +that have their own extensions incompatible with SVr4/XSI. +.RS +.bP +Available terminfo +subsets are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', and \*(``AIX\*(''; +see \fBterminfo\fP(5) for details. +.bP +You can also choose the subset \*(``BSD\*('' which selects only capabilities +with termcap equivalents recognized by 4.4BSD. +.bP +If you select any other value for \fB\-R\fP, +it is the same as no subset, i.e., all capabilities are used. +.RE +.IP +A few options override the subset selected with \fB\-R\fP, +if they are processed later in the command parameters: +.RS +.TP 5 +\fB\-C\fP +sets the \*(``BSD\*('' subset as a side-effect. +.TP 5 +\fB\-I\fP +sets the subset to all capabilities. +.TP 5 +\fB\-r\fP +sets the subset to all capabilities. +.RE +.TP +\fB\-s \fI[d|i|l|c]\fR +The \fB\-s\fP option sorts the fields within each type according to the argument +below: +.br +.RS 5 +.TP 5 +\fBd\fP +leave fields in the order that they are stored in the \fIterminfo\fP database. +.TP 5 +\fBi\fP +sort by \fIterminfo\fP name. +.TP 5 +\fBl\fP +sort by the long C variable name. +.TP 5 +\fBc\fP +sort by the \fItermcap\fP name. +.RE +.IP +If the \fB\-s\fP option is not given, the fields printed out will be +sorted alphabetically by the \fBterminfo\fP name within each type, +except in the case of the \fB\-C\fP or the \fB\-L\fP options, which cause the +sorting to be done by the \fBtermcap\fP name or the long C variable +name, respectively. +.TP 5 +\fB\-T\fP +eliminates size-restrictions on the generated text. +This is mainly useful for testing and analysis, since the compiled +descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). +.TP +\fB\-t\fP +tells \fBtic\fP to discard commented-out capabilities. +Normally when translating from terminfo to termcap, +untranslatable capabilities are commented-out. +.TP 5 +\fB\-U\fP +tells \fBinfocmp\fP to not post-process the data +after parsing the source file. +This feature helps when comparing the actual contents of two source files, +since it excludes the inferences that \fBinfocmp\fP makes to fill in missing +data. +.TP 5 +\fB\-V\fP +reports the version of \fI\%ncurses\fP which was used in this program, +and exits. +.TP 5 +\fB\-v\fP \fIn\fP +prints out tracing information on standard error as the program runs. +.IP +The optional parameter \fIn\fP is a number from 1 to 10, inclusive, +indicating the desired level of detail of information. +If \fI\%ncurses\fP is built without tracing support, +the optional parameter is ignored. +.TP +\fB\-W\fP +By itself, the \fB\-w\fP option will not force long strings to be wrapped. +Use the \fB\-W\fP option to do this. +.TP 5 +\fB\-w\fP \fIwidth\fP +changes the output to \fIwidth\fP characters. +.TP +\fB\-x\fP +print information for user-defined capabilities (see \fBuser_caps\fP(5). +These are extensions to the terminfo repertoire which can be loaded +using the \fB\-x\fP option of \fBtic\fP. +.SH FILES +.TP +.I \*d +compiled terminal description database +.SH EXTENSIONS +The +\fB\-0\fP, +\fB\-1\fP, +\fB\-E\fP, +\fB\-F\fP, +\fB\-G\fP, +\fB\-Q\fP, +\fB\-R\fP, +\fB\-T\fP, +\fB\-V\fP, +\fB\-a\fP, +\fB\-e\fP, +\fB\-f\fP, +\fB\-g\fP, +\fB\-i\fP, +\fB\-l\fP, +\fB\-p\fP, +\fB\-q\fP and +\fB\-t\fP +options are not supported in SVr4 curses. +.PP +SVr4 infocmp does not distinguish between absent and cancelled capabilities. +Also, it shows missing integer capabilities as \fB\-1\fP +(the internal value used to represent missing integers). +This implementation shows those as \*(``NULL\*('', +for consistency with missing strings. +.PP +The \fB\-r\fP option's notion of \*(``termcap\*('' capabilities +is System V Release 4's. +Actual BSD curses versions will have a more restricted set. +To see only the +4.4BSD set, use \fB\-r\fP \fB\-RBSD\fP. +.SH PORTABILITY +X/Open Curses, Issue 7 (2009) provides a description of \fBinfocmp\fP. +It does not mention the options used for converting to termcap format. +.SH HISTORY +Although System V Release 2 provided a terminfo library, +it had no documented tool for decompiling the terminal descriptions. +Tony Hansen (AT&T) wrote the first \fBinfocmp\fP in early 1984, +for System V Release 3. +.PP +Eric Raymond used the AT&T documentation in 1995 to provide an equivalent +\fBinfocmp\fP for \fI\%ncurses\fP. +In addition, he added a few new features such as: +.bP +the \fB\-e\fP option, to support \fIfallback\fP +(compiled-in) terminal descriptions +.bP +the \fB\-i\fP option, to help with analysis +.PP +Later, Thomas Dickey added the \fB\-x\fP (user-defined capabilities) +option, and the \fB\-E\fP option to support fallback entries with +user-defined capabilities. +.PP +For a complete list, see the \fIEXTENSIONS\fP section. +.PP +In 2010, Roy Marples provided an \fBinfocmp\fP program for NetBSD. +It is less capable than the SVr4 or \fI\%ncurses\fP versions +(e.g., it lacks the sorting options documented in X/Open), +but does include the \fB\-x\fP option adapted from \fI\%ncurses\fP. +.SH BUGS +The \fB\-F\fP option of \fB\%infocmp\fP(1M) should be a +\fB\%toe\fP(1M) mode. +.SH AUTHORS +Eric S. Raymond +and +.br +Thomas E. Dickey +.SH SEE ALSO +\fB\%captoinfo\fP(1M), +\fB\%infotocap\fP(1M), +\fB\%tic\fP(1M), +\fB\%toe\fP(1M), +\fB\%curses\fP(3X), +\fB\%terminfo\fP(5), +\fB\%user_caps\fP(5) +.PP +https://invisible\-island.net/ncurses/tctest.html diff --git a/upstream/fedora-40/man1/infotocap.1m b/upstream/fedora-40/man1/infotocap.1m new file mode 100644 index 00000000..fd3f1d44 --- /dev/null +++ b/upstream/fedora-40/man1/infotocap.1m @@ -0,0 +1,97 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1999-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: infotocap.1m,v 1.39 2023/12/10 14:12:43 tom Exp $ +.TH infotocap 1M 2023-12-10 "ncurses 6.4" "User commands" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.ds d /usr/share/terminfo +.SH NAME +\fB\%infotocap\fP \- +convert a \fI\%terminfo\fR description into a \fI\%termcap\fR description +.SH SYNOPSIS +.B infotocap +.RI [ tic-option ] +.I file +\&.\|.\|. +.P +.B "infotocap \-V" +.SH DESCRIPTION +\fB\%infotocap\fP translates terminal descriptions. +It looks in each given text \fIfile\fP for \fI\%terminfo\fP entries and, +For each one found, +it writes an analogous \fI\%termcap\fP description to the standard +output stream. +\fI\%terminfo\fP \*(``\fBuse\fP\*('' capabilities translate to +\fI\%termcap\fP \fBtc\fP capabilities. +Because \fI\%termcap\fP is a less expressive format than +\fI\%terminfo\fP, +some capabilities cannot be translated. +.PP +This utility is implemented as a link to \fB\%tic\fP(1M), +with the latter's +.B \-C +option implied. +You can use other \fB\%tic\fP options such as +.BR \-1 , +.BR \-f , +.BR \-v , +.BR \-w , +and +.BR \-x . +The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated +with this program and exits with a successful status. +.SH FILES +.TP +.I \*d +compiled terminal description database +.SH PORTABILITY +None of X/Open Curses, +Issue 7 (2009), +SVr4, +or NetBSD document this application. +.SH AUTHORS +Eric S. Raymond +and +.br +Thomas E. Dickey +.SH SEE ALSO +\fB\%infocmp\fP(1M), +\fB\%tic\fP(1M), +\fB\%curses\fP(3X), +\fB\%terminfo\fP(5) diff --git a/upstream/fedora-40/man1/infotopam.1 b/upstream/fedora-40/man1/infotopam.1 new file mode 100644 index 00000000..00a6bc46 --- /dev/null +++ b/upstream/fedora-40/man1/infotopam.1 @@ -0,0 +1,247 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Infotopam User Manual" 0 "07 April 2004" "netpbm documentation" + +.SH NAME +infotopam - convert Amiga .info icons to PAM + +.UN synopsis +.SH SYNOPSIS +.PP +\fBinfotopam\fP +[\fB-forcecolor\fP] +[\fB-numcolors\fP \fInumcolors\fP] +[\fB-selected\fP] +[\fIindex color\fP ...] +[\fIfilename\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white space in +place of the equals sign to separate an option name from its value. + +.UN examples +.SH EXAMPLES +.PP +By default, \fBinfotopam\fP converts the first icon in a .info file: + +.nf + infotopam amiga.info > amiga.first.pam + +.fi +.PP +Use the \fI-selected\fP option to convert the second icon in a .info +file. Here \fBinfotopam\fP reads from Standard Input: + +.nf + infotopam -selected < amiga.info > amiga.second.pam + +.fi +.PP +Use the \fI-forcecolor\fP option to force color conversion for a 1 +bit-plane .info file: + +.nf + infotopam -forcecolor bw.info > bw.pam + +.fi +.PP +Use \fI-numcolors\fP to override colors for indexes 0 and 3. Notice the +two ways to specify the color: + +.nf + infotopam -numcolors 2 0 green 3 #FF0000 icon.info > icon.pam + +.fi +.PP +Since Amiga monitors do not use square pixels, some icons may appear +squished. Filtering the output through \fBpamscale\fP can fix this: + +.nf + infotopam squish.info | pamtopnm | pamscale -yscale 1.7 > normal.pnm + +.fi + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBinfotopam\fP converts an Amiga .info (icon) file to a PAM image. +\fBinfotopam\fP reads a .info file from \fIfilename\fP, or from Standard +Input if you do not specify a file name, and writes the converted PAM image to +Standard Output. +.PP +\fBinfotopam\fP currently handles 1 and 2 bit-plane icons. If the .info +icon only has 1 bit-plane, \fBinfotopam\fP generates a bitmap +(black&white) PAM image; otherwise it generates a color PAM image. You +can force \fBinfotopam\fP to convert 1 bit-plane images to color PAM images by +using the \fI-forcecolor\fP option. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBinfotopam\fP recognizes the following +command line options: + + +.TP +\fB-forcecolor\fP + + +.sp +Forces \fBinfotopam\fP to convert 1 bit-plane icons to color PAM + images instead of bitmap PAM images. \fBinfotopam\fP uses the index 2 + color for black and the index 1 color for white (more on this + below). + +.TP +\fB-numcolors\fP \fInumcolors\fP + + +.sp +Tells \fBinfotopam\fP how many colors to override. Pixels in the + Amiga .info files are assigned an index value rather than a specific color. + The standard colors for a 2 bit-plane icon are: + +.nf + Index 0: Blue (00, 55, AA) + Index 1: White (FF, FF, FF) + Index 2: Black (00, 00, 20) + Index 3: Orange (FF, 8A, 00) + +.fi +.sp +To override the colors, first specify how many colors to override using + \fI-numcolors\fP, then specify an (\fIindex color\fP) pair for each color + you want to override, where \fIindex\fP is a value from 0 to 3 and + \fIcolor\fP the new color for that index. Specify \fIcolor\fP as + described for the +.UR libnetpbm_image.html#colorname +\fBpnm_parsecolor()\fP argument +.UE +\&. + +.TP +\fB-selected\fP + + +Tells \fBinfotopam\fP to convert the selected (second) icon instead of + the normal (first) icon. Each Amiga .info icon file contains two icon + images. The first image is the normal, unselected icon, and the second + image is the selected icon. By default \fBinfotopam\fP converts the first + icon. You can tell \fBinfotopam\fP to convert the second icon by using the + \fI-selected\fP option. + + +.PP +All options can be abbreviated to their shortest unique prefix. + +.UN seealso +.SH SEE ALSO +.PP +.BR "pam" (1)\c +\& +.BR "pamtopnm" (1)\c +\& +.BR "pamscale" (1)\c +\& + + +.UN notes +.SH NOTES +.PP +Thanks to the following people on comp.sys.amiga.programmer for tips +and pointers on decoding the info file format: + + +.IP \(bu +Ben Hutchings +.IP \(bu +Thomas Richter +.IP \(bu +Kjetil Svalastog Matheussen +.IP \(bu +Anders Melchiorsen +.IP \(bu +Dirk Stoecker +.IP \(bu +Ronald V.D. + +.PP +The format of the Amiga .info file is as follows: + +.nf + DiskObject header 78 bytes + Optional DrawerData header 56 bytes + First icon header 20 bytes + First icon data Varies + Second icon header 20 bytes + Second icon data Varies + +.fi +.PP +The DiskObject header contains, among other things, the magic number +(0xE310), the object width and height (inside the embedded Gadget header), +and the version. +.PP +Each icon header contains the icon width and height, which can be smaller +than the object width and height, and the number of bit-planes. +.PP +The icon data has the following format: + +.RS + +.PP +\fIBIT-PLANE\fP planes, each with \fIHEIGHT\fP rows of (\fIWIDTH\fP + +15) / 16 * 2 bytes length. +.RE +.PP +So if you have a 9x3x2 icon, the icon data will look like this: + +.nf + aaaa aaaa a000 0000 + aaaa aaaa a000 0000 + aaaa aaaa a000 0000 + bbbb bbbb b000 0000 + bbbb bbbb b000 0000 + bbbb bbbb b000 0000 + +.fi +.PP +where \fIa\fP is a bit for the first bit-plane, \fIb\fP is a bit for the +second bit-plane, and \fI0\fP is padding. Thanks again to Ben Hutchings for +his very helpful post! + +.UN history +.SH HISTORY +.PP +\fBinfotopam\fP was new in Netpbm 10.22 (April 2004). + +.UN limitations +.SH LIMITATIONS +.PP +\fBinfotopam\fP currently only handles 1 and 2 bit-plane icons. +.PP +There is no \fBpamtoinfo\fP command, since the .info files contain a lot +more than just icon data, and mapping the colors would be difficult. + +.UN author +.SH AUTHOR +.PP +Copyright (C) 2000, 2004 by Richard Griswold. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/infotopam.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/install-info.1 b/upstream/fedora-40/man1/install-info.1 new file mode 100644 index 00000000..f438aaca --- /dev/null +++ b/upstream/fedora-40/man1/install-info.1 @@ -0,0 +1,146 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.1. +.TH INSTALL-INFO "1" "October 2023" "GNU texinfo 7.1" "User Commands" +.SH NAME +install-info \- update info/dir entries +.SH SYNOPSIS +.B install-info +[\fI\,OPTION\/\fR]... [\fI\,INFO-FILE \/\fR[\fI\,DIR-FILE\/\fR]] +.SH DESCRIPTION +Add or remove entries in INFO\-FILE from the Info directory DIR\-FILE. +INFO\-FILE and DIR\-FILE are required unless the \fB\-\-info\-file\fR +or \fB\-\-dir\-file\fR (or \fB\-\-info\-dir\fR) options are given, respectively. +.SH OPTIONS +.TP +\fB\-\-add\-once\fR +add only to first matching section, not all. +.TP +\fB\-\-align\fR=\fI\,COL\/\fR +start description of new entries at column COL. +.TP +\fB\-\-calign\fR=\fI\,COL\/\fR +format second and subsequent description lines to +start at column COL. +.TP +\fB\-\-debug\fR +report what is being done. +.TP +\fB\-\-delete\fR +delete existing entries for INFO\-FILE from DIR\-FILE; +don't insert any new entries. +.TP +\fB\-\-defsection\fR=\fI\,TEXT\/\fR +like \fB\-\-section\fR, but only use TEXT if no sections +are present in INFO\-FILE (replacing "Miscellaneous"). +.TP +\fB\-\-description\fR=\fI\,TEXT\/\fR +the description of the entry is TEXT; used with +the \fB\-\-name\fR option to become synonymous with the +\fB\-\-entry\fR option. +.TP +\fB\-\-dir\-file\fR=\fI\,NAME\/\fR +specify file name of Info directory file; +equivalent to using the DIR\-FILE argument. +.TP +\fB\-\-dry\-run\fR +same as \fB\-\-test\fR. +.TP +\fB\-\-entry\fR=\fI\,TEXT\/\fR +insert TEXT as an Info directory entry, +overriding any corresponding entry from DIR\-FILE. +TEXT is written as an Info menu item line followed +.TP +by zero or more extra lines starting with whitespace. +If you specify more than one entry, all are added. +If you don't specify any entries, they are determined +.IP +from information in the Info file itself. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-info\-dir\fR=\fI\,DIR\/\fR +same as \fB\-\-dir\-file\fR=\fI\,DIR\/\fR/dir. +.TP +\fB\-\-info\-file\fR=\fI\,FILE\/\fR +specify Info file to install in the directory; +equivalent to using the INFO\-FILE argument. +.TP +\fB\-\-item\fR=\fI\,TEXT\/\fR +same as \fB\-\-entry\fR=\fI\,TEXT\/\fR. +.TP +\fB\-\-keep\-old\fR +do not replace entries, or remove empty sections. +.TP +\fB\-\-maxwidth\fR, \fB\-\-max\-width\fR=\fI\,COL\/\fR +wrap description at column COL. +.TP +\fB\-\-menuentry\fR=\fI\,TEXT\/\fR +same as \fB\-\-name\fR=\fI\,TEXT\/\fR. +.TP +\fB\-\-name\fR=\fI\,TEXT\/\fR +the name of the entry is TEXT; used with \fB\-\-description\fR +to become synonymous with the \fB\-\-entry\fR option. +.TP +\fB\-\-no\-indent\fR +do not format new entries in the DIR file. +.TP +\fB\-\-quiet\fR +suppress warnings. +.TP +\fB\-\-regex\fR=\fI\,R\/\fR +put this file's entries in all sections that match the +regular expression R (ignoring case). +.TP +\fB\-\-remove\fR +same as \fB\-\-delete\fR. +.TP +\fB\-\-remove\-exactly\fR +only remove if the info file name matches exactly; +suffixes such as .info and .gz are not ignored. +.TP +\fB\-\-section\fR=\fI\,SEC\/\fR +put entries in section SEC of the directory. +If you specify more than one section, all the entries +.TP +are added in each of the sections. +If you don't specify any sections, they are determined +.TP +from information in the Info file itself; +if nothing is available there, the \fB\-\-defsection\fR +value is used; if that is not specified, the +final default is "Miscellaneous". +.TP +\fB\-\-section\fR R SEC +equivalent to \fB\-\-regex\fR=\fI\,R\/\fR \fB\-\-section\fR=\fI\,SEC\/\fR \fB\-\-add\-once\fR. +.TP +\fB\-\-silent\fR +suppress warnings. +.TP +\fB\-\-test\fR +suppress updating of DIR\-FILE. +.TP +\fB\-\-version\fR +display version information and exit. +.SH "REPORTING BUGS" +Email bug reports to bug\-texinfo@gnu.org, +general questions and discussion to help\-texinfo@gnu.org. +.br +Texinfo home page: http://www.gnu.org/software/texinfo/ +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B install-info +is maintained as a Texinfo manual. If the +.B info +and +.B install-info +programs are properly installed at your site, the command +.IP +.B info install-info +.PP +should give you access to the complete manual. diff --git a/upstream/fedora-40/man1/install.1 b/upstream/fedora-40/man1/install.1 new file mode 100644 index 00000000..9a24e8e0 --- /dev/null +++ b/upstream/fedora-40/man1/install.1 @@ -0,0 +1,138 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH INSTALL "1" "January 2024" "GNU coreutils 9.4" "User Commands" +.SH NAME +install \- copy files and set attributes +.SH SYNOPSIS +.B install +[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,SOURCE DEST\/\fR +.br +.B install +[\fI\,OPTION\/\fR]... \fI\,SOURCE\/\fR... \fI\,DIRECTORY\/\fR +.br +.B install +[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY SOURCE\/\fR... +.br +.B install +[\fI\,OPTION\/\fR]... \fI\,-d DIRECTORY\/\fR... +.SH DESCRIPTION +.\" Add any additional description here +.PP +This install program copies files (often just compiled) into destination +locations you choose. If you want to download and install a ready\-to\-use +package on a GNU/Linux system, you should instead be using a package manager +like \fByum\fP(1) or \fBapt\-get\fP(1). +.PP +In the first three forms, copy SOURCE to DEST or multiple SOURCE(s) to +the existing DIRECTORY, while setting permission modes and owner/group. +In the 4th form, create all components of the given DIRECTORY(ies). +.PP +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-\-backup\fR[=\fI\,CONTROL\/\fR] +make a backup of each existing destination file +.TP +\fB\-b\fR +like \fB\-\-backup\fR but does not accept an argument +.TP +\fB\-c\fR +(ignored) +.TP +\fB\-C\fR, \fB\-\-compare\fR +compare content of source and destination files, and +if no change to content, ownership, and permissions, +do not modify the destination at all +.TP +\fB\-d\fR, \fB\-\-directory\fR +treat all arguments as directory names; create all +components of the specified directories +.TP +\fB\-D\fR +create all leading components of DEST except the last, +or all components of \fB\-\-target\-directory\fR, +then copy SOURCE to DEST +.TP +\fB\-\-debug\fR +explain how a file is copied. Implies \fB\-v\fR +.TP +\fB\-g\fR, \fB\-\-group\fR=\fI\,GROUP\/\fR +set group ownership, instead of process' current group +.TP +\fB\-m\fR, \fB\-\-mode\fR=\fI\,MODE\/\fR +set permission mode (as in chmod), instead of rwxr\-xr\-x +.TP +\fB\-o\fR, \fB\-\-owner\fR=\fI\,OWNER\/\fR +set ownership (super\-user only) +.TP +\fB\-p\fR, \fB\-\-preserve\-timestamps\fR +apply access/modification times of SOURCE files +to corresponding destination files +.TP +\fB\-s\fR, \fB\-\-strip\fR +strip symbol tables +.TP +\fB\-\-strip\-program\fR=\fI\,PROGRAM\/\fR +program used to strip binaries +.TP +\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR +override the usual backup suffix +.TP +\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR +copy all SOURCE arguments into DIRECTORY +.TP +\fB\-T\fR, \fB\-\-no\-target\-directory\fR +treat DEST as a normal file +.TP +\fB\-v\fR, \fB\-\-verbose\fR +print the name of each created file or directory +.TP +\fB\-\-preserve\-context\fR +preserve SELinux security context +.TP +\fB\-Z\fR +set SELinux security context of destination +file and each created directory to default type +.TP +\fB\-\-context\fR[=\fI\,CTX\/\fR] +like \fB\-Z\fR, or if CTX is specified then set the +SELinux or SMACK security context to CTX +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.PP +The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX. +The version control method may be selected via the \fB\-\-backup\fR option or through +the VERSION_CONTROL environment variable. Here are the values: +.TP +none, off +never make backups (even if \fB\-\-backup\fR is given) +.TP +numbered, t +make numbered backups +.TP +existing, nil +numbered if numbered backups exist, simple otherwise +.TP +simple, never +always make simple backups +.SH AUTHOR +Written by David MacKenzie. +.SH "REPORTING BUGS" +GNU coreutils online help: +.br +Report any translation bugs to +.SH COPYRIGHT +Copyright \(co 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +\fBcp\fP(1) +.PP +.br +Full documentation +.br +or available locally via: info \(aq(coreutils) install invocation\(aq diff --git a/upstream/fedora-40/man1/intro.1 b/upstream/fedora-40/man1/intro.1 new file mode 100644 index 00000000..38dd27ed --- /dev/null +++ b/upstream/fedora-40/man1/intro.1 @@ -0,0 +1,305 @@ +.\" Copyright (c) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH intro 1 2023-10-31 "Linux man-pages 6.06" +.SH NAME +intro \- introduction to user commands +.SH DESCRIPTION +Section 1 of the manual describes user commands and tools, +for example, file manipulation tools, shells, compilers, +web browsers, file and image viewers and editors, and so on. +.SH NOTES +Linux is a flavor of UNIX, and as a first approximation +all user commands under UNIX work precisely the same under +Linux (and FreeBSD and lots of other UNIX-like systems). +.P +Under Linux, there are GUIs (graphical user interfaces), where you +can point and click and drag, and hopefully get work done without +first reading lots of documentation. +The traditional UNIX environment +is a CLI (command line interface), where you type commands to +tell the computer what to do. +That is faster and more powerful, +but requires finding out what the commands are. +Below a bare minimum, to get started. +.SS Login +In order to start working, you probably first have to open a session by +giving your username and password. +The program +.BR login (1) +now starts a +.I shell +(command interpreter) for you. +In case of a graphical login, you get a screen with menus or icons +and a mouse click will start a shell in a window. +See also +.BR xterm (1). +.SS The shell +One types commands to the +.IR shell , +the command interpreter. +It is not built-in, but is just a program +and you can change your shell. +Everybody has their own favorite one. +The standard one is called +.IR sh . +See also +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR zsh (1). +.P +A session might go like: +.P +.in +4n +.EX +.RB "knuth login: " aeb +.RB "Password: " ******** +.RB "$ " date +Tue Aug 6 23:50:44 CEST 2002 +.RB "$ " cal + August 2002 +Su Mo Tu We Th Fr Sa + 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 31 +\& +.RB "$ " ls +bin tel +.RB "$ " "ls \-l" +total 2 +drwxrwxr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-rw\-r\-\- 1 aeb 37 Aug 6 23:52 tel +.RB "$ " "cat tel" +maja 0501\-1136285 +peter 0136\-7399214 +.RB "$ " "cp tel tel2" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "mv tel tel1" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel1 +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "diff tel1 tel2" +.RB "$ " "rm tel1" +.RB "$ " "grep maja tel2" +maja 0501\-1136285 +$ +.EE +.in +.P +Here typing Control-D ended the session. +.P +The +.B $ +here was the command prompt\[em]it is the shell's way of indicating +that it is ready for the next command. +The prompt can be customized +in lots of ways, and one might include stuff like username, +machine name, current directory, time, and so on. +An assignment PS1="What next, master? " +would change the prompt as indicated. +.P +We see that there are commands +.I date +(that gives date and time), and +.I cal +(that gives a calendar). +.P +The command +.I ls +lists the contents of the current directory\[em]it tells you what +files you have. +With a +.I \-l +option it gives a long listing, +that includes the owner and size and date of the file, and the +permissions people have for reading and/or changing the file. +For example, the file "tel" here is 37 bytes long, owned by aeb +and the owner can read and write it, others can only read it. +Owner and permissions can be changed by the commands +.I chown +and +.IR chmod . +.P +The command +.I cat +will show the contents of a file. +(The name is from "concatenate and print": all files given as +parameters are concatenated and sent to "standard output" +(see +.BR stdout (3)), +here +the terminal screen.) +.P +The command +.I cp +(from "copy") will copy a file. +.P +The command +.I mv +(from "move"), on the other hand, only renames it. +.P +The command +.I diff +lists the differences between two files. +Here there was no output because there were no differences. +.P +The command +.I rm +(from "remove") deletes the file, and be careful! it is gone. +No wastepaper basket or anything. +Deleted means lost. +.P +The command +.I grep +(from "g/re/p") finds occurrences of a string in one or more files. +Here it finds Maja's telephone number. +.SS Pathnames and the current directory +Files live in a large tree, the file hierarchy. +Each has a +.I "pathname" +describing the path from the root of the tree (which is called +.IR / ) +to the file. +For example, such a full pathname might be +.IR /home/aeb/tel . +Always using full pathnames would be inconvenient, and the name +of a file in the current directory may be abbreviated by giving +only the last component. +That is why +.I /home/aeb/tel +can be abbreviated +to +.I tel +when the current directory is +.IR /home/aeb . +.P +The command +.I pwd +prints the current directory. +.P +The command +.I cd +changes the current directory. +.P +Try alternatively +.I cd +and +.I pwd +commands and explore +.I cd +usage: "cd", "cd .", "cd ..", "cd /", and "cd \[ti]". +.SS Directories +The command +.I mkdir +makes a new directory. +.P +The command +.I rmdir +removes a directory if it is empty, and complains otherwise. +.P +The command +.I find +(with a rather baroque syntax) will find files with given name +or other properties. +For example, "find . \-name tel" would find +the file +.I tel +starting in the present directory (which is called +.IR . ). +And "find / \-name tel" would do the same, but starting at the root +of the tree. +Large searches on a multi-GB disk will be time-consuming, +and it may be better to use +.BR locate (1). +.SS Disks and filesystems +The command +.I mount +will attach the filesystem found on some disk (or floppy, or CDROM or so) +to the big filesystem hierarchy. +And +.I umount +detaches it again. +The command +.I df +will tell you how much of your disk is still free. +.SS Processes +On a UNIX system many user and system processes run simultaneously. +The one you are talking to runs in the +.IR foreground , +the others in the +.IR background . +The command +.I ps +will show you which processes are active and what numbers these +processes have. +The command +.I kill +allows you to get rid of them. +Without option this is a friendly +request: please go away. +And "kill \-9" followed by the number +of the process is an immediate kill. +Foreground processes can often be killed by typing Control-C. +.SS Getting information +There are thousands of commands, each with many options. +Traditionally commands are documented on +.IR "man pages" , +(like this one), so that the command "man kill" will document +the use of the command "kill" (and "man man" document the command "man"). +The program +.I man +sends the text through some +.IR pager , +usually +.IR less . +Hit the space bar to get the next page, hit q to quit. +.P +In documentation it is customary to refer to man pages +by giving the name and section number, as in +.BR man (1). +Man pages are terse, and allow you to find quickly some forgotten +detail. +For newcomers an introductory text with more examples +and explanations is useful. +.P +A lot of GNU/FSF software is provided with info files. +Type "info info" +for an introduction on the use of the program +.IR info . +.P +Special topics are often treated in HOWTOs. +Look in +.I /usr/share/doc/howto/en +and use a browser if you find HTML files there. +.\" +.\" Actual examples? Separate section for each of cat, cp, ...? +.\" gzip, bzip2, tar, rpm +.SH SEE ALSO +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR locate (1), +.BR login (1), +.BR man (1), +.BR xterm (1), +.BR zsh (1), +.BR wait (2), +.BR stdout (3), +.BR man\-pages (7), +.BR standards (7) diff --git a/upstream/fedora-40/man1/iostat.1 b/upstream/fedora-40/man1/iostat.1 new file mode 100644 index 00000000..f7e45e29 --- /dev/null +++ b/upstream/fedora-40/man1/iostat.1 @@ -0,0 +1,479 @@ +.\" iostat manual page - (C) 1998-2020 Sebastien Godard (sysstat orange.fr) +.TH IOSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- +.SH NAME +iostat \- Report Central Processing Unit (CPU) statistics and input/output +statistics for devices and partitions. + +.SH SYNOPSIS +.ie 'yes'no' \{ +.B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ] +.BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] " +.BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] [" +.IB "device " "[...] | ALL ] [ \-\-debuginfo ] [ " "interval " "[ " "count " "] ] " +.\} +.el \{ +.B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ] +.BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] " +.BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] [" +.IB "device " "[...] | ALL ] [ " "interval " "[ " "count " "] ]" +.\} + +.SH DESCRIPTION +.RB "The " "iostat" +command is used for monitoring system input/output device +loading by observing the time the devices are active in relation +to their average transfer rates. The +.B iostat +command generates reports +that can be used to change system configuration to better balance +the input/output load between physical disks. +.PP +The first report generated by the +.B iostat +command provides statistics +concerning the time since the system was booted, unless the +.B \-y +option is used (in this case, this first report is omitted). +Each subsequent report +covers the time since the previous report. All statistics are reported +each time the +.B iostat +command is run. The report consists of a +CPU header row followed by a row of +CPU statistics. On +multiprocessor systems, CPU statistics are calculated system-wide +as averages among all processors. A device header row is displayed +followed by a line of statistics for each device that is configured. +.PP +The +.I interval +parameter specifies the amount of time in seconds between +each report. The +.IR "count " "parameter can be specified in conjunction with the " "interval" +.RI "parameter. If the " "count " "parameter is specified, the value of " "count" +.RI "determines the number of reports generated at " "interval " "seconds apart. If the" +.IR "interval " "parameter is specified without the " "count " "parameter, the" +.B iostat +command generates reports continuously. + +.SH REPORTS +The +.B iostat +command generates two types of reports, the CPU +Utilization report and the Device Utilization report. + +.IP "CPU Utilization Report" +The first report generated by the +.B iostat +command is the CPU Utilization Report. For multiprocessor systems, the CPU values are +global averages among all processors. +The report has the following format: +.RS +.IP %user +Show the percentage of CPU utilization that occurred while +executing at the user level (application). +.IP %nice +Show the percentage of CPU utilization that occurred while +executing at the user level with nice priority. +.IP %system +Show the percentage of CPU utilization that occurred while +executing at the system level (kernel). +.IP %iowait +Show the percentage of time that the CPU or CPUs were idle during which +the system had an outstanding disk I/O request. +.IP %steal +Show the percentage of time spent in involuntary wait by the virtual CPU +or CPUs while the hypervisor was servicing another virtual processor. +.IP %idle +Show the percentage of time that the CPU or CPUs were idle and the system +did not have an outstanding disk I/O request. +.RE +.PP +.IP "Device Utilization Report" +The second report generated by the +.B iostat +command is the Device Utilization Report. +The device report provides statistics on a per physical device +or partition basis. Block devices and partitions for which statistics are +to be displayed may be entered on the command line. +If no device nor partition is entered, then statistics are displayed +for every device used by the system, and +providing that the kernel maintains statistics for it. +If the +.B ALL +keyword is given on the command line, then statistics are +displayed for every device defined by the system, including those +that have never been used. +Transfer rates are shown in 1K blocks by default, unless the environment +variable +.B POSIXLY_CORRECT +is set, in which case 512-byte blocks are used. +The report may show the following fields, depending on the flags used (e.g. +.BR "\-x" ", " "\-s " "and " "\-k " "or " "\-m" "):" +.RS +.IP Device: +This column gives the device (or partition) name as listed in the +.IR "/dev " "directory." +.IP tps +Indicate the number of transfers per second that were issued +to the device. A transfer is an I/O request to the +device. Multiple logical requests can be combined into a single I/O +request to the device. A transfer is of indeterminate size. +.IP "Blk_read/s (kB_read/s, MB_read/s)" +Indicate the amount of data read from the device expressed in a number of +blocks (kilobytes, megabytes) per second. Blocks are equivalent to sectors +and therefore have a size of 512 bytes. +.IP "Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s)" +Indicate the amount of data written to the device expressed in a number of +blocks (kilobytes, megabytes) per second. +.IP "Blk_dscd/s (kB_dscd/s, MB_dscd/s)" +Indicate the amount of data discarded for the device expressed in a number of +blocks (kilobytes, megabytes) per second. +.IP "Blk_w+d/s (kB_w+d/s, MB_w+d/s)" +Indicate the amount of data written to or discarded for the device expressed +in a number of blocks (kilobytes, megabytes) per second. +.IP "Blk_read (kB_read, MB_read)" +The total number of blocks (kilobytes, megabytes) read. +.IP "Blk_wrtn (kB_wrtn, MB_wrtn)" +The total number of blocks (kilobytes, megabytes) written. +.IP "Blk_dscd (kB_dscd, MB_dscd)" +The total number of blocks (kilobytes, megabytes) discarded. +.IP "Blk_w+d (kB_w+d, MB_w+d)" +The total number of blocks (kilobytes, megabytes) written or discarded. +.IP r/s +The number (after merges) of read requests completed per second for the device. +.IP w/s +The number (after merges) of write requests completed per second for the device. +.IP d/s +The number (after merges) of discard requests completed per second for the device. +.IP f/s +The number (after merges) of flush requests completed per second for the device. +This counts flush requests executed by disks. Flush requests are not tracked for partitions. +Before being merged, flush operations are counted as writes. +.IP "sec/s (kB/s, MB/s)" +The number of sectors (kilobytes, megabytes) read from, written to or +discarded for the device per second. +.IP "rsec/s (rkB/s, rMB/s)" +The number of sectors (kilobytes, megabytes) read from the device per second. +.IP "wsec/s (wkB/s, wMB/s)" +The number of sectors (kilobytes, megabytes) written to the device per second. +.IP "dsec/s (dkB/s, dMB/s)" +The number of sectors (kilobytes, megabytes) discarded for the device per second. +.IP rqm/s +The number of I/O requests merged per second that were queued to the device. +.IP rrqm/s +The number of read requests merged per second that were queued to the device. +.IP wrqm/s +The number of write requests merged per second that were queued to the device. +.IP drqm/s +The number of discard requests merged per second that were queued to the device. +.IP %rrqm +The percentage of read requests merged together before being sent to the device. +.IP %wrqm +The percentage of write requests merged together before being sent to the device. +.IP %drqm +The percentage of discard requests merged together before being sent to the device. +.IP areq\-sz +The average size (in kilobytes) of the I/O requests that were issued to the device. +.br +Note: In previous versions, this field was known as avgrq\-sz and was expressed in sectors. +.IP rareq\-sz +The average size (in kilobytes) of the read requests that were issued to the device. +.IP wareq\-sz +The average size (in kilobytes) of the write requests that were issued to the device. +.IP dareq\-sz +The average size (in kilobytes) of the discard requests that were issued to the device. +.IP await +The average time (in milliseconds) for I/O requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP r_await +The average time (in milliseconds) for read requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP w_await +The average time (in milliseconds) for write requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP d_await +The average time (in milliseconds) for discard requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP f_await +The average time (in milliseconds) for flush requests issued to the device +to be served. +The block layer combines flush requests and executes at most one at a time. +Thus flush operations could be twice as long: Wait for current flush request, +then execute it, then wait for the next one. +.IP aqu\-sz +The average queue length of the requests that were issued to the device. +.br +Note: In previous versions, this field was known as avgqu\-sz. +.IP %util +Percentage of elapsed time during which I/O requests were issued to the device +(bandwidth utilization for the device). Device saturation occurs when this +value is close to 100% for devices serving requests serially. +But for devices serving requests in parallel, such as RAID arrays and +modern SSDs, this number does not reflect their performance limits. +.RE + +.SH OPTIONS +.TP +.B \-c +Display the CPU utilization report. +.TP +.B \-\-compact +Don't break the Device Utilization Report into sub-reports so that all the metrics get displayed +on a single line. +.TP +.B \-d +Display the device utilization report. +.if 'yes'no' \{ +.TP +.B \-\-debuginfo +Print debug output to stderr. +.\} +.TP +.B \-\-dec={ 0 | 1 | 2 } +Specify the number of decimal places to use (0 to 2, default value is 2). +.TP +.BI "\-f " "directory" +.RE +.BI "+f " "directory" +.RS +Specify an alternative directory for +.B iostat +to read devices statistics. Option +.BR "\-f " "tells " "iostat " "to use only the files located in the alternative directory, " +whereas option +.B +f +tells it to use both the standard kernel files and the files located in the alternative directory +to read device statistics. + +.IR "directory" " is a directory containing files with statistics for devices managed in userspace." +It may contain: + +- a "diskstats" file whose format is compliant with that located in "/proc", +.br +- statistics for individual devices contained in files whose format is compliant with that of files located in +"/sys". + +In particular, the following files located in +.I "directory" +.RB "may be used by " "iostat" ":" + +.IR "directory" "/block/" "device" "/stat" +.br +.IR "directory" "/block/" "device" "/" "partition" "/stat" + +.IR "partition" " files must have an entry in " "directory" "/dev/block/ directory, e.g.:" + +.IR "directory" "/dev/block/" "major" ":" "minor" " --> ../../block/" "device" "/" "partition" +.RE +.TP +.BI "\-g " "group_name " "{ " "device " "[...] | ALL }" +Display statistics for a group of devices. +The +.B iostat +command reports statistics for each individual device in the list +then a line of global statistics for the group displayed as +.I group_name +and made up of all the devices in the list. The +.B ALL +keyword means that all the block devices defined by the system shall be +included in the group. +.TP +.B \-H +This option must be used with option +.B \-g +and indicates that only global +statistics for the group are to be displayed, and not statistics for +individual devices in the group. +.TP +.B \-h +This option is equivalent to specifying +.BR "\-\-human \-\-pretty" "." +.TP +.B \-\-human +Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.) +The units displayed with this option supersede any other default units (e.g. +kilobytes, sectors...) associated with the metrics. +.TP +.BI "\-j { ID | LABEL | PATH | UUID | ... } [ " "device " "[...] | ALL ]" +Display persistent device names. Keywords +.BR "ID" ", " "LABEL" ", " +etc. specify the type of the persistent name. These keywords are not limited, +only prerequisite is that directory with required persistent names is present in +.IR "/dev/disk" "." +Optionally, multiple devices can be specified in the chosen persistent name type. +Because persistent device names are usually long, option +.B \-\-pretty +is implicitly set with this option. +.TP +.B \-k +Display statistics in kilobytes per second. +.TP +.B \-m +Display statistics in megabytes per second. +.TP +.B \-N +Display the registered device mapper names for any device mapper devices. +Useful for viewing LVM2 statistics. +.TP +.B \-o JSON +Display the statistics in JSON (JavaScript Object Notation) format. +JSON output field order is undefined, and new fields may be added +in the future. +.TP +.BI "\-p [ { " "device" "[,...] | ALL } ]" +Display statistics for +block devices and all their partitions that are used by the system. +If a device name is entered on the command line, then statistics for it +and all its partitions are displayed. Last, the +.B ALL +keyword indicates that statistics have to be displayed for all the block +devices and partitions defined by the system, including those that have +never been used. If option +.B \-j +is defined before this option, devices entered on the command line can be +specified with the chosen persistent name type. +.TP +.B \-\-pretty +Make the Device Utilization Report easier to read by a human. +The device name will be printed on the right side. The report may also be broken +into sub-reports if there are many metrics to display (use +.B \-\-compact +option to prevent this). +.TP +.B \-s +Display a short (narrow) version of the report that should fit in 80 +characters wide screens. +.TP +.B \-t +Print the time for each report displayed. The timestamp format may depend +on the value of the +.BR "S_TIME_FORMAT " "environment variable (see below)." +.TP +.B \-V +Print version number then exit. +.TP +.B \-x +Display extended statistics. +.TP +.B \-y +Omit first report with statistics since system boot, if displaying +multiple records at given interval. +.TP +.B \-z +Tell +.B iostat +to omit output for any devices for which there was no activity +during the sample period. + +.SH ENVIRONMENT +The +.B iostat +command takes into account the following environment variables: +.TP +.B POSIXLY_CORRECT +When this variable is set, transfer rates are shown in 512-byte blocks instead +of the default 1K blocks. +.TP +.B S_COLORS +By default statistics are displayed in color when the output is connected to a terminal. +Use this variable to change the settings. Possible values for this variable are +.IR "never" ", " "always " "or " "auto" +(the latter is equivalent to the default settings). +.br +Please note that the color (being red, yellow, or some other color) used to display a value +is not indicative of any kind of issue simply because of the color. It only indicates different +ranges of values. +.TP +.B S_COLORS_SGR +Specify the colors and other attributes used to display statistics on the terminal. +Its value is a colon-separated list of capabilities that defaults to +.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "." +Supported capabilities are: +.RS +.TP +.B I= +SGR (Select Graphic Rendition) substring for device names. +.TP +.B N= +SGR substring for non-zero statistics values. +.TP +.BR "W=" " (or " "M=" ")" +SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the +metric's meaning). +.TP +.BR "X=" " (or " "H=" ")" +SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the +metric's meaning). +.TP +.B Z= +SGR substring for zero values. +.RE +.TP +.B S_TIME_FORMAT +If this variable exists and its value is +.B ISO +then the current locale will be ignored when printing the date in the report +header. The +.B iostat +command will use the ISO 8601 format (YYYY-MM-DD) instead. +The timestamp displayed with option +.B \-t +will also be compliant with ISO 8601 format. + +.SH EXAMPLES +.TP +.B iostat +Display a single history since boot report for all CPU and Devices. +.TP +.B iostat \-d 2 +Display a continuous device report at two second intervals. +.TP +.B iostat \-d 2 6 +Display six reports at two second intervals for all devices. +.TP +.B iostat \-x sda sdb 2 6 +Display six reports of extended statistics at two second intervals for devices +sda and sdb. +.TP +.B iostat \-p sda 2 6 +Display six reports at two second intervals for device sda and all its +partitions (sda1, etc.) + +.SH BUGS +.IR "/proc " "filesystem must be mounted for" +.BR "iostat " "to work." +.PP +Kernels older than 2.6.x are no longer supported. +.PP +.RB "Although " "iostat" +speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)... +A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes. + +.SH FILES +.IR "/proc/stat " "contains system statistics." +.br +.IR "/proc/uptime " "contains system uptime." +.br +.IR "/proc/diskstats " "contains disks statistics." +.br +.IR "/sys " "contains statistics for block devices." +.br +.IR "/proc/self/mountstats " "contains statistics for network filesystems." +.br +.IR "/dev/disk " "contains persistent device names." + +.SH AUTHOR +Sebastien Godard (sysstat orange.fr) + +.SH SEE ALSO +.BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "tapestat" "(1), " "nfsiostat" "(1)," +.BR "cifsiostat" "(1)" +.PP +.I https://github.com/sysstat/sysstat +.br +.I https://sysstat.github.io/ diff --git a/upstream/fedora-40/man1/isodebug.1 b/upstream/fedora-40/man1/isodebug.1 new file mode 100644 index 00000000..58f0d9d3 --- /dev/null +++ b/upstream/fedora-40/man1/isodebug.1 @@ -0,0 +1,108 @@ +.\" @(#)isodebug.8 1.1 06/02/08 Copyr 2006 J. Schilling +.\" Manual page for isodebug +.\" Modified for cdrkit distribution by E.Bloch +.\" +.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a +.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o +.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u +.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A +.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O +.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U +.if t .ds s \\(*b +.if t .ds S SS +.if n .ds a ae +.if n .ds o oe +.if n .ds u ue +.if n .ds s sz +.TH ISODEBUG 1 "06/02/08" "J\*org Schilling" "Schily\'s USER COMMANDS" +.SH NAME +isodebug \- print genisoimage debug info from ISO-9660 image +.SH SYNOPSIS +.B +isodebug +[ +.I options +] +[ +.I file +] +.SH DESCRIPTION +.B Isodebug +reads the debug info written by +.BR genisoimage (8) +from within a ISO-9660 file system image and prints them. +. \" .SH RETURNS +. \" .SH ERRORS +.SH OPTIONS +.TP +.B \-help +Prints a short summary of the +.B isodebug +options and exists. +.TP +.B \-version +Prints the +.B isodebug +version number string and exists. +.TP +.BI \-i " filename +Filename to read ISO-9660 image from. +.TP +.BI dev= target +SCSI target to use as CD/DVD-Recorder. +See +.BR wodim (1) +for more information on now to use this option. +.SH FILES +.SH "SEE ALSO" +.BR wodim (1), +.BR genisoimage (1). +.SH AUTHOR +.nf +J\*org Schilling +Seestr. 110 +D-13353 Berlin +Germany +.fi +.PP + + +.SH AUTHOR +.nf +J\*org Schilling +Seestr. 110 +D-13353 Berlin +Germany +.fi + +.PP +This manpage describes the program implementation of +.B +isodebug +as shipped by the cdrkit distribution. See +.B +http://alioth.debian.org/projects/debburn/ +for details. It is a spinoff from the original program distributed in the +cdrtools package [1]. However, the cdrtools developers are not +involved in the development of this spinoff and therefore shall not be made +responsible for any problem caused by it. Do not try to get support for this +program by contacting the original author(s). +.PP +If you have support questions, send them to +.PP +.B +debburn-devel@lists.alioth.debian.org +.br +.PP +If you have definitely found a bug, send a mail to this list or to +.PP +.B +submit@bugs.debian.org +.br +.PP +writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body. +.PP +.br +[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de + + diff --git a/upstream/fedora-40/man1/isoinfo.1 b/upstream/fedora-40/man1/isoinfo.1 new file mode 100644 index 00000000..1a00540a --- /dev/null +++ b/upstream/fedora-40/man1/isoinfo.1 @@ -0,0 +1,365 @@ +.\" +.\" @(#)isoinfo.8 1.7 04/06/01 joerg +.\" +.\" Modified for cdrkit in 12/2006 +.\" +.\" -*- nroff -*- +.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a +.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o +.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u +.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A +.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O +.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U +.if t .ds s \\(*b +.if t .ds S SS +.if n .ds a ae +.if n .ds o oe +.if n .ds u ue +.if n .ds s sz +.TH ISOINFO 1 "04/06/01" "Version 2.0" +.SH NAME +devdump, isoinfo, isovfy, isodump \- Utility programs for dumping and verifying iso9660 +images. +.SH SYNOPSIS +.B devdump +.I isoimage +.PP +.B isodump +.I isoimage +.PP +.B isoinfo +[ +.B \-d +] +[ +.B \-h +] +[ +.B \-R +] +[ +.B \-J +] +[ +.B \-j +.I charset +] +[ +.B \-f +] +[ +.B \-l +] +[ +.B \-p +] +[ +.B \-T +.I sector +] +[ +.B \-N +.I sector +] +[ +.B \-i +.I isoimage +] +[ +.B \-x +.I path +] +.PP +.B isovfy +.I isoimage +.SH DESCRIPTION +.B devdump +is a crude utility to interactively display the contents of device or +filesystem images. +The initial screen is a display of the first 256 bytes of the first 2048 byte +sector. +The commands are the same as with +.BR isodump . +.PP +.B isodump +is a crude utility to interactively display the contents of iso9660 images +in order to verify directory integrity. +The initial screen is a display of the first part of the root directory, +and the prompt shows you the extent number and offset in the extent. +.RS +.PP +You can use the 'a' and 'b' +commands to move backwards and forwards within the image. The 'g' command +allows you to goto an arbitrary extent, and the 'f' command specifies +a search string to be used. The '+' command searches forward for the next +instance of the search string, and the 'q' command exits +.B devdump +or +.BR isodump . +.RE +.PP +.B isoinfo +is a utility to perform directory like listings of iso9660 images. +.PP +.B isovfy +is a utility to verify the integrity of an iso9660 image. Most of the tests +in +.B isovfy +were added after bugs were discovered in early versions of +.B genisoimage. +It isn't all that clear how useful this is anymore, but it doesn't hurt to +have this around. + +.SH OPTIONS +The options common to all programs are +.BR \-help , \-h , \-version , +.BI i =name, dev =name. +The +.B isoinfo +program has additional command line options. The options are: +.TP +.B \-help +.TP +.B \-h +print a summary of all options. +.TP +.B \-d +Print information from the primary volume descriptor (PVD) of the iso9660 +image. This includes information about Rock Ridge, Joliet extensions +and Eltorito boot information +if present. +.TP +.B \-f +generate output as if a 'find . -print' command had been run on the iso9660 +image. You should not use the +.B -l +image with the +.B -f +option. +.TP +.B \-i iso_image +Specifies the path of the iso9660 image that we wish to examine. +The options +.B \-i +and +.BI dev= target +are mutual exclusive. +.TP +.BI dev= target +Sets the SCSI target for the drive, see notes above. +A typical device specification is +.BI dev= 6,0 +\&. +If a filename must be provided together with the numerical target +specification, the filename is implementation specific. +The correct filename in this case can be found in the system specific +manuals of the target operating system. +On a +.I FreeBSD +system without +.I CAM +support, you need to use the control device (e.g. +.IR /dev/rcd0.ctl ). +A correct device specification in this case may be +.BI dev= /dev/rcd0.ctl:@ +\&. +.sp +On Linux, drives connected to a parallel port adapter are mapped +to a virtual SCSI bus. Different adapters are mapped to different +targets on this virtual SCSI bus. +.sp +If no +.I dev +option is present, the program +will try to get the device from the +.B CDR_DEVICE +environment. +.sp +If the argument to the +.B dev= +option does not contain the characters ',', '/', '@' or ':', +it is interpreted as an label name that may be found in the file +/etc/wodim.conf (see FILES section). +.sp +The options +.B \-i +and +.BI dev= target +are mutual exclusive. +.TP +.B \-l +generate output as if a 'ls -lR' command had been run on the iso9660 image. +You should not use the +.B -f +image with the +.B -l +option. +.TP +.B \-N sector +Quick hack to help examine single session disc files that are to be written to +a multi-session disc. The sector number specified is the sector number at +which the iso9660 image should be written when send to the cd-writer. Not +used for the first session on the disc. +.TP +.B \-p +Print path table information. +.TP +.B \-R +Extract information from Rock Ridge extensions (if present) for permissions, +file names and ownerships. +.TP +.B \-J +Extract information from Joliet extensions (if present) for file names. +.TP +.B \-j charset +Convert Joliet file names (if present) to the supplied charset. See +.BR genisoimage (8) +for details. +.TP +.B \-T sector +Quick hack to help examine multi-session images that have already been burned +to a multi-session disc. The sector number specified is the sector number for +the start of the session we wish to display. +.TP +.B \-x pathname +Extract specified file to stdout. +.SH AUTHOR +The author of the original sources (1993 .\|.\|. 1998) is +Eric Youngdale or is to blame +for these shoddy hacks. +J\*org Schilling wrote the SCSI transport library and its adaptation layer to +the programs and newer parts (starting from 1999) of the utilities, this makes +them +Copyright (C) 1999-2004 J\*org Schilling. +Patches to improve general usability would be gladly accepted. +.PP +This manpage describes the program implementation of +.B +isoinfo +as shipped by the cdrkit distribution. See +.B +http://alioth.debian.org/projects/debburn/ +for details. It is a spinoff from the original program distributed in the +cdrtools package [1]. However, the cdrtools +developers are not involved in the development of this spinoff and therefore +shall not be made responsible for any problem caused by it. Do not try to get +support for this program by contacting the original author(s). +.PP +If you have support questions, send them to +.PP +.B +debburn-devel@lists.alioth.debian.org +.br +.PP +If you have definitely found a bug, send a mail to this list or to +.PP +.B +submit@bugs.debian.org +.br +.PP +writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body. +.SH BUGS +The user interface really sucks. +.SH FUTURE IMPROVEMENTS +These utilities are really quick hacks, which are very useful for debugging +problems in genisoimage or in an iso9660 filesystem. In the long run, it would +be nice to have a daemon that would NFS export a iso9660 image. +.PP +The isoinfo program is probably the program that is of the most use to +the general user. +.SH AVAILABILITY +These utilities come with the +.B cdrkit +package, and the primary download site +is http://debburn.alioth.debian.org/ and FTP mirrors of distributions. +Despite the name, the software is not beta. + +.SH ENVIRONMENT +.TP +.B CDR_DEVICE +This may either hold a device identifier that is suitable to the open +call of the SCSI transport library or a label in the file /etc/wodim.conf. +.TP +.B RSH +If the +.B RSH +environment is present, the remote connection will not be created via +.BR rcmd (3) +but by calling the program pointed to by +.BR RSH . +Use e.g. +.BR RSH= /usr/bin/ssh +to create a secure shell connection. +.sp +Note that this forces the program +to create a pipe to the +.B rsh(1) +program and disallows the program +to directly access the network socket to the remote server. +This makes it impossible to set up performance parameters and slows down +the connection compared to a +.B root +initiated +.B rcmd(3) +connection. +.TP +.B RSCSI +If the +.B RSCSI +environment is present, the remote SCSI server will not be the program +.B /opt/schily/sbin/rscsi +but the program pointed to by +.BR RSCSI . +Note that the remote SCSI server program name will be ignored if you log in +using an account that has been created with a remote SCSI server program as +login shell. + +.SH FILES +.TP +/etc/wodim.conf +Default values can be set for the following options in /etc/wodim.conf. +.RS +.TP +CDR_DEVICE +This may either hold a device identifier that is suitable to the open +call of the SCSI transport library or a label in the file /etc/wodim.conf +that allows to identify a specific drive on the system. +.TP +Any other label +is an identifier for a specific drive on the system. +Such an identifier may not contain the characters ',', '/', '@' or ':'. +.sp +Each line that follows a label contains a TAB separated list of items. +Currently, four items are recognized: the SCSI ID of the drive, the +default speed that should be used for this drive, the default FIFO size +that should be used for this drive and drive specific options. The values for +.I speed +and +.I fifosize +may be set to -1 to tell the program to use the global defaults. +The value for driveropts may be set to "" if no driveropts are used. +A typical line may look this way: +.sp +teac1= 0,5,0 4 8m "" +.sp +yamaha= 1,6,0 -1 -1 burnfree +.sp +This tells the program +that a drive named +.I teac1 +is at scsibus 0, target 5, lun 0 and should be used with speed 4 and +a FIFO size of 8 MB. +A second drive may be found at scsibus 1, target 6, lun 0 and uses the +default speed and the default FIFO size. +.RE +.SH SEE ALSO +.BR genisoimage (1), +.BR wodim (1), +.BR readcd (1), +.BR ssh (1). +.RE +.SH SOURCES +.PP +.br +[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de + diff --git a/upstream/fedora-40/man1/jbigtopnm.1 b/upstream/fedora-40/man1/jbigtopnm.1 new file mode 100644 index 00000000..88c6ab8f --- /dev/null +++ b/upstream/fedora-40/man1/jbigtopnm.1 @@ -0,0 +1,141 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Jbigtopnm User Manual" 0 "28 July 2020" "netpbm documentation" + +.SH NAME +jbigtopnm - JBIG to PNM image file converter + +.UN synopsis +.SH SYNOPSIS + +\fBjbigtopnm\fP +[\fB-xmax\fP] +[\fB-ymax\fP] +[\fB-binary\fP] +[\fB-diagnose\fP] +[\fB-plane\fP] +[\fIinput-file\fP [\fIoutput-file\fP]] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBjbigtopnm\fP reads a JBIG bi-level image entity (BIE) from a +file or standard input, decompresses it, and outputs a PBM or PGM +file. If the input has one plane, or you choose just one plane of it, +the output is PBM. Otherwise, the output is PGM. +.PP +JBIG is a highly effective lossless compression algorithm for +bi-level images (one bit per pixel), which is particularly suitable +for scanned document pages. +.PP +A JBIG encoded image can be stored in several resolutions in one or +several BIEs. All resolution layers except the lowest one are stored +efficiently as differences to the next lower resolution layer. You +can use options \fB-x\fP and \fB-y\fP to stop the decompression at a +specified maximal output image size. The input file can consist of +several concatenated BIEs which contain different increasing +resolution layers of the same image. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBjbigtopnm\fP recognizes the following +command line options: +.PP +Before Netpbm 10.85 (December 2018), only single-character single-hyphen +abbreviations of the options are accepted. + + + +.TP +\fB-xmax\fP \fInumber\fP +Decode only up to the largest resolution layer which is still not +more than \fInumber\fP pixels wide. If no such resolution layer +exists, then use the smallest one available. + +.TP +\fB-ymax\fP\fI number\fP +Decode only up to the largest resolution layer which is still not +more than \fInumber\fP pixels high. If no such resolution layer +exists, then use the smallest one available. You can also use options +\fB-x\fP and \fB-y\fP together which selects the largest layer that +satisfies both limits. + +.TP +\fB-binary\fP +Use binary values instead of Gray code words in order to decode +pixel values from multiple bitplanes. This option has effect only if +the input has more than one bitplane and you don't select just one of +those bitplanes. Note that the decoder has to be used in the same +mode as the encoder and cannot determine from the BIE, whether Gray or +binary code words were used by the encoder. + +.TP +\fB-diagnose\fP +Diagnose a BIE. With this option, \fBjbigtopnm\fP only prints a +summary of the header information found in the input file and then +exits. + +.TP +\fB-plane\fP\fI number\fP +If the input contains multiple bitplanes, then extract only the +specified single plane as a PBM file. The first plane has number 0. + + + +.UN standards +.SH STANDARDS +.PP +This program implements the JBIG image coding algorithm as +specified in ISO/IEC 11544:1993 and ITU-T T.82(1993). + +.UN author +.SH AUTHOR + + +.PP +\fBjbigtopnm\fP is based on the JBIG library by Markus Kuhn, part +of his +.UR http://www.cl.cam.ac.uk/~mgk25/jbigkit/ +\fBJBIG-KIT\fP package +.UE +\&. The \fBjbgtopbm\fP program is part of the +\fBJBIG-KIT\fP package. +.PP +\fBjbigtopnm\fP is part of the Netpbm package of graphics tools. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (1)\c +\&, +.BR "pnmtojbig" (1)\c +\& + +.UN license +.SH LICENSE +.PP +There was at one time concern about the need for patent licenses to +use \fBjbigtopnm\fP, but any relevant patents expired by 2012. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/jbigtopnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man1/jed.1 b/upstream/fedora-40/man1/jed.1 new file mode 100644 index 00000000..04471ecd --- /dev/null +++ b/upstream/fedora-40/man1/jed.1 @@ -0,0 +1,517 @@ +.\" ================================================================== +.\" Jed programmers editor, this manpage was writen by +.\" "Boris D. Beletsky" copyright(c) 1996 +.\" This manpage may be freely distrebuted as part of GNU Debian Linux +.\" ================================================================== +.TH JED 1 "OCT 1996" Debian "User Manuals" +.SH NAME +Jed \- programmers editor +.SH SYNOPSIS +.B jed \-\-version +.br +.B jed\-script \-\-version +.br +.B xjed \-\-version +.sp +.B jed [\-\-secure] [\-\-batch|\-\-script|\-\-help] [options] +.I file +.B ... +.br +.B jed\-script [\-\-secure] +.I script file +.B [script options] ... +.br +.B xjed [\-\-secure] [X options] [\-\-batch|\-\-script|\-\-help] [options] +.I file +.B ... +.SH DESCRIPTION +.B Jed - programmers editor +.LP +Features: +.LP +Color syntax +.I highlighting. +Emulation of +.B Emacs, +.B EDT, +.B Wordstar, +and Brief editors. +Extensible in a language resembling C. Completely customizable. +Editing TeX files with AUC-TeX style editing (BiBTeX support too). +Folding support, and much more... +.LP +For complete documentation, see GNU info files, this manual only +provides brief tutorial. +.SH OPTIONS +.SS major options +.LP +.I \-\-version +.RS +prints the version and compiletime variables. +.RE +.I \-\-help +.RS +prints usage information. +.RE +.I \-\-secure +.RS +runs Jed in secure mode, e.g. you can't run any external commands with +.I system() +or +.I run_shell_cmd(). +.RE +.I \-\-batch +.RS +run Jed in batch mode. +This is a non-interactive mode. +.RE +.I \-\-script +.RS +this is a mode like +.I \-\-batch +but jed does not eval the startup files. It behaves like +.I slsh. +You must give the file that should be evaluated as second argument. It's +the same as calling +.B jed\-script. +.SS minor options +.LP +.I \-n +.RS +do not load +.I .jedrc +file. +.RE +.I \-a 'file' +.RS +load +.I file +as user configuration file instead of .jedrc. +.RE +.I + 'n' +.RS +goto line +.I n +in buffer (notice that in order to this option to take effect, if must +appear before the file name in the command line, like 'jed +3 file') +.RE +.I \-g 'n' +.RS +goto line +.I n +in buffer (notice that in order to this option to take effect, if must +appear after the file name in the command line, like 'jed file \-g 3') +.RE +.I \-l 'file' +.RS +load +.I file +as S\-Lang code. +.RE +.I \-f 'function' +.RS +execute S\-Lang function named +.I function +.RE +.I \-s 'string' +.RS +search forward for +.I string +.RE +.I \-2 +.RS +split window +.RE +.I \-i 'file' +.RS +insert +.I file +into current buffer. +.RE +.LP +.SS X options +.B xjed +accapts the common options like +.I \-display, \-name, \-fn and \-geometry. +Additionaly it accepts +.LP +.I \-facesize SIZE, \-fs SIZE +.RS +if build with XRENDERFONT support, selects the font size +.I SIZE. +Use it with the option +.I \-fn +to select a scalable font. +.RE +.I \-foreground COLOR, \-fg COLOR +.RS +sets the foreground color. +.RE +.I \-background COLOR, \-bg COLOR +.RS +sets the background color. +.RE +.I \-fgMouse COLOR, \-mfg COLOR +.RS +sets the foreground color of the mouse pointer. +.RE +.I \-bgMouse COLOR, \-mbg COLOR +.RS +sets the background color of the mouse pointer. +.RE +.I \-Iconic, \-ic +.RS +start iconified. +.RE +.I \-title NAME +.RS +sets the window title to +.I NAME. +.RE +.LP +For more options look at +.B xterm.c. +.SH CONFIGURATION +.RS +.I Emulating Other Editors +.RE +.LP +JED's ability to create new functions using the +.I S\-Lang +programming language as well as allowing the user to choose key bindings, +makes the emulation of other editors possible. Currently, JED provides +reasonable emulation of the +.I Emacs, EDT, and Wordstar +editors. +.LP +.RS +.I Emacs Emulation +.RE +.LP +.I Emacs Emulation +is provided by the S\-Lang code in +.I emacs.sl. +The +basic functionality of Emacs is emulated; most Emacs users +should have no problem with JED. To enable Emacs emulation in JED, make sure +that the line: +.LP +.RS +.I () = evalfile ("emacs"); +.RE +.LP +is in your +.I jed.rc +(.jedrc) startup file. JED is distributed +with this line already present in the default jed.rc file. +.LP +.RS +.I EDT Emulation +.RE +.LP +For +.I EDT +emulation, +.I edt.sl +must be loaded. This is accomplished by +ensuring that the line: +.LP +.RS +.I () = evalfile ("edt"); +.RE +.LP +is in present in the jed.rc (.jedrc) Startup File. +.LP +.RS +.I Wordstar Emulation +.RE +.LP +wordstar.sl contains the S\-Lang code for JED's Wordstar +emulation. Adding the line +.LP +.RS +.I () = evalfile ("wordstar"); +.RE +.LP +to your jed.rc (.jedrc) startup file will enable JED's +Wordstar emulation. +.SH RUN TIME +.LP +.RS +.I Status line and Windows +.RE +.LP +.I JED +supports multiple windows. Each window may contain the same +buffer or +different buffers. A status line is displayed immediately below +each +window. The status line contains information such as the JED +version +number, the buffer name, +.I mode, +etc. Please beware of the +following indicators: +.LP +.I ** +.RS +buffer has been modified since last save. +.RE +.I %% +.RS +buffer is read only. +.RE +.I m +.RS +Mark set indicator. This means a region is being defined. +.RE +.I d +.RS +File changed on disk indicator. This indicates that the +file associated with the buffer is newer than the +buffer itself. +.RE +.I s +.RS +spot pushed indicator. +.RE +.I + +.RS +Undo is enabled for the buffer. +.RE +.I [Narrow] +.RS +Buffer is narrowed to a region of LINES. +.RE +.I [Macro] +.RS +A macro is being defined. +.RE +.LP +.RS +.I Mini-Buffer. +.RE +.LP +The +.I Mini-Buffer +consists of a single line located at the bottom of the +screen. Much of the dialog between the user and JED takes place in this +buffer. For example, when you search for a string, JED will prompt you +for the string in the Mini-Buffer. +.LP +The +.I Mini-Buffer +also provides a direct link to the S\-Lang interpreter. +To access the interpreter, press +.I Ctrl-X Esc +and the +.I S\-Lang> +prompt will appear in the Mini-Buffer. Enter any valid S\-Lang expression for +evaluation by the interpreter. +.LP +It is possible to recall data previously entered into the +.I Mini-Buffer +by using the up and down arrow keys. This makes it possible to use and edit +previous expressions in a convenient and efficient manner. +.LP +.RS +.I Basic Editing +.RE +.LP +.I Editing with JED +is pretty easy - most keys simply insert themselves. +Movement around the buffer is usually done using the +.I arrow keys or page up and page down keys. +If +.I edt.sl +is loaded, the keypads on +VTxxx +terminals function as well. Here, only the +highlights are +touched upon +(cut/paste operations are not considered `highlights'). +In the following, any character prefixed by the +.I ^ +character denotes a +Control character. On keyboards without an explicit Escape key, +.I "Ctrl-[" +will most likely generate and Escape character. +.LP +A +.I prefix argument +to a command may be generated by first hitting the +.I Esc +key, then entering the number followed by pressing the desired +key. Normally, the prefix argument is used simply for +repetition. For +example, +to move to the right 40 characters, one would press +.I "Esc 4 0" +followed immediately by the right arrow key. +This illustrates the use of the repeat argument for repetition. +However, the +prefix argument may be used in other ways as well. For example, +to begin +defining a region, one would press the +.I "Ctrl-@" +key. This sets the mark and begins highlighting. +Pressing the +.I "Ctrl-@" +key with a prefix +argument will abort the act of defining the region and to pop the +mark. + +The following list of useful keybindings assumes that +.I emacs.sl +has been loaded. +.LP +.I Ctrl-L +.RS +Redraw screen. +.RE +.I Ctrl-_ +.RS +Undo (Control-underscore, also Ctrl-X u'). +.RE +.I Esc q +.RS +Reformat paragraph (wrap mode). Used with a prefix +argument. will justify the paragraph as well. +.RE +.I Esc n +.RS +narrow paragraph +(wrap mode). Used with a prefix +argument will justify the paragraph as well. +.RE +.I Esc ; +.RS +Make Language comment (Fortran +and C) +.RE +.I Esc \\\\ +.RS +Trim whitespace around point +.RE +.I Esc ! +.RS +Execute shell command +.RE +.I Esc $ +.RS +Ispell word +.RE +.I Ctrl-X ? +.RS +Show line/column information. +.RE +.I ` +.RS +quoted_insert --- insert +next char as is (backquote key) +.RE +.I Esc s +.RS +Center line. +.RE +.I Esc u +.RS +Upcase word. +.RE +.I Esc d +.RS +Downcase word. +.RE +.I Esc c +.RS +Capitalize word. +.RE +.I Esc x +.RS +Get M-x minibuffer prompt with command +completion +.RE +.I Ctrl-X Ctrl-B +.RS +pop up a list of buffers +.RE +.I Ctrl-X Ctrl-C +.RS +exit JED +.RE +.I Ctrl-X 0 +.RS +Delete +Current Window +.RE +.I Ctrl-X 1 +.RS +One Window. +.RE +.I Ctrl-X 2 +.RS +Split Window. +.RE +.RS +.I Ctrl-X o +.RE +.RS +Other window. +.RE +.I Ctrl-X b +.RS +switch to buffer +.RE +.I Ctrl-X k +.RS +kill buffer +.RE +.I Ctrl-X s +.RS +save some buffers +.RE +.I Ctrl-X Esc +.RS +Get "S\-Lang>" prompt for interface to the S\-Lang +interpreter. +.RE +.I Esc . +.RS +Find tag +.RE +.I Ctrl-@ +.RS +Set Mark (Begin defining a region). Used with a +prefix argument aborts the act +of defining the region and +pops the Mark. +.RE +.RE +.\"--------------------------------------------------------- +.SH FILES +.I /usr/share/jed/lib/*.sl +.RS +these are the default runtime jed slang files +.RE +.I /usr/share/jed/lib/site.sl +.RS +This is the default startup file. +.RE +.I /etc/jed.rc +.RS +The system wide configuration file. +.RE +.I ~/.jedrc +.RS +Per user configuration file. +.SH AUTHOR +.I "John E. Davis" +.RS +Jed's Author +.RE + + +--- This document was +.I translated +to nroff +by "Boris D. Beletsky" diff --git a/upstream/fedora-40/man1/joe.1 b/upstream/fedora-40/man1/joe.1 new file mode 100644 index 00000000..2f334656 --- /dev/null +++ b/upstream/fedora-40/man1/joe.1 @@ -0,0 +1,6002 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "JOE" "" "March 2016" "" "" +. +.SH "NAME" +\fBJOE\fR \- Joe\'s Own Editor +. +.SH "Syntax" +\fBjoe [global\-options] [ [local\-options] filename ]\.\.\.\fR +. +.br +\fBjstar [global\-options] [ [local\-options] filename ]\.\.\.\fR +. +.br +\fBjmacs [global\-options] [ [local\-options] filename ]\.\.\.\fR +. +.br +\fBrjoe [global\-options] [ [local\-options] filename ]\.\.\.\fR +. +.br +\fBjpico [global\-options] [ [local\-options] filename ]\.\.\.\fR +. +.SH "Description" +JOE is a powerful console screen editor\. It has a "mode\-less" user interface which is similar to many user\-friendly PC editors\. Users of Micro\-Pro\'s WordStar or Borland\'s "Turbo" languages will feel at home\. JOE is a full featured UNIX screen\-editor though, and has many features for editing programs and text\. +. +.P +JOE also emulates several other editors\. JSTAR is a close imitation of WordStar with many "JOE" extensions\. JPICO is a close imitation of the Pine mailing system\'s PICO editor, but with many extensions and improvements\. JMACS is a GNU\-EMACS imitation\. RJOE is a restricted version of JOE, which allows you to edit only the files specified on the command line\. +. +.P +Although JOE is actually five different editors, it still requires only one executable, but one with five different names\. The name of the editor with an "rc" appended gives the name of JOE\'s initialization file, which determines the personality of the editor\. +. +.P +JOE is free software; you can distribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation\. JOE is available over the Internet from \fIhttp://www\.sourceforge\.net/projects/joe\-editor\fR\. +. +.SH "Usage" +To start the editor, type \fBjoe\fR followed by zero or more names of files you want to edit\. Each file name may be preceded by a local option setting (see the local options table which follows)\. Other global options, which apply to the editor as a whole, may also be placed on the command line (see the global options table which follows)\. If you are editing a new file, you can either give the name of the new file when you invoke the editor, or in the editor when you save the new file\. A modified syntax for file names is provided to allow you to edit program output, standard input/output, or sections of files or devices\. See the section \fIFilenames\fR below for details\. +. +.P +Once you are in the editor, you can type in text and use special control\-character sequences to perform other editing tasks\. To find out what the control\-character sequences are, read the rest of this man page or type \fB^K H\fR for help in the editor\. +. +.P +Now for some obscure computer\-lore: +. +.P +The \fB^\fR means that you hold down the \fBControl\fR key while pressing the following key (the same way the \fBShift\fR key works for uppercase letters)\. A number of control\-key sequences are duplicated on other keys, so that you don\'t need to press the control key: \fBEsc\fR will work in place of \fB^[\fR, \fBDel\fR will work in place of \fB^?\fR, \fBBackspace\fR will work in place of \fB^H\fR, \fBTab\fR will work in place of \fB^I\fR, \fBReturn\fR or \fBEnter\fR will work in place of \fB^M\fR and \fBLinefeed\fR will work in place of \fB^J\fR\. Some keyboards may give you trouble with some control keys\. \fB^\fR_, \fB^^\fR and \fB^@\fR can usually be entered without pressing shift (i\.e\., try \fB^\-\fR, \fB^6\fR and \fB^2\fR)\. Other keyboards may reassign these to other keys\. Try: \fB^\.\fR, \fB^,\fR and \fB^/\fR\. \fB^Space\fR can usually be used in place of \fB^@\fR\. \fB^\e\fR and \fB^]\fR are interpreted by many communication programs, including telnet and kermit\. Usually you just hit the key twice to get it to pass through the communication program\. +. +.P +On some keyboards, holding the \fBAlt\fR key down while pressing another key is the same as typing \fBEsc\fR before typing the other key\. +. +.P +Once you have typed \fB^K H\fR, the first help window appears at the top of the screen\. You can continue to enter and edit text while the help window is on\. To page through other topics, hit \fBEsc ,\fR and \fBEsc \.\fR (that is, \fBEsc ,\fR and \fBEsc \.\fR)\. Use \fB^K H\fR to dismiss the help window\. +. +.P +You can customize the keyboard layout, the help screens and a number of behavior defaults by copying JOE\'s initialization file (usually \fB/etc/joe/joerc\fR) to \fB\.joerc\fR in your home directory and then by modifying it\. See the section \fIjoerc\fR below\. +. +.P +To have JOE used as your default editor for e\-mail and News, you need to set the \fBEDITOR\fR and \fBVISUAL\fR environment variables in your shell initialization file (\fB\.cshrc\fR or \fB\.profile\fR) to refer to JOE (JOE usually resides as \fB/usr/bin/joe\fR)\. +. +.P +There are a number of other obscure invocation parameters which may have to be set, particularly if your terminal screen is not updating as you think it should\. See the section \fIEnvironment variables\fR below\. +. +.P + \fI\fR +. +.SH "Command Line Options" +These options can also be specified in the joerc file\. Local options can be set depending on the file\-name extension\. Programs (\.c, \.h or \.p extension) usually have autoindent enabled\. Wordwrap is enabled on other files, but rc files have it disabled\. +. +.P +An option is enabled when it\'s given like this: +. +.IP "" 4 +. +.nf + +\-wordwrap +. +.fi +. +.IP "" 0 +. +.P +An option is disabled when it\'s given like this: +. +.IP "" 4 +. +.nf + +\-\-wordwrap +. +.fi +. +.IP "" 0 +. +.P +Some options take arguments\. Arguments are given like this: +. +.IP "" 4 +. +.nf + +\-lmargin 5 +. +.fi +. +.IP "" 0 +. +.P +The following global options may be specified on the command line: +. +.IP "\(bu" 4 +asis +. +.br +Characters with codes above 127 will be sent to the terminal as\-is, instead of as inverse of the corresponding character below 128\. If this does not work, check your terminal server\. This option has no effect if UTF\-8 encoding is used\. +. +.br + +. +.IP "\(bu" 4 +assume_256color +. +.br +Assume ANSI\-like terminal emulator supports 256 colors even if termcap entry says it doesn\'t\. +. +.br + +. +.IP "\(bu" 4 +assume_color +. +.br +Assume ANSI\-like terminal emulator supports color even if termcap entry says it doesn\'t\. +. +.br + +. +.IP "\(bu" 4 +text_color \fBcolor\fR +. +.br +Set color for text\. +. +.br + +. +.IP "\(bu" 4 +status_color \fBcolor\fR +. +.br +Set color for status bar\. +. +.br + +. +.IP "\(bu" 4 +help_color \fBcolor\fR +. +.br +Set color for help\. +. +.br + +. +.IP "\(bu" 4 +menu_color \fBcolor\fR +. +.br +Set color for menus\. +. +.br + +. +.IP "\(bu" 4 +prompt_color \fBcolor\fR +. +.br +Set color for prompts\. +. +.br + +. +.IP "\(bu" 4 +msg_color \fBcolor\fR +. +.br +Set color for messages\. +. +.br + +. +.IP "\(bu" 4 +autoswap +. +.br +Automatically swap \fB^K B\fR with \fB^K K\fR if necessary to mark a legal block during block copy/move commands\. +. +.br + +. +.IP "\(bu" 4 +backpath path +. +.br +Sets path to a directory where all backup files are to be stored\. If this is unset (the default) backup files are stored in the directory containing the file\. +. +.br + +. +.IP "\(bu" 4 +baud nnn +. +.br +Set the baud rate for the purposes of terminal screen optimization (overrides value reported by stty)\. JOE inserts delays for baud rates below 19200, which bypasses tty buffering so that typeahead will interrupt the screen output\. Scrolling commands will not be used for 38400 baud and above\. This is useful for X\-terms and other console ttys which really aren\'t going over a serial line\. +. +.br + +. +.IP "\(bu" 4 +beep +. +.br +Enable beeps when edit commands return errors, for example when the cursor goes past extremes\. +. +.br + +. +.IP "\(bu" 4 +break_links +. +.br +When enabled, JOE first deletes the file before writing it in order to break hard\-links and symbolic\-links\. +. +.br + +. +.IP "\(bu" 4 +break_hardlinks +. +.br +When enabled, and the file is not a symbolic links, JOE first deletes the file before writing it in order to break hard\-links\. +. +.br + +. +.IP "\(bu" 4 +brpaste +. +.br +When JOE starts, send command to the terminal emulator that enables "bracketed paste mode" (but only if the terminal seems to have the ANSI command set)\. In this mode, text pasted into the window is bracketed with ESC [ 2 0 0 ~ and ESC [ 2 0 1 ~\. +. +.br + +. +.IP "\(bu" 4 +columns nnn +. +.br +Set number of columns in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\. +. +.br + +. +.IP "\(bu" 4 +csmode +. +.br +Enable continued search mode: Successive \fB^K F\fRs repeat the current search instead of prompting for a new one\. +. +.br + +. +.IP "\(bu" 4 +dopadding +. +.br +Enable JOE to send padding NULs to the terminal (for very old terminals)\. +. +.br + +. +.IP "\(bu" 4 +exask +. +.br +When set, \fB^K X\fR prompts for a new name before saving the file\. +. +.br + +. +.IP "\(bu" 4 +floatmouse +. +.br +When set, mouse clicks can position the cursor beyond the ends of lines\. +. +.br + +. +.IP "\(bu" 4 +guess_crlf +. +.br +When set, JOE tries to guess the file format MS\-DOS or UNIX\. +. +.br + +. +.IP "\(bu" 4 +guess_indent +. +.br +When set, JOE tries to guess the indentation character and indentation step based on the contents of the file\. The algorithm is to find the greatest common factor of the three most common indentations found in the file\. +. +.br + +. +.IP "\(bu" 4 +guess_non_utf8 +. +.br +When set, enable guessing of non\-UTF\-8 files in UTF\-8 locales\. +. +.br + +. +.IP "\(bu" 4 +guess_utf8 +. +.br +When set, enable guessing of UTF\-8 files in non\-UTF\-8 locales\. +. +.br + +. +.IP "\(bu" 4 +guess_utf16 +. +.br +When set, enable guessing of UTF\-16 files\. If a UTF\-16BE or UTF\-16LE file is detected, it is converted to UTF\-8 during load, and converted back to UTF\-16 during save\. +. +.br + +. +.IP "\(bu" 4 +helpon +. +.br +When set, start off with the on\-line help enabled\. +. +.br + +. +.IP "\(bu" 4 +help_is_utf8 +. +.br +When set, the help text in the joerc file is assumed to be UTF\-8\. +. +.br + +. +.IP "\(bu" 4 +icase +. +.br +Search is case insensitive by default when set\. +. +.br + +. +.IP "\(bu" 4 +joe_state +. +.br +Enable reading and writing of ~/\.joe_state file +. +.br + +. +.IP "\(bu" 4 +joexterm +. +.br +Set this if xterm was configured with \-\-paste64 option for better mouse support\. +. +.br + +. +.IP "\(bu" 4 +keepup +. +.br +The column number on the status line is updated constantly when this is set, otherwise it is updated only once a second\. +. +.br + +. +.IP "\(bu" 4 +language \fBlanguage\fR +. +.br +Sets language for aspell\. +. +.br + +. +.IP "\(bu" 4 +lightoff +. +.br +Automatically turn off \fB^K B\fR \fB^K K\fR highlighting after a block operation\. +. +.br + +. +.IP "\(bu" 4 +lines nnn +. +.br +Set number of lines in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\. +. +.br + +. +.IP "\(bu" 4 +marking +. +.br +Enable marking mode: highlights between \fB^K B\fR and cursor\. +. +.br + +. +.IP "\(bu" 4 +menu_above +. +.br +Put menus above prompt instead of below them\. +. +.br + +. +.IP "\(bu" 4 +menu_explorer +. +.br +Stay in menu when a directory is selected (otherwise the directory is added to the path and the cursor jumps back to the prompt)\. +. +.br + +. +.IP "\(bu" 4 +menu_jump +. +.br +Jump into the file selection menu when \fBTab\fR \fBTab\fR is hit\. +. +.br + +. +.IP "\(bu" 4 +mid +. +.br +If this option is set and the cursor moves off the window, the window will be scrolled so that the cursor is in the center\. This option is forced on slow terminals which don\'t have scrolling commands\. +. +.br + +. +.IP "\(bu" 4 +left nn +. +.br +This sets the number of columns the screen scrolls to the left when cursor moves past the left edge or when the crawll command is issued\. If nn is negative, then it\'s the fraction of the screen to scroll\. For example, \-2 means scroll 1/2 the screen\. +. +.br + +. +.IP "\(bu" 4 +right nn +. +.br +This sets the number of columns the screen scrolls to the right when cursor moves past the right edge or when the crawlr command is issued\. If nn is negative, then it\'s the fraction of the screen to scroll\. For example, \-3 means scroll 1/3 the screen\. +. +.br + +. +.IP "\(bu" 4 +mouse +. +.br +Enable xterm mouse support\. +. +.br + +. +.IP "\(bu" 4 +nobackups +. +.br +Disable backup files\. +. +.br + +. +.IP "\(bu" 4 +nocurdir +. +.br +Disable current\-directory prefix in prompts\. +. +.br + +. +.IP "\(bu" 4 +noexmsg +. +.br +Disable exiting message ("File not changed so no update needed") +. +.br + +. +.IP "\(bu" 4 +nolinefeeds +. +.br +Disable sending linefeeds to preserve screen history in terminal emulator\'s scroll\-back buffer (only relevant when notite mode is enabled)\. +. +.br +. +.br + +. +.IP "\(bu" 4 +nolocks +. +.br +Disable EMACS compatible file locks\. +. +.br + +. +.IP "\(bu" 4 +nomodcheck +. +.br +Disable periodic file modification check\. +. +.br + +. +.IP "\(bu" 4 +nonotice +. +.br +This option prevents the copyright notice from being displayed when the editor starts\. +. +.br + +. +.IP "\(bu" 4 +nosta +. +.br +This option eliminates the top\-most status line\. It\'s nice for when you only want to see your text on the screen or if you\'re using a vt52\. +. +.br + +. +.IP "\(bu" 4 +notagsmenu +. +.br +Disable selection menu for tags search with multiple results\. +. +.br + +. +.IP "\(bu" 4 +notite +. +.br +Disable ti and te termcap sequences which are usually set up to save and restore the terminal screen contents when JOE starts and exits\. +. +.br + +. +.IP "\(bu" 4 +pastehack +. +.br +If keyboard input comes in as one block assume it\'s a mouse paste and disable autoindent and wordwrap\. +. +.br + +. +.IP "\(bu" 4 +noxon +. +.br +Disable \fB^S\fR and \fB^Q\fR flow control, possibly allowing \fB^S\fR and \fB^Q\fR to be used as editor keys\. +. +.br + +. +.IP "\(bu" 4 +orphan +. +.br +Orphan extra files given on the command line instead of creating windows for them (the files are loaded, but you need to use switch\-buffer commands to access them)\. +. +.br + +. +.IP "\(bu" 4 +pg nnn +. +.br +Set number of lines to keep during Page Up and Page Down (use \-1 for 1/2 window size)\. +. +.br + +. +.IP "\(bu" 4 +regex +. +.br +Use standard regular expression syntax by default, instead of the JOE syntax (where special characters have their meaning only when preceded with backslash)\. +. +.br + +. +.IP "\(bu" 4 +restore +. +.br +Set to have cursor positions restored to last positions of previously edited files\. +. +.br + +. +.IP "\(bu" 4 +rtbutton +. +.br +Swap left and right mouse buttons\. +. +.br + +. +.IP "\(bu" 4 +search_prompting +. +.br +Show previous search string in search command (like in PICO)\. +. +.br + +. +.IP "\(bu" 4 +skiptop nnn +. +.br +When set to N, the first N lines of the terminal screen are not used by JOE and are instead left with their original contents\. This is useful for programs which call JOE to leave a message for the user\. +. +.br + +. +.IP "\(bu" 4 +square +. +.br +Enable rectangular block mode\. +. +.br + +. +.IP "\(bu" 4 +transpose +. +.br +Transpose rows with columns in all menus\. +. +.br + +.IP "\(bu" 4 +title +. +.br +Display context (titles) in status line. When enabled this shows the first line of the function that the cursor is in on the status line\. The syntax file context.jsf identifies which lines are title lines\. +. +.br + +. +.IP "\(bu" 4 +type +. +.br +Select file type, overriding the automatically determined type\. The file types are defined in the \fBftyperc\fR file\. +. +.br + +. +.IP "\(bu" 4 +undo_keep nnn +. +.br +Sets number of undo records to keep (0 means infinite)\. +. +.br + +. +.IP "\(bu" 4 +usetabs +. +.br +Set to allow rectangular block operations to use tabs\. +. +.br + +. +.IP "\(bu" 4 +wrap +. +.br +Enable search to wrap to beginning of file\. +. +.br + +. +.IP "" 0 +. +.P +The following local options may be specified on the command line: +. +.IP "\(bu" 4 ++nnn +. +.br +The cursor starts on the specified line\. +. +.br + +. +.IP "\(bu" 4 +autoindent +. +.br +Enable auto\-indent mode\. When you hit \fBEnter\fR on an indented line, the indentation is duplicated onto the new line\. +. +.br + +. +.IP "\(bu" 4 +c_comment +. +.br +Enable \fB^G\fR skipping of C\-style comments /\fI\.\.\.\fR/ +. +.br + +. +.IP "\(bu" 4 +cpara \fBcharacters\fR +. +.br +Sets list of characters which can indent paragraphs\. +. +.br + +. +.IP "\(bu" 4 +cnotpara \fBcharacters\fR +. +.br +Sets list of characters which begin lines which are definitely not part of paragraphs\. +. +.br + +. +.IP "\(bu" 4 +cpp_comment +. +.br +Enable \fB^G\fR skipping of C++\-style comments // \.\.\. +. +.br + +. +.IP "\(bu" 4 +crlf +. +.br +JOE uses CR\-LF as the end of line sequence instead of just LF\. This is for editing MS\-DOS or VMS files\. +. +.br + +. +.IP "\(bu" 4 +encoding \fBencoding\fR +. +.br +Set file encoding (like utf\-8 or 8859\-1)\. +. +.br + +. +.IP "\(bu" 4 +flowed +. +.br +Set to force an extra space after each line of a paragraph but the last\. +. +.br + +. +.IP "\(bu" 4 +force +. +.br +When set, a final newline is appended to the file if there isn\'t one when the file is saved\. +. +.br + +. +.IP "\(bu" 4 +french +. +.br +When set, only one space is inserted after periods in paragraph reformats instead of two\. +. +.br + +. +.IP "\(bu" 4 +hex +. +.br +Enable hex\-dump mode\. +. +.br + +. +.IP "\(bu" 4 +highlight +. +.br +Enable syntax highlighting\. +. +.br + +. +.IP "\(bu" 4 +highlighter_context +. +.br +Enable use of syntax file to identify comments and strings which should be skipped over during \fB^G\fR matching\. +. +.br + +. +.IP "\(bu" 4 +indentc nnn +. +.br +Sets the indentation character for shift left and shift right (\fB^K ,\fR and \fB^K \.\fR)\. Use 32 for \fBSpace\fR, 9 for \fBTab\fR\. +. +.br + +. +.IP "\(bu" 4 +indentfirst +. +.br +When set, the smart home key jumps to the indentation point first, otherwise it jumps to column 1 first\. +. +.br + +. +.IP "\(bu" 4 +istep nnn +. +.br +Sets indentation step\. +. +.br + +. +.IP "\(bu" 4 +linums +. +.br +Enable line number display\. +. +.br + +. +.IP "\(bu" 4 +lmargin +. +.br +Set left margin\. +. +.br + +. +.IP "\(bu" 4 +lmsg +. +.br +Define left\-side status bar message\. +. +.br + +. +.IP "\(bu" 4 +overwrite +. +.br +Enable overtype mode\. Typing overwrites existing characters instead of inserting before them\. +. +.br + +. +.IP "\(bu" 4 +picture +. +.br +Enable "picture" mode\- allows cursor to go past ends of lines\. +. +.br + +. +.IP "\(bu" 4 +pound_comment +. +.br +\fB^G\fR ignores # \.\.\. comments\. +. +.br + +. +.IP "\(bu" 4 +purify +. +.br +Fix indentation if necessary before shifting or smart backspace\. For example, if indentation uses a mix of tabs and spaces, and indentc is space, then indentation will be converted to all spaces before the shifting operation\. +. +.br + +. +.IP "\(bu" 4 +rdonly +. +.br +Set read\-only mode\. +. +.br + +. +.IP "\(bu" 4 +rmargin nnn +. +.br +Set right margin\. +. +.br + +. +.IP "\(bu" 4 +rmsg \fBstring\fR +. +.br +Define right\-side status bar message\. +. +.br + +. +.IP "\(bu" 4 +semi_comment +. +.br +\fB^G\fR ignores ; \.\.\. comments\. +. +.br + +. +.IP "\(bu" 4 +single_quoted +. +.br +\fB^G\fR ignores \'\.\.\.\' +. +.br + +. +.IP "\(bu" 4 +smartbacks +. +.br +Enable smart backspace and tab\. When this mode is set backspace and tab indent or unindent based on the values of the istep and indentc options\. +. +.br + +. +.IP "\(bu" 4 +smarthome +. +.br +Home key first moves cursor to beginning of line, then if hit again, to the first non\-blank character\. +. +.br + +. +.IP "\(bu" 4 +smsg \fBstring\fR +. +.br +Define status command format when cursor is on a character\. +. +.br + +. +.IP "\(bu" 4 +spaces +. +.br +Insert spaces when \fBTab\fR key is hit\. +. +.br + +. +.IP "\(bu" 4 +syntax \fBsyntax\fR +. +.br +Set syntax for syntax highlighting\. +. +.br + +. +.IP "\(bu" 4 +tab nnn +. +.br +Set tab stop width\. +. +.br + +. +.IP "\(bu" 4 +text_delimiters \fBword delimiter list\fR +. +.br +Give list of word delimiters which \fB^G\fR will step through\. +. +.IP "" 0 +. +.P +For example, "begin=end:if=elif=else=endif" means that \fB^G\fR will jump between the matching if, elif, else and endif\. +. +.IP "\(bu" 4 +vhdl_comment +. +.br +\fB^G\fR ignores \-\- \.\.\. comments +. +.br + +. +.IP "\(bu" 4 +wordwrap +. +.br +JOE wraps the previous word when you type past the right margin\. +. +.br + +. +.IP "\(bu" 4 +zmsg \fBstring\fR +. +.br +Define status command format when cursor is at end of file\. +. +.br + +. +.IP "\(bu" 4 +xmsg \fBstring\fR +. +.br +Define startup message (usually the copyright notice)\. +. +.br + +. +.IP "\(bu" 4 +aborthint \fBstring\fR +. +.br +Give the key sequence to show in prompts for abort (usually ^C)\. +. +.br + +. +.IP "\(bu" 4 +helphint \fBstring\fR +. +.br +Give the key sequence to show in prompts for help (usually ^K H)\. +. +.br + +. +.IP "" 0 +. +.SS "Colors and attributes" +Combine attributes and up to one foreground color and one background color to create arguments for color options like text_color\. For example: bold+bg_green+blue +. +.IP "\(bu" 4 +Attributes: bold, inverse, blink, dim, underline, and italic +. +.IP "\(bu" 4 +Foreground colors: white, cyan, magenta, blue, yellow, green, red, or black +. +.IP "\(bu" 4 +Background colors: bg_white, bg_cyan, bg_magenta, bg_blue, bg_yellow, bg_green, bg_red or bg_black +. +.IP "" 0 +. +.P +With a 16 color or 256 color terminal emulator (export TERM=xterm\-16color), these brighter than normal colors become available: +. +.IP "\(bu" 4 +Foreground: WHITE, CYAN, MAGENTA, BLUE, YELLOW, GREEN, RED or BLACK +. +.IP "\(bu" 4 +Background: bg_WHITE, bg_CYAN, bg_MAGENTA, bg_BLUE, bg_YELLOW, bg_GREEN, bg_RED or bg_BLACK +. +.IP "" 0 +. +.P +With a 256 color terminal emulator (export TERM=xterm\-256color), these become available: +. +.IP "\(bu" 4 +fg_RGB and bg_RGB, where R, G and B rand from 0 \- 5\. So: fg_500 is bright red\. +. +.IP "\(bu" 4 +fg_NN and bg_NN give shades of grey, where the intensity, NN, ranges from 0 \- 23\. +. +.IP "" 0 +. +.SS "Status line definition strings" +\-lmsg defines the left\-justified string and \-rmsg defines the right\-justified string\. The first character of \-rmsg is the background fill character\. +. +.P +\-smsg defines the status command (\fB^K Space\fR)\. \-zmsg defines it when the cursor is at the end of the file\. The last character of smsg or zmsg is the fill character\. +. +.P +The following escape sequences can be used in these strings: +. +.IP "" 4 +. +.nf + +%t 12 hour time +%u 24 hour time +%T O for overtype mode, I for insert mode +%W W if wordwrap is enabled +%I A if autoindent is enabled +%X Rectangle mode indicator +%n File name +%m \'(Modified)\' if file has been changed +%* \'*\' if file has been changed +%R Read\-only indicator +%r Row (line) number +%c Column number +%o Byte offset into file +%O Byte offset into file in hex +%a Ascii value of character under cursor +%A Ascii value of character under cursor in hex +%w Width of character under cursor +%p Percent of file cursor is at +%l No\. lines in file +%k Entered prefix keys +%S \'*SHELL*\' if there is a shell running in window +%M Macro recording message +%y Syntax +%e Encoding +%x Context (first non\-indented line going backwards) +%dd day +%dm month +%dY year +%Ename% value of environment variable +%Tname% value of option (ON or OFF for Boolean options) +. +.fi +. +.IP "" 0 +. +.P +These formatting escape sequences may also be given: +. +.IP "" 4 +. +.nf + +\ei Inverse +\eu Underline +\eb Bold +\ed Dim +\ef Blink +\el Italic +. +.fi +. +.IP "" 0 +. +.P +. +.br +. +.SH "Basic Editing" +When you type characters into the editor, they are normally inserted into the file being edited (or appended to the file if the cursor is at the end of the file)\. This is the normal operating mode of the editor\. If you want to replace some existing text, you have to delete the old text before or after you type in the replacement text\. The \fBBackspace\fR key can be used for deleting text: move the cursor to right after the text you want to delete and hit \fBBackspace\fR a number of times\. +. +.P +Hit the \fBEnter\fR or \fBReturn\fR key to insert a line\-break\. For example, if the cursor was in the middle of a line and you hit \fBEnter\fR, the line would be split into two lines with the cursor appearing at the beginning of the second line\. Hit \fBBackspace\fR at the beginning of a line to eliminate a line\-break\. +. +.P +Use the arrow keys to move around the file\. If your keyboard doesn\'t have arrow keys (or if they don\'t work for some reason), use \fB^F\fR to move forwards (right), \fB^B\fR to move backwards (left), \fB^P\fR to move to the previous line (up), and \fB^N\fR to move to the next line (down)\. The right and left arrow keys simply move forwards or backwards one character at a time through the text: if you\'re at the beginning of a line and you press left\-arrow, you will end up at the end of the previous line\. The up and down arrow keys move forwards and backwards by enough characters so that the cursor appears in the same column that it was in on the original line\. +. +.P +If you want to indent the text you enter, you can use the \fBTab\fR key\. This inserts a special control character which makes the characters which follow it begin at the next tab stop\. Tab stops normally occur every 8 columns, but this can be changed with the \fB^T D\fR command\. PASCAL and C programmers often set tab stops on every 4 columns\. +. +.P +If for some reason your terminal screen gets messed up (for example, if you receive a mail notice from biff), you can have the editor refresh the screen by hitting \fB^R\fR\. +. +.P +There are many other keys for deleting text and moving around the file\. For example, hit \fB^D\fR to delete the character the cursor is on instead of deleting backwards like \fBBackspace\fR\. \fB^D\fR will also delete a line\-break if the cursor is at the end of a line\. Type \fB^Y\fR to delete the entire line the cursor is on or \fB^J\fR to delete just from the cursor to the end of the line\. +. +.P +Hit \fB^A\fR to move the cursor to the beginning of the line it\'s on\. Hit \fB^E\fR to move the cursor to the end of the line\. Hit \fB^U\fR or \fB^V\fR for scrolling the cursor up or down 1/2 a screen\'s worth\. +. +.br +"Scrolling" means that the text on the screen moves, but the cursor stays at the same place relative to the screen\. Hit \fB^K U\fR or \fB^K V\fR to move the cursor to the beginning or the end of the file\. Look at the help screens in the editor to find even more delete and movement commands\. +. +.P +If you make a mistake, you can hit \fB^_\fR to "undo" it\. On most keyboards you hit just \fB^\-\fR to get \fB^_\fR, but on some you might have to hold both the \fBShift\fR and \fBControl\fR keys down at the same time to get it\. If you "undo" too much, you can "redo" the changes back into existence by hitting \fB^^\fR (type this with just \fB^6\fR on most keyboards)\. +. +.SS "Cursor position history" +If you were editing in one place within the file, and you then temporarily had to look or edit some other place within the file, you can get back to the original place by hitting \fB^K \-\fR\. This command actually returns you to the last place you made a change in the file\. You can step through a history of places with \fB^K \-\fR and \fB^K =\fR, in the same way you can step through the history of changes with the "undo" and "redo" commands\. +. +.SS "Save and exit" +When you are done editing the file, hit \fB^K X\fR to exit the editor\. You will be prompted for a file name if you hadn\'t already named the file you were editing\. +. +.P +When you edit a file, you actually edit only a copy of the file\. So if you decide that you don\'t want the changes you made to a file during a particular edit session, you can hit \fB^C\fR to exit the editor without saving them\. +. +.P +If you edit a file and save the changes, a backup copy of that file is created in the current directory, with a \fB~\fR appended to the name, which contains the original version of the file\. +. +.SS "File operations" +You can hit \fB^K D\fR to save the current file (possibly under a different name from what the file was called originally)\. After the file is saved, you can hit \fB^K E\fR to edit a different file\. +. +.P +If you want to save only a selected section of the file, see the section on \fIBlocks\fR below\. +. +.P +If you want to include another file in the file you\'re editing, use \fB^K R\fR to insert it\. +. +.P + \fI\fR +. +.SS "Filenames" +Wherever JOE expects you to enter a file name, whether on the command line or in prompts within the editor, you may also type: +. +.IP "\(bu" 4 +!command +. +.IP "" 0 +. +.P +To read or write data to or from a shell command\. For example, use \fBjoe \'!ls\'\fR to get a copy of your directory listing to edit or from within the editor use \fB^K D !mail jhallen@world\.std\.com\fR to send the file being edited to me\. +. +.IP "\(bu" 4 +>>filename +. +.IP "" 0 +. +.P +Use this to have JOE append the edited text to the end of the file "filename\." +. +.IP "\(bu" 4 +filename,START,SIZE +. +.IP "" 0 +. +.P +Use this to access a fixed section of a file or device\. \fBSTART\fR and \fBSIZE\fR may be entered in decimal (ex\.: 123) octal (ex\.: 0777) or hexadecimal (ex\.: 0xFF)\. For example, use \fBjoe /dev/fd0,508,2\fR to edit bytes 508 and 509 of the first floppy drive in Linux\. +. +.IP "\(bu" 4 +\- +. +.IP "" 0 +. +.P +Use this to get input from the standard input or to write output to the standard output\. For example, you can put JOE in a pipe of commands: \fBquota \-v | joe | mail root\fR, if you want to complain about your low quota\. +. +.SS "Using JOE in a shell script" +JOE used to use /dev/tty to access the terminal\. This caused a problem with idle\-session killers (they would kill JOE because the real tty device was not being accessed for a long time), so now JOE only uses /dev/tty if you need to pipe a file into JOE, as in: +. +.IP "" 4 +. +.nf + +echo "hi" | joe +. +.fi +. +.IP "" 0 +. +.P +If you want to use JOE in a shell script which has its stdin/stdout redirected, but you do not need to pipe to it, you should simply redirect JOE\'s stdin/stdout to /dev/tty: +. +.IP "" 4 +. +.nf + +joe filename /dev/tty +. +.fi +. +.IP "" 0 +. +.P +. +.br +. +.br +. +.SS "Word wrap and formatting" +If you type past the right edge of the screen in a C or PASCAL language file, the screen will scroll to the right to follow the cursor\. If you type past the right edge of the screen in a normal file (one whose name doesn\'t end in \.c, \.h or \.p), JOE will automatically wrap the last word onto the next line so that you don\'t have to hit \fBEnter\fR\. This is called word\-wrap mode\. Word\-wrap can be turned on or off with the \fB^T W\fR command\. JOE\'s initialization file is usually set up so that this mode is automatically turned on for all non\-program files\. See the section below on the \fIjoerc\fR file to change this and other defaults\. +. +.P +Aside for Word\-wrap mode, JOE does not automatically keep paragraphs formatted like some word\-processors\. Instead, if you need a paragraph to be reformatted, hit \fB^K J\fR\. This command "fills in" the paragraph that the cursor is in, fitting as many words in a line as is possible\. A paragraph, in this case, is a block of text separated above and below by a blank line\. +. +.P +The margins which JOE uses for paragraph formatting and word\-wrap can be set with the \fB^T L\fR and \fB^T R\fR commands\. If the left margin is set to a value other than 1, then when you start typing at the beginning of a line, the cursor will immediately jump to the left margin\. +. +.P +There are a number of options which control the paragraph reformatter and word wrapper: +. +.IP "\(bu" 4 +The \fBcpara\fR option provides a list of characters which can indent a paragraph\. For example, in e\-mail quoted matter is indicated by \fB>\fR at the beginnings of line, so this character should be in the cpara list\. +. +.IP "\(bu" 4 +The \fBcnotpara\fR option provides a list of characters which, if they are the first non\-whitespace character of a line, indicate that the line is not to be included as part of a paragraph for formatting\. For example, lines beginning with \'\.\' in nroff can not be paragraph lines\. +. +.IP "\(bu" 4 +Autoindent mode affects the formatter\. If autoindent is disabled, only the first line will be indented\. If autoindent is enabled, the entire paragraph is indented\. +. +.IP "\(bu" 4 +\fBfrench\fR determines how many spaces are inserted after periods\. +. +.IP "\(bu" 4 +When \fBflowed\fR is enabled, a space is inserted after each but the last line of the paragraph\. This indicates that the lines belong together as a single paragraph in some programs\. +. +.IP "\(bu" 4 +When \fBovertype\fR is enabled, the word wrapper will not insert lines\. +. +.IP "" 0 +. +.SS "Centering" +If you want to center a line within the margins, use the \fB^K A\fR command\. +. +.SS "Spell checker" +Hit \fBEsc N\fR to check the spelling of the word the cursor is on using the aspell program (or ispell program if you modify the joerc file)\. Hit \fBEsc L\fR to check the highlighted block or the entire file if no block is highlighted\. +. +.P +JOE passes the language and character encoding to the spell checker\. To change the language, hit \fB^T V\fR\. For example, use en_US for English\. +. +.SS "Overtype mode" +Sometimes it\'s tiresome to have to delete old text before or after you insert new text\. This happens, for example, when you are changing a table and you want to maintain the column position of the right side of the table\. +. +.br +When this occurs, you can put the editor in overtype mode with \fB^T T\fR\. +. +.br +When the editor is in this mode, the characters you type in replace existing characters, in the way an idealized typewriter would\. Also, \fBBackspace\fR simply moves left instead of deleting the character to the left, when it\'s not at the end or beginning of a line\. Overtype mode is not the natural way of dealing with text electronically, so you should go back to insert\-mode as soon as possible by typing \fB^T T\fR again\. +. +.P +If you need to insert while you\'re in overtype mode, hit \fB^@\fR\. This inserts a single \fBSpace\fR into the text\. +. +.SS "Control and Meta characters" +Each character is represented by a number\. For example, the number for \'A\' is 65 and the number for \'1\' is 49\. All of the characters which you normally see have numbers in the range of 32 \- 126 (this particular arbitrary assignment between characters and numbers is called the ASCII character set)\. The numbers outside of this range, from 0 to 255, aren\'t usually displayed, but sometimes have other special meanings\. The number 10, for example, is used for the line\-breaks\. You can enter these special, non\-displayed \fBcontrol characters\fR by first hitting \fB^Q\fR and then hitting a character in the range \fB@ A B C \.\.\. X Y Z [ ^ ] \e _\fR to get the number 0 \- 31, and ? to get 127\. For example, if you hit \fB^Q J\fR, you\'ll insert a line\-break character, or if you hit \fB^Q I\fR, you\'ll insert a \fBTab\fR character (which does the same thing the \fBTab\fR key does)\. A useful control character to enter is 12 (\fB^Q L\fR), which causes most printers to advance to the top of the page\. You\'ll notice that JOE displays this character as an underlined L\. You can enter the characters above 127, the \fBmeta characters\fR, by first hitting \fB^\e\fR\. This adds 128 to the next (possibly control) character entered\. JOE displays characters above 128 in inverse\-video\. Some foreign languages, which have more letters than English, use the meta characters for the rest of their alphabet\. You have to put the editor in \fBasis\fR mode to have these passed untranslated to the terminal\. +. +.P +\fBNote:\fR JOE now normally passes all 8\-bits to the terminal unless the locale is set to C or POSIX\. If the locale is C or POSIX, then the \fBasis\fR flag determines if \fBmeta characters\fR are shown in inverse video or passed directly to the terminal\. +. +.P +\fBNote:\fR In older version of JOE, you had to use \fBEsc \'\fR to enter control characters\. +. +.SH "Character sets and UTF\-8" +JOE natively handles two classes of character sets: UTF\-8 and byte coded (like ISO\-8859\-1)\. For these character sets, the file is loaded as\-is into memory, and is exactly preserved during save, even if it contains UTF\-8 coding errors\. +. +.P +It can not yet natively handle other major classes such as UTF\-16 or GB2312\. There are other restrictions: character sets must use LF (0x0A) or CR\-LF (0x0D \- 0x0A) as line terminators, space must be 0x20 and tab must be 0x09\. Basically, the files must be UNIX or MS\-DOS compatible text files\. +. +.P +This means EBCDIC will not work properly (but you would need to handle fixed record length lines anyway) and character sets which use CR terminated lines (MACs) will not yet work\. +. +.P +JOE now supports UTF\-16 (both big endian and little endian)\. It supports UTF\-16 by converting to UTF\-8 during load, and converting back to UTF\-16 during save\. +. +.P +The terminal and the file can have different encodings\. JOE will translate between the two\. Currently, one of the two must be UTF\-8 for translation to work\. +. +.P +The character set for the terminal and the default character set assumed for files is determined by the \'LC_ALL\' environment variable (and if that\'s not set, LC_CTYPE and LANG are also checked)\. +. +.P +For example, if LC_ALL is set to: +. +.IP "" 4 +. +.nf + +de_DE +. +.fi +. +.IP "" 0 +. +.P +Then the character set will be ISO\-8859\-1\. +. +.P +If LC_ALL is set to: +. +.IP "" 4 +. +.nf + +de_DE\.UTF\-8 +. +.fi +. +.IP "" 0 +. +.P +The character set will be UTF\-8\. +. +.P +Hit \fB^T E\fR to change the coding for the file\. Hit \fBTab\fR \fBTab\fR at this prompt to get a list of available codings\. There are a number of built\-in character sets, plus you can install character sets in the ~/\.joe/charmaps and /usr/share/joe/charmaps directories\. +. +.P +Check: /usr/share/i18n/charmaps for example character set files\. Only byte oriented character sets will work\. Also, the file should not be gzipped (all of the charmap files in /usr/share/i18n/charmaps on my computer were compressed)\. The parser is very bad, so basically the file has to look exactly like the example one in /usr/share/joe/charmaps\. +. +.P +You can hit \fB^K Space\fR to see the current character set\. +. +.P +You can hit \fB^Q x\fR to enter a Unicode character if the file coding is UTF\-8\. +. +.SH "Prompts" +Most prompts record a history of the responses you give them\. You can hit up and down arrow to step through these histories\. +. +.P +Prompts are actually single line windows with no status line, so you can use any editing command that you normally use on text within the prompts\. The prompt history is actually just other lines of the same "prompt file"\. Thus you can can search backwards though the prompt history with the normal \fB^K F\fR command if you want\. +. +.P +Since prompts are windows, you can also switch out of them with \fB^K P\fR and \fB^K N\fR\. +. +.SS "Completion and selection menus" +You can hit \fBTab\fR in just about any prompt to request JOE to complete the word you are typing\. If JOE beeps, there are either no completions or many\. As with the "bash" shell, hit \fBTab\fR twice to bring up a list of all the possibilities\. This list is actually a menu, but by default, the cursor does not jump into it since it is usually easier to just type in your selection\. You can, however, jump into the menu window with \fB^K P\fR (move to previous window) and use the arrow keys and to make your selection\. Also in a menu, you can hit the first letter of any of the items to make the cursor jump directly to it\. The \fB^T\fR option menu works like this\. +. +.P +If the menu is too large to fit in the window, you can hit Page Up and Page Down to scroll it (even if you have not jumped into it)\. +. +.P +\fBTab\fR completion works in the search and replace prompts as well\. In this case, JOE tries to complete the word based on the contents of the buffer\. If you need search for the \fBTab\fR character itself, you can enter it with \fB^Q Tab\fR\. +. +.P +Also, you can hit \fBEsc Enter\fR in a text window to request JOE to complete the word you are typing\. As with the search prompt, JOE tries to complete the word based on the contents of the buffer\. It will bring up a menu of possibilities if you hit \fBEsc Enter\fR twice\. +. +.SH "Where am I?" +Hit \fB^K Space\fR to have JOE report the line number, column number, and byte number on the last line of the screen\. The number associated with the character the cursor is on (its ASCII code) is also shown\. You can have the line number and/or column number always displayed on the status line by placing the appropriate escape sequences in the status line setup strings\. Edit the joerc file for details\. +. +.SH "What if I hit ^K by accident?" +Hit the space bar\. This runs an innocuous command (it shows the line number on the status bar)\. +. +.SH "Temporarily suspending the editor" +If you need to temporarily stop the editor and go back to the shell, hit \fB^K Z\fR\. You might want to do this to stop whatever you\'re editing and answer an e\-mail message or read this man page, for example\. You have to type \fBfg\fR or \fBexit\fR (you\'ll be told which when you hit \fB^K Z\fR) to return to the editor\. +. +.SH "Searching for text" +Hit \fB^K F\fR to have the editor search forwards or backwards for a text fragment (\fBstring\fR) for you\. You will be prompted for the text to search for\. After you hit \fBEnter\fR, you are prompted to enter options\. +. +.br +You can just hit \fBEnter\fR again to have the editor immediately search forwards for the text, or you can enter one or more of these options: +. +.IP "\(bu" 4 +\fBb\fR +. +.br + +. +.IP "" 0 +. +.P +Search backwards instead of forwards\. +. +.IP "\(bu" 4 +\fBi\fR +. +.br + +. +.IP "" 0 +. +.P +Treat uppercase and lower case letters as the same when searching\. Normally uppercase and lowercase letters are considered to be different\. +. +.IP "\(bu" 4 +\fBnnn\fR +. +.br + +. +.IP "" 0 +. +.P +(where \fBnnn\fR is a number) If you enter a number, JOE searches for the Nth occurrence of the text\. This is useful for going to specific places in files structured in some regular manner\. +. +.IP "\(bu" 4 +\fBr\fR +. +.br + +. +.IP "" 0 +. +.P +Replace text\. If you enter the \fBr\fR option, then you will be further prompted for replacement text\. Each time the editor finds the search text, you will be prompted as to whether you want to replace the found search text with the replacement text\. You hit: \fBy\fR to replace the text and then find the next occurrence, \fBn\fR to not replace this text, but to then find the next occurrence, \fBr\fR to replace all of the remaining occurrences of the search text in the remainder of the file without asking for confirmation (subject to the \fBnnn\fR option above), or \fB^C\fR to stop searching and replacing\. +. +.P +You can also hit \fBB\fR or \fBBackspace\fR to back up to the previously found text (if it had been replaced, the replacement is undone)\. +. +.IP "\(bu" 4 +\fBa\fR +. +.br + +. +.IP "" 0 +. +.P +The search covers all loaded buffers\. So to replace all instances of "foo" with "bar" in all \.c files in the current directory: +. +.IP "" 4 +. +.nf + +joe *\.c + ^K F + foo + ra + bar +. +.fi +. +.IP "" 0 +. +.IP "\(bu" 4 +\fBe\fR +. +.br + +. +.IP "" 0 +. +.P +The search covers all files in the grep or make error list\. You can use a UNIX command to generate a list of files and search and replace through the list\. So to replace all instances of "foo" with "bar" in all \.c files which begin with f\. You can also use "ls" and "find" instead of grep to create the file list\. +. +.IP "" 4 +. +.nf + +Esc G + grep \-n foo f*\.c +^K F + foo + re + bar +. +.fi +. +.IP "" 0 +. +.IP "\(bu" 4 +\fBx\fR +. +.br + +. +.IP "" 0 +. +.P +JOE will use the standard syntax for regular expressions if this option is given\. In the standard syntax, these characters have their special meanings directly, and do not have to be escaped with backslash: \., *, +, ?, {, }, (, ), |, ^, $ and [\. +. +.IP "\(bu" 4 +\fBy\fR +. +.br + +. +.IP "" 0 +. +.P +JOE will use the JOE syntax for regular expressions instead of the standard syntax\. This overrides the "\-regex" option\. +. +.IP "\(bu" 4 +\fBv\fR +. +.br + +. +.IP "" 0 +. +.P +JOE will send debug information about the regular expression to the startup log\. The log can be viewed with the showlog command\. +. +.P +You can hit \fB^L\fR to repeat the previous search\. +. +.P +You can hit \fB^K H\fR at the search and replace options prompt to bring up a list of all search and replace options\. +. +.SS "Regular Expressions" +A number of special character sequences may be entered as search text: +. +.IP "\(bu" 4 +\fB\e*\fR +. +.br + +. +.IP "" 0 +. +.P +This finds zero or more of the item to the left\. For example, if you give \fBAB\e*C\fR as the search text, JOE will try to find an A followed by any number of Bs, and then a C\. +. +.IP "\(bu" 4 +\fB\e+\fR +. +.br + +. +.IP "" 0 +. +.P +This finds one or more of the item to the left\. For example, if you give \fBAB\e+C\fR as the search text, JOE will try to find an A followed by one or more Bs, and then a C\. +. +.IP "\(bu" 4 +\fB\e?\fR +. +.br + +. +.IP "" 0 +. +.P +This indicates that the item to the left is optional\. For example, if you give \fBAB\e?C\fR as the search text, JOE will find AC or ABC\. +. +.IP "\(bu" 4 +\fB\e{min,max}\fR +. +.br + +. +.IP "" 0 +. +.P +This indicates that JOE should try to find a string with a specific number of occurrences of the item to the left\. For example, \fBAX\e{2,5}B\fR will match these strings: AXXB, AXXXB, AXXXXB, and AXXXXXB\. Min can be left out to indicate 0 occurrences\. Max (and the comma) can be left out to indicate any number of occurrences\. +. +.IP "\(bu" 4 +\fB\e\.\fR +. +.br + +. +.IP "" 0 +. +.P +This finds exactly one character\. For example, if you give \fBA\e\.B\fR as the search text, JOE will find AXB, but not AB or AXXB\. +. +.IP "\(bu" 4 +\fB\e!\fR +. +.br + +. +.IP "" 0 +. +.P +This works like \fB\.\fR, but matches a balanced C\-language expression\. For example, if you search for \fBmalloc(\e!\e*)\fR, then JOE will find all function calls to \fBmalloc\fR, even if there was a \fB)\fR within the parenthesis\. +. +.IP "\(bu" 4 +\fB\e|\fR +. +.br + +. +.IP "" 0 +. +.P +This finds the item on the left or the item on the right\. For example, if you give \fBA\e|B\fR as the search text, JOE will try to find either an A or a B\. +. +.IP "\(bu" 4 +\fB\e( \e)\fR +. +.br + +. +.IP "" 0 +. +.P +Use these to group characters together\. For example, if you search for \fB\e(foo\e)\e+\fR, then JOE will find strings like "foo", and "foofoofoo"\. +. +.IP "\(bu" 4 +\fB^ \e$\fR +. +.br + +. +.IP "" 0 +. +.P +These match the beginnings and endings of lines\. For example, if you give \fB^test\e$\fR, then JOE with find \fBtest\fR on a line by itself\. +. +.IP "\(bu" 4 +\fB\e\fI\e\e\fR\fR +. +.br + +. +.IP "" 0 +. +.P +These match the beginnings and endings of words\. For example, if you give \fB\e\fIis\e\e\fR\fR, then JOE will find the word "is" but will not find the "is" in "this"\. +. +.IP "\(bu" 4 +\fB\e[\.\.\.]\fR +. +.br + +. +.IP "" 0 +. +.P +This matches any single character which appears within the brackets\. For example, if \fB\e[Tt]his\fR is entered as the search string, then JOE finds both \fBThis\fR and \fBthis\fR\. Ranges of characters can be entered within the brackets\. For example, \fB\e[A\-Z]\fR finds any uppercase letter\. If the first character given in the brackets is \fB^\fR, then JOE tries to find any character not given in the the brackets\. To include \fB\-\fR itself, include it as the last or first character (possibly after \fB^\fR)\. +. +.IP "\(bu" 4 +\fB\e\e\fR +. +.br + +. +.IP "" 0 +. +.P +Matches a single \e\. +. +.IP "\(bu" 4 +\fB\en\fR +. +.br + +. +.IP "" 0 +. +.P +This finds the special end\-of\-line or line\-break character\. +. +.P +A number of special character sequences may also be given in the replacement string: +. +.IP "\(bu" 4 +\fB\e&\fR +. +.br + +. +.IP "" 0 +. +.P +This gets replaced by the text which matched the search string\. For example, if the search string was \fB\e\fI\e*\e\e\fR\fR, which matches words, and you give \fB"\e&"\fR, then JOE will put quote marks around words\. +. +.IP "\(bu" 4 +\fB\e1 \- \e9\fR +. +.br + +. +.IP "" 0 +. +.P +These get replaced with the text which matched the Nth grouping; the text within the Nth set of \e( \e)\. +. +.IP "\(bu" 4 +\fB\el, \eu\fR +. +.br + +. +.IP "" 0 +. +.P +Convert the next character of the replacement text to lowercase or uppercase\. +. +.IP "\(bu" 4 +\fB\eL, \eU\fR +. +.br + +. +.IP "" 0 +. +.P +Convert all following replacement text to lowercase or uppercase\. Conversion stops when \eE is encountered\. +. +.IP "\(bu" 4 +\fB\e\e\fR +. +.br + +. +.IP "" 0 +. +.P +Use this if you need to put a \fB\e\fR in the replacement string\. +. +.IP "\(bu" 4 +\fB\en\fR +. +.br + +. +.IP "" 0 +. +.P +Use this if you need to put a line\-break in the replacement string\. +. +.P +Some examples: +. +.P +Suppose you have a list of addresses, each on a separate line, which starts with "Address:" and has each element separated by commas\. Like so: +. +.P +Address: S\. Holmes, 221b Baker St\., London, England +. +.P +If you wanted to rearrange the list, to get the country first, then the city, then the person\'s name, and then the address, you could do this: +. +.P +Type \fB^K F\fR to start the search, and type: +. +.P +\fBAddress:\e(\e\.\e*\e),\e(\e\.\e*\e),\e(\e\.\e*\e),\e(\e\.\e*\e)\e$\fR +. +.P +to match "Address:", the four comma\-separated elements, and then the end of the line\. When asked for options, you would type \fBr\fR to replace the string, and then type: +. +.P +\fBAddress:\e4,\e3,\e1,\e2\fR +. +.P +To shuffle the information the way you want it\. After hitting return, the search would begin, and the sample line would be changed to: +. +.P +Address: England, London, S\. Holmes, 221b Baker St\. +. +.P + \fI\fR +. +.SS "Escape sequences" +JOE understands the following escape sequences withing search and replacement strings: +. +.IP "\(bu" 4 +\ex{10ffff} +. +.br + +. +.IP "" 0 +. +.P +This matches a specific Unicode code point given in hexadecimal\. +. +.IP "\(bu" 4 +\exFF +. +.br + +. +.IP "" 0 +. +.P +This matches a specific character specified in hexadecimal\. +. +.IP "\(bu" 4 +\e377 +. +.br + +. +.IP "" 0 +. +.P +This matches a specific character specified in octal\. +. +.IP "\(bu" 4 +\ep{Ll} +. +.br + +. +.IP "" 0 +. +.P +This matches any character in the named Unicode category or block\. +. +.P +The block names, such as "Latin\-1 Supplement" or "Arabic" can be found here: +. +.P +Unicode Blocks \fIftp://ftp\.unicode\.org/Public/8\.0\.0/ucd/Blocks\.txt\fR +. +.P +The category names such as "Ll" can be found here: +. +.P +Unicode Categories \fIftp://ftp\.unicode\.org/Public/5\.1\.0/ucd/UCD\.html#General_Category_Values\fR +. +.P +Note that a single letter matches all of the category names which start with that letter\. For example, \ep{N} (any number) include \ep{Nd} (decimal digit), \ep{Nl} (letter number) and \ep{No} (other number)\. +. +.IP "\(bu" 4 +\ed +. +.br + +. +.IP "" 0 +. +.P +This matches any Unicode digit\. This is the same as \ep{Nd}\. +. +.IP "\(bu" 4 +\eD +. +.br + +. +.IP "" 0 +. +.P +This matches anything except for a Unicode digit\. This is the same as \e[^\ep{Nd}]\. +. +.IP "\(bu" 4 +\ew +. +.br + +. +.IP "" 0 +. +.P +This matches any word character\. This is the same as \e[^\ep{C}\ep{P}\ep{Z}]\. +. +.IP "\(bu" 4 +\eW +. +.br + +. +.IP "" 0 +. +.P +This matches anything except for a word character\. This is the same as \e[\ep{C}\ep{P}\ep{Z}]\. +. +.IP "\(bu" 4 +\es +. +.br + +. +.IP "" 0 +. +.P +This matches any space character\. This is the same as \e[\et\er\ef\en\ep{Z}]\. +. +.IP "\(bu" 4 +\eS +. +.br + +. +.IP "" 0 +. +.P +This matches anything except for a spacing character\. This is the same as \e[^\et\er\ef\en\ep{Z}]\. +. +.IP "\(bu" 4 +\ei +. +.br + +. +.IP "" 0 +. +.P +This matches an identifier start character\. This is the same as \e[\ep{L}\ep{Pc}\ep{Nl}]\. +. +.IP "\(bu" 4 +\eI +. +.br + +. +.IP "" 0 +. +.P +This matches anything except for an identifier start character\. This is the same as \e[^\ep{L}\ep{Pc}\ep{Nl}]\. +. +.IP "\(bu" 4 +\ec +. +.br + +. +.IP "" 0 +. +.P +This matches an identifier continuation character\. This is the same as \e[\ei\ep{Mn}\ep{Mc}\ep{Nd}\ex{200c}\ex{200d}]\. +. +.IP "\(bu" 4 +\eC +. +.br + +. +.IP "" 0 +. +.P +This matches anything except for an identifier continuation character\. This is the same as \e[^\ei\ep{Mn}\ep{Mc}\ep{Nd}\ex{200c}\ex{200d}]\. +. +.IP "\(bu" 4 +\et Tab +. +.IP "\(bu" 4 +\en Newline +. +.IP "\(bu" 4 +\er Carriage return +. +.IP "\(bu" 4 +\eb Backspace +. +.IP "\(bu" 4 +\ea Alert +. +.IP "\(bu" 4 +\ef Formfeed +. +.IP "\(bu" 4 +\ee Escape +. +.IP "\(bu" 4 +\e\e Backslash +. +.IP "" 0 +. +.SH "Incremental search" +Use \fBEsc S\fR to start an increment search forwards, or \fBEsc R\fR to start an incremental search backwards\. As you type the search string, the cursor will jump to the first text that matches the regular expression you have entered so far\. +. +.P +Hit \fBEsc S\fR or \fBEsc R\fR again to find the next occurrence of the text or to switch the direction of the search\. +. +.P +\fB^S\fR, \fB^\e\fR and \fB^L\fR have the same effect as \fBEsc S\fR\. \fB^R\fR has the same effect as \fBEsc R\fR\. These keys are to support JMACS\. +. +.P +Hit \fBBackspace\fR to undo the last incremental search action\. The last action could be a repeat of a previous search or the entering of a new character\. +. +.P +Use \fB^Q\fR to insert control characters into the search text\. Previously, ` could also be used for this\. +. +.P +Hit any other key to exit the increment search\. +. +.SH "Goto matching delimiter" +Hit \fB^G\fR to jump between matching delimiters\. This works on both character delimiters (like \'(\' and \')\') and word delimiters for languages like Pascal and Verilog which use "begin" and "end" to delimit blocks\. It also works for matching start and end tags in XML\. If a word is not known, \fB^G\fR starts a search with the word moved into the search prompt\. +. +.P +For \fB^G\fR to work on word delimiters, the cursor must be positioned on the first letter of the word\. So in XML, if the cursor is on the < in , it will jump to the >\. But if it is one the \'f\', it will jump to the matching \. Likewise, in C, \fB^G\fR will jump between #if, #else and #endif, but you need to position the cursor on the letter, not the \'#\'\. +. +.P +\fB^G\fR is smart enough to skip delimiters found in quoted or commented\-out matter\. You need to tell JOE how your language indicates this: see the \fBftyperc\fR file for examples of how this is done\. +. +.P +The are a number of options which control the behavior of \fB^G\fR\. These options control which kinds of comments \fB^G\fR can skip over: +. +.IP "\(bu" 4 +c_comment +. +.IP "\(bu" 4 +cpp_comment +. +.IP "\(bu" 4 +pount_comment +. +.IP "\(bu" 4 +semi_comment +. +.IP "\(bu" 4 +vhdl_comment +. +.IP "" 0 +. +.P +These options determine which kinds of strings \fB^G\fR can skip over: +. +.IP "\(bu" 4 +single_quoted +. +.IP "\(bu" 4 +double_quoted +. +.IP "" 0 +. +.P +This option allows an annotated syntax file to determine which text can be counted as comments or strings which can be skipped over by \fB^G\fR: +. +.IP "\(bu" 4 +highlighter_context +. +.IP "" 0 +. +.P +This option enables the use of syntax files to identify comments and strings which should be skipped over during \fB^G\fR matching\. The syntax file states should be annotated with the \fBstring\fR and \fBcomment\fR keywords for this to work\. +. +.IP "\(bu" 4 +text_delimiters +. +.IP "" 0 +. +.P +This option provides a list of word delimiters to match\. For example, "begin=end:if=elif=else=endif" means that \fB^G\fR will jump between the matching if, elif, else and endif\. It will also jump between begin and end\. +. +.P +\fB^G\fR has a built\-in table for matching character delimiters\- it knows that \fB(\fR goes with \fB)\fR\. +. +.P +\fB^G\fR has a built\-in parser to handle start/end tag matching for XML\. +. +.P + \fI\fR +. +.SH "Regions" +If you want to move, copy, save or delete a specific section of text, you can do it with highlighted blocks\. First, move the cursor to the start of the section of text you want to work on, and press \fB^K B\fR\. Then move the cursor to the character just after the end of the text you want to affect and press \fB^K K\fR\. The text between the \fB^K B\fR and \fB^K K\fR should become highlighted\. Now you can move your cursor to someplace else in your document and press \fB^K M\fR to move the highlighted text there\. +. +.br +You can press \fB^K C\fR to make a copy of the highlighted text and insert it to where the cursor is positioned\. \fB^K Y\fR to deletes the highlighted text\. \fB^K W\fR, writes the highlighted text to a file\. +. +.P +A very useful command is \fB^K /\fR, which filters a block of text through a UNIX command\. For example, if you select a list of words with \fB^K B\fR and \fB^K K\fR, and then type \fB^K / sort\fR, the list of words will be sorted\. Another useful UNIX command for \fB^K /\fR, is \fBtr\fR\. If you type \fB^K / tr a\-z A\-Z\fR, then all of the letters in the highlighted block will be converted to uppercase\. +. +.SS "How do I deselect a highlighted region?" +After you are finished with some region operations, you can just leave the highlighting on if you don\'t mind it (but don\'t accidentally hit \fB^K Y\fR)\. If it really bothers you, however, just hit \fB^K B ^K K\fR, to turn the highlighting off\. +. +.P +Beginning with JOE 4\.2, you can hit \fB^C\fR to cancel the region selection\. +. +.SS "New ways of selecting regions" +The classic way is to hit \fB^K B\fR at the beginning and \fB^K K\fR at the end\. These set pointers called markb and markk\. Once these are set you can jump to markb with \fBEsc B\fR and jump to markk with \fBEsc K\fR\. +. +.P +New way: hit Ctrl\-\fBRight Arrow\fR to start selecting rightward\. Each time you hit Ctrl\-\fBRight Arrow\fR, the block is extended one more to the right\. This uses a simple macro: "begin_marking,rtarw,toggle_marking"\. +. +.P +Unfortunately, there is no standard way to get the keysequence given by the terminal emulator when you hit Ctrl\-\fBRight Arrow\fR\. Instead you have to determine this sequence yourself and enter it directly in the joerc file\. Some examples are given for Xterm and gnome\-terminal\. Hit \fB^Q\fR Ctrl\-\fBRight Arrow\fR within JOE to have the sequence shown on your screen\. Note that Putty uses \fBEsc Esc [ C\fR which will not appear with \fB^Q Right Arrow\fR (also \fBEsc Esc\fR is the set bookmark command, so you need to unbind it to do this in Putty)\. +. +.P +Also you can hit Ctrl\-\fBDelete\fR to cut and Ctrl\-\fBInsert\fR to paste if the sequence for these keys are known\. +. +.P +The mouse can also be used to select text if mouse support is enabled in JOE\. +. +.SH "Indenting program blocks" +Auto\-indent mode is toggled with the \fB^T I\fR command\. The \fBjoerc\fR file is normally set up so that files with names ending with \.p, \.c or \.h have auto\-indent mode enabled\. When auto\-indent mode is enabled and you hit \fBEnter\fR, the cursor will be placed in the same column that the first non\-whitespace character was on in the original line\. +. +.P +You can use the \fB^K ,\fR and \fB^K \.\fR commands to shift a block of text to the left or right\. If no highlighting is set when you give these commands, the program block (as indicated by indentation) that the cursor is located in will be selected, and will be moved by subsequent \fB^K ,\fR and \fB^K \.\fR commands\. +. +.P +The number of columns these commands shift by and the character used for shifting can be set through the istep and indentc options\. These options are available in the \fB^T\fR menu\. Also, \fB^T =\fR can be used to quickly select from a number of common values for indentation step and character\. +. +.P +JOE has a number of additional options related to indenting programs: +. +.IP "\(bu" 4 +smartbacks +. +.br +Enable smart backspace and tab\. When this mode is set \fBBackspace\fR and \fBTab\fR indent or unindent based on the values of the istep and indentc options\. +. +.br + +. +.IP "\(bu" 4 +smarthome +. +.br +The \fBHome\fR and \fB^A\fR keys first move the cursor to the beginning of the line, then if hit again, to the first non\-blank character\. +. +.br + +. +.IP "\(bu" 4 +indentfirst +. +.br +Smart home goes to first non\-blank character first, instead of going to the beginning of the line first\. +. +.br + +. +.IP "\(bu" 4 +purify +. +.br +Fix indentation if necessary before shifting or smart backspace\. For example, if indentation uses a mix of tabs and spaces, and indentc is space, then indentation will be converted to all spaces before the shifting operation\. +. +.br + +. +.IP "\(bu" 4 +guess_indent +. +.br +When set, JOE tries to guess the indentation character and indentation step based on the contents of the file\. The algorithm is to find the greatest common factor of the three most common indentations found in the file\. +. +.br + +. +.IP "" 0 +. +.SH "Rectangle mode" +Type \fB^T X\fR to have \fB^K B\fR and \fB^K K\fR select rectangular blocks instead of stream\-of\-text blocks\. This is also known as columnar mode\. This mode is useful for moving, copying, deleting or saving columns of text\. You can also filter columns of text with the \fB^K /\fR command\- if you want to sort a column, for example\. The insert file command, \fB^K R\fR is also affected\. +. +.P +When rectangle mode is selected, overtype mode is also useful (\fB^T T\fR)\. When overtype mode is selected, rectangles will replace existing text instead of getting inserted before it\. Also the delete block command (\fB^K Y\fR) will clear the selected rectangle with \fBSpaces\fR and \fBTabs\fR instead of deleting it\. Overtype mode is especially useful for the filter block command (\fB^K /\fR), since it will maintain the original width of the selected column\. +. +.SH "Picture mode" +Use \fB^T P\fR to enter or exit picture mode\. Picture mode helps with ASCII drawings\. +. +.P +Picture mode controls how JOE handles the case where the cursor is past the ends of lines\. This happens when you use the up or down arrow keys to move the cursor from the end of a long line to a short line\. +. +.P +If you attempt to type a character in this case: +. +.P +If picture mode is off, the cursor will jump to the end of the line and insert it there\. +. +.P +If picture mode is on, the line is filled with spaces so that the character can be inserted at the cursor position\. +. +.SH "Windows" +You can edit more than one file at the same time or edit two or more different places of the same file\. To do this, hit \fB^K O\fR, to split the screen into two windows\. Use \fB^K P\fR or \fB^K N\fR to move the cursor into the top window or the lower window\. Use \fB^K E\fR to edit a new file in one of the windows\. A window will go away when you save the file with \fB^K X\fR or abort the file with \fB^C\fR\. If you abort a file which exists in two windows, one of the window goes away, not the file\. +. +.P +You can hit \fB^K O\fR within a window to create even more windows\. If you have too many windows on the screen, but you don\'t want to eliminate them, you can hit \fB^K I\fR\. This will show only the window the cursor is in, or if there was only one window on the screen to begin with, try to fit all hidden windows on the screen\. If there are more windows than can fit on the screen, you can hit \fB^K N\fR on the bottom\-most window or \fB^K P\fR on the top\-most window to get to them\. +. +.P +If you gave more than one file name to JOE on the command line, each file will be placed in a different window\. +. +.P +You can change the height of the windows with the \fB^K G\fR and \fB^K T\fR commands\. +. +.SS "Windowing system model" +JOE has an unusual model for its windowing system\. Basically you have a ring of windows, but only a section of this ring may fit on the screen\. The windows not on the screen still exist, they are just scrolled off\. When you hit \fB^K N\fR on the bottom window of the screen, it scrolls further windows from the ring onto the screen, possibly letting the top window scroll out of view\. +. +.P +Native JOE tries to keep each loaded buffer in a window, so users can find all of the buffers by scrolling through the windows\. The \fBexplode\fR command (\fB^K I\fR) either expands all windows to the size of the screen so that only one window can fit on the screen, or shrinks them all as much as possible to fit many on the screen\. +. +.P +On the other hand, JOE supports "orphan" buffers\- files loaded into the editor, but which are not in a window\. \fB^C\fR normally closes a window and discards the buffer that was in it\. If you hit \fB^C\fR on the last remaining window, it will normally exit the editor\. However, if there are orphan buffers, \fB^C\fR will instead load them into this final window to give you a chance to explicitly discard them\. If the \fBorphan\fR option is given on the command line, as in \fBjoe \-orphan *\.c\fR, then JOE only loads the first file into a window and leaves all the rest as orphans\. +. +.P +\fBorphan\fR also controls whether the edit command \fB^K E\fR creates a new window for a newly loaded file, or reuses the current window (orphaning its previous occupant)\. +. +.P +The \fBbufed\fR command prompts for a name of a buffer to switch into a window\. Its completion list will show all buffers, including orphans and buffers which appear in other windows\. \fBEsc V\fR and \fBEsc U\fR (\fBnbuf\fR and \fBpbuf\fR commands) allow you to cycle through all buffers within a single window\. +. +.P +Windows maintain a stack of occupants to support the pop\-up shell window feature\. When a pop\-up window is dismissed, the previous buffer is returned to the window\. +. +.SH "Scratch buffers" +Scratch buffers are buffers which JOE does not worry about trying to preserve\. JOE will not ask to save modified scratch buffers\. Pop\-up shell windows, the startup log and compile and grep message windows are scratch buffers\. You can create your own scratch buffer with the \fBscratch\fR command\. +. +.P +The following commands load scratch buffers: +. +.IP "\(bu" 4 +\fBshowlog\fR Show startup log +. +.IP "\(bu" 4 +\fBmwind\fR Show message window (compile / grep messages from \fBEsc C\fR and \fBEsc G\fR commands)\. +. +.IP "" 0 +. +.SH "Keyboard macros" +Macros allow you to record a series of keystrokes and replay them with the press of two keys\. This is useful to automate repetitive tasks\. To start a macro recording, hit \fB^K [\fR followed by a number from 0 to 9\. The status line will display (Macro n recording\.\.\.)\. Now, type in the series of keystrokes that you want to be able to repeat\. The commands you type will have their usual effects\. Hit \fB^K ]\fR to stop recording the macro\. Hit \fB^K\fR followed by the number you recorded the macro in to execute one iteration of the key\-strokes\. +. +.P +For example, if you want to put "**" in front of a number of lines, you can type: +. +.P +\fB^K [ 0 ^A **\fR\fIdown arrow\e\fR \fB^K ]\fR +. +.P +Which starts the macro recording, moves the cursor to the beginning of the line, inserts "**", moves the cursor down one line, and then ends the recording\. Since we included the key\-strokes needed to position the cursor on the next line, we can repeatedly use this macro without having to move the cursor ourselves, something you should always keep in mind when recording a macro\. +. +.SS "Keyboard macro subroutines" +If you find that the macro you are recording itself has a repeated set of key\-strokes in it, you can record a macro within the macro, as long as you use a different macro number\. Also you can execute previously recorded macros from within new macros\. +. +.SS "Query suspend" +If your macro includes a prompt for user input, and you want the user to fill in the prompt every time the macro is executed, hit \fB^K ?\fR at the point in the macro recording where the user action is required\. Keyboard input will not be recorded at this point\. When the user completes the prompt, macro recording will continue\. +. +.P +When the macro is executed, the macro player will pause at the point where \fB^K ?\fR was entered to allow user input\. When the user completes the prompt, the player continues with the rest of the macro\. +. +.SS "Repeat" +You can use the repeat command, \fB^K \e\fR, to repeat a macro, or any other edit command or even a normal character, a specified number of times\. Hit \fB^K \e\fR, type in the number of times you want the command repeated and press \fBEnter\fR\. The next edit command you now give will be repeated that many times\. For example, to delete the next 20 lines of text, type: +. +.P +\fB^K \e 20\fR\fIreturn\fR\fB^Y\fR +. +.SH "Macros and commands" +A macro is a comma separated list of commands\. When the macro is executed, each command is executed until either the end of the list is reached, or one of the commands fails (non\-zero return value from the command)\. Failed commands beep if you have beeps enabled (\fB^T B\fR)\. +. +.P +Hit \fBEsc D\fR to insert the current set of keyboard macros as text into the current buffer\. For example, the "**" insert macro above looks like this: +. +.IP "" 4 +. +.nf + +home,"**",dnarw ^K 0 Macro 0 +. +.fi +. +.IP "" 0 +. +.P +You could insert this into your \.joerc file and change the key sequence (the \fBK 0\fR) to something more permanent\. +. +.SS "Define your own" +You can bind macros to key sequences or define your own named macros in the joerc file\. For example, this will define a macro called \fBfoo\fR: +. +.IP "" 4 +. +.nf + +:def foo eof,bol +. +.fi +. +.IP "" 0 +. +.P +\fBfoo\fR will position the cursor at the beginning of the last line of the file\. \fBeof\fR jumps to the end of the file\. \fBbol\fR jumps to the beginning of a line\. Once a macro has been named this way it will show up in the completion list of the \fBEsc X\fR command prompt\. +. +.SS "Command prompt" +You can execute a macro directly by typing it into the command prompt\. Hit \fBEsc X\fR to bring up the command prompt\. Hit \fBTab\fR at this prompt for a completion list of all available commands\. +. +.P +Here is a \fIcomplete list of commands\fR\. +. +.SS "Macro don\'t stop modifier" +Sometimes, you expect commands to sometimes fail, but want the rest of the commands in the list to be executed anyway\. To mark a command which is allowed to fail, postfix it with \'!\'\. For example, here a macro which hits down page in the window above: +. +.IP "" 4 +. +.nf + +prevw,pgdn!,nextw +. +.fi +. +.IP "" 0 +. +.P +If prevw fails, the macro is aborted as usual\. Even if pgdn fails (already at end of buffer), nextw will be executed so that the cursor is returned to the original window\. +. +.SS "Macro repeat argument modifiers" +Repeat arguments can be specified with \fB^K \e\fR\. When a command is executed with a repeat argument, it is repeatedly executed the specified number of times\. If the repeat argument is negative, an opposite command (if one exists) is executed instead\. For example, if you repeat "rtarw" \-3 times, "ltarw" will be repeated 3 times\. If a negative argument is given for a command which does not have an opposite, the repeat argument is ignored\. +. +.P +Normally, if a repeat argument is specified for a macro, the macro is simply repeated the given number of times\. If a negative argument is given, the argument is ignored\. +. +.P +Sometimes you want to allow negative arguments for macros and have their behavior modified\. To do this, postfix each command within the macro which should be switched to its opposite for negative arguments with \'\-\'\. For example, here is the page down other window macro: +. +.IP "" 4 +. +.nf + +prevw,pgdn\-!,nextw +. +.fi +. +.IP "" 0 +. +.P +Now if you execute this with an argument of \-2, it will be repeated twice, but pgup will be executed instead of pgdn\. (note that several postfix modifiers can be placed after each command)\. +. +.P +Sometimes when a repeat argument is given to macro, you want only one of the commands in the list to be repeated, not the entire macro\. This can be indicated as follows: +. +.IP "" 4 +. +.nf + +prevw,pgdn#!,nextw +. +.fi +. +.IP "" 0 +. +.P +If this is executed with an argument of 2, prevw is executed once, pgdn is executed twice, and nextw is executed once\. +. +.P +Finally, even more complex semantics can be expressed with the "if" command: +. +.IP "" 4 +. +.nf + +if~,"arg<0",then, + ltarw, +else, + rtarw, +endif +. +.fi +. +.IP "" 0 +. +.P +When the macro is executed, the "arg" math variable is set to the given repeat argument\. The "argset" variable is set to true if the user set an argument, even if it\'s 1\. If no argument was given, argset is false\. +. +.P +If any command in the list is postfixed with ~ (if above), the macro is not repeated, even if there is an argument\. \'arg\' is still set to the given repeat count, however\. +. +.SS "\'psh\'/\'query\' interaction" +The \'psh\' command saves the \fB^K B\fR and \fB^K K\fR positions on a stack\. When the macro completes, (or when the \'pop\' command is called) the positions are restored\. +. +.P +The \'query\' command suspends macro execution until the current dialog is complete\. It also suspends the automatic \'pop\' which happens at the end of a macro\- so if the macro ends in a dialog you often want to call \'query\' to prevent the \fB^K B\fR \fB^K K\fR positions from being restored too early\. +. +.SH "Tags search" +If you are editing a large C program with many source files, you can use the \fBctags\fR program to generate a \fBtags\fR file\. This file contains a list of program symbols and the files and positions where the symbols are defined\. +. +.P +First, create the tags file with the "ctags" program\. For example: +. +.IP "" 4 +. +.nf + +ctags *\.c *\.h +. +.fi +. +.IP "" 0 +. +.P +This will create a file called "tags" in the current directory\. +. +.P +JOE looks for the "tags" file in the current directory\. If there is none, it will try to open the file specified by the TAGS environment variable\. +. +.P +Paths in the tags file are always relative to location of the tags file itself\. +. +.P +The tags file contains a list of identifier definition locations in one of these formats: +. +.IP "" 4 +. +.nf + +identifier filename /search\-expression/[;comments] + +identifier filename ?search\-expression?[;comments] + +identifier filename line\-number[;comments] +. +.fi +. +.IP "" 0 +. +.P +Some versions of ctags include class\-names in the identifiers: +. +.IP "" 4 +. +.nf + +class::member +. +.fi +. +.IP "" 0 +. +.P +In this case, JOE will match on any of these strings: +. +.IP "" 4 +. +.nf + +member +::member +class::member +. +.fi +. +.IP "" 0 +. +.P +Some versions of ctags include a filename in the identifier: +. +.IP "" 4 +. +.nf + +filename:identifier +. +.fi +. +.IP "" 0 +. +.P +In this case JOE will only find the identifier if the buffer name matches the filename\. +. +.P +The search\-expression is a vi regular expression, but JOE only supports the following special characters: +. +.IP "" 4 +. +.nf + +^ at the beginning means expression starts at beginning of line + +$ at the end means expression ends at end of line + +\ex quote x (suppress meaning of /, ?, ^ or $) +. +.fi +. +.IP "" 0 +. +.P +Type \fB^K ;\fR to bring up a tags search prompt\. If the cursor had been on an identifier, the prompt is pre\-loaded with it\. Tab completion works in this prompt (it uses the tags file to find completions)\. +. +.P +When you hit \fBEnter\fR, the tags search commences: +. +.P +If there is one and only one match, JOE will jump directly to the definition\. +. +.P +If there are multiple matches, then the behavior is controlled by the notagsmenu option\. If notagsmenu is enabled JOE jumps to the first definition\. If you hit \fB^K ;\fR again before hitting any other keys, JOE jumps to the next definition, and so on\. The "tagjump" command also performs this function\. +. +.P +If notagsmenu is disabled, JOE brings up a menu of all the matches\. You select the one you want and JOE jumps to it\. If you hit \fB^K ;\fR again before hitting any other keys, the same menu re\-appears with the cursor left in the original location\. +. +.P +You can hit \fB^K \-\fR to move the cursor back to the original location before the tags search (often \fB^C\fR will work as well)\. +. +.P +Since \fB^K ;\fR loads the definition file into the current window, you probably want to split the window first with \fB^K O\fR, to have both the original file and the definition file loaded\. +. +.SH "Calculator" +JOE has a built\-in calculator which can be invoked with \fBEsc M\fR\. +. +.SS "Math functions" +sin, cos, tan, exp, sqrt, cbrt, ln, log, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, int, floor, ceil, abs, erf, erfc, j0, j1, y0, y1 +. +.SS "Variables" +. +.IP "\(bu" 4 +e +. +.br +Set to \'e\' +. +.br + +. +.IP "\(bu" 4 +pi +. +.br +Set to \'pi\' +. +.br + +. +.IP "\(bu" 4 +top +. +.br +Set to line number of top window line +. +.br + +. +.IP "\(bu" 4 +lines +. +.br +Set to number of lines in file +. +.br + +. +.IP "\(bu" 4 +line +. +.br +Set to current line number +. +.br + +. +.IP "\(bu" 4 +col +. +.br +Set to current column number +. +.br + +. +.IP "\(bu" 4 +byte +. +.br +Set to current byte number +. +.br + +. +.IP "\(bu" 4 +size +. +.br +Set to buffer size +. +.br + +. +.IP "\(bu" 4 +height +. +.br +Set to window height +. +.br + +. +.IP "\(bu" 4 +width +. +.br +Set to window width +. +.br + +. +.IP "\(bu" 4 +char +. +.br +Set to ASCII val of character under cursor +. +.br + +. +.IP "\(bu" 4 +markv +. +.br +True if there is a valid block set (^KB \.\.\. ^KK) +. +.br + +. +.IP "\(bu" 4 +rdonly +. +.br +True if file is read\-only +. +.br + +. +.IP "\(bu" 4 +arg +. +.br +Current repeat argument +. +.br + +. +.IP "\(bu" 4 +argset +. +.br +True if a repeat argument was given +. +.br + +. +.IP "\(bu" 4 +is_shell +. +.br +True if executed in an active shell window +. +.br + +. +.IP "\(bu" 4 +no_windows +. +.br +No\. buffer windows on the screen +. +.br + +. +.IP "\(bu" 4 +ans +. +.br +Result of previous expression +. +.br + +. +.IP "" 0 +. +.SS "Commands" +. +.IP "\(bu" 4 +hex +. +.br +Hex display mode +. +.br + +. +.IP "\(bu" 4 +dec +. +.br +Decimal display mode +. +.br + +. +.IP "\(bu" 4 +ins +. +.br +Insert \'ans\' into buffer +. +.br + +. +.IP "\(bu" 4 +sum +. +.br +Sum of numbers in block +. +.br + +. +.IP "\(bu" 4 +cnt +. +.br +Count numbers in block +. +.br + +. +.IP "\(bu" 4 +avg +. +.br +Average value of numbers in block +. +.br + +. +.IP "\(bu" 4 +dev +. +.br +Standard deviation of numbers in block +. +.br + +. +.IP "\(bu" 4 +eval +. +.br +Evaluate math expressions in block (or whole file if no block set)\. +. +.br + +. +.IP "\(bu" 4 +joe(\.\.\.) +. +.br +Execute a JOE macro (argument in same format as joerc file macros)\. Return value of JOE macro is returned (for macro success, return true (non\-zero))\. +. +.br + +. +.IP "" 0 +. +.P +For example: +. +.IP "" 4 +. +.nf + +joe(sys,"[ 1 == 1 ]",rtn) +. +.fi +. +.IP "" 0 +. +.P +([ 1 == 1 ]) is a shell command\. "[" is a synonym for the "test" UNIX command\. +. +.P +Returns true\. +. +.P +Remember: argument for JOE macro command "if" is a math expression\. So for example, the macro: +. +.IP "" 4 +. +.nf + +if,"joe(sys,\e"[ 1 == 1 ]\e",rtn)",then,"TRUE",endif +. +.fi +. +.IP "" 0 +. +.P +Types TRUE into the buffer\. +. +.SS "Operators:" +. +.IP "\(bu" 4 +!x +. +.br +Logical not of x\. +. +.br + +. +.IP "\(bu" 4 +x +. +.br +Raise x to power of y\. +. +.br + +. +.IP "\(bu" 4 +a*b +. +.br +Multiply\. +. +.br + +. +.IP "\(bu" 4 +a/b +. +.br +Divide\. +. +.br + +. +.IP "\(bu" 4 +a%b +. +.br +Modulus\. +. +.br + +. +.IP "\(bu" 4 +a+b +. +.br +Add\. +. +.br + +. +.IP "\(bu" 4 +a\-b +. +.br +Subtract\. +. +.br + +. +.IP "\(bu" 4 +ab +. +.br +True if a is greater than b\. +. +.br + +. +.IP "\(bu" 4 +a>=b +. +.br +True if a is greater than or equal to b\. +. +.br + +. +.IP "\(bu" 4 +a==b +. +.br +True if a equals b\. +. +.br + +. +.IP "\(bu" 4 +a!=b +. +.br +True if a does not equal b\. +. +.br + +. +.IP "\(bu" 4 +a&&b +. +.br +True if both a and b are true\. +. +.br + +. +.IP "\(bu" 4 +a||b +. +.br +True if ether a or b are true\. +. +.br + +. +.IP "\(bu" 4 +a?b:c +. +.br +If a is true return b, otherwise return c\. +. +.br + +. +.IP "\(bu" 4 +a=b +. +.br +Assign b to a\. +. +.br + +. +.IP "\(bu" 4 +a:b +. +.br +Execute a, then execute b\. +. +.br + +. +.IP "" 0 +. +.TP +&&, || and ? : work as in C and sh as far as side effects: if the +. +.TP +left side of && is false, the right side is not evaluated\. +is expression separator\. +. +.SH "Shell windows" +Hit \fB^K \'\fR to run a command shell in one of JOE\'s windows\. When the cursor is at the end of a shell window (use \fB^K V\fR if it\'s not), whatever you type is passed to the shell instead of the buffer\. Any output from the shell or from commands executed in the shell is appended to the shell window (the cursor will follow this output if it\'s at the end of the shell window)\. This command is useful for recording the results of shell commands\- for example the output of \fBmake\fR, the result of \fBgrep\fRping a set of files for a string, or directory listings from \fBFTP\fR sessions\. Besides typeable characters, the keys \fB^C\fR, \fBBackspace\fR, \fBDel\fR, \fBReturn\fR and \fB^D\fR are passed to the shell\. Type the shell \fBexit\fR command to stop recording shell output\. If you press \fB^C\fR in a shell window, when the cursor is not at the end of the window, the shell is \fBkill\fRed\. +. +.P +If you use Bash, you can hit: \fB^Q Up Arrow\fR and \fB^Q Down Arrow\fR to scroll through Bash\'s history buffer\. Other keys work as well: try \fB^Q ^A\fR to go to beginning of line or \fB^Q ^E\fR to go to end of line\. Unfortunately JOE only emulates a dumb terminal, so you have to use a lot of imagination to do any editing beyond hitting backspace\. +. +.P +In general, any character quoted with \fB^Q\fR is sent to the shell\. +. +.P +Also sent to the shell: \fBTab\fR, \fBBackspace\fR, \fBEnter\fR, \fB^C\fR and \fB^D\fR\. +. +.P + \fI\fR +. +.SH "Pop\-up shell windows" +Hit F1 \- F4 to open and switch between shell windows\. +. +.P +Pop\-up shell windows use a full terminal emulator so that when you type "man ls" it\'s formatted correctly (it works well enough so that some interactive programs can be used)\. Even so, the shell window is still an edit buffer\. +. +.P +The old shell window (with no terminal emulation) still exists: use \fB^K \'\fR to invoke it as usual\. This is useful to see control sequences emitted by a program\. +. +.P +More of the keys get passed to the running program in pop\-up shell windows compared with the older one\. There is a :vtshell section of the joerc file to control which ones\. In particular arrow keys and Ctrl\-C are passed to the program\. It means you can easily step through bash history with the arrow keys, or abort programs the normal way with Ctrl\-C\. +. +.P +On the other hand, loss of Ctrl\-C means it\'s less obvious how to close the window\. One way is to move the cursor off of the shell data entry point (with Ctrl\-P), and then hit Ctrl\-C\. Another is to hit \fB^K Q\fR\. Finally, you can type \'pop\' at the command prompt\. +. +.P +If you need to pass a key to the shell that JOE normally uses, quote it\. For example, if you invoke "emacs \-nw" in the shell window, you can exit it with: +. +.IP "" 4 +. +.nf + +^Q ^X ^C +. +.fi +. +.IP "" 0 +. +.P +To quickly position the cursor back to the point where data is entered into the shell, hit \fB^K V\fR\. +. +.P +When you open a shell window, a JOE\-specific startup\-script is sourced\. It\'s located in /etc/joe/shell\.sh (also /etc/joe/shell\.csh)\. It contains some aliases which allow you to control JOE with fake shell commands\. I have these commands so far: +. +.IP "\(bu" 4 +clear +. +.br +erase shell window (delete buffer contents) +. +.br + +. +.IP "\(bu" 4 +joe file +. +.br +edit a file in JOE +. +.br + +. +.IP "\(bu" 4 +math 1+2 +. +.br +evaluate equation using JOE\'s calculator +. +.br + +. +.IP "\(bu" 4 +cd xyz +. +.br +change directory, keep JOE up to date +. +.br + +. +.IP "\(bu" 4 +markb +. +.br +same as ^KB +. +.br + +. +.IP "\(bu" 4 +markk +. +.br +same as ^KK +. +.br + +. +.IP "\(bu" 4 +mark command +. +.br +execute shell command, mark it\'s output +. +.br + +. +.IP "\(bu" 4 +parse command +. +.br +execute shell command, parse it\'s output for file names and line numbers (for find or grep) +. +.br + +. +.IP "\(bu" 4 +parser comman +. +.br +execute shell command, parse it\'s output for errors (for gcc) +. +.br + +. +.IP "\(bu" 4 +release +. +.br +release parsed errors +. +.br + +. +.IP "\(bu" 4 +pop +. +.br +dismiss shell window (same as ^K Q) +. +.br + +. +.IP "" 0 +. +.P +These work by emitting an escape sequence recognized by the terminal emulator: \fBEsc { joe_macro }\fR\. When this is received, the macro is executed\. For security, only macros defined in the joerc file which begin with "shell_" can be executed this way\. +. +.SS "Use cases" +Pop\-up shell windows have a number of nice use cases: +. +.IP "\(bu" 4 +Use it to browse manual pages +. +.IP +Hit F1 and type "man fopen"\. Use \'b\' (\'u\') and space to control \fImore\fR (or \fIless\fR) while viewing the manual\. You can leave the manual on the screen in one window while editing in another window\. +. +.IP "\(bu" 4 +Use it to switch directories +. +.IP +Hit F1 and navigate to the directory while using \fIcd\fR\. Once you are in the right place, hit \fB^K E\fR to load a file (or type "edit file" from the shell)\. +. +.IP "\(bu" 4 +Use it in conjunction with the error parser to find files +. +.IP +Hit F1 and navigate to a directory\. Use grep or find (or both) to generate a list of files): +. +.IP "" 0 +. +.IP "" 4 +. +.nf + + parse grep \-n FIXME *\.c +. +.fi +. +.IP "" 0 +. +.P +Or: +. +.IP "" 4 +. +.nf + + markb; find \. | xargs grep \-n FIXME; markk; parse +. +.fi +. +.IP "" 0 +. +.P +(Note that you can\'t say this: +. +.IP "" 4 +. +.nf + + parse find \. | xargs grep \-n FIXME +. +.fi +. +.IP "" 0 +. +.P +\&\.\.\.the issue is that only the words to the left of the pipe symbol are passed as arguments to the parse command)\. +. +.P +Now use \fB^P\fR to position the cursor on one of the lines of the list\. Hit \fBEsc Space\fR to have JOE edit the file and jump to the specified line (also you can use \fBEsc \-\fR and \fBEsc =\fR to step through the list)\. +. +.IP "\(bu" 4 +Use it in conjunction with search and replace to edit many files +. +.IP +Once JOE has a list of files (from above), use search and replace with the \'e\' option to visit all of them: +. +.IP "" 0 +. +.IP "" 4 +. +.nf + + ^K F + Find: + Options: re + Replace: +. +.fi +. +.IP "" 0 +. +.IP "\(bu" 4 +Build your project +. +.IP "" 0 +. +.P +Easily capture errors from a build with: +. +.IP "" 4 +. +.nf + + parserr make +. +.fi +. +.IP "" 0 +. +.P +Hit \fBEsc =\fR and \fBEsc \-\fR to step through the errors\. +. +.SS "How it works\.\." +. +.IP "\(bu" 4 +There is a new mode "ansi"\. (\fBEsc X\fR mode ansi)\. When this mode is enabled, the screen updater hides escape sequences which are in the buffer\. Otherwise you get a big mess from the sequences surrounding colored output from \'ls\'\. +. +.IP "\(bu" 4 +There is a new built\-in syntax: "ansi"\. (\fB^T Y\fR ansi)\. This syntax parses the ANSI color control sequences so that text gets colored\. +. +.IP "\(bu" 4 +There is a terminal emulator to interpret control sequences from the shell program\. It emulates a terminal by modifying the contents of an edit buffer\. +. +.IP "\(bu" 4 +When the edit window is resized we tell the shell by issuing the TIOCSSIZE or TIOCSWINSZ ioctl\. This way, the program running in the shell knows the window size\. +. +.IP "" 0 +. +.SH "Compiler and grep/find parsers" +JOE has two parsers which can be used to generate the error list (list of file names / line numbers)\. +. +.P +The "parserr" command parses the entire buffer, or if the block is set, just the highighted block for compiler error messages\. The messages should be in this format: +. +.IP "" 4 +. +.nf + + file\.name line\-number : +. +.fi +. +.IP "" 0 +. +.P +The file name needs to be made of numbers, letters, \'/\', \'\.\' and \'\-\'\. It must have at leat one \'\.\' in it\. There needs to be a colon somewhere after the line number\. Lines not in this format are ignored\. +. +.P +The "gparse\' command parses the entire buffer, or if the block is set, just the highlighted block for a list of filenames or filenames with line numbers from "grep \-n", "find" and similar programs\. +. +.IP "" 4 +. +.nf + +filename + +filename: + +filename:line\-number: +. +.fi +. +.IP "" 0 +. +.P +Once JOE has the error list, there are a number of things you can do with it: +. +.IP "\(bu" 4 +Visit the files/locations in the list with \fBEsc \-\fR and \fBEsc =\fR +. +.IP "\(bu" 4 +Search and replace across all files in the list by using the \'e\' search and replace option\. +. +.IP "\(bu" 4 +Clear the list by using the "release" command\. +. +.IP "" 0 +. +.P +Also, you can use \fBEsc Space\fR (\'jump\' command) to parse the line the cursor is on and jump to the parsed filename and line number\. \'jump\' uses the grep/find parser unless \'parserr\' had been previously issued in the buffer\. +. +.SS "Grep\-find" +Hit \fBEsc G\fR to bring up the prompt\. Enter a command which results in file names with line numbers, for example: \'grep \-n fred *\.c\'\. This will list all instances of \'fred\' in the *\.c files\. You need the \'\-n\' to get the line numbers\. +. +.P +Now you can hit \fBEsc Space\fR on one of the lines to jump to the selected file\. Also, you can use \fBEsc =\fR and \fBEsc \-\fR to step through each line\. +. +.SS "Compile" +Hit \fBEsc C\fR to save all modified files and then bring up the compile prompt\. Enter the command you want to use for the compiler (typically "make \-w")\. The compiler will run in a shell window\. When it\'s complete, the results are parsed\. +. +.P +The \'\-w\' flag should be given to "make" so that it prints messages whenever it changes directories\. The message are in this format: +. +.IP "" 4 +. +.nf + +make[1]: Entering directory `/home/jhallen/joe\-editor\-mercurial/joe\' +. +.fi +. +.IP "" 0 +. +.P +If there are any errors or warnings from the compiler you can hit \fBEsc Space\fR on one of the lines to jump to the selected file\. Also, you can use \fBEsc =\fR and \fBEsc \-\fR to step through each line\. +. +.SH "Syntax highlighting" +To enable highlight use \fB^T H\fR\. +. +.P +To select the syntax, use \fB^T Y\fR\. You can hit \fBTab\fR \fBTab\fR at the prompt for a completion list\. +. +.P +JOE tries to determine the syntax to use based on the name and contents of the file\. The configuration file /etc/joe/ftyperc contains the definitions\. +. +.P +Each syntax is defined by a file located /usr/share/joe/syntax/\. +. +.SH "How JOE syntax highlighting works" +\fIfrom c\.jsf \fIhttp://joe\-editor\.hg\.sourceforge\.net/hgweb/joe\-editor/joe\-editor/file/tip/syntax/c\.jsf\.in\fR, slightly modified\fR +. +.P +A deterministic state machine that performs lexical analysis of the target language is provided in a syntax file\. (This is the "assembly language" of syntax highlighting\. A separate program could in principal be used to convert a regular expression NFA syntax into this format)\. +. +.P +Each state begins with: +. +.IP "" 4 +. +.nf + +: +. +.fi +. +.IP "" 0 +. +.P +\fIname\e\fR is the state\'s name\. +. +.P +\fIcolor\-name\e\fR is the color used for characters eaten by the state (really a symbol for a user definable color)\. +. +.P +\fIcontext\e\fR tells JOE if the current character is part of a comment or a string\. This allows JOE to skip over comments and strings when matching characters such as parentheses\. To use this feature, the highlighter_context option must be applied to the files highlighted by the corresponding syntax\. To apply the option, add it to ftyperc for those file entries\. +. +.P +The valid contexts are: +. +.IP "\(bu" 4 +comment This character is part of a comment\. Example: /* comment */ +. +.IP "\(bu" 4 +string This character is part of a string\. Examples: "string" \'c\' \'string\' +. +.IP "" 0 +. +.P +The comment and string delimiters themselves should be marked with the appropriate context\. The context is considered to be part of the color, so the recolor=\-N and recolormark options apply the context to previous characters\. +. +.P +The first state defined is the initial state\. +. +.P +Within a state, define transitions (jumps) to other states\. Each jump has the form: +. +.IP "" 4 +. +.nf + + [