From 141fe2c6e06aa426e9dc41fb62c14f0ca8a1937b Mon Sep 17 00:00:00 2001 From: Ben Gras Date: Mon, 2 May 2005 13:01:42 +0000 Subject: [PATCH] Added man pages. --- man/Makefile | 16 + man/man1/M.1 | 35 + man/man1/acd.1 | 860 ++++++++++++++ man/man1/anm.1 | 63 ++ man/man1/ar.1 | 56 + man/man1/ash.1 | 1123 ++++++++++++++++++ man/man1/asize.1 | 37 + man/man1/at.1 | 34 + man/man1/banner.1 | 22 + man/man1/basename.1 | 33 + man/man1/bc.1 | 730 ++++++++++++ man/man1/bsfilt.1 | 86 ++ man/man1/cal.1 | 27 + man/man1/calendar.1 | 44 + man/man1/cat.1 | 33 + man/man1/cawf.1 | 760 +++++++++++++ man/man1/cc.1 | 588 ++++++++++ man/man1/cdiff.1 | 31 + man/man1/cgrep.1 | 33 + man/man1/chgrp.1 | 38 + man/man1/chmem.1 | 65 ++ man/man1/chmod.1 | 62 + man/man1/cksum.1 | 34 + man/man1/clear.1 | 17 + man/man1/cmp.1 | 34 + man/man1/comm.1 | 39 + man/man1/compress.1 | 42 + man/man1/cp.1 | 223 ++++ man/man1/crc.1 | 29 + man/man1/crontab.1 | 93 ++ man/man1/ctags.1 | 84 ++ man/man1/cut.1 | 46 + man/man1/date.1 | 78 ++ man/man1/dd.1 | 62 + man/man1/df.1 | 75 ++ man/man1/dhrystone.1 | 29 + man/man1/diff.1 | 47 + man/man1/dosdir.1 | 44 + man/man1/dosread.1 | 30 + man/man1/doswrite.1 | 28 + man/man1/du.1 | 31 + man/man1/echo.1 | 68 ++ man/man1/ed.1 | 69 ++ man/man1/eject.1 | 24 + man/man1/elvis.1 | 100 ++ man/man1/elvrec.1 | 47 + man/man1/env.1 | 93 ++ man/man1/expand.1 | 28 + man/man1/expr.1 | 243 ++++ man/man1/factor.1 | 22 + man/man1/fgrep.1 | 35 + man/man1/file.1 | 24 + man/man1/find.1 | 84 ++ man/man1/finger.1 | 84 ++ man/man1/flex.1 | 779 +++++++++++++ man/man1/flexdoc.1 | 2441 ++++++++++++++++++++++++++++++++++++++++ man/man1/fmt.1 | 26 + man/man1/fold.1 | 29 + man/man1/format.1 | 67 ++ man/man1/fortune.1 | 23 + man/man1/fsck.1 | 51 + man/man1/grep.1 | 50 + man/man1/head.1 | 28 + man/man1/host.1 | 207 ++++ man/man1/hostaddr.1 | 43 + man/man1/id.1 | 29 + man/man1/ifdef.1 | 44 + man/man1/install.1 | 177 +++ man/man1/isodir.1 | 29 + man/man1/isoinfo.1 | 19 + man/man1/isoread.1 | 27 + man/man1/join.1 | 118 ++ man/man1/kill.1 | 35 + man/man1/last.1 | 44 + man/man1/leave.1 | 26 + man/man1/loadfont.1 | 37 + man/man1/loadkeys.1 | 30 + man/man1/login.1 | 28 + man/man1/look.1 | 38 + man/man1/lp.1 | 59 + man/man1/ls.1 | 164 +++ man/man1/mail.1 | 98 ++ man/man1/make.1 | 76 ++ man/man1/makewhatis.1 | 27 + man/man1/man.1 | 201 ++++ man/man1/mesg.1 | 38 + man/man1/mixer.1 | 24 + man/man1/mkdir.1 | 33 + man/man1/mkfifo.1 | 30 + man/man1/mkfs.1 | 88 ++ man/man1/mkproto.1 | 36 + man/man1/modem.1 | 39 + man/man1/mount.1 | 44 + man/man1/mt.1 | 109 ++ man/man1/nm.1 | 40 + man/man1/od.1 | 38 + man/man1/passwd.1 | 44 + man/man1/paste.1 | 40 + man/man1/patch.1 | 555 +++++++++ man/man1/playwave.1 | 16 + man/man1/postmort.1 | 37 + man/man1/pr.1 | 37 + man/man1/prep.1 | 27 + man/man1/ps.1 | 68 ++ man/man1/pwd.1 | 23 + man/man1/rcp.1 | 90 ++ man/man1/readall.1 | 36 + man/man1/readfs.1 | 31 + man/man1/recwave.1 | 20 + man/man1/ref.1 | 88 ++ man/man1/remsync.1 | 184 +++ man/man1/rget.1 | 169 +++ man/man1/rlogin.1 | 87 ++ man/man1/rmdir.1 | 27 + man/man1/rsh.1 | 94 ++ man/man1/rz.1 | 95 ++ man/man1/sed.1 | 390 +++++++ man/man1/shar.1 | 40 + man/man1/size.1 | 39 + man/man1/sleep.1 | 24 + man/man1/sort.1 | 50 + man/man1/spell.1 | 33 + man/man1/split.1 | 30 + man/man1/stat.1 | 106 ++ man/man1/strings.1 | 29 + man/man1/strip.1 | 24 + man/man1/stty.1 | 250 ++++ man/man1/su.1 | 58 + man/man1/sum.1 | 29 + man/man1/svc.1 | 47 + man/man1/synctree.1 | 76 ++ man/man1/sysenv.1 | 27 + man/man1/sz.1 | 235 ++++ man/man1/tail.1 | 34 + man/man1/tar.1 | 49 + man/man1/tee.1 | 29 + man/man1/telnet.1 | 587 ++++++++++ man/man1/template.1 | 46 + man/man1/term.1 | 70 ++ man/man1/termcap.1 | 26 + man/man1/tget.1 | 68 ++ man/man1/time.1 | 26 + man/man1/touch.1 | 31 + man/man1/tr.1 | 47 + man/man1/true.1 | 24 + man/man1/tsort.1 | 23 + man/man1/tty.1 | 26 + man/man1/umount.1 | 35 + man/man1/uname.1 | 41 + man/man1/unexpand.1 | 28 + man/man1/uniq.1 | 36 + man/man1/uud.1 | 33 + man/man1/uue.1 | 43 + man/man1/vol.1 | 125 ++ man/man1/wc.1 | 30 + man/man1/whatis.1 | 32 + man/man1/whereis.1 | 26 + man/man1/which.1 | 32 + man/man1/who.1 | 31 + man/man1/whoami.1 | 26 + man/man1/write.1 | 33 + man/man1/xargs.1 | 176 +++ man/man1/yacc.1 | 111 ++ man/man1/yap.1 | 391 +++++++ man/man1/yes.1 | 25 + man/man2/access.2 | 109 ++ man/man2/alarm.2 | 38 + man/man2/brk.2 | 86 ++ man/man2/chdir.2 | 62 + man/man2/chmod.2 | 132 +++ man/man2/chown.2 | 102 ++ man/man2/chroot.2 | 62 + man/man2/close.2 | 84 ++ man/man2/creat.2 | 142 +++ man/man2/dup.2 | 86 ++ man/man2/execve.2 | 206 ++++ man/man2/exit.2 | 57 + man/man2/fcntl.2 | 262 +++++ man/man2/fork.2 | 74 ++ man/man2/getgid.2 | 34 + man/man2/getpid.2 | 33 + man/man2/getuid.2 | 34 + man/man2/intro.2 | 449 ++++++++ man/man2/ioctl.2 | 69 ++ man/man2/kill.2 | 93 ++ man/man2/link.2 | 111 ++ man/man2/lseek.2 | 86 ++ man/man2/mkdir.2 | 112 ++ man/man2/mknod.2 | 131 +++ man/man2/mount.2 | 51 + man/man2/open.2 | 186 +++ man/man2/pause.2 | 43 + man/man2/pipe.2 | 89 ++ man/man2/ptrace.2 | 231 ++++ man/man2/read.2 | 83 ++ man/man2/reboot.2 | 62 + man/man2/rename.2 | 135 +++ man/man2/rmdir.2 | 77 ++ man/man2/setsid.2 | 40 + man/man2/setuid.2 | 48 + man/man2/sigaction.2 | 244 ++++ man/man2/sigpending.2 | 33 + man/man2/sigprocmask.2 | 75 ++ man/man2/sigsuspend.2 | 39 + man/man2/stat.2 | 181 +++ man/man2/svrctl.2 | 59 + man/man2/sync.2 | 27 + man/man2/time.2 | 62 + man/man2/times.2 | 68 ++ man/man2/umask.2 | 38 + man/man2/uname.2 | 35 + man/man2/unlink.2 | 84 ++ man/man2/utime.2 | 85 ++ man/man2/wait.2 | 162 +++ man/man2/write.2 | 97 ++ man/man3/abort.3 | 27 + man/man3/abs.3 | 24 + man/man3/assert.3 | 42 + man/man3/atof.3 | 39 + man/man3/bstring.3 | 84 ++ man/man3/configfile.3 | 194 ++++ man/man3/crypt.3 | 71 ++ man/man3/ctime.3 | 116 ++ man/man3/ctype.3 | 95 ++ man/man3/curses.3 | 248 ++++ man/man3/directory.3 | 89 ++ man/man3/editline.3 | 169 +++ man/man3/end.3 | 42 + man/man3/execl.3 | 196 ++++ man/man3/exit.3 | 39 + man/man3/fclose.3 | 45 + man/man3/ferror.3 | 58 + man/man3/fopen.3 | 99 ++ man/man3/fread.3 | 66 ++ man/man3/fseek.3 | 53 + man/man3/g_h_b_n.3 | 165 +++ man/man3/getc.3 | 79 ++ man/man3/getcwd.3 | 36 + man/man3/getenv.3 | 29 + man/man3/getgrent.3 | 136 +++ man/man3/getlogin.3 | 45 + man/man3/getopt.3 | 150 +++ man/man3/getpass.3 | 28 + man/man3/getpwent.3 | 139 +++ man/man3/gets.3 | 68 ++ man/man3/getservent.3 | 112 ++ man/man3/getttyent.3 | 107 ++ man/man3/hton.3 | 60 + man/man3/int64.3 | 193 ++++ man/man3/malloc.3 | 117 ++ man/man3/oneC_sum.3 | 45 + man/man3/popen.3 | 51 + man/man3/printf.3 | 264 +++++ man/man3/putc.3 | 70 ++ man/man3/puts.3 | 43 + man/man3/qsort.3 | 36 + man/man3/rand.3 | 33 + man/man3/random.3 | 131 +++ man/man3/rcmd.3 | 141 +++ man/man3/regex.3 | 541 +++++++++ man/man3/resolver.3 | 280 +++++ man/man3/scanf.3 | 251 +++++ man/man3/servxcheck.3 | 120 ++ man/man3/setbuf.3 | 112 ++ man/man3/sigset.3 | 85 ++ man/man3/sleep.3 | 31 + man/man3/stdarg.3 | 123 ++ man/man3/stdio.3 | 199 ++++ man/man3/string.3 | 149 +++ man/man3/system.3 | 30 + man/man3/termcap.3 | 167 +++ man/man3/termios.3 | 155 +++ man/man3/ttyname.3 | 28 + man/man3/ttyslot.3 | 56 + man/man3/ungetc.3 | 41 + man/man4/console.4 | 268 +++++ man/man4/controller.4 | 387 +++++++ man/man4/dev.4 | 261 +++++ man/man4/fd.4 | 88 ++ man/man4/ip.4 | 1466 ++++++++++++++++++++++++ man/man4/lp.4 | 28 + man/man4/mtio.4 | 98 ++ man/man4/tty.4 | 736 ++++++++++++ man/man5/TZ.5 | 138 +++ man/man5/configfile.5 | 83 ++ man/man5/crontab.5 | 137 +++ man/man5/dhcp.conf.5 | 498 ++++++++ man/man5/dir.5 | 43 + man/man5/ethers.5 | 36 + man/man5/fstab.5 | 87 ++ man/man5/hosts.5 | 57 + man/man5/keymap.5 | 167 +++ man/man5/passwd.5 | 200 ++++ man/man5/resolv.conf.5 | 48 + man/man5/resolver.5 | 98 ++ man/man5/rhosts.5 | 59 + man/man5/serv.access.5 | 166 +++ man/man5/termcap.5 | 1865 ++++++++++++++++++++++++++++++ man/man5/ttytab.5 | 95 ++ man/man5/utmp.5 | 70 ++ man/man5/whatis.5 | 57 + man/man6/advent.6 | 22 + man/man6/ttt.6 | 23 + man/man7/ACK.7 | 2090 ++++++++++++++++++++++++++++++++++ man/man7/ascii.7 | 76 ++ man/man7/environ.7 | 111 ++ man/man7/hier.7 | 195 ++++ man/man7/man.7 | 278 +++++ man/man7/re_format.7 | 269 +++++ man/man8/MAKEDEV.8 | 53 + man/man8/add_route.8 | 47 + man/man8/adduser.8 | 43 + man/man8/backup.8 | 52 + man/man8/badblocks.8 | 34 + man/man8/boot.8 | 524 +++++++++ man/man8/checkhier.8 | 29 + man/man8/chown.8 | 35 + man/man8/cleantmp.8 | 65 ++ man/man8/config.8 | 334 ++++++ man/man8/cron.8 | 165 +++ man/man8/dhcpd.8 | 208 ++++ man/man8/dosminix.8 | 287 +++++ man/man8/elvprsv.8 | 54 + man/man8/fdisk.8 | 58 + man/man8/fingerd.8 | 53 + man/man8/ftpd.8 | 145 +++ man/man8/getty.8 | 40 + man/man8/halt.8 | 33 + man/man8/ifconfig.8 | 50 + man/man8/inet.8 | 147 +++ man/man8/init.8 | 141 +++ man/man8/installboot.8 | 395 +++++++ man/man8/intr.8 | 71 ++ man/man8/irdpd.8 | 74 ++ man/man8/mkdist.8 | 30 + man/man8/mknod.8 | 33 + man/man8/monitor.8 | 606 ++++++++++ man/man8/nonamed.8 | 306 +++++ man/man8/part.8 | 116 ++ man/man8/partition.8 | 66 ++ man/man8/pr_routes.8 | 26 + man/man8/printroot.8 | 29 + man/man8/pwdauth.8 | 58 + man/man8/rarpd.8 | 75 ++ man/man8/rdate.8 | 20 + man/man8/readclock.8 | 61 + man/man8/reboot.8 | 49 + man/man8/repartition.8 | 41 + man/man8/rlogind.8 | 103 ++ man/man8/rshd.8 | 166 +++ man/man8/screendump.8 | 35 + man/man8/serial-ip.8 | 232 ++++ man/man8/shutdown.8 | 88 ++ man/man8/slip.8 | 82 ++ man/man8/srccrc.8 | 33 + man/man8/sync.8 | 33 + man/man8/update.8 | 29 + man/man8/usage.8 | 969 ++++++++++++++++ man/man9/as.9 | 410 +++++++ man/man9/awk.9 | 246 ++++ man/man9/de.9 | 311 +++++ man/man9/dis88.9 | 82 ++ man/man9/elle.9 | 555 +++++++++ man/man9/elvis.9 | 1256 +++++++++++++++++++++ man/man9/kermit.9 | 128 +++ man/man9/m4.9 | 183 +++ man/man9/macros.9 | 1463 ++++++++++++++++++++++++ man/man9/mined.9 | 198 ++++ 368 files changed, 50911 insertions(+) create mode 100644 man/Makefile create mode 100644 man/man1/M.1 create mode 100644 man/man1/acd.1 create mode 100644 man/man1/anm.1 create mode 100644 man/man1/ar.1 create mode 100644 man/man1/ash.1 create mode 100644 man/man1/asize.1 create mode 100644 man/man1/at.1 create mode 100644 man/man1/banner.1 create mode 100644 man/man1/basename.1 create mode 100644 man/man1/bc.1 create mode 100644 man/man1/bsfilt.1 create mode 100644 man/man1/cal.1 create mode 100644 man/man1/calendar.1 create mode 100644 man/man1/cat.1 create mode 100644 man/man1/cawf.1 create mode 100644 man/man1/cc.1 create mode 100644 man/man1/cdiff.1 create mode 100644 man/man1/cgrep.1 create mode 100644 man/man1/chgrp.1 create mode 100644 man/man1/chmem.1 create mode 100644 man/man1/chmod.1 create mode 100644 man/man1/cksum.1 create mode 100644 man/man1/clear.1 create mode 100644 man/man1/cmp.1 create mode 100644 man/man1/comm.1 create mode 100644 man/man1/compress.1 create mode 100644 man/man1/cp.1 create mode 100644 man/man1/crc.1 create mode 100644 man/man1/crontab.1 create mode 100644 man/man1/ctags.1 create mode 100644 man/man1/cut.1 create mode 100644 man/man1/date.1 create mode 100644 man/man1/dd.1 create mode 100644 man/man1/df.1 create mode 100644 man/man1/dhrystone.1 create mode 100644 man/man1/diff.1 create mode 100644 man/man1/dosdir.1 create mode 100644 man/man1/dosread.1 create mode 100644 man/man1/doswrite.1 create mode 100644 man/man1/du.1 create mode 100644 man/man1/echo.1 create mode 100644 man/man1/ed.1 create mode 100644 man/man1/eject.1 create mode 100644 man/man1/elvis.1 create mode 100644 man/man1/elvrec.1 create mode 100644 man/man1/env.1 create mode 100644 man/man1/expand.1 create mode 100644 man/man1/expr.1 create mode 100644 man/man1/factor.1 create mode 100644 man/man1/fgrep.1 create mode 100644 man/man1/file.1 create mode 100644 man/man1/find.1 create mode 100644 man/man1/finger.1 create mode 100644 man/man1/flex.1 create mode 100644 man/man1/flexdoc.1 create mode 100644 man/man1/fmt.1 create mode 100644 man/man1/fold.1 create mode 100644 man/man1/format.1 create mode 100644 man/man1/fortune.1 create mode 100644 man/man1/fsck.1 create mode 100644 man/man1/grep.1 create mode 100644 man/man1/head.1 create mode 100644 man/man1/host.1 create mode 100644 man/man1/hostaddr.1 create mode 100644 man/man1/id.1 create mode 100644 man/man1/ifdef.1 create mode 100644 man/man1/install.1 create mode 100644 man/man1/isodir.1 create mode 100644 man/man1/isoinfo.1 create mode 100644 man/man1/isoread.1 create mode 100644 man/man1/join.1 create mode 100644 man/man1/kill.1 create mode 100644 man/man1/last.1 create mode 100644 man/man1/leave.1 create mode 100644 man/man1/loadfont.1 create mode 100644 man/man1/loadkeys.1 create mode 100644 man/man1/login.1 create mode 100644 man/man1/look.1 create mode 100644 man/man1/lp.1 create mode 100644 man/man1/ls.1 create mode 100644 man/man1/mail.1 create mode 100644 man/man1/make.1 create mode 100644 man/man1/makewhatis.1 create mode 100644 man/man1/man.1 create mode 100644 man/man1/mesg.1 create mode 100644 man/man1/mixer.1 create mode 100644 man/man1/mkdir.1 create mode 100644 man/man1/mkfifo.1 create mode 100644 man/man1/mkfs.1 create mode 100644 man/man1/mkproto.1 create mode 100644 man/man1/modem.1 create mode 100644 man/man1/mount.1 create mode 100644 man/man1/mt.1 create mode 100644 man/man1/nm.1 create mode 100644 man/man1/od.1 create mode 100644 man/man1/passwd.1 create mode 100644 man/man1/paste.1 create mode 100644 man/man1/patch.1 create mode 100644 man/man1/playwave.1 create mode 100644 man/man1/postmort.1 create mode 100644 man/man1/pr.1 create mode 100644 man/man1/prep.1 create mode 100644 man/man1/ps.1 create mode 100644 man/man1/pwd.1 create mode 100644 man/man1/rcp.1 create mode 100644 man/man1/readall.1 create mode 100644 man/man1/readfs.1 create mode 100644 man/man1/recwave.1 create mode 100644 man/man1/ref.1 create mode 100644 man/man1/remsync.1 create mode 100644 man/man1/rget.1 create mode 100644 man/man1/rlogin.1 create mode 100644 man/man1/rmdir.1 create mode 100644 man/man1/rsh.1 create mode 100644 man/man1/rz.1 create mode 100644 man/man1/sed.1 create mode 100644 man/man1/shar.1 create mode 100644 man/man1/size.1 create mode 100644 man/man1/sleep.1 create mode 100644 man/man1/sort.1 create mode 100644 man/man1/spell.1 create mode 100644 man/man1/split.1 create mode 100644 man/man1/stat.1 create mode 100644 man/man1/strings.1 create mode 100644 man/man1/strip.1 create mode 100644 man/man1/stty.1 create mode 100644 man/man1/su.1 create mode 100644 man/man1/sum.1 create mode 100644 man/man1/svc.1 create mode 100644 man/man1/synctree.1 create mode 100644 man/man1/sysenv.1 create mode 100644 man/man1/sz.1 create mode 100644 man/man1/tail.1 create mode 100644 man/man1/tar.1 create mode 100644 man/man1/tee.1 create mode 100644 man/man1/telnet.1 create mode 100644 man/man1/template.1 create mode 100644 man/man1/term.1 create mode 100644 man/man1/termcap.1 create mode 100644 man/man1/tget.1 create mode 100644 man/man1/time.1 create mode 100644 man/man1/touch.1 create mode 100644 man/man1/tr.1 create mode 100644 man/man1/true.1 create mode 100644 man/man1/tsort.1 create mode 100644 man/man1/tty.1 create mode 100644 man/man1/umount.1 create mode 100644 man/man1/uname.1 create mode 100644 man/man1/unexpand.1 create mode 100644 man/man1/uniq.1 create mode 100644 man/man1/uud.1 create mode 100644 man/man1/uue.1 create mode 100644 man/man1/vol.1 create mode 100644 man/man1/wc.1 create mode 100644 man/man1/whatis.1 create mode 100644 man/man1/whereis.1 create mode 100644 man/man1/which.1 create mode 100644 man/man1/who.1 create mode 100644 man/man1/whoami.1 create mode 100644 man/man1/write.1 create mode 100644 man/man1/xargs.1 create mode 100644 man/man1/yacc.1 create mode 100644 man/man1/yap.1 create mode 100644 man/man1/yes.1 create mode 100644 man/man2/access.2 create mode 100644 man/man2/alarm.2 create mode 100644 man/man2/brk.2 create mode 100644 man/man2/chdir.2 create mode 100644 man/man2/chmod.2 create mode 100644 man/man2/chown.2 create mode 100644 man/man2/chroot.2 create mode 100644 man/man2/close.2 create mode 100644 man/man2/creat.2 create mode 100644 man/man2/dup.2 create mode 100644 man/man2/execve.2 create mode 100644 man/man2/exit.2 create mode 100644 man/man2/fcntl.2 create mode 100644 man/man2/fork.2 create mode 100644 man/man2/getgid.2 create mode 100644 man/man2/getpid.2 create mode 100644 man/man2/getuid.2 create mode 100644 man/man2/intro.2 create mode 100644 man/man2/ioctl.2 create mode 100644 man/man2/kill.2 create mode 100644 man/man2/link.2 create mode 100644 man/man2/lseek.2 create mode 100644 man/man2/mkdir.2 create mode 100644 man/man2/mknod.2 create mode 100644 man/man2/mount.2 create mode 100644 man/man2/open.2 create mode 100644 man/man2/pause.2 create mode 100644 man/man2/pipe.2 create mode 100644 man/man2/ptrace.2 create mode 100644 man/man2/read.2 create mode 100644 man/man2/reboot.2 create mode 100644 man/man2/rename.2 create mode 100644 man/man2/rmdir.2 create mode 100644 man/man2/setsid.2 create mode 100644 man/man2/setuid.2 create mode 100644 man/man2/sigaction.2 create mode 100644 man/man2/sigpending.2 create mode 100644 man/man2/sigprocmask.2 create mode 100644 man/man2/sigsuspend.2 create mode 100644 man/man2/stat.2 create mode 100644 man/man2/svrctl.2 create mode 100644 man/man2/sync.2 create mode 100644 man/man2/time.2 create mode 100644 man/man2/times.2 create mode 100644 man/man2/umask.2 create mode 100644 man/man2/uname.2 create mode 100644 man/man2/unlink.2 create mode 100644 man/man2/utime.2 create mode 100644 man/man2/wait.2 create mode 100644 man/man2/write.2 create mode 100644 man/man3/abort.3 create mode 100644 man/man3/abs.3 create mode 100644 man/man3/assert.3 create mode 100644 man/man3/atof.3 create mode 100644 man/man3/bstring.3 create mode 100644 man/man3/configfile.3 create mode 100644 man/man3/crypt.3 create mode 100644 man/man3/ctime.3 create mode 100644 man/man3/ctype.3 create mode 100644 man/man3/curses.3 create mode 100644 man/man3/directory.3 create mode 100644 man/man3/editline.3 create mode 100644 man/man3/end.3 create mode 100644 man/man3/execl.3 create mode 100644 man/man3/exit.3 create mode 100644 man/man3/fclose.3 create mode 100644 man/man3/ferror.3 create mode 100644 man/man3/fopen.3 create mode 100644 man/man3/fread.3 create mode 100644 man/man3/fseek.3 create mode 100644 man/man3/g_h_b_n.3 create mode 100644 man/man3/getc.3 create mode 100644 man/man3/getcwd.3 create mode 100644 man/man3/getenv.3 create mode 100644 man/man3/getgrent.3 create mode 100644 man/man3/getlogin.3 create mode 100644 man/man3/getopt.3 create mode 100644 man/man3/getpass.3 create mode 100644 man/man3/getpwent.3 create mode 100644 man/man3/gets.3 create mode 100644 man/man3/getservent.3 create mode 100644 man/man3/getttyent.3 create mode 100644 man/man3/hton.3 create mode 100644 man/man3/int64.3 create mode 100644 man/man3/malloc.3 create mode 100644 man/man3/oneC_sum.3 create mode 100644 man/man3/popen.3 create mode 100644 man/man3/printf.3 create mode 100644 man/man3/putc.3 create mode 100644 man/man3/puts.3 create mode 100644 man/man3/qsort.3 create mode 100644 man/man3/rand.3 create mode 100644 man/man3/random.3 create mode 100644 man/man3/rcmd.3 create mode 100644 man/man3/regex.3 create mode 100644 man/man3/resolver.3 create mode 100644 man/man3/scanf.3 create mode 100644 man/man3/servxcheck.3 create mode 100644 man/man3/setbuf.3 create mode 100644 man/man3/sigset.3 create mode 100644 man/man3/sleep.3 create mode 100644 man/man3/stdarg.3 create mode 100644 man/man3/stdio.3 create mode 100644 man/man3/string.3 create mode 100644 man/man3/system.3 create mode 100644 man/man3/termcap.3 create mode 100644 man/man3/termios.3 create mode 100644 man/man3/ttyname.3 create mode 100644 man/man3/ttyslot.3 create mode 100644 man/man3/ungetc.3 create mode 100644 man/man4/console.4 create mode 100644 man/man4/controller.4 create mode 100644 man/man4/dev.4 create mode 100644 man/man4/fd.4 create mode 100644 man/man4/ip.4 create mode 100644 man/man4/lp.4 create mode 100644 man/man4/mtio.4 create mode 100644 man/man4/tty.4 create mode 100644 man/man5/TZ.5 create mode 100644 man/man5/configfile.5 create mode 100644 man/man5/crontab.5 create mode 100644 man/man5/dhcp.conf.5 create mode 100644 man/man5/dir.5 create mode 100644 man/man5/ethers.5 create mode 100644 man/man5/fstab.5 create mode 100644 man/man5/hosts.5 create mode 100644 man/man5/keymap.5 create mode 100644 man/man5/passwd.5 create mode 100644 man/man5/resolv.conf.5 create mode 100644 man/man5/resolver.5 create mode 100644 man/man5/rhosts.5 create mode 100644 man/man5/serv.access.5 create mode 100644 man/man5/termcap.5 create mode 100644 man/man5/ttytab.5 create mode 100644 man/man5/utmp.5 create mode 100644 man/man5/whatis.5 create mode 100644 man/man6/advent.6 create mode 100644 man/man6/ttt.6 create mode 100644 man/man7/ACK.7 create mode 100644 man/man7/ascii.7 create mode 100644 man/man7/environ.7 create mode 100644 man/man7/hier.7 create mode 100644 man/man7/man.7 create mode 100644 man/man7/re_format.7 create mode 100644 man/man8/MAKEDEV.8 create mode 100644 man/man8/add_route.8 create mode 100644 man/man8/adduser.8 create mode 100644 man/man8/backup.8 create mode 100644 man/man8/badblocks.8 create mode 100644 man/man8/boot.8 create mode 100644 man/man8/checkhier.8 create mode 100644 man/man8/chown.8 create mode 100644 man/man8/cleantmp.8 create mode 100644 man/man8/config.8 create mode 100644 man/man8/cron.8 create mode 100644 man/man8/dhcpd.8 create mode 100644 man/man8/dosminix.8 create mode 100644 man/man8/elvprsv.8 create mode 100644 man/man8/fdisk.8 create mode 100644 man/man8/fingerd.8 create mode 100644 man/man8/ftpd.8 create mode 100644 man/man8/getty.8 create mode 100644 man/man8/halt.8 create mode 100644 man/man8/ifconfig.8 create mode 100644 man/man8/inet.8 create mode 100644 man/man8/init.8 create mode 100644 man/man8/installboot.8 create mode 100644 man/man8/intr.8 create mode 100644 man/man8/irdpd.8 create mode 100644 man/man8/mkdist.8 create mode 100644 man/man8/mknod.8 create mode 100644 man/man8/monitor.8 create mode 100644 man/man8/nonamed.8 create mode 100644 man/man8/part.8 create mode 100644 man/man8/partition.8 create mode 100644 man/man8/pr_routes.8 create mode 100644 man/man8/printroot.8 create mode 100644 man/man8/pwdauth.8 create mode 100644 man/man8/rarpd.8 create mode 100644 man/man8/rdate.8 create mode 100644 man/man8/readclock.8 create mode 100644 man/man8/reboot.8 create mode 100644 man/man8/repartition.8 create mode 100644 man/man8/rlogind.8 create mode 100644 man/man8/rshd.8 create mode 100644 man/man8/screendump.8 create mode 100644 man/man8/serial-ip.8 create mode 100644 man/man8/shutdown.8 create mode 100644 man/man8/slip.8 create mode 100644 man/man8/srccrc.8 create mode 100644 man/man8/sync.8 create mode 100644 man/man8/update.8 create mode 100644 man/man8/usage.8 create mode 100644 man/man9/as.9 create mode 100644 man/man9/awk.9 create mode 100644 man/man9/de.9 create mode 100644 man/man9/dis88.9 create mode 100644 man/man9/elle.9 create mode 100644 man/man9/elvis.9 create mode 100644 man/man9/kermit.9 create mode 100644 man/man9/m4.9 create mode 100644 man/man9/macros.9 create mode 100644 man/man9/mined.9 diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 000000000..81705cbc9 --- /dev/null +++ b/man/Makefile @@ -0,0 +1,16 @@ + +MAN=/usr/man + +all:: + +clean:: + +install:: + -rm -rf $(MAN) + mkdir $(MAN) + tar cf - `find . -name '*.[0-9]'` | (cd $(MAN) && tar xf -) + chown -R bin /usr/man + chgrp -R operator /usr/man + find /usr/man -type f | xargs chmod 644 + find /usr/man -type d | xargs chmod 755 + makewhatis $(MAN) diff --git a/man/man1/M.1 b/man/man1/M.1 new file mode 100644 index 000000000..e529238bb --- /dev/null +++ b/man/man1/M.1 @@ -0,0 +1,35 @@ +.TH M 1 +.SH NAME +M, U \- conveniently mount and unmount +.SH SYNOPSIS +\fBM \fIdevice\fR [\fB\-r\fR]\fR +.br +\fBU \fIdevice\fR\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-r" "Mount read-only" +.SH EXAMPLES +.EX "M root" "Mount the RAM image on /root" +.EX "M 0" "Mount /dev/fd0 on /fd0" +.EX "U fd1" "Unmount /dev/fd1 from /fd1" +.SH DESCRIPTION +.PP +\fIM\fR and \fIU\fR allow easy mounting and unmounting of a device by using +only an abbreviated device name or keyword. Special keywords are +\fBroot\fR, \fBtmp\fR, and \fBusr\fR for the three hard disk partitions +Minix runs in. Floppy devices are mounted on \fB/fd0\fR or \fB/fd1\fR. You +can use \fB0\fR and \fB1\fR instead of \fBfd0\fR and \fBfd1\fP. A device it +doesn't know about is mounted on \fB/mnt\fR. +.SH "SEE ALSO" +.BR mount (1), +.BR umount (1). diff --git a/man/man1/acd.1 b/man/man1/acd.1 new file mode 100644 index 000000000..60f36c938 --- /dev/null +++ b/man/man1/acd.1 @@ -0,0 +1,860 @@ +.TH ACD 1 +.SH NAME +acd \- a compiler driver +.SH SYNOPSIS +.B acd +\fB\-v\fR[\fIn\fR] +\fB\-vn\fR[\fIn\fR] +.BI \-name " name" +.BI \-descr " descr" +.BI \-T " dir" +.RI [ arg " ...]" +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Acd +is a compiler driver, a program that calls the several passes that are needed +to compile a source file. It keeps track of all the temporary files used +between the passes. It also defines the interface of the compiler, the +options the user gets to see. +.PP +This text only describes +.B acd +itself, it says nothing about the different options the C-compiler accepts. +(It has nothing to do with any language, other than being a tool to give +a compiler a user interface.) +.SH OPTIONS +.B Acd +itself takes five options: +.TP +\fB\-v\fR[\fIn\fR] +Sets the diagnostic level to +.I n +(by default +.BR 2 ). +The higher +.I n +is, the more output +.B acd +generates: +.B \-v0 +does not produce any output. +.B \-v1 +prints the basenames of the programs called. +.B \-v2 +prints names and arguments of the programs called. +.B \-v3 +shows the commands executed from the description file too. +.B \-v4 +shows the program read from the description file too. Levels 3 and 4 use +backspace overstrikes that look good when viewing the output with a smart +pager. +.TP +\fB\-vn\fR[\fIn\fR] +Like +.B \-v +except that no command is executed. The driver is just play-acting. +.TP +.BI \-name " name" +.B Acd +is normally linked to the name the compiler is to be called with by the +user. The basename of this, say +.BR cc , +is the call name of the driver. It plays a role in selecting the proper +description file. With the +.B \-name +option one can change this. +.B Acd \-name cc +has the same effect as calling the program as +.BR cc . +.TP +.BI \-descr " descr" +Allows one to choose the pass description file of the driver. By default +.I descr +is the same as +.IR name , +the call name of the program. If +.I descr +doesn't start with +.BR / , +.BR ./ , +or +.BR ../ +then the file +.BI /usr/lib/ descr /descr +will be used for the description, otherwise +.I descr +itself. Thus +.B cc \-descr newcc +calls the C-compiler with a different description file without changing the +call name. Finally, if +.I descr +is \fB"\-"\fP, standard input is read. (The default lib directory +.BR /usr/lib , +may be changed to +.I dir +at compile time by \fB\-DLIB=\e"\fP\fIdir\fP\fB\e"\fP. The default +.I descr +may be set with \fB\-DDESCR=\e"\fP\fIdescr\fP\fB\e"\fP for simple +installations on a system without symlinks.) +.TP +.BI \-T " dir" +Temporary files are made in +.B /tmp +by default, which may be overridden by the environment variable +.BR TMPDIR , +which may be overridden by the +.B \-T +option. +.SH "THE DESCRIPTION FILE" +The description file is a program interpreted by the driver. It has variables, +lists of files, argument parsing commands, and rules for transforming input +files. +.SS Syntax +There are four simple objects: +.PP +.RS +Words, Substitutions, Letters, and Operators. +.RE +.PP +And there are two ways to group objects: +.PP +.RS +Lists, forming sequences of anything but letters, +.SP +Strings, forming sequences of anything but Words and Operators. +.RE +.PP +Each object has the following syntax: +.IP Words +They are sequences of characters, like +.BR cc , +.BR \-I/usr/include , +.BR /lib/cpp . +No whitespace and no special characters. The backslash character +.RB ( \e ) +may be used to make special characters common, except whitespace. A backslash +followed by whitespace is completely removed from the input. The sequence +.B \en +is changed to a newline. +.IP Substitutions +A substitution (henceforth called 'subst') is formed with a +.BR $ , +e.g. +.BR $opt , +.BR $PATH , +.BR ${lib} , +.BR $\(** . +The variable name after the +.B $ +is made of letters, digits and underscores, or any sequence of characters +between parentheses or braces, or a single other character. A subst indicates +that the value of the named variable must be substituted in the list or string +when fully evaluated. +.IP Letters +Letters are the single characters that would make up a word. +.IP Operators +The characters +.BR = , +.BR + , +.BR \- , +.BR \(** , +.BR < , +and +.B > +are the operators. The first four must be surrounded by whitespace if they +are to be seen as special (they are often used in arguments). The last two +are always special. +.IP Lists +One line of objects in the description file forms a list. Put parentheses +around it and you have a sublist. The values of variables are lists. +.IP Strings +Anything that is not yet a word is a string. All it needs is that the substs +in it are evaluated, e.g. +.BR $LIBPATH/lib$key.a . +A single subst doesn't make a string, it expands to a list. You need at +least one letter or other subst next to it. Strings (and words) may also +be formed by enclosing them in double quotes. Only +.B \e +and +.B $ +keep their special meaning within quotes. +.SS Evaluation +One thing has to be carefully understood: Substitutions are delayed until +the last possible moment, and description files make heavy use of this. +Only if a subst is tainted, either because its variable is declared local, or +because a subst in its variable's value is tainted, is it immediately +substituted. So if a list is assigned to a variable then this list is only +checked for tainted substs. Those substs are replaced by the value +of their variable. This is called partial evaluation. +.PP +Full evaluation expands all substs, the list is flattened, i.e. all +parentheses are removed from sublists. +.PP +Implosive evaluation is the last that has to be done to a list before it +can be used as a command to execute. The substs within a string have been +evaluated to lists after full expansion, but a string must be turned into +a single word, not a list. To make this happen, a string is first exploded +to all possible combinations of words choosing one member of the lists within +the string. These words are tried one by one to see if they exist as a +file. The first one that exists is taken, if none exists than the first +choice is used. As an example, assume +.B LIBPATH +equals +.BR "(/lib /usr/lib)" , +.B key +is +.B (c) +and +.B key +happens to be local. Then we have: +.PP +.RS +\fB"$LIBPATH/lib$key.a"\fP +.RE +.PP +before evaluation, +.PP +.RS +\fB"$LIBPATH/lib(c).a"\fP +.RE +.PP +after partial evaluation, +.PP +.RS +\fB"(/lib/libc.a /usr/lib/libc.a)"\fP +.RE +.PP +after full evaluation, and finally +.PP +.RS +.B /usr/lib/libc.a +.RE +.PP +after implosion, if the file exists. +.SS Operators +The operators modify the way evaluation is done and perform a special +function on a list: +.TP +.B \(** +Forces full evaluation on all the list elements following it. Use it to +force substitution of the current value of a variable. This is the only +operator that forces immediate evaluation. +.TP +.B + +When a +.B + +exists in a list that is fully evaluated, then all the elements before the +.B + +are imploded and all elements after the +.B + +are imploded and added to the list if they are not already in the list. So +this operator can be used either for set addition, or to force implosive +expansion within a sublist. +.TP +.B \- +Like +.BR + , +except that elements after the +.B \- +are removed from the list. +.PP +The set operators can be used to gather options that exclude each other +or for their side effect of implosive expansion. You may want to write: +.PP +.RS +\fBcpp \-I$LIBPATH/include\fP +.RE +.PP +to call cpp with an extra include directory, but +.B $LIBPATH +is expanded using a filename starting with +.B \-I +so this won't work. Given that any problem in Computer Science can be solved +with an extra level of indirection, use this instead: +.PP +.RS +.ft B +cpp \-I$INCLUDE +.br +INCLUDE = $LIBPATH/include + +.ft P +.RE +.SS "Special Variables" +There are three special variables used in a description file: +.BR $\(** , +.BR $< , +and +.BR $> . +These variables are always local and mostly read-only. They will be +explained later. +.SS "A Program" +The lists in a description file form a program that is executed from the +first to the last list. The first word in a list may be recognized as a +builtin command (only if the first list element is indeed simply a word.) +If it is not a builtin command then the list is imploded and used as a +\s-2UNIX\s+2 command with arguments. +.PP +Indentation (by tabs or spaces) is not just makeup for a program, but are +used to group lines together. Some builtin commands need a body. These +bodies are simply lines at a deeper indentation. +.PP +Empty lines are not ignored either, they have the same indentation level as +the line before it. Comments (starting with a +.B # +and ending at end of line) have an indentation of their own and can be used +as null commands. +.PP +.B Acd +will complain about unexpected indentation shifts and empty bodies. Commands +can share the same body by placing them at the same indentation level before +the indented body. They are then "guards" to the same body, and are tried +one by one until one succeeds, after which the body is executed. +.PP +Semicolons may be used to separate commands instead of newlines. The commands +are then all at the indentation level of the first. +.SS "Execution phases" +The driver runs in three phases: Initialization, Argument scanning, and +Compilation. Not all commands work in all phases. This is further explained +below. +.SS "The Commands" +The commands accept arguments that are usually generic expressions that +implode to a word or a list of words. When +.I var +is specified, then a single word or subst needs to be given, so +an assignment can be either +.I name +.B = +.IR value , +or +.BI $ name +.B = +.IR value . +.TP +.IB "var " = " expr ..." +The partially evaluated list of expressions is assigned to +.IR var . +During the evaluation is +.I var +marked as local, and after the assignment set from undefined to defined. +.TP +.BI unset " var" +.I Var +is set to null and is marked as undefined. +.TP +.BI import " var" +If +.I var +is defined in the environment of +.B acd +then it is assigned to +.IR var . +The environment variable is split into words at whitespace and colons. Empty +space between two colons +.RB ( :: ) +is changed to a dot. +.TP +.BI mktemp " var " [ suffix ] +Assigns to +.I var +the name of a new temporary file, usually something like /tmp/acd12345x. If +.I suffix +is present then it will be added to the temporary file's name. (Use it +because some programs require it, or just because it looks good.) +.B Acd +remembers this file, and will delete it as soon as you stop referencing it. +.TP +.BI temporary " word" +Mark the file named by +.I word +as a temporary file. You have to make sure that the name is stored in some +list in imploded form, and not just temporarily created when +.I word +is evaluated, because then it will be immediately removed and forgotten. +.TP +.BI stop " suffix" +Sets the target suffix for the compilation phase. Something like +.B stop .o +means that the source files must be compiled to object files. At least one +.B stop +command must be executed before the compilation phase begins. It may not be +changed during the compilation phase. (Note: There is no restriction on +.IR suffix , +it need not start with a dot.) +.TP +.BI treat " file suffix" +Marks the file as having the given suffix for the compile phase. Useful +for sending a +.B \-l +option directly to the loader by treating it as having the +.B .a +suffix. +.TP +.BI numeric " arg" +Checks if +.I arg +is a number. If not then +.B acd +will exit with a nice error message. +.TP +.BI error " expr ..." +Makes the driver print the error message +.I "expr ..." +and exit. +.TP +.BI if " expr " = " expr" +.B If +tests if the two expressions are equal using set comparison, i.e. each +expression should contain all the words in the other expression. If the +test succeeds then the if-body is executed. +.TP +.BI ifdef " var" +Executes the ifdef-body if +.I var +is defined. +.TP +.BI ifndef " var" +Executes the ifndef-body if +.I var +is undefined. +.TP +.BI iftemp " arg" +Executes the iftemp-body if +.I arg +is a temporary file. Use it when a command has the same file as input and +output and you don't want to clobber the source file: +.SP +.RS +.nf +.ft B +transform .o .o + iftemp $\(** + $> = $\(** + else + cp $\(** $> + optimize $> +.ft P +.fi +.RE +.TP +.BI ifhash " arg" +Executes the ifhash-body if +.I arg +is an existing file with a '\fB#\fP' as the very first character. This +usually indicates that the file must be pre-processed: +.SP +.RS +.nf +.ft B +transform .s .o + ifhash $\(** + mktemp ASM .s + $CPP $\(** > $ASM + else + ASM = $\(** + $AS \-o $> $ASM + unset ASM +.ft P +.fi +.RE +.TP +.B else +Executes the else-body if the last executed +.BR if , +.BR ifdef , +.BR ifndef , +.BR iftemp , +or +.B ifhash +was unsuccessful. Note that +.B else +need not immediately follow an if, but you are advised not to make use of +this. It is a "feature" that may not last. +.TP +.BI apply " suffix1 suffix2" +Executed inside a transform rule body to transform the input file according +to another transform rule that has the given input and output suffixes. The +file under +.B $\(** +will be replaced by the new file. So if there is a +.B .c .i +preprocessor rule then the example of +.B ifhash +can be replaced by: +.SP +.RS +.nf +.ft B +transform .s .o + ifhash $\(** + apply .c .i + $AS \-o $> $* +.ft P +.fi +.RE +.TP +.BI include " descr" +Reads another description file and replaces the +.B include +with it. Execution continues with the first list in the new program. The +search for +.I descr +is the same as used for the +.B \-descr +option. Use +.B include +to switch in different front ends or back ends, or to call a shared +description file with a different initialization. Note that +.I descr +is only evaluated the first time the +.B include +is called. After that the +.B include +has been replaced with the included program, so changing its argument won't +get you a different file. +.TP +.BI arg " string ..." +.B Arg +may be executed in the initialization and scanning phase to post an argument +scanning rule, that's all the command itself does. Like an +.B if +that fails it allows more guards to share the same body. +.TP +.BI transform " suffix1 suffix2" +.BR Transform , +like +.BR arg , +only posts a rule to transform a file with the suffix +.I suffix1 +into a file with the suffix +.IR suffix2 . +.TP +.BI prefer " suffix1 suffix2" +Tells that the transformation rule from +.I suffix1 +to +.I suffix2 +is to be preferred when looking for a transformation path to the stop suffix. +Normally the shortest route to the stop suffix is used. +.B Prefer +is ignored on a +.BR combine , +because the special nature of combines does not allow ambiguity. +.SP +The two suffixes on a +.B transform +or +.B prefer +may be the same, giving a rule that is only executed when preferred. +.TP +.BI combine " suffix-list suffix" +.B Combine +is like +.B transform +except that it allows a list of input suffixes to match several types of +input files that must be combined into one. +.TP +.B scan +The scanning phase may be run early from the initialization phase with the +.B scan +command. Use it if you need to make choices based on the arguments before +posting the transformation rules. After running this, +.B scan +and +.B arg +become no-ops. +.TP +.B compile +Move on to the compilation phase early, so that you have a chance to run +a few extra commands before exiting. This command implies a +.BR scan . +.PP +Any other command is seen as a \s-2UNIX\s+2 command. This is where the +.B < +and +.B > +operators come into play. They redirect standard input and standard output +to the file mentioned after them, just like the shell. +.B Acd +will stop with an error if the command is not successful. +.SS The Initialization Phase +The driver starts by executing the program once from top to bottom to +initialize variables and post argument scanning and transformation rules. +.SS The Scanning Phase +In this phase the driver makes a pass over the command line arguments to +process options. Each +.B arg +rule is tried one by one in the order they were posted against the front of +the argument list. If a match is made then the matched arguments are removed +from the argument list and the arg-body is executed. If no match can be made +then the first argument is moved to the list of files waiting to be +transformed and the scan is restarted. +.PP +The match is done as follows: Each of the strings after +.B arg +must match one argument at the front of the argument list. A character +in a string must match a character in an argument word, a subst in a string +may match 1 to all remaining characters in the argument, preferring the +shortest possible match. The hyphen in a argument starting with a hyphen +cannot be matched by a subst. Therefore: +.PP +.RS +.B arg \-i +.RE +.PP +matches only the argument +.BR \-i . +.PP +.RS +.B arg \-O$n +.RE +.PP +matches any argument that starts with +.B \-O +and is at least three characters long. Lastly, +.PP +.RS +.B arg \-o $out +.RE +.PP +matches +.B \-o +and the argument following it, unless that argument starts with a hyphen. +.PP +The variable +.B $\(** +is set to all the matched arguments before the arg-body is executed. All +the substs in the arg strings are set to the characters they match. The +variable +.B $> +is set to null. All the values of the variables are saved and the variables +marked local. All variables except +.B $> +are marked read-only. After the arg-body is executed is the value of +.B $> +concatenated to the file list. This allows one to stuff new files into the +transformation phase. These added names are not evaluated until the start +of the next phase. +.SS The Compilation Phase +The files gathered in the file list in the scanning phase are now transformed +one by one using the transformation rules. The shortest, or preferred route +is computed for each file all the way to the stop suffix. Each file is +transformed until it lands at the stop suffix, or at a combine rule. After +a while all files are either fully transformed or at a combine rule. +.PP +The driver chooses a combine rule that is not on a path from another combine +rule and executes it. The file that results is then transformed until it +again lands at a combine rule or the stop suffix. This continues until all +files are at the stop suffix and the program exits. +.PP +The paths through transform rules may be ambiguous and have cycles, they will +be resolved. But paths through combines must be unambiguous, because of +the many paths from the different files that meet there. A description file +will usually have only one combine rule for the loader. However if you do +have a combine conflict then put a no-op transform rule in front of one to +resolve the problem. +.PP +If a file matches a long and a short suffix then the long suffix is preferred. +By putting a null input suffix (\fB""\fP) in a rule one can match any file +that no other rule matches. You can send unknown files to the loader this +way. +.PP +The variable +.B $\(** +is set to the file to be transformed or the files to be combined before the +transform or combine-body is executed. +.B $> +is set to the output file name, it may again be modified. +.B $< +is set to the original name of the first file of +.B $\(** +with the leading directories and the suffix removed. +.B $\(** +will be made up of temporary files after the first rule. +.B $> +will be another temporary file or the name of the target file +.RB ( $< +plus the stop suffix), if the stop suffix is reached. +.PP +.B $> +is passed to the next rule; it is imploded and checked to be a single word. +This driver does not store intermediate object files in the current directory +like most other compilers, but keeps them in +.B /tmp +too. (Who knows if the current directory can have files created in?) As an +example, here is how you can express the "normal" method: +.PP +.RS +.nf +.ft B +transform .s .o + if $> = $<.o + # Stop suffix is .o + else + $> = $<.o + temporary $> + $AS \-o $> $\(** +.ft P +.fi +.RE +.PP +Note that +.B temporary +is not called if the target is already the object file, or you would lose +the intended result! +.B $> +is known to be a word, because +.B $< +is local. (Any string whose substs are all expanded changes to a word.) +.SS "Predefined Variables" +The driver has three variables predefined: +.BR PROGRAM , +set to the call name of the driver, +.BR VERSION , +the driver's version number, and +.BR ARCH , +set to the name of the default output architecture. The latter is optional, +and only defined if +.B acd +was compiled with \fB\-DARCH=\e"\fP\fIarch-name\fP\fB\e"\fP. +.SH EXAMPLE +As an example a description file for a C compiler is given. It has a +front end (ccom), an intermediate code optimizer (opt), a code generator (cg), +an assembler (as), and a loader (ld). The compiler can pre-process, but +there is also a separate cpp. If the +.B \-D +and options like it are changed to look like +.B \-o +then this example is even as required by \s-2POSIX\s+2. +.RS +.nf + +# The compiler support search path. +C = /lib /usr/lib /usr/local/lib + +# Compiler passes. +CPP = $C/cpp $CPP_F +CCOM = $C/ccom $CPP_F +OPT = $C/opt +CG = $C/cg +AS = $C/as +LD = $C/ld + +# Predefined symbols. +CPP_F = \-D__EXAMPLE_CC__ + +# Library path. +LIBPATH = $USERLIBPATH $C + +# Default transformation target. +stop .out + +# Preprocessor directives. +arg \-D$name +arg \-U$name +arg \-I$dir + CPP_F = $CPP_F $\(** + +# Stop suffix. +arg \-c + stop .o + +arg \-E + stop .E + +# Optimization. +arg \-O + prefer .m .m + OPT = $OPT -O1 + +arg \-O$n + numeric $n + prefer .m .m + OPT = $OPT $\(** + +# Add debug info to the executable. +arg \-g + CCOM = $CCOM -g + +# Add directories to the library path. +arg \-L$dir + USERLIBPATH = $USERLIBPATH $dir + +# \-llib must be searched in $LIBPATH later. +arg \-l$lib + $> = $LIBPATH/lib$lib.a + +# Change output file. +arg \-o$out +arg \-o $out + OUT = $out + +# Complain about a missing argument. +arg \-o + error "argument expected after '$\(**'" + +# Any other option (like \-s) are for the loader. +arg \-$any + LD = $LD $\(** + +# Preprocess C-source. +transform .c .i + $CPP $\(** > $> + +# Preprocess C-source and send it to standard output or $OUT. +transform .c .E + ifndef OUT + $CPP $\(** + else + $CPP $\(** > $OUT + +# Compile C-source to intermediate code. +transform .c .m +transform .i .m + $CCOM $\(** $> + +# Intermediate code optimizer. +transform .m .m + $OPT $\(** > $> + +# Intermediate to assembly. +transform .m .s + $CG $\(** > $> + +# Assembler to object code. +transform .s .o + if $> = $<.o + ifdef OUT + $> = $OUT + $AS \-o $> $\(** + +# Combine object files and libraries to an executable. +combine (.o .a) .out + ifndef OUT + OUT = a.out + $LD \-o $OUT $C/crtso.o $\(** $C/libc.a +.fi +.RE +.SH FILES +.TP 25n +.RI /usr/lib/ descr /descr +\- compiler driver description file. +.SH "SEE ALSO" +.BR cc (1). +.SH ACKNOWLEDGEMENTS +Even though the end result doesn't look much like it, many ideas were +nevertheless derived from the ACK compiler driver by Ed Keizer. +.SH BUGS +\s-2POSIX\s+2 requires that if compiling one source file to an object file +fails then the compiler should continue with the next source file. There is +no way +.B acd +can do this, it always stops after error. It doesn't even know what an +object file is! (The requirement is stupid anyhow.) +.PP +If you don't think that tabs are 8 spaces wide, then don't mix them with +spaces for indentation. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/anm.1 b/man/man1/anm.1 new file mode 100644 index 000000000..f84d2e527 --- /dev/null +++ b/man/man1/anm.1 @@ -0,0 +1,63 @@ +.TH ANM 1 +.SH NAME +anm \- print name list +.SH SYNOPSIS +\fBanm \fR[\fB\-gnoprus\fR] \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-g" "Global symbols only" +.FL "\-n" "Sort numerically" +.FL "\-o" "Prepend the filename to each line" +.FL "\-p" "No sorting\(emuse symbol table order" +.FL "\-r" "Sort in reverse order" +.FL "\-u" "List undefined symbols only" +.FL "\-s" "Sort in section order" +.SH EXAMPLES +.EX "anm \-gn test.o" "Print global symbols in numerical order" +.SH DESCRIPTION +.PP +.I Anm +prints the name list (symbol table) of each ACK format object +.I file +in the argument list. +If no file name is given, \fIa.out\fR is used. +Each symbol name is preceded by its value, a section indicator +and a type indicator. +The section indicators are: +.PP +.ta 0.25i 0.50i +.nf + \fBU\fR Undefined symbol + \fBA\fR Absolute symbol + \fB\-\fR Other symbol +.sp +The type indicators are: +.PP + \fBF\fR Filename + \fBM\fR Module name + \fBS\fR Section name + \fBE\fR External (global) symbol + \fB\-\fR Local symbol +.fi +.PP +The output is sorted alphabetically, unless otherwise specified. +Notice that \fIanm\fR can only be used on ACK format object files +(that is: \fI.o\fR and \fI.out\fR files). +If you want to get the name list of an executable program use +.I nm +instead. +.SH "SEE ALSO" +.BR asize (1), +.BR nm (1), +.BR ar (1), +.BR size (1). diff --git a/man/man1/ar.1 b/man/man1/ar.1 new file mode 100644 index 000000000..4ec53188c --- /dev/null +++ b/man/man1/ar.1 @@ -0,0 +1,56 @@ +.TH AR 1 +.SH NAME +ar, aal \- archivers +.SH SYNOPSIS +\fBar\fR [\fBdmpqrtx\fR][\fBabciluv\fR]\fR [\fIposname\fR] \fIarchive\fR [\fIfile \fR...]\fR +.br +\fBaal\fR [\fBdpqrtx\fR][\fBclv\fR]\fR \fIarchive\fR [\fIfile \fR...]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "ar r libc.a sort.s" "Replace \fIsort\fR.s in \fIlibc.a\fR" +.EX "ar rb a.s libc.a b.s" "Insert \fIb.s\fR before \fIa.s\fR in \fIlibc.a\fR" +.SH DESCRIPTION +.PP +\fIAr\fR allows groups of files to be put together into a single archive. +It is normally used for libraries of compiled procedures. \fIAal\fR is like +\fIar\fP, but is to be used with the ACK compiler. The following keys +are allowed: +.PP +.ta 0.25i 0.50i +.nf + \fBd\fR: Delete. \fIAr\fR will delete the named members. + \fBm\fR: Move named files. \fIAr\fR expects \fIa\fR, \fIb\fR, or \fIi\fR to be specified. + \fBp\fR: Print the named files (list them on \fIstdout\fR) + \fBq\fR: Quickly append to the end of the archive file. + \fBr\fR: Replace (append when not in archive). + \fBt\fR: Print the archive's table of contents. + \fBx\fR: Extract +.fi +.PP +\fBThe keys may optionally concatencated with one or more of the following\fR: +.nf +.PP + \fBa\fR: After \fIposname\fR + \fBb\fR: Before \fIposname\fR + \fBc\fR: Create (suppresses creation message) + \fBi\fR: Before \fIposname\fR + \fBl\fR: Local temporary file for work instead of \fI/tmp/ar.$$$$$\fR + \fBu\fR: Replace only if dated later than member in archive + \fBv\fR: Verbose +.PP +.fi +.SH "SEE ALSO" +.BR anm (1), +.BR asize (1), +.BR nm (1), +.BR size (1). diff --git a/man/man1/ash.1 b/man/man1/ash.1 new file mode 100644 index 000000000..7c5009f14 --- /dev/null +++ b/man/man1/ash.1 @@ -0,0 +1,1123 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Kenneth Almquist. +.\" +.\" 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. +.\" +.\" @(#)sh.1 5.1 (Berkeley) 3/7/91 +.\" +.TH SH 1 "March 7, 1991" +.UC 7 +.de h \" subheading +.sp +.ti -0.3i +.B "\\$1" +.PP +.. +.de d \" begin display +.sp +.in +4 +.nf +.. +.de e \" end display +.in -4 +.fi +.sp +.. +.de c \" command, etc. +.br +.HP 3 +\fB\\$1\fR +.br +.. +.de b \" begin builtin command +.HP 3 +.B \\$1 +.. +.SH NAME +ash, sh, ., break, case, cd, command, continue, eval, exec, exit, export, for, getopts, hash, if, jobs, local, read, readonly, return, set, setvar, shift, trap, umask, unset, wait, while \- a shell +.SH SYNOPSIS +.B ash +[ +.B -efIijnsxz +] [ +.B +efIijnsxz +] [ +.B -c +.I command +] [ +.I arg +] ... +.SH COPYRIGHT +Copyright 1989 by Kenneth Almquist. +.SH DESCRIPTION +.I Ash +is a version of +.I sh +with features similar to those of the System V shell. +This manual page lists all the features of +.I ash +but concentrates on the ones not in other shells. +.h "Invocation" +If the +.B -c +options is given, then the shell executes the specified shell command. +The +.B -s +flag cause the shell to read commands from the standard input (after +executing any command specified with the +.B -c +option. +If neither the +.B -s +or +.B -c +options are set, then the first +.I arg +is taken as the name of a file to read commands from. +If this is impossible because there are no arguments following +the options, then +.I ash +will set the +.B -s +flag and will read commands from the standard input. +.PP +The shell sets the initial value of the positional parameters from the +.IR arg s +remaining after any +.I arg +used as the name of a file of commands is deleted. +.PP +The flags (other than +.BR -c ) +are set by preceding them with ``-'' and cleared by preceding them +with ``+''; see the +.I set +builtin command for a list of flags. +If no value is specified for the +.B -i +flag, the +.B -s +flag is set, and the standard input and output of the shell +are connected to terminals, then the +.B -i +flag will be set. +If no value is specified for the +.B -j +flag, then the +.B -j +flag will be set if the +.B -i +flag is set. +.PP +When the shell is invoked with the +.B -c +option, it is good practice to include the +.I -i +flag if the command was entered interactively by a user. +For compatibility with the System V shell, the +.I -i +option should come after the +.B -c +option. +.PP +If the first character of argument zero to the shell is ``-'', +the shell is assumed to be a login shell, and the files +.B /etc/profile +and +.B .profile +are read if they exist. +If the environment variable SHINIT is set on entry to the shell, +the commands in SHINIT are normally parsed and executed. SHINIT is +not examined if the shell is a login shell, or if it the shell is running a +shell procedure. (A shell is considered to be running a shell +procedure if neither the +.B -s +nor the +.B -c +options are set.) +.h "Control Structures" +A +.I list +is a sequence of zero or more commands separated by newlines, +semicolons, or ampersands, and optionally terminated by one of these +three characters. (This differs from the System V shell, which +requires a list to contain at least one command in most cases.) The +commands in a list are executed in the order they are written. +If command is followed by an ampersand, the shell starts the command +and immediately proceed onto the next command; otherwise it waits +for the command to terminate before proceeding to the next one. +.PP +``&&'' and ``||'' are binary operators. +``&&'' executes the first command, and then executes the second command +iff the exit status of the first command is zero. ``||'' is similar, +but executes the second command iff the exit status of the first command +is nonzero. ``&&'' and ``||'' both have the same priority. +.PP +The ``|'' operator is a binary operator which feeds the standard output +of the first command into the standard input of the second command. +The exit status of the ``|'' operator is the exit status of the second +command. ``|'' has a higher priority than ``||'' or ``&&''. +.PP +An +.I if +command looks like +.d +\fBif\fR list +\fBthen\fR list +.ti -\w'[ 'u +[ \fBelif\fR list + \fBthen\fR list ] ... +.ti -\w'[ 'u +[ \fBelse\fR list ] +\fBfi\fR +.e +.PP +A +.I while +command looks like +.d +\fBwhile\fR list +\fBdo\fR list +\fBdone\fR +.e +The two lists are executed repeatedly while the exit status of the first +list is zero. The +.I until +command is similar, but has the word +.B until +in place of +.B while + repeats until the exit status of the first list +is zero. +.PP +The +.I for +command looks like +.d +\fBfor\fR variable \fBin\fR word... +\fBdo\fR list +\fBdone\fR +.e +The words are expanded, and then the list is executed repeatedly with +the variable set to each word in turn. +.B do +and +.B done +may be replaced with +``{'' and ``}''. +.PP +The +.I break +and +.I continue +commands look like +.d +\fBbreak\fR [ num ] +\fBcontinue\fR [ num ] +.e +.I Break +terminates the +.I num +innermost +.I for +or +.I while +loops. +.I Continue +continues with the next iteration of the +.IRnum'th +innermost loop. +These are implemented as builtin commands. +.PP +The +.I case +command looks like +.d +\fBcase\fR word \fBin\fR +pattern\fB)\fR list \fB;;\fR +\&... +\fBesac\fR +.e +The pattern can actually be one or more patterns (see +.I Patterns +below), separated by ``|'' characters. +.PP +Commands may be grouped by writing either +.d +\fB(\fRlist\fB)\fR +.e +or +.d +\fB{\fR list; \fB}\fR +.e +The first of these executes the commands in a subshell. +.PP +A function definition looks like +.d +name \fB( )\fR command +.e +A function definition is an executable statement; when executed it installs +a function named +.B name +and returns an exit status of zero. +The command is normally a list enclosed between ``{'' and ``}''. +.PP +Variables may be declared to be local to a function by using a +.I local +command. This should appear as the first staement of a function, +and looks like +.d +\fBlocal\fR [ variable | \fB-\fR ] ... +.e +.I Local +is implemented as a builtin command. +.PP +When a variable is made local, it inherits the initial value and +exported and readonly flags from the variable with the same name in the +surrounding scope, if there is one. Otherwise, the variable is +initially unset. +.I Ash +uses dynamic scoping, so that if you make the variable +.B x +local to function +.IR f , +which then calls function +.IR g , +references to the variable +.B x +made inside +.I g +will refer to the variable +.B x +declared inside +.IR f , +not to the global variable named +.BR x . +.PP +The only special parameter than can be made local is ``\fB-\fR''. +Making ``\fB-\fR'' local any shell options that are changed via the +.I set +command inside the function to be restored to their original values +when the function returns. +.PP +The +.I return +command looks like +.d +\fBreturn\fR [ exitstatus ] +.e +It terminates the currently executing function. +.I Return +is implemented as a builtin command. +.h "Simple Commands" +A simple command is a sequence of words. The execution of a simple +command proceeds as follows. First, the leading words of the form +``name=value'' are stripped off and assigned to the environment of +the command. Second, the words are expanded. Third, the first +remaining word is taken as the command name that command is located. +Fourth, any redirections are performed. Fifth, the command is +executed. We look at these operations in reverse order. +.PP +The execution of the command varies with the type of command. +There are three types of commands: shell functions, builtin commands, +and normal programs. +.PP +When a shell function is executed, all of the shell positional parameters +(except $0, which remains unchanged) are set to the parameters to the shell +function. The variables which are explicitly placed in the environment +of the command (by placing assignments to them before the function name) +are made local to the function and are set to values given. +Then the command given in the function definition is executed. +The positional parameters are restored to their original values when +the command completes. +.PP +Shell builtins are executed internally to the shell, without spawning +a new process. +.PP +When a normal program is executed, the shell runs the program, passing +the parameters and the environment to the program. If the program is +a shell procedure, the shell will interpret the program in a subshell. +The shell will reinitialize itself in this case, so that the effect +will be as if a new shell had been invoked to handle the shell procedure, +except that the location of commands located in the parent shell will +be remembered by the child. If the program is a file beginning with +``#!'', the remainder of the first line specifies an interpreter for +the program. The shell (or the operating system, under Berkeley UNIX) +will run the interpreter in this case. The arguments to the interpreter +will consist of any arguments given on the first line of the program, +followed by the name of the program, followed by the arguments passed +to the program. +.h "Redirection" +Input/output redirections can be intermixed with the words in a simple +command and can be placed following any of the other commands. When +redirection occurs, the shell saves the old values of the file descriptors +and restores them when the command completes. The ``<'', ``>'', and ``>>'' +redirections open a file for input, output, and appending, respectively. +The ``<&digit'' and ``>&digit'' makes the input or output a duplicate +of the file descriptor numbered by the digit. If a minus sign is used +in place of a digit, the standard input or standard output are closed. +.PP +The ``<<\ word'' redirection +takes input from a +.I here +document. +As the shell encounters ``<<'' redirections, it collects them. The +next time it encounters an unescaped newline, it reads the documents +in turn. The word following the ``<<'' specifies the contents of the +line that terminates the document. If none of the quoting methods +('', "", or \e) are used to enter the word, then the document is treated +like a word inside double quotes: ``$'' and backquote are expanded +and backslash can be used to escape these and to continue long lines. +The word cannot contain any variable or command substitutions, and +its length (after quoting) must be in the range of 1 to 79 characters. +If ``<<-'' is used in place of ``<<'', then leading tabs are deleted +from the lines of the document. (This is to allow you do indent shell +procedures containing here documents in a natural fashion.) +.PP +Any of the preceding redirection operators may be preceded by a single +digit specifying the file descriptor to be redirected. There cannot +be any white space between the digit and the redirection operator. +.h "Path Search" +When locating a command, the shell first looks to see if it has a +shell function by that name. Then, if PATH does not contain an +entry for "%builtin", it looks for a builtin command by that name. +Finally, it searches each entry in PATH in turn for the command. +.PP +The value of the PATH variable should be a series of entries separated +by colons. +Each entry consists of a directory name, or a directory name followed +by a flag beginning with a percent sign. +The current directory should be indicated by an empty directory name. +.PP +If no percent sign is present, then the entry causes the shell to +search for the command in the specified directory. If the flag is +``%builtin'' then the list of shell builtin commands is searched. +If the flag is ``%func'' then the directory is searched for a file which +is read as input to the shell. This file should define a function +whose name is the name of the command being searched for. +.PP +Command names containing a slash are simply executed without performing +any of the above searches. +.h "The Environment" +The environment of a command is a set of name/value pairs. When the +shell is invoked, it reads these names and values, sets the shell +variables with these names to the corresponding values, and marks +the variables as exported. The +.I export +command can be used to mark additional variables as exported. +.PP +The environment of a command is constructed by constructing name/value +pairs from all the exported shell variables, and then modifying this +set by the assignments which precede the command, if any. +.h "Expansion" +The process of evaluating words when a shell procedure is executed is +called +.IR expansion . +Expansion consists of four steps: variable substitution, command +substitution, word splitting, and file name generation. If a word +is the expression following the word +.B case +in a case statement, the file name +which follows a redirection symbol, or an assignment to the environment +of a command, then the word cannot be split into multiple words. In +these cases, the last two steps of the expansion process are omitted. +.h "Variable Substitution" +To be written. +.h "Command Substitution" +.I Ash +accepts two syntaxes for command substitution: +.d +`\fIlist\fR` +.e +and +.d +$(\fIlist\fR) +.e +Either of these may be included in a word. +During the command substitution process, the command (syntactly a +.IR list ) +will be executed and anything that the command writes to the standard +output will be captured by the shell. The final newline (if any) of +the output will be deleted; the rest of the output will be substituted +for the command in the word. +.h "Word Splitting" +When the value of a variable or the output of a command is substituted, +the resulting text is subject to word splitting, unless the dollar sign +introducing the variable or backquotes containing the text were enclosed +in double quotes. In addition, ``$@'' is subject to a special type of +splitting, even in the presence of double quotes. +.PP +Ash uses two different splitting algorithms. The normal approach, which +is intended for splitting text separated by which space, is used if the +first character of the shell variable IFS is a space. Otherwise an alternative +experimental algorithm, which is useful for splitting (possibly empty) +fields separated by a separator character, is used. +.PP +When performing splitting, the shell scans the replacement text looking +for a character (when IFS does not begin with a space) or a sequence of +characters (when IFS does begin with a space), deletes the character or +sequence of characters, and spits the word into two strings at that +point. When IFS begins with a space, the shell deletes either of the +strings if they are null. As a special case, if the word containing +the replacement text is the null string, the word is deleted. +.PP +The variable ``$@'' is special in two ways. First, splitting takes +place between the positional parameters, even if the text is enclosed +in double quotes. Second, if the word containing the replacement +text is the null string and there are no positional parameters, then +the word is deleted. The result of these rules is that "$@" is +equivalent to "$1" "$2" ... "$\fIn\fR", where \fIn\fR is the number of +positional parameters. (Note that this differs from the System V shell. +The System V documentation claims that "$@" behaves this way; in fact +on the System V shell "$@" is equivalent to "" when there are no +positional paramteters.) +.h "File Name Generation" +Unless the +.B -f +flag is set, file name generation is performed after word splitting is +complete. Each word is viewed as a series of patterns, separated by +slashes. The process of expansion replaces the word with the names of +all existing files whose names can be formed by replacing each pattern +with a string that matches the specified pattern. There are two +restrictions on this: first, a pattern cannot match a string containing +a slash, and second, a pattern cannot match a string starting with a +period unless the first character of the pattern is a period. +.PP +If a word fails to match any files and the +.B -z +flag is not set, then the word will be left unchanged (except that the +meta-characters will be converted to normal characters). If the +.B -z +flag is set, then the word is only left unchanged if none +of the patterns contain a character that can match anything besides +itself. Otherwise the +.B -z +flag forces the word to be replaced with the names of the files that it +matches, even if there are zero names. +.h "Patterns" +A +.I pattern +consists of normal characters, which match themselves, and meta-characters. +The meta-characters are ``!'', ``*'', ``?'', and ``[''. These characters lose +there special meanings if they are quoted. When command or variable +substitution is performed and the dollar sign or back quotes are not +double quoted, the value of the variable or the output of the command +is scanned for these characters and they are turned into meta-characters. +.PP +Two exclamation points at the beginning of a pattern function as a ``not'' +operator, causing the pattern to match any string that the remainder of +the pattern does +.I not +match. Other occurances of exclamation points in a pattern match +exclamation points. Two exclamation points are required rather than one +to decrease the incompatibility with the System V shell (which does not +treat exclamation points specially). +.PP +An asterisk (``*'') matches any string of characters. +A question mark matches any single character. +A left bracket (``['') introduces a character class. The end of the +character class is indicated by a ``]''; if the ``]'' is missing then +the ``['' matches a ``['' rather than introducing a character class. +A character class matches any of the characters between the square +brackets. A range of characters may be specified using a minus sign. +The character class may be complemented by making an exclamation point +the first character of the character class. +.PP +To include a ``]'' in a character class, make it the first character listed +(after the ``!'', if any). +To include a minus sign, make it the first or last character listed. +.h "The /u Directory" +By convention, the name ``/u/user'' refers to the home directory of the +specified user. There are good reasons why this feature should be supported +by the file system (using a feature such as symbolic links) rather than +by the shell, but +.I ash +is capable of performing this mapping if the file system doesn't. +If the mapping is done by +.IR ash , +setting the +.B -f +flag will turn it off. +.h "Character Set" +.I Ash +silently discards nul characters. Any other character will be handled +correctly by +.IR ash , +including characters with the high order bit set. +.h "Job Names and Job Control" +The term +.I job +refers to a process created by a shell command, or in the case of a +pipeline, to the set of processes in the pipeline. The ways to refer +to a job are: +.d +%\fInumber\fR +%\fIstring\fR +%% +\fIprocess_id\fR +.e +The first form identifies a job by job number. +When a command is run, +.I ash +assigns it a job number +(the lowest unused number is assigned). +The second form identifies a job by giving a prefix of the command used +to create the job. The prefix must be unique. If there is only one job, +then the null prefix will identify the job, so you can refer to the job +by writing ``%''. The third form refers to the \fIcurrent job\fR. The +current job is the last job to be stopped while it was in the foreground. +(See the next paragraph.) The last form identifies a job by giving the +process id of the last process in the job. +.PP +If the operating system that +.I ash +is running on supports job control, +.I ash +will allow you to use it. +In this case, typing the suspend character (typically ^Z) while running +a command will return you to +.I ash +and will make the suspended command the current job. You can then continue +the job in the background by typing +.IR bg , +or you can continue it in the foreground by typing +.IR fg . +.h "Atty" +If the shell variable ATTY is set, and the shell variable TERM is not +set to ``emacs'', then \fIash\fR generates appropriate escape sequences +to talk to +.IR atty (1). +.h "Exit Statuses" +By tradition, an exit status of zero means that a command has succeeded +and a nonzero exit status indicates that the command failed. This is +better than no convention at all, but in practice it is extremely useful +to allow commands that succeed to use the exit status to return information +to the caller. A variety of better conventions have been proposed, but +none of them has met with universal approval. The convention used by +\fIash\fR and all the programs included in the \fIash\fR distribution is +as follows: +.ta 1i 2i +.nf + 0 Success. + 1 Alternate success. + 2 Failure. + 129-... Command terminated by a signal. +.fi +The \fIalternate success\fR return is used by commands to indicate various +conditions which are not errors but which can, with a little imagination, +be conceived of as less successful than plain success. For example, +.I test +returns 1 when the tested condition is false and +.I getopts +returns 1 when there are no more options. +Because this convention is not used universally, the +.B -e +option of +.I ash +causes the shell to exit when a command returns 1 even though that +contradicts the convention described here. +.PP +When a command is terminated by a signal, the uses 128 plus the signal +number as the exit code for the command. +.h "Builtin Commands" +This concluding section lists the builtin commands which are builtin +because they need to perform some operation that can't be performed by a +separate process. In addition to these, there are several other commands +.RI ( catf , +.IR echo , +.IR expr , +.IR line , +.IR nlecho , +.IR test , +.RI `` : '', +and +.IR true ) +which can optionally be compiled into the shell. The builtin +commands described below that accept options use the System V Release 2 +.IR getopt (3) +syntax. +.sp +.b bg +[ +.I job +] ... +.br +Continue the specified jobs (or the current job if no jobs are given) +in the background. +This command is only available on systems with Bekeley job control. +.b command +.IR "command arg" ... +.br +Execute the specified builtin command. (This is useful when you have a +shell function with the same name as a builtin command.) +.b cd +[ +.I directory +] +.br +Switch to the specified directory (default $HOME). +If the an entry for CDPATH appears in the environment of the cd command +or the shell variable CDPATH is set and the directory name does not +begin with a slash, then the directories listed in CDPATH will be +searched for the specified directory. The format of CDPATH is the +same as that of PATH. +In an interactive shell, the cd command will print out the name of the +directory that it actually switched to if this is different from the +name that the user gave. These may be different either because +the CDPATH mechanism was used or because a symbolic link was crossed. +.\" .b ".\fI\h'0.1i'file" +.\" Cawf can't do \h'0.1i' +.b . +.I file +.br +The commands in the specified file are read and executed by the shell. +A path search is not done to find the file because the directories in +PATH generally contain files that are intended to be executed, not read. +.b eval +.IR string ... +.br +The strings are parsed as shell commands and executed. +(This differs from the System V shell, which concatenates the arguments +(separated by spaces) and parses the result as a single command.) +.b exec +[ +.IR "command arg" ... +] +.br +Unless +.I command +is omitted, +the shell process is replaced with the specified program (which must be a real +program, not a shell builtin or function). +Any redirections on the exec command are marked as permanent, so that they +are not undone when the exec command finishes. +If the command is not found, the exec command causes the shell to exit. +.b exit +[ +.I exitstatus +] +.br +Terminate the shell process. If +.I exitstatus +is given it is used as the +exit status of the shell; otherwise the exit status of the preceding +command is used. +.b export +.IR name ... +.br +The specified names are exported so that they will appear in the environment +of subsequent commands. The only way to un-export a variable is to unset it. +.I Ash +allows the value of a variable to be set at the same time it is exported +by writing +.d +\fBexport\fR name=value +.e +With no arguments the export command lists the names of all exported variables. +.b fg +[ +.I job +] +.br +Move the specified job or the current job to the foreground. +This command is only available on systems with Bekeley job control. +.b getopts +.I optstring +.I var +.br +The System V +.I getopts +command. +.b hash +.B -rv +.IR command ... +.br +The shell maintains a hash table which remembers the locations of +commands. With no arguments whatsoever, the hash command prints +out the contents of this table. Entries which have not been looked +at since the last +.I cd +command are marked with an asterisk; it is possible for these entries +to be invalid. +.sp +With arguments, the hash command removes the specified commands from +the hash table (unless they are functions) and then locates them. +With the +.B -v +option, +.I hash +prints the locations of the commands as it finds them. +The +.B -r +option causes the +.I hash +command to delete all the entries in the hash table except for +functions. +.b jobid +[ +.I job +] +.br +Print the process id's of the processes in the job. If the job argument +is omitted, use the current job. +.b jobs +.br +This command lists out all the background processes which are children +of the current shell process. +.b pwd +.br +Print the current directory. The builtin command may differ from the +program of the same name because the builtin command remembers what +the current directory is rather than recomputing it each time. This +makes it faster. However, if the current directory is renamed, the +builtin version of pwd will continue to print the old name for the +directory. +.b read +[ +.B -p +.I prompt +] +[ +.B -e +] +.IR variable ... +.br +The prompt is printed if the +.B -p +option is specified and the standard input is a terminal. Then a +line is read from the standard input. The trailing newline is deleted +from the line and the line is split as described +in the section on word splitting above, and the pieces are assigned to +the variables in order. If there are more pieces than variables, the +remaining pieces (along with the characters in IFS that separated them) +are assigned to the last variable. If there are more variables than +pieces, the remaining variables are assigned the null string. +.sp +The +.B -e +option causes any backslashes in the input to be treated specially. +If a backslash is followed by a newline, the backslash and the newline +will be deleted. If a backslash is followed by any other character, +the backslash will be deleted and the following character will be treated +as though it were not in IFS, even if it is. +.b readonly +.IR name ... +.br +The specified names are marked as read only, so that they cannot be +subsequently modified or unset. +.I Ash +allows the value of a variable to be set at the same time it is marked +read only by writing +.d +\fBreadonly\fR name=value +.e +With no arguments the readonly command lists the names of all +read only variables. +.b set +[ +{ +.BI - options +| +.BI + options +| +.B -- +} +] +.IR arg ... +.br +The +.I set +command performs three different functions. +.sp +With no arguments, it lists the values of all shell variables. +.sp +If options are given, it sets the specified option flags, or clears +them if the option flags are introduced with a +.B + +rather than a +.BR - . +Only the first argument to +.I set +can contain options. +The possible options are: +.sp +.ta 0.4i +.in +0.4i +.ti -0.4i +\fB-e\fR Causes the shell to exit when a command terminates with +a nonzero exit status, except when the exit status of the command is +explicitly tested. The exit status of a command is considered to be +explicitly tested if the command is used to control an +.IR if , +.IR elif , +.IR while , +or +.IR until ; +or if the command is the left hand operand of an ``&&'' or ``||'' +operator. +.sp +.ti -0.4i +\fB-f\fR Turn off file name generation. +.sp +.ti -0.4i +\fB-I\fR Cause the shell to ignore end of file conditions. +(This doesn't apply when the shell a script sourced using the ``.'' +command.) The shell will in fact exit if it gets 50 eof's in a +row. +.sp +.ti -0.4i +\fB-i\fR Make the shell interactive. This causes the shell to +prompt for input, to trap interrupts, to ignore quit and terminate signals, +and to return to the main command loop rather than exiting on error. +.sp +.ti -0.4i +\fB-j\fR Turns on Berkeley job control, on systems that support it. +When the shell starts up, the +.B -j +is set by default if the +.B -i +flag is set. +.sp +.ti -0.4i +\fB-n\fR Causes the shell to read commands but not execute them. +(This is marginally useful for checking the syntax of scripts.) +.sp +.ti -0.4i +\fB-s\fR If this flag is set when the shell starts up, the shell +reads commands from its standard input. The shell doesn't examine the +value of this flag any other time. +.sp +.ti -0.4i +\fB-x\fR If this flag is set, the shell will print out each +command before executing it. +.sp +.ti -0.4i +\fB-z\fR If this flag is set, the file name generation process +may generate zero files. If it is not set, then a pattern which does +not match any files will be replaced by a quoted version of the pattern. +.in -0.4i +.sp +The third use of the set command is to set the values of the shell's +positional parameters to the specified +.IR args . +To change the positional parameters without changing any options, +use ``\fB--\fR'' as the first argument to +.IR set . +If no args are present, the set command will leave the value of the +positional parameters unchanged, so to set the positional parameters +to set of values that may be empty, execute the command +.d +shift $# +.e +first to clear out the old values of the positional parameters. +.b setvar +.I variable +.I value +.br +Assigns +.I value +to +.IR variable . +(In general it is better to write +.I variable=value +rather than using +.IR setvar . +.I Setvar +is intended to be used in functions that assign values to variables whose +names are passed as parameters.) +.b shift +[ +.I n +] +.br +Shift the positional parameters +.I n +times. +A shift sets the value of $1 to the value of $2, the value of $2 to +the value of $3, and so on, decreasing the value of $# by one. +If there are zero positional parameters, shifting doesn't do anything. +.b trap +[ +.I action +] +.IR signal ... +.br +Cause the shell to parse and execute +.I action +when any of the specified signals are received. +The signals are specified by signal number. +.I Action +may be null or omitted; +the former causes the specified signal to be ignored and the latter +causes the default action to be taken. +When the shell forks off a subshell, it resets trapped (but not ignored) +signals to the default action. +The trap command has no effect on signals that were ignored on entry +to the shell. +.b umask +[ +.I mask +] +.br +Set the value of umask (see +.IR umask (2)) +to the specified octal value. If the argument is omitted, the umask +value is printed. +.b unset +.IR name ... +.br +The specified variables and functions are unset and unexported. +If a given name corresponds to both a variable and a function, both the +variable and the function are unset. +.b wait +[ +.I job +] +.br +Wait for the specified job to complete and return the exit status of the +last process in the job. If the argument is omitted, wait for all jobs +to complete and the return an exit status of zero. +.SH EXAMPLES +The following function redefines the \fIcd\fR command: +.d +cd() { + if command cd "$@" + then if test -f .enter + then . .enter + else return 0 + fi + fi +} +.e +This function causes the file ``.enter'' to be read when you enter a +directory, if it exists. The \fIcommand\fR command is used to access the +real \fIcd\fR command. The ``return 0'' ensures that the function will +return an exit status of zero if it successfully changes to a directory +that does not contain a ``.enter'' file. Redefining existing commands +is not always a good idea, but this example shows that you can do it if +you want to. +.PP +The suspend function distributed with +.I ash +looks like +.d +# Copyright (C) 1989 by Kenneth Almquist. All rights reserved. +# This file is part of ash, which is distributed under the terms +# specified by the Ash General Public License. + +suspend() { + local - + set +j + kill -TSTP 0 +} +.e +This turns off job control and then sends a stop signal to the current +process group, which suspends the shell. (When job control is turned +on, the shell ignores the TSTP signal.) Job control will be turned back +on when the function returns because ``-'' is local to the function. +As an example of what \fInot\fR to do, consider an earlier version of +\fIsuspend\fR: +.d +suspend() { + suspend_flag=$- + set +j + kill -TSTP 0 + set -$suspend_flag +} +.e +There are two problems with this. First, \fBsuspend_flag\fR is a global +variable rather than a local one, which will cause problems in the +(unlikely) circumstance that the user is using that variable for some +other purpose. Second, consider what happens if shell received an interrupt +signal after it executes the first \fIset\fR command but before it executes +the second one. The interrupt signal will abort the shell function, so +that the second \fIset\fR command will never be executed and job control +will be left off. The first version of \fIsuspend\fR avoids this problem +by turning job control off only in a local copy of the shell options. The +local copy of the shell options is discarded when the function is terminated, +no matter how it is terminated. +.SH HINTS +Shell variables can be used to provide abbreviations for things which +you type frequently. For example, I set +.br +.\" \h'1i'export h=$HOME +.\" Cawf can't do \h'1i' +.in +1i +export h=$HOME +.in -1i +.br +in my .profile so that I can type the name of my home directory simply +by typing ``$h''. +.PP +When writing shell procedures, try not to make assumptions about what is +imported from the environment. Explicitly unset or initialize all variables, +rather than assuming they will be unset. If you use cd, it is a good idea +to unset CDPATH. +.PP +People sometimes use ``<&-'' or ``>&-'' to provide no input to a command +or to discard the output of a command. A better way to do this is +to redirect the input or output of the command to +.BR /dev/null . +.PP +Word splitting and file name generation are performed by default, +and you have to explicitly use double quotes to suppress it. This is +backwards, but you can learn to live with it. Just get in the habit of +writing double quotes around variable and command substitutions, and +omit them only when you really want word splitting and file name generation. +If you want word splitting but not file name generation, use the +.B -f +option. +.SH AUTHORS +Kenneth Almquist +.SH "SEE ALSO" +echo(1), expr(1), line(1), pwd(1), true(1). +.SH BUGS +When command substitution occurs inside a here document, the commands inside +the here document are run with their standard input closed. For example, +the following will not word because the standard input of the +.I line +command will be closed when the command is run: +.d +cat <<-! +Line 1: $(line) +Line 2: $(line) +! +.e +.PP +Unsetting a function which is currently being executed may cause strange +behavior. +.PP +The shell syntax allows a here document to be terminated by an end of file +as well as by a line containing the terminator word which follows the ``<<''. +What this means is that if you mistype the terminator line, the shell +will silently swallow up the rest of your shell script and stick it +in the here document. diff --git a/man/man1/asize.1 b/man/man1/asize.1 new file mode 100644 index 000000000..a11a97883 --- /dev/null +++ b/man/man1/asize.1 @@ -0,0 +1,37 @@ +.TH ASIZE 1 +.SH NAME +asize \- report the size of an object file +.SH SYNOPSIS +\fBasize \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "asize test.o" "Give the size of \fItest.o\fR" +.SH DESCRIPTION +.PP +.I Asize +prints for each argument +the (decimal) number of bytes used by the different sections, +as well as their sum in decimal and hexadecimal. +If no +.I file +is given \fIa.out\fR is used. +.I Asize +can only be used to obtain the size of a \(M2 \fI.o\fR or \fI.out\fR file. +To obtain the size of an executable, use +.I size +instead. +.SH "SEE ALSO" +.BR anm (1), +.BR nm (1), +.BR ar (1), +.BR size (1). diff --git a/man/man1/at.1 b/man/man1/at.1 new file mode 100644 index 000000000..8930593d8 --- /dev/null +++ b/man/man1/at.1 @@ -0,0 +1,34 @@ +.TH AT 1 +.SH NAME +at \- execute commands at a later time +.SH SYNOPSIS +\fBat \fItime\fR [\fImonth day\fR] [\fIfile\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "at 2315 Jan 31 myfile" "Myfile executed Jan 31 at 11:15 pm" +.EX "at 0900" "Job input read from \fIstdin\fR" +.EX "at 0711 4 29 " "Read from \fIstdin\fR, exec on April 29" +.SH DESCRIPTION +.PP +\fBAt\fR prepares a file to be executed later at the specified time by +creating a special entry in \fB/usr/spool/at\fR. The \fBcron\fR daemon +takes care of executing these jobs. It checks to see if any +files in \fB/usr/spool/at\fR should now be run, and if so, it runs them +and then puts them in \fB/usr/spool/at/past\fR. +The name of the file created in \fB/usr/spool/at\fR by \fBat\fR is +YY.DDD.HHMM.UU (where YY, DDD, HH, and MM give the time to execute and +UU is a unique number). Note that when the command runs, it will not be able +to use standard input unless specifically redirected. Standard output +will be mailed to the owner of the job. +.SH "SEE ALSO" +.BR cron (8). diff --git a/man/man1/banner.1 b/man/man1/banner.1 new file mode 100644 index 000000000..6636d7b82 --- /dev/null +++ b/man/man1/banner.1 @@ -0,0 +1,22 @@ +.TH BANNER 1 +.SH NAME +banner \- print a banner +.SH SYNOPSIS +\fBbanner \fIarg ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "banner happy birthday" "Print a banner saying happy birthday" +.SH DESCRIPTION +.PP +\fIBanner\fR prints its arguments on \fIstdout\fR using a matrix +of 6 x 6 pixels per character. diff --git a/man/man1/basename.1 b/man/man1/basename.1 new file mode 100644 index 000000000..60bd83b9c --- /dev/null +++ b/man/man1/basename.1 @@ -0,0 +1,33 @@ +.TH BASENAME 1 +.SH NAME +basename, dirname \- strip off file prefixes and suffixes +.SH SYNOPSIS +\fBbasename \fIfile\fR [\fIsuffix\fR]\fR +.br +\fBdirname \fIfile\fR +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "basename /user/ast/file.c" "Strips path to yield \fIfile.c\fP" +.EX "basename /user/file.c .c" "Strips path and \fI.c\fP to yield \fIfile\fP" +.EX "dirname /user/file.c" "Strips basename to yield \fI/user\fP" +.SH DESCRIPTION +.PP +.I Basename +removes the initial directory names (if any) yielding the name of the +file itself. +If a second argument is present, it is interpreted as a suffix and is +also stripped, if present. +.PP +.I Dirname +removes the final component of a path, yielding the directory a file is in. +.PP +These programs are primarily used in shell scripts. diff --git a/man/man1/bc.1 b/man/man1/bc.1 new file mode 100644 index 000000000..a53644ad6 --- /dev/null +++ b/man/man1/bc.1 @@ -0,0 +1,730 @@ +.\" +.\" bc.1 - the *roff document processor source for the bc manual +.\" +.\" This file is part of bc written for MINIX. +.\" Copyright (C) 1991, 1992 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, 675 Mass Ave, Cambridge, MA 02139, USA. +.\" +.\" You may contact the author by: +.\" e-mail: phil@cs.wwu.edu +.\" us-mail: Philip A. Nelson +.\" Computer Science Department, 9062 +.\" Western Washington University +.\" Bellingham, WA 98226-9062 +.\" +.\" +.TH bc 1 .\" "Command Manual" v1.02 "Feb 3, 1992" +.SH NAME +bc - An arbitrary precision calculator language +.SH SYNTAX +\fBbc\fR [ \fB-lws\fR ] [ \fI file ...\fR ] +.SH VERSION +This man page documents GNU bc version 1.02. +.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 -l +Define the standard math library. +.IP -w +Give warnings for extensions to POSIX \fBbc\fR. +.IP -s +Process exactly the POSIX \fBbc\fR language. +.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 significant decimal digits in 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. +.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 16 (F). Assigning a +value outside this range to \fBibase\fR will result in a value of 2 +or 16. Input numbers may contain the characters 0-9 and A-F. (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 \fBFFF\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. +.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 cause the side effect of assigning the printed value the 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. +.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 the 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 +"b" (bell), "f" (form feed), "n" (newline), "r" (carriage return), "t" +(tab), and "\e" (backslash). Any other character following the +backslash will be ignored. This still does not allow the double quote +character to be part of any string. +.IP "{ statement_list }" +This is the compound statement. It allows multiple statements to be +grouped together for execution. +.IP "\fBif\fR ( expression ) \fBthen\fR 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.) +.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. Numbers are only call by value parameters. Arrays are only +call by variable. 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 variable 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 +in the fact that 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. +.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 in radians. +.IP "c (\fIx\fR)" +The cosine of x in radians. +.IP "a (\fIx\fR)" +The arctangent of x. +.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 +\fB +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 +\fB +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 +\fB +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 +\fB +define f (x) { + if (x <= 1) return (1); + return (f(x-1) * x); +} +\fR +.RE +.fi +.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 11n +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 "array parameters" +POSIX \fBbc\fR does not have array parameters. Other implementations +of \fBbc\fR may have call by value array parameters. +.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 multiply +The multiply routine may yield incorrect results if a number +has more than LONG_MAX / 90 total digits. For 32 bit longs, this number is +23,860,929 digits. +.IP "code size" +Each function and the "main" program are limited to 10240 bytes of +compiled byte code each. This limit (BC_MAX_SEGS) can be easily changed +to have more than 10 segments of 1024 bytes. +.IP "variable names" +The current limit on the number of unique names is 32767 for each of +simple variables, arrays and functions. +.SH FILES +In most installations, \fBbc\fR is completely self-contained. +Where executable size is of importance or the C compiler does +not deal with very long strings, \fBbc\fR will read +the standard math library from the file /usr/local/lib/libmath.b. +(The actual location may vary. It may be /lib/libmath.b.) +.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. +.SH AUTHOR +.nf +Philip A. Nelson +phil@cs.wwu.edu +.fi +.SH ACKNOWLEDGEMENTS +The author would like to thank Steve Sommars (sesv@iwtsf.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/man/man1/bsfilt.1 b/man/man1/bsfilt.1 new file mode 100644 index 000000000..c8830d669 --- /dev/null +++ b/man/man1/bsfilt.1 @@ -0,0 +1,86 @@ +.\" manual page for bsfilt(1) +.\" +.\" +.\" Copyright (c) 1991 Purdue University Research Foundation, +.\" West Lafayette, Indiana 47907. All rights reserved. +.\" +.\" Written by Victor A. Abell , Purdue +.\" University Computing Center. Not derived from licensed software; +.\" derived from awf(1) by Henry Spencer of the University of Toronto. +.\" +.\" Permission is granted to anyone to use this software for any +.\" purpose on any computer system, and to alter it and redistribute +.\" it freely, subject to the following restrictions: +.\" +.\" 1. The author is not responsible for any consequences of use of +.\" this software, even if they arise from flaws in it. +.\" +.\" 2. The origin of this software must not be misrepresented, either +.\" by explicit claim or by omission. Credits must appear in the +.\" documentation. +.\" +.\" 3. Altered versions must be plainly marked as such, and must not +.\" be misrepresented as being the original software. Credits must +.\" appear in the documentation. +.\" +.\" 4. This notice may not be removed or altered. +.\" +.TH BSFILT 1 "February, 1991" +.BY "Purdue University" +.SH NAME +bsfilt, colcrt \- a colcrt-like backspace filter +.SH SYNOPSIS +.B bsfilt +[ +.B - +] [ +.B -U +] [ file ... ] +.SH DESCRIPTION +.I Bsfilt +filters backspace sequences from the input \fIfile\fR(s) +(standard input if none) +in an approximation of +.IR colcrt (1). +Both the backspace and the character it returns to are removed, +unless they form an underline sequence. +Underline sequences are treated according to the settings of +the +.B \- +and +.B \-U +options. +.SH OPTIONS +.TP +.B \- +specifies that no underlining of any kind is to be propagated. +Without this option or the +.B \-U +option, +.I bsfilt +approximates underlining with minus signs (`-') in following lines. +.TP +.B \-U +specifies that underlining with underscore (`_') and backspace (`\b') +character sequences is permitted. +.SH SEE ALSO +cawf(1), colcrt(1) and nroff(1). +.SH DIAGNOSTICS +Diagnostic messages are delivered to the standard error file. +.SH HISTORY +Vic Abell of Purdue University wrote +.I bsfilt +to have a backspace filter for +.IR cawf (1) +that is independent of licensed source code. +.SH BUGS +The maximum length of a line that can be underlined with minus signs is +fixed. +.LP +.I Bsfilt +does not examine the characters that are being overprinted via backspace +operations. +Thus, overprinting that is intended to form a new character from several +different ones is ineffective and only the last character of the +sequence is propagated \- e. g., ``o^H+'', intended to look like +a bullet, is reduced to `+'. diff --git a/man/man1/cal.1 b/man/man1/cal.1 new file mode 100644 index 000000000..addb30363 --- /dev/null +++ b/man/man1/cal.1 @@ -0,0 +1,27 @@ +.TH CAL 1 +.SH NAME +cal \- print a calendar +.SH SYNOPSIS +\fBcal\fR [\fImonth\fR] \fIyear\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "cal 3 1992" "Print March 1992" +.SH DESCRIPTION +.PP +\fICal\fR prints a calendar for a month or year. The year can be +between 1 and 9999. +Note that the year 91 is not a synonym for 1991, but is itself a +valid year about 19 centuries ago. The calendar produced is the one used +by England and her colonies. Try Sept. 1752, Feb 1900, and Feb 2000. If +you do not understand what is going on, look up \fICalendar, Gregorian\fR in a +good encyclopedia. diff --git a/man/man1/calendar.1 b/man/man1/calendar.1 new file mode 100644 index 000000000..f1daf5c87 --- /dev/null +++ b/man/man1/calendar.1 @@ -0,0 +1,44 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- reminder service +.SH SYNOPSIS +\fBcalendar [\fB\-\fR] [\fB\-r\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-" "Work for every user and send mail to him" +.FL "\-r" "Restrict multiple execution on the same day" +.SH EXAMPLES +.EX "calendar" "Check \fIcalendar\fR file in current directory" +.EX "calendar" "Normary used under the control of cron(8)" +.EX "calendar \-r" " Normary used in /etc/rc file" +.SH DESCRIPTION +.PP +Basically \fIcalendar\fR program consults the file \fIcalendar\fR in the +current directory and display lines which contain today's or tomorrow's date. +Month-day formats such +as '12/25', 'Dec. 25', 'december 25', '*/25', '12/*', '*/*' are +recognized. The asterisk +means 'all' days or 'all' months. On weekends 'tomorrow' extends through +next Monday without any consideration about holidays. +To prevent ambiguity, the formats '25 Dec.' and '25/12' are not recognized. +.PP +When an argument \fB\-\fR is present, \fIcalendar\fR works for all users +with a file \fIcalendar\fR in their login directories and sends them mail. +Normally this is done daily under the control of \fIcron\fR. +.PP +The \fB\-r\fR option does its the same job as \fB\-\fR option, but touches +the \fIcalendar\fR to prevents further access on the same day. +Normally this is done in the \fI/etc/rc\fR file on a machine which may be +booted several times in one day. +.SH "SEE ALSO" +.BR cron (8). diff --git a/man/man1/cat.1 b/man/man1/cat.1 new file mode 100644 index 000000000..c6215988e --- /dev/null +++ b/man/man1/cat.1 @@ -0,0 +1,33 @@ +.TH CAT 1 +.SH NAME +cat \- concatenate files and write them to stdout +.SH SYNOPSIS +\fBcat\fR [\fB\-u\fR]\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-u" "Unbuffered output" +.SH EXAMPLES +.EX "cat file" "Display file on the terminal" +.EX "cat file1 file2 | lp" "Concatenate 2 files and print result" +.SH DESCRIPTION +.PP +.I Cat +concatenates its input files and copies the result to \fIstdout\fR. +If no input file is named, or \- is encountered as a file name, standard +input is used. +Output is buffered in 512 byte blocks unless the +.B \-u +flag is given. +If you just want to copy a file, \fIcp\fR should be used since it is faster. +.SH "SEE ALSO" +.BR cp (1). diff --git a/man/man1/cawf.1 b/man/man1/cawf.1 new file mode 100644 index 000000000..3d3ad3451 --- /dev/null +++ b/man/man1/cawf.1 @@ -0,0 +1,760 @@ +.\" manual page for cawf(1) +.\" +.\" +.\" Copyright (c) 1991 Purdue University Research Foundation, +.\" West Lafayette, Indiana 47907. All rights reserved. +.\" +.\" Written by Victor A. Abell , Purdue +.\" University Computing Center. Not derived from licensed software; +.\" derived from awf(1) by Henry Spencer of the University of Toronto. +.\" +.\" Permission is granted to anyone to use this software for any +.\" purpose on any computer system, and to alter it and redistribute +.\" it freely, subject to the following restrictions: +.\" +.\" 1. The author is not responsible for any consequences of use of +.\" this software, even if they arise from flaws in it. +.\" +.\" 2. The origin of this software must not be misrepresented, either +.\" by explicit claim or by omission. Credits must appear in the +.\" documentation. +.\" +.\" 3. Altered versions must be plainly marked as such, and must not +.\" be misrepresented as being the original software. Credits must +.\" appear in the documentation. +.\" +.\" 4. This notice may not be removed or altered. +.\" +.\" Some of the stuff in this file is a bit contorted, because it's also +.\" the regression-test input. +.nr ES 5n +.de ES +.PP +.in +\\n(ESu +.nf +.. +.de EE +.in -\\n(ESu +.fi +.PP +.. +.de PT +.ie \\n(.$>1 .TP "\\$2" +.el .TP +.ie !'\\$1'' \\$1 +.el \(bu +.. +.ds Nr \fInroff\fR +.TH CAWF 1 "November, 1992" +.BY "Purdue University" +.SH NAME +cawf, nroff \- C version of the nroff-like, Amazingly Workable (text) Formatter +.SH SYNOPSIS +.B cawf +.RB [ \-c\c +.IR config ] +.RB [ \-d\c +.IR device ] +.RB [ \-e ] +.RB [ \-f\c +.IR font ] +.RB [ \-h ] +.RB [ \-m\c +.IR acros ] +.RI [ file " ...]" +.SH DESCRIPTION +.I Cawf +formats the text from the input \fIfile\fR(s) +(standard input if none) +in an approximation of \*(Nr. +It comes closest to duplicating \*(Nr's +.B man +or +.B ms +macro package styles. +It has some limited support for \*(Nr's +.B me +macros. +.SH OPTIONS +Options must precede file names. +.TP +.BI \-c config +defines an alternate path to the device configuration file. +Normally the device configuration file is found in +.I device.cf +in the +.I cawf +library (see the +.B FILES +section). +.IP +The device configuration file contains device character strings for +selecting fonts and the bold or italic type faces. +See the +.B DEVICES +section for more information. +.TP +.BI \-d device +specifies the name of the output device. +There are three built\-in devices \- ANSI, NONE and NORMAL \- and +other devices may be defined in the device configuration file. +See the +.B DEVICES +section for more information. +.IP +The NORMAL device is the default. +.TP +.B \-e +directs +.I cawf +to issue an eject (FF or ^L) after the last page. +.TP +.BI \-f font +specifies the one font for the device, declared with the +.BI \-d device +option, that is to be used for the +entire document. +.I Font +must match a font associated with the device's stanza in the device +configuration file. +See the +.B DEVICES +section for more information. +.IP +No +.I font +may be specified for the built\-in devices ANSI, NONE or NORMAL. +.TP +.B \-h +requests a help display. +.TP +.BI \-m acro +specifies the macro file to be used. +The standard +.I cawf +distribution supplies macro files to support ``\-man'', ``\-me'' or ``\-ms''. +.I Cawf +finds a macro file by constructing its name from `m', +.I acro +and +.B .mac +\- e. g., +.BI \-m an +is converted to +.BR man.mac . +The default directory for macro files is defined when +.I cawf +is compiled; it's \fIC:\\SYS\\LIB\\CAWF\fP in the MS\-DOS environment; +.I /usr/lib/cawf +in the UNIX environment. +.TP +file ... +are the names of files containing \*(Nr source text. +.SH NROFF COMPATIBILITY +.I Cawf +accepts the following raw \*(Nr requests: +.ES +\&.\e" .ad .bp .br .ce .de .di .ds +\&.el .fi .fl .ft .i0 .ie .if .in +\&.it .lg .li .ll .ls .na .ne .nf +\&.nr .ns .pl .po .ps .rm .rn .rr +\&.rs .so .sp .ta .ti .tm .tr +.EE +and the following in-text codes: +.ES +\e$ \e% \e* \e" \ec \ef \eh \ek +\en \es \ew +.EE +plus the full list of \*(Nr/\c +.I troff +special characters in +the original V7 \fItroff\fR manual. +.PP +Many restrictions are present; the behavior in general is a subset of +\*(Nr's. Of particular note are the following: +.IP \(bu 2 +The fully supported nroff request control character is the period. +There is limited support for the non\-break, acute accent control +character. +.PT +Point sizes do not exist; +.B .ps +is ignored. +.PT +Special vertical spacing \- the +.B .vs +request included \- is ignored. +.PT +Conditionals cover only the numeric comparisons >, =, <, >= and <= on +.BR \en(.$ ; +string com\%par\%isons between a macro parameter and a literal; +.B n +(always true); +and +.BR t +(always false). +Only single line input is accepted from conditionals; +multi\-line input \- e.g., \\(\fIanything\fP\\) \- is not supported. +.PT +The handling of strings is generally primitive. +.IP \(bu +Horizontal motion via +.B \eh +must be supplied with a number register interpolation and must be +positive - e. g., +.BR \ew\en(NN , +where the value in NN is >= 0. +.IP \(bu +The +.B \ek +function is reliable only after TAB characters, so it is useful only +for measuring table positions. +.IP \(bu +The +.B .di +request only turns output on and off \- any macro name is ignored. +.IP \(bu +Expressions - e. g., +.B .sp +- are reasonably general, but the +.BR | , +.BR & , +and +.BR :\& +operators do not exist, there must be white space between the end of the \*(Nr +function and the beginning of the expression, and +.B \ew +requires that quote (') be used as the delimiters. +.B \ew +counts the characters inside the quotes and scales the result in ens, +so that, for example, \ew'\e(bu' equals 4n, and \ew'\e(bu'/1n equals 4. +.PT +The only acceptable count for the +.B .it +request is one, +and it is effective only with +.BR man , +.B me +or +.B ms +macros. +.PT +The default scaling factor is `v' for the +.BR .ne , +.BR .sp , +and +.B .pl +raw \*(Nr requests; it is `u' for +.BR .nr ; +and `n' for +.BR .in , +.BR .ll , +.BR .ls , +.BR .po , +.BR .ta +and +.BR .ti . +(A different scaling factor may be specified with a trailing character.) +.PT +Some obsolete or meaningless requests \- +.BR .i0 , +.B .lg +and +.B .li +\&\- are silently ignored. +.P +White space at the beginning of lines, +and embedded white space within lines is dealt with properly. +Sentence terminators at ends of lines are understood to imply +extra space afterward in filled lines. +Tabs are im\%plemented crudely and not exactly, although +usually they work as expected. +Hyphenation is done only at explicit hyphens, em-dashes, and \*(Nr +discretionary hyphens. +By default bold and italic characters are emulated with backspacing and +overprinting, but the +.B \-d +and +.B \-f +options, combined with the contents of the device configuration file, +may be used to generate special codes for bold and italic characters. +(See the +.B DEVICES +section for more information.) +.SH "MAN MACROS" +The +.B man +macro set replicates the full V7 manual macros, +plus a few semi-random oddballs. +The full list is: +.ES +\&.AT .B .BI .BR .BY .DE .DT .HP +\&.I .IB .IP .IR .IX .LP .NB .P +\&.PD .PP .RB .RE .RI .RS .SH .SM +\&.SS .TH .TP .UC +.EE +.B .BY +and +.B .NB +each take a single string argument (respectively, an indi\%cation of +authorship and a note about the status of the manual page) and arrange +to place it in the page footer. +.B .AT +and +.B .IX +do nothing. +.SH "ME MACROS" +The +.B me +macro subset has been derived from the +.I cawf +.B ms +macros by Chet Creider . +It includes: +.ES +\&.(l .(q .)l .)q .b .bu .i .ip +\&.lp .np .pp .r .sh .sm .u .uh +.EE +The .(l C and .(l L options are supported. +In addition, the .AB, .AE, .AI, .AU, .DA, .ND, .TL and .UX macros have +been retained from the +.B ms +set, and the .XP macro has been borrowed from the Berkeley additions to the +.B ms +macro set. +.SH "MS MACROS" +The +.B ms +macro set is a substantial subset of the V7 manuscript macros. +The macros are: +.ES +\&.AB .AE .AI .AU .B .CD .DA .DE +\&.DS .I .ID .IP .LD .LG .LP .ND +\&.NH .NL .PP .QE .QP .QS .R .RE +\&.RP .RS .SH .SM .TL .TP .UL .UX +.EE +Size changes are recognized but ignored, as are +.B .RP +and +.BR .ND . +.B .UL +just prints its argument in italics. +.BR .DS / .DE +does not do a keep, +nor do any of the other macros that normally imply keeps. +.LP +The +.B DY +string variable is available. +The +.BR PD , +.BR PI , +and +.BR LL +number registers exist and can be changed. +.SH "HEADERS AND FOOTERS" +.I Cawf +allows the placement of text into the five line header and +footer sections from the +.BR LH , +.BR CH , +.BR RF , +.BR LF , +.BR CF , +and +.B RF +string variables, via the control of the +.B .^b +request: +.LP +.ta \w'.^b HF 0'u+3n +.nf +\&.^b fh 1 enables header string placement on the first page +\&.^b fh 0 disables header string placement on the first page +\&.^b HF 1 enables header/footer string placement +\&.^b HF 0 disables header/footer string placement +.fi +.LP +There are appropriate +.B .^b +requests in the distribution +.BR man , +.B me +and +.B ms +macro files. +(The +.B me +and +.B ms +macro files use another +.B .^b +request, \fB.^b NH\fP, to enable numbered header processing.) +.SH OUTPUT +The default output format supported by +.IR cawf , +in its distributed form, +is that appropriate to a dumb terminal, +using overprinting for italics (via underlining) and bold. +The \*(Nr special characters are printed as some vague approximation +(it's sometimes extremely vague) to their correct appearance. +.PP +One part of +.IR cawf 's +knowledge of the output device, related to the formation of characters, +is established by a device file, which is read before the user's input. +The search for it begins in +.IR cawf 's +library directory, under the name \fIterm\fP.\fBdev\fP +(where \fIterm\fR is the value of the TERM environment variable). +Failing to find that, +.I cawf +searches for +.BR dumb.dev . +(See the +.B FILES +section for a description of the path to +.IR cawf 's +library directory.) +The device file +uses special internal requests +to set up resolution, special characters +and more normal \*(Nr functions to set up page length, etc. +.PP +.I Cawf +has limited support for fonts special forms of bold and italic characters. +It is provided through the +.B \-c +.IR config , +.BI \-d device +and +.BI \-f font +options. +See the +.B DEVICES +section for more information. +.PP +Note the distinction between the device and the output device configuration +files. +The device file typically defines characters and constant output parameters. +The output device configuration file defines font and type face codes. +It is usually not necessary to define a separate device file for each +device represented in the output device configuration file \- the +.I dumb.dev +device file will suffice for almost all representations. +.SH DEVICES +.I Cawf +supports primitive output device configuration for font and type face +control. +One font may be selected for the entire document by directing +.I cawf +to issue a font selection control character string at the beginning +of the document, and control character strings may be selected for +switching between the bold, italic and Roman type faces. +.PP +The +.B \-c +.IR config, +.BI \-d device +and +.BI \-f font +options direct the font and type face selections. +.PP +The +.BI \-d device +option specifies the name of the device. +.I Cawf +has three built\-in devices \- ANSI, NONE and NORMAL. +When the ANSI device is selected, +.I cawf +issues the ANSI shadow mode control codes, ``ESC [ 7 m'', to represent +the bold face; +the ANSI underscore control codes, ``ESC [ 4 m'', to represent the italic +face; +and the ANSI control codes, ``ESC [ 0 m'', to represent the ROMAN face. +No +.BI \-f font +specification is permitted with the ANSI device. +.PP +When the NONE device is selected, +.I cawf +uses no special output codes to represent the type faces. +No +.BI \-f font +specification is permitted with the ANSI device. +.PP +The NORMAL output device is the default. +When it's selected, +.I cawf +overprints each bold character two times, using three issuances of each +bold character, separated by backspace characters; +it issues an underscore and backspace before each italic character. +No +.BI \-f font +specification is permitted with the ANSI device. +The +.IR bsfilt (1) +filter may be used to further process the backspace codes output for +a NORMAL device. +.PP +All other devices named in the +.BI \-d device +option must be represented by a stanza in the device configuration file. +The device configuration file is usually contained in +.I device.cf +in +.IR cawf's +library directory (see the +.B FILES +section for more information). +An alternate device configuration file path may be specified with the +.BI \-c config +option. +.PP +The +.B DEVICE CONFIGURATION FILE +section describes the organization of the device configuration file. +It is easy to add devices to the +.I device.cf +supplied in the +.I cawf +distribution. +.PP +The +.BI \-f font +option may be used with the +.BI \-d device +option, when the appropriate stanza in the device configuration file +contains an entry for the named +.IR font . +The +.B DEVICE CONFIGURATION FILE +section describes how fonts are defined in device configuration file +stanzas. +.SH DEVICE CONFIGURATION FILE +The device configuration file defines the special character codes +necessary to direct output devices to select fonts and to produce +bold, italic and Roman type faces. +.PP +The configuration file is usually found in +.I device.cf +in +.IR cawf 's +library directory (see the +.B FILES +section for more information). +It is organized into two main parts \- comments and device stanzas. +Comments are any lines that begin with the pound sign (`#') character. +They are informational only and +.I cawf +ignores them. +.I Cawf +also ignores empty lines, so they may be used as vertical white space. +.PP +Stanzas name devices and define their font and type face control strings. +A stanza begins with the name of the device, starting at the beginning +of a line and occupying the entire line. +The body of the stanza, defining fonts and type faces, is formed of +lines beginning with white space (a TAB or space characters) that +directly follow the device name. +.PP +Individual lines of the stanza body contain a key character, followed +by a equal sign, followed by the font name (if a font key) and the +output device control codes. +.I Cawf +issues the font control codes once, at the beginning of output, so +only one font may be selected. +The type face control codes are issued at each change of type face. +.PP +The key characters are: +.ne 4 +.PP +.RS +.nf +b for bold +f for font definition +i for italic +r for Roman +.fi +.RE +.PP +The `b', `i' and `r' key codes are followed by an equal sign (`=') and +their control code definition. +The `f' key code is followed by an equal sign (`='), the font name, +another equal sign and the font control code definition. +.PP +Control code definitions may contain any printable ASCII characters. +Non\-printable characters may be encoded in octal notation with the `\\nnn' +form or in hexadecimal with the `\\xnn' form. +The special code, `\\E' (or `\\e') represents the ESC control +character (\\033 or \\x1b). +.PP +Here's a sample showing the definition for the HP LaserJet III. +The stanza name is ``lj3''. +All its non\-printable characters are ESCs; the first is coded in +octal form; the second with '\\E'; the rest, in hexadecimal form. +TAB is used as the leading white space character for the stanza +body lines. +.PP +.RS +.nf +# HP LaserJet III + +lj3 + b=\\033(s7B + i=\\E(s1S + r=\\x1b(s0B\\x1b(s0S + f=c10=\x1b&l0O\x1b(8U\x1b(s0p12h10v0s0b3T + f=c12ibm=\x1b&l0O\x1b(10U\x1b(s0p10.00h12.0v0s0b3T + f=lg12=\x1b&l0O\x1b(8U\x1b(s12h12v0s0b6T +.fi +.RE +.PP +The distribution +.I device.cf +file defines the following devices and fonts. +.LP +.ta \w'kxp1180'u+3n +\w'Italic:'u+3n +\w'bps10'u+6n +.nf +.ne 3 +epson dot matrix printer in Epson FX-86e/FX-800 mode + Bold: Double-strike + Fonts: none + +.ne 4 +ibmppds IBM Personal Printer Data Stream (PPDS) protocol + Bold: Double-strike + Italic: Underline + Fonts: none + +.ne 12 +kxp1124 Panasonic KX\-P1124 dot matrix printer in PGM mode + Bold: Emphasized + Fonts: c10 10 Characters Per Inch (CPI) Courier + c12 12 CPI Courier + bps10 10 CPI Bold PS + bps12 12 CPI Bold PS + p10 10 CPI Prestige + p12 12 CPI Prestige + s10 10 CPI Script + s12 12 CPI Script + ss10 10 CPI Sans Serif + ss12 12 CPI Sans Serif + +.ne 10 +kxp1180 Panasonic KX\-P1180 dot matrix printer in PGM mode + Bold: Emphasized + Fonts: c10 10 Characters Per Inch (CPI) Courier + c12 12 CPI Courier + bps10 10 CPI Bold PS + bps12 12 CPI Bold PS + p10 10 CPI Prestige + p12 12 CPI Prestige + ss10 10 CPI Sans Serif + ss12 12 CPI Sans Serif + +.ne 6 +lj3 HP LaserJet III + Fonts: c10 10 point, 12 Characters Per Inch (CPI) + Courier + c12ibm 12 point, 10 CPI Courier, IBM\-PC + Symbol Set + lg12 12 point, 12 CPI Letter Gothic + +.ne 4 +vgamono VGA monochrome monitor for MS\-DOS + (ANSI.SYS driver required for MS\-DOS) + Italic: Reverse-video + Fonts: none +.SH FILES +.I Cawf +resource files are located in the +.I cawf +library directory \- \fI C:\\SYS\\LIB\\CAWF\fP, the MS\-DOS environment +default; +or +.IR /usr/lib/cawf , +the UNIX environment default. +These defaults can be overridden by the CAWFLIB environment variable, +or changed in the cawflib.h header file. + +.ta \w'device.cf'u+3n +.nf +common common device-independent initialization +device.cf output device configurations +*.dev device-specific initialization +m*.mac macro package files +.SH DIAGNOSTICS +Unlike +.IR nroff , +.I cawf +complains whenever it sees unknown requests. +All diagnostics appear on the standard error file. +.ad +.SH HISTORY +Vic Abell of Purdue University derived +.I cawf +from +.IR awf , +\&``the Amazingly Workable (text) Formatter,'' +written by Henry Spencer of the University of Toronto. +The Toronto work was a supplement to the C News project. +The Purdue effort was aimed at producing a C language version that +would run on small systems, particularly MS\-DOS ones. +The adaptation of the +.B me +macros was done by Chet Creider . +Chet also contributed ideas for device, font and type face support. +.PP +The MS\-DOS version of +.I cawf +has been compiled with version 2.5 of Microsoft's Quick-C compiler. +It runs under the Mortis Kern Systems Toolkit KornShell, +.IR ksh (1), +and COMMAND.COM. +.SH BUGS +Nroff and troff mavens will have many complaints. +Some may even represent bugs and not deliberate omissions. +.PP +Watch out for scaling factors - especially on requests like +.BR \ew . +.PP +The overprinting required to create bold and italicized characters is +tiresome on a slow printer. +The +.IR bsfilt (1) +post\-filter from this distribution may be used to alleviate that +nuisance by managing the backspacing codes from +.IR cawf 's +NORMAL device output. +.PP +The printing of bold and italic characters is sometimes better handled by +special printer codes. +Use +.IR cawf 's +.B \-c +.IR config , +.BI \-d device +and +.BI \-f font +options to produce special font and device output control codes. +.PP +.I Cawf +has a small amount of built-in code for the +.BR man , +.B me +and +.B ms +macro packages, but none for any others. +.PP +The stacking for the +.B .so +request is limited. +.SH SEE ALSO +bsfilt(1), +colcrt(1), +man(7), +me(7), +ms(7) +and +nroff(1). diff --git a/man/man1/cc.1 b/man/man1/cc.1 new file mode 100644 index 000000000..6397c960d --- /dev/null +++ b/man/man1/cc.1 @@ -0,0 +1,588 @@ +.TH CC 1 +.SH NAME +cc, pc, m2 \- Minix C, Pascal, and Modula-2 compilers +.SH SYNOPSIS +.in +.5i +.ti -.5i +.BR cc |\c +.BR pc |\c +.BR m2 +.RB [ "\-D \fIname\fR[\fB=\fIvalue" ]] +\&... +.RB [ "\-U \fIname" ] +\&... +.RB [ "\-I \fIdirectory" ] +\&... +.RB [ \-.\fIsuffix ] +\&... +.RB [ \-c ] +.RB [ \-E ] +.RB [ \-P ] +.RB [ \-S ] +.RB [ \-c.\fIsuffix ] +.RB [ \-O ] +.RB [ \-O\fIlevel ] +.RB [ \-OS ] +.RB [ \-OT ] +.RB [ \-g ] +.RB [ \-n ] +.RB [ \-a ] +.RB [ \-R ] +.RB [ \-A ] +.RB [ \-s ] +.RB [ \-fsoft ] +.RB [ \-fnone ] +.RB [ \-w ] +.RB [ \-wo ] +.RB [ \-ws ] +.RB [ \-wa ] +.RB [ \-3 ] +.RB [ \-_ ] +.RB [ \-W\fIname\fB\-\fIoption ] +\&... +.RB [ \-m\fIarch ] +.RB [ "\-o \fIoutfile" ] +.RB [ "\-L \fIdirectory" ] +\&... +.RB [ \-i ] +.RB [ \-sep ] +.RB [ \-com ] +.RB [ \-r ] +.RB [ "\-stack \fIsize" ] +.I operand +\&... +.sp .4v +.ti -.5i +(Minix-86 subset:) +.ti -.5i +.BR cc |\c +.BR pc |\c +.BR m2 +.RB [ "\-D\fIname\fR[\fB=\fIvalue" ]] +\&... +.RB [ "\-U\fIname" ] +\&... +.RB [ "\-I\fIdirectory" ] +\&... +.RB [ \-.o ] +\&... +.RB [ \-c ] +.RB [ \-E ] +.RB [ \-P ] +.RB [ \-S ] +.RB [ \-c.\fIsuffix ] +.RB [ \-O ] +.RB [ \-O\fIlevel ] +.RB [ \-n ] +.RB [ \-a ] +.RB [ \-R ] +.RB [ \-A ] +.RB [ \-s ] +.RB [ \-f ] +.RB [ \-w ] +.RB [ \-wo ] +.RB [ \-ws ] +.RB [ \-wa ] +.RB [ \-3 ] +.RB [ \-_ ] +\&... +.RB [ \-m ] +.RB [ "\-o \fIoutfile" ] +.RB [ "\-L\fIdirectory" ] +\&... +.RB [ \-i ] +.RB [ \-sep ] +.RB [ \-com ] +.I operand +\&... +.in -.5i +.SH DESCRIPTION +.BR Cc , +.BR pc , +and +.BR m2 +are the call names of the Minix C, Pascal, and Modula-2 compilers from +the Amsterdam Compiler Kit (ACK). +.PP +All these call names are links to the +.B acd +driver program. +.B Acd +uses the driver description file +.B /usr/lib/descr +that describes the steps necessary to compile a source file. The +.BR acd (1) +manual page describes a few more flags, like +.BR \-v , +that may be useful for debugging compiler problems. +.PP +Minix-86 uses a C program as the compiler driver. This driver is not as +flexible as the one implemented with the +.B acd +driver, and offers a smaller number of options. The second line of +the synopsis above shows the options that the Minix-86 driver supports. The +rest of this manual page is geared towards the +.B acd +driver. People writing software for Minix-86, or that should be +portable to all Minix versions should stick to the options listed under +the Minix-86 compiler. +.SH OPTIONS +The transformations done by the compiler are modified by the following +options. They are a superset of the options required by \s-2POSIX\s+2, +with the Minix or compiler specific ones are marked as such. Options +for one specific compiler are ignored for others. Read the OPTIONS section +of +.BR acd (1) +for the driver specific options. +.PP +.TP +.BI \-D " name\fR[\fB=\fIvalue\fR]" +Same as if +.BI #define " name value" +had been given. +.B 1 +is assumed if +.I value +is omitted. This argument, like all the other double arguments, may also +be given as a single argument. (I.e. either as +.BI \-D "\0name" +or +.BI \-D name\fR.) +(The Minix-86 driver is not so flexible, the proper form can be seen in +the synopsis.) +.TP +.BI \-U " \fIname" +Undefine the pre-defined symbol +.IR name . +.TP +.BI \-I " directory" +Extend the include directory path with the given directory. These +directories are searched for include files in the given order before the +standard places. The standard place for the C compiler is +.BR /usr/include , +and for the Modula-2 compiler it is +.BR /usr/lib/m2 . +.TP +.BI \-. suffix +Act as if a source file with the given suffix is present on the command line. +For each language found on the command line the appropriate libraries are +selected. The first language mentioned selects the runtime startoff. +The call name of the driver also chooses the language, so \fBcc\fP is an +implicit +.BR \-.c . +The runtime startoff can be omitted by specifying +.B \-.o +for those rare cases where you want to supply your own startoff. (Minix) +.TP +.B \-c +Transform the input files to object files and stop. The +.B \-o +option may be used under Minix to set the name of the object file. +.BR Make (1) +likes this, because +.BI "cc \-c" " dir/file" .c +puts +.IB file .o +in the current directory, but +.BI "cc \-c" " dir/file" .c +.BI \-o " dir/file" .o +puts the +.B .o +file where +.B make +expects it to be by its builtin +.B .c.o +rule. +(Minix-86 can only use +.B \-o +to name an executable.) +.TP +.B \-E +Run the preprocessor over the input files and send the result to standard +output or the file named by +.BR \-o . +Standard input is read if an input file is named "\fB\-\fR". +.TP +.B \-P +Run the preprocessor over the input files and put the result to files +with the suffix +.BR .i . +File and line number information is omitted from the output. Use +.B \-P \-E +under Minix to omit this info for +.B \-E +too. +.TP +.B \-S +Transform the input files to assembly files with suffix +.BR .s . +.TP +.BI \-c. suffix +Transform the input files to files with the given suffix. This can only +succeed if there is a valid transformation from the input file to the +given suffix. The same goes for +.B \-c +and other options that are just special cases of this option, except for +.BR \-P , +.B \-c.i +keeps the line number info. The option +.B \-c.a +makes the driver transform the input files to object files and add them to a +library. (So you do not need to know how the archiver works.) Note that you +need to give object files as arguments if you want to replace old object +files. Transformed files are added under a (unique) temporary name. With +.B \-o +you can name the library. (Minix) (Minix-86 can't do +.BR \-c.a .) +.TP +.B \-O +Optimize code. This option is a no-op, because all the compilers already +use the +.BR \-O1 +optimization level to get code of reasonable quality. Use +.BR \-O0 +to turn off optimization to speed up compilation at debug time. +.TP +.BI \-O level +Compile with the given optimization level. (Minix) +.PP +.B \-OS +.br +.B \-OT +.RS +Optimize for space or for time. (Minix) +.RE +.TP +.B \-g +Compile the C source with debugging information. (The way +.BR \-g , +.B \-s +and +.B \-O +interact is left unspecified.) +.TP +.B \-n +Omit the file and line number tracking that is used for runtime error reports +from Pascal or Modula-2 programs. The +.B \-n +flag is normally used to compile library modules, but may also be useful to +make a program smaller and faster once debugged. (Pascal & Modula-2) +.TP +.B \-a +Enable assertions, i.e. statements of the form \fBassert\fI\ test\fR +that cause a descriptive runtime error if the boolean expression +.I test +evaluates false. (Pascal & Modula-2) +.TP +.B \-R +Disable runtime checks like overflow checking. (Pascal & Modula-2) +.TP +.B \-A +Enable array bound checks. (Pascal & Modula-2) +.TP +.B \-s +Strip the resulting executable of its symbol table. +.PP +.B \-fsoft +.br +.B \-f +.RS +Use software floating point instead of hardware floating point. This is +a loader flag, but in general it is best to specify this flag in all +phases of the compilation. (Minix) +.RE +.TP +.B \-fnone +Ignored. Used under Minix-vmd to omit floating point printing/scanning +code. The standard Minix compiler figures this out automatically using +a special loader trick. (Minix) +.TP +.B \-w +Do not produce warnings about dubious C language constructs. Normally +the compiler is configured to do the maximum amount of checking +without being too annoying. (Minix) +.TP +.B \-wo +Omit warnings about old (K&R) style. (Minix) +.TP +.B \-ws +Omit strict warnings. (Minix) +.TP +.B \-wa +Omit all warnings. (Minix) +.TP +.B \-3 +Only accept 3rd edition Modula-2. (Modula-2) +.TP +.B \-_ +Allow underscores in Pascal or Modula-2 identifiers, but not at the beginning +of an identifier. (Pascal & Modula-2) +.TP +.BI \-W name \- option +If +.I name +is the name of the compiler this driver is working for, then +.I option +is activated for that compiler. See below for a per-compiler list. Any other +.B \-W +option is ignored. (\fB\-W\fP is described by \s-2POSIX\s+2 as an optional +flag to send options to the different compiler passes with a totally +different (and nicely ignored) syntax as described here.) (Minix-86 ignores +any +.B \-W +flag.) +.TP +.B \-m +Under Minix-86 this option transforms the function declarations (prototypes) +to the old K&R form, i.e. the arguments declarations are removed. This saves +a lot of memory in the compiler and may allow a large program to be compiled. +One must make sure that function arguments are properly type-cast where +necessary. (Minix) +.TP +.BI \-m arch +Set the target architecture for a cross compiler. Normally the compiler +produces code for the same architecture it itself is compiled for. The +.B ARCH +environment variable may also be used to set the architecture. Architectures +names are: +.B i86 +(Intel 8086 and 286), +.B i386 +(Intel 386, 486, ...), +.B m68000 +(Motorola MC68000 & MC68010, 16-bit ints), +.B m68010 +(Motorola MC68000 & MC68010, 32-bit ints), +.B m68020 +(Motorola MC68020, 32-bit ints), +.B sparc +(Sun SPARC). (Minix) (Ignored under Minix-86.) +.TP +.BI \-o " outfile" +Set the output file for the +.BR \-c , +.BR \-c.a , +and +.BR \-E +options, or choose the executable name instead of the default +.BR a.out . +(Minix-86 can only choose the executable name.) +.TP +.BI \-L " directory" +Extend the library search path with +.IR directory . +These directories are searched for libraries named by +.B \-l +in the given order before the standard places. The standard places are +.B /lib/\c +.IR arch , +and +.B /usr/lib/\c +.IR arch . +The search for libaries in directories added with +.B \-L +looks in +.IB directory /\c +.IR arch +and +.I directory +itself. +.RI ( Arch +is the machine architecture name. This is +Minix dependent, compilers on other systems usually only look in +.IR directory .) +(Minix-86 only has +.B /lib +and +.B /usr/lib +as the standard places.) +.PP +.B \-sep +.br +.B \-com +.RS +Create a Separate I&D or a common I&D executable. The text segment of a +separate I&D executable is read-only and shareable. For an +.B i86 +binary this also means that the text and data segment can each be 64 +kilobytes large instead of just 64 kilobytes together. Separate I&D is the +default. Common I&D is probably only useful for the bootstraps. The +.B \-i +option has the same meaning as +.BR \-sep , +but should no longer be used. +(Minix) +.RE +.TP +.B \-r +Makes the loader produce a relocatable object file, i.e. a file that +may be loaded again. The runtime startoff and the default libraries are +omitted, only the files mentioned are combined. (Minix) +.TP +.BI \-stack " size" +Allow the process +.I size +bytes of heap and stack. +.I Size +is a C-style decimal, octal, or hexadecimal number, optionally followed by +the multipliers +.BR m , +.BR k , +.BR w , +and +.B b +for mega (1024*1024), kilo (1024), "word" (2 or 4), and byte (1). Uppercase +letters are accepted too. A size of +.B 32kw +is used by default, translating to 64k for +.BR i86 , +and 132k for other architectures. Too large a size is rounded down to keep +the data segment within 64 kilobytes for the +.BR i86 . +(Minix) +.SH OPERANDS +All leftover operands are treated as files to be compiled, with one +exception. The construct +.BI \-l " library" +is used to denote a library, usually +.BI lib library .a\fR, +that is to be searched in the directories mentioned with +.B \-L +or the standard places. These libraries keep their place among the +(transformed) input files when presented to the loader. (It is a common +mistake to write +.BR "cc\ \-lcurses\ x.c" +instead of +.BR "cc\ x.c\ \-lcurses" .) +.SH IMPLEMENTATION +The Minix compiler implementation uses the ACK compilers adapted for use +under Minix as described below. Read +.BR ACK (7) +for more detailed information on the ACK compilers themselves. +.SS "Feature test macros" +The preprocessors are given these arguments to define feature test macros: +.B \-D__ACK__ +tells what compiler is used. +.B \-D__minix +tells that this is Minix. +.BI \-D__ arch +tells the architecture. +(More macros are defined, but they are only to be used in the include files.) +.PP +The symbols above are predefined by the preprocessor so that your program is +able to "sense" the environment it is in. It is also possible for your +program to do the opposite, to tell what kind of environment it likes to +have. By default, +.B cc +compiles a standard C program. If you want the extensions described in +POSIX.1 to become visible, then you have to set +.BR _POSIX_SOURCE " to " 1 +at the start of your program. +To enable \s-2UNIX\s+2 or Minix extensions you need to also set +.BR _MINIX " to " 1 . +If you don't want to clutter your source files with these symbols then you +can use +.B cc \-D_MINIX \-D_POSIX_SOURCE +to get the POSIX.1 and the Minix extensions. +.SS "Preprocessing" +Pascal, Modula-2, EM source (see below), and Assembly source are +preprocessed by the C preprocessor if the very first character in the file +is a '\fB#\fP' character. +.SS "Assembly dialects" +No two compilers use the same assembly language. To be able to use the same +assembly dialect for the low level support routines an assembly converter is +provided. The input of this converter can be of type +.BR ack , +.BR ncc , +or +.BR bas , +and the output can be of type +.BR ack , +.BR ncc , +or +.BR gnu . +The suffix of the file tells the assembly dialect (see below), or one can +use the option +.BI \-Was\- dialect +to tell the driver what the dialect of a plain +.B .s +file is. The assembly converter is not as smart as the assembler, the +translation is more or less a text substitution. It leaves a lot of +checking to the target assembler. You have to restrict yourself to a subset +that is understood by both assemblers. The ACK assembler for instance +doesn't care if you use `ax' or `eax' for a 32 bit register, it looks at the +instruction type. The GNU assembler doesn't like this, so you have to use +the proper register name in ACK assembly that is to be translated to GNU +assembly. Expressions are converted as is, even if the operator precedence +rules of the two assembly languages differ. So use parentheses. The +converter does promise one thing: compiler output can be properly +translated. (Note that under Minix-86 +.B \-W +is ignored. All assembly should therefore be in the "ncc" dialect.) +.SH FILES +.TP 10 +.B /usr/lib/descr +The compiler description file. +.TP +.B .c +Suffix of a C source file. +.TP +.B .mod +Modula-2. +.TP +.B .p +Pascal. +.TP +.B .i +Preprocessed C source. +.TP +.B .k +ACK machine independent compact EM code produced by the C, Pascal, or +Modula-2 front end (or any other ACK front end.) The ACK compilers are +based on the UNCOL idea where several front ends compile to a common +intermediate language, and several back ends transform the intermediate +language to the target machine language. The ACK intermediate language +is named "EM". +.TP +.B .m +Peephole optimized EM. +.TP +.B .gk +Result of the (optional) EM global optimizer. +.TP +.B .g +Result of the second EM peephole optimizer used after the global optimizer. +.TP +.B .e +Human readable EM. (Human created or decoded compact EM.) +.TP +.B .s +Target machine assembly. (Current compiler dialect.) +.TP +.B .ack.s +ACK assembly. +.TP +.B .ncc.s +ACK Xenix style assembly. This dialect is used by the 16 bit ACK ANSI C +compiler. +.TP +.B .gnu.s +GNU assembly. +.TP +.B .bas.s +BCC assembly. (Used by the Bruce Evans' BCC compiler, for many years the +compiler for Minix-386.) +.TP +.B .o +Object code. +.TP +.B .a +Object code library. +.TP +.B a.out +Default output executable. +.SH "SEE ALSO" +.BR acd (1), +.BR ACK (7). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/cdiff.1 b/man/man1/cdiff.1 new file mode 100644 index 000000000..9f9e99e03 --- /dev/null +++ b/man/man1/cdiff.1 @@ -0,0 +1,31 @@ +.TH CDIFF 1 +.SH NAME +cdiff \- context diff +.SH SYNOPSIS +\fBcdiff\fR [\fB\-c\fIn\fR] \fIoldfile \fInewfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Provide \fIn\fR lines of context" +.SH EXAMPLES +.EX "cdiff old new >f" "Write context diff on \fIf\fR" +.EX "cdiff \-c1 old new >f" "Use only 1 line of context" +.SH DESCRIPTION +.PP +\fICdiff\fR produces a context diff by first running \fIdiff\fR and then +adding context. +Some update programs, like \fIpatch\fR, can use context diffs to update +files, even in the presence of other, independent changes. +.SH "SEE ALSO" +.BR cmp (1), +.BR diff (1), +.BR patch (1). diff --git a/man/man1/cgrep.1 b/man/man1/cgrep.1 new file mode 100644 index 000000000..4f2ce3dc1 --- /dev/null +++ b/man/man1/cgrep.1 @@ -0,0 +1,33 @@ +.TH CGREP 1 +.SH NAME +cgrep \- grep and display context +.SH SYNOPSIS +\fBcgrep\fR [\fB\-a \fIn\fR]\fR [\fB\-b \fIn\fR] [\fB\-f\fR] [\fB\-l \fIn\fR] [\fB\-n\fR] [\fB\-w \fIn\fR] \fIpattern\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "How many lines to display after the matching line" +.FL "\-b" "How many lines to display before the matching line" +.FL "\-f" "Suppress file name in the output" +.FL "\-l" "Lines are truncated to this length before comparison" +.FL "\-n" "Suppress line numbers in the output" +.FL "\-w" "Sets window size (same as \fB\-a\fR n \fB\-b\fR n)" +.SH EXAMPLES +.EX "cgrep \-w 3 hello file1" "Print 3 lines of context each way" +.SH DESCRIPTION +.PP +\fICgrep\fR is a program like \fIgrep\fR, except that it also can print +a few lines above and/or below the matching lines. +It also prints the line numbers of the output. +.SH "SEE ALSO" +.BR grep (1), +.BR fgrep (1). diff --git a/man/man1/chgrp.1 b/man/man1/chgrp.1 new file mode 100644 index 000000000..4b6b32432 --- /dev/null +++ b/man/man1/chgrp.1 @@ -0,0 +1,38 @@ +.TH CHGRP 1 +.SH NAME +chgrp \- change group +.SH SYNOPSIS +\fBchgrp [\fB\-R\fR] [\fIowner:\fR]\fIgroup \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-R" "Change directory hierarchies" +.SH EXAMPLES +.EX "chgrp system file1 file2" "Make \fIsystem\fR the group of the files" +.EX "chrgp \-R other dir1" "Make \fIother\fR the group of all files below dir1" +.SH DESCRIPTION +.PP +The group field (and optionally owner field) of the named files is changed to +.I group +and +.I owner . +Alternatively, a decimal gid (uid) may be specified instead of a group name. +If the \fB\-R\fR flag is used, the changes will be applied recursively to +all files in named directories. Only the superuser may execute this command +to set arbitrary groups. Normal users can only change the group if they own +the file, and the group is their own group (Minix), or one of their +supplementary groups (Minix-vmd). +.SH "SEE ALSO" +.BR chown (8), +.BR chmod (1), +.BR ls (1), +.BR chown (2). diff --git a/man/man1/chmem.1 b/man/man1/chmem.1 new file mode 100644 index 000000000..f3da10234 --- /dev/null +++ b/man/man1/chmem.1 @@ -0,0 +1,65 @@ +.TH CHMEM 1 +.SH NAME +chmem \- change memory allocation +.SH SYNOPSIS +\fBchmem\fR [\fB+\fR]\fR [\fB\-\fR] [\fB=\fR] \fIamount file\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "chmem =50000 a.out" "Give \fIa.out\fP 50K of stack space" +.EX "chmem \-4000 a.out" "Reduce the stack space by 4000 bytes" +.EX "chmem +1000 file1" "Increase each stack by 1000 bytes" +.SH DESCRIPTION +.PP +When a program is loaded into memory, it is allocated enough memory +for the text and data+bss segments, plus +an area for the stack. +Data segment growth using +.I malloc , +.I brk , +or +.I sbrk +eats up stack space from the low end. +The amount of stack space to allocate is derived +from a field in the executable program's file header. +If the combined stack and data segment growth exceeds the stack space +allocated, the program will be terminated. +.PP +It is therefore important to set the amount of stack space carefully. +If too little is provided, the program may crash. +If too much is provided, memory will be wasted, and fewer programs will be able +to fit in memory and run simultaneously. +\s-2MINIX\s+2 +does not swap, so that when memory is full, subsequent attempts to fork will +fail. +The compiler sets the stack space +to the largest possible value (for the Intel CPUs, 64K \- text \- data). +For many programs, this value is far too large. +Nonrecursive programs that do not call +.I brk , +.I sbrk , +or +.I malloc , +and do not have any local arrays usually do not need more than 8K of stack +space. +.PP +The +.I chmem +command changes the value of the header field that determines the stack allocation, and +thus indirectly the total memory required to run the program. +The = option sets the stack size +to a specific value; the + and \- options increment and decrement the +current value by the indicated amount. +The old and new stack sizes are printed. +.SH "SEE ALSO" +.BR install (1), +.BR brk (2). diff --git a/man/man1/chmod.1 b/man/man1/chmod.1 new file mode 100644 index 000000000..ee1dc4296 --- /dev/null +++ b/man/man1/chmod.1 @@ -0,0 +1,62 @@ +.TH CHMOD 1 +.SH NAME +chmod \- change access mode for files +.SH SYNOPSIS +\fBchmod [\fB\-R\fR] \fImode \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-R" "Change hierarchies recursively" +.SH EXAMPLES +.EX "chmod 755 file" "Owner: rwx Group: r\-x Others: r\-x" +.EX "chmod +x file1 file2" "Make \fIfile1\fR and \fIfile2\fR executable" +.EX "chmod a\-w file" "Make \fIfile\fR read only" +.EX "chmod u+s file" "Turn on SETUID for \fIfile\fR" +.EX "chmod \-R o+w dir" "Allow writing for all files in dir" +.SH DESCRIPTION +.PP +The given mode is applied to each file in the file list. If the \fB\-R\fR +flag is present, the files in a directory will be changed as well. +The mode can be either absolute or symbolic. Absolute modes are given as an +octal number that represents the new file mode. The mode bits are defined as +follows: +.ta 0.25i +.nf +.PP + 4000 Set effective user id on execution to file's owner id + 2000 Set effective group id on execution to file's group id + 0400 file is readable by the owner of the file + 0200 writeable by owner + 0100 executable by owner + 0070 same as above, for other users in the same group + 0007 same as above, for all other users +.PP +.fi +Symbolic modes modify the current file mode in a specified way. The form is: +.PP + [who] op permissions { op permissions ...} {, [who] op ... } +.PP +The possibilities for \fIwho\fR are \fIu\fR, \fIg\fR, \fIo\fR, and \fIa\fR, +standing for user, group, other and all, respectively. +If \fIwho\fR is omitted, \fIa\fR is assumed, but the current umask is used. +The op can be \fI+\fR, \fI-\fR, or \fI=\fR; \fI+\fR turns on the +given permissions, \fI\- \fRturns them off; \fI=\fR sets the permissions +exclusively for the given \fIwho\fR. +For example \fIg=x\fR sets the group permissions to \fI--x\fR. +.PP +The possible permissions are \fIr\fR, \fIw\fR, \fIx\fR; which stand for read, +write, and execute; \fIs\fR turns on the set effective user/group id bits. +\fIs\fR only makes sense with \fIu\fR and \fIg\fR;\fR o+s\fR is +harmless. +.SH "SEE ALSO" +.BR ls (1), +.BR chmod (2). diff --git a/man/man1/cksum.1 b/man/man1/cksum.1 new file mode 100644 index 000000000..671e5a7e7 --- /dev/null +++ b/man/man1/cksum.1 @@ -0,0 +1,34 @@ +.TH CKSUM 1 +.SH NAME +cksum \- display file checksum and size +.SH SYNOPSIS +\fBcksum \fR[\fIfile\fR ...]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "cksum" "Display CRC and size of \fIstdin\fR" +.EX "cksum *.c" "Display CRC and size of \fI.c\fP files" +.SH DESCRIPTION +.PP +.I Cksum +calculates and writes to standard output the 32-bits CRC of the input +.I files , +or of stdin if no +.I files +were specified. The size in bytes of each +.I file +will be displayed after a space. The name of each +.I file +will be displayed after another space. +.SH "SEE ALSO" +.BR crc (1), +.BR sum (1). diff --git a/man/man1/clear.1 b/man/man1/clear.1 new file mode 100644 index 000000000..c90a55bae --- /dev/null +++ b/man/man1/clear.1 @@ -0,0 +1,17 @@ +.TH CLEAR 1 +.SH NAME +clear, clr \- clear the screen +.SH SYNOPSIS +.B clear +.br +.B clr +.SH DESCRIPTION +.B Clear +or its synonym +.B clr +clears the screen. It is exactly equivalent to +.BR "tget -str cl" . +.SH "SEE ALSO" +.BR tget (1). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/cmp.1 b/man/man1/cmp.1 new file mode 100644 index 000000000..bc34c341b --- /dev/null +++ b/man/man1/cmp.1 @@ -0,0 +1,34 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +\fBcmp\fR [\fB\-ls\fR] \fIfile1 file2\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-l" "Loud mode. Print bytes that differ (in octal)" +.FL "\-s" "Silent mode. Print nothing, just return exit status" +.SH EXAMPLES +.EX "cmp file1 file2" "Tell whether the files are the same" +.EX "cmp \-l file1 file2" "Print all corresponding bytes that differ" +.SH DESCRIPTION +.PP +Two files are compared. +If they are identical, exit status 0 is returned. +If they differ, exit status 1 is returned. +If the files cannot be opened, exit status 2 is returned. +If one of the file arguments is \-, then +\fIstdin\fR is compared to +the other file. +.SH "SEE ALSO" +.BR comm (1), +.BR diff (1). diff --git a/man/man1/comm.1 b/man/man1/comm.1 new file mode 100644 index 000000000..b68460848 --- /dev/null +++ b/man/man1/comm.1 @@ -0,0 +1,39 @@ +.TH COMM 1 +.SH NAME +comm \- print lines common to two sorted files +.SH SYNOPSIS +\fBcomm\fR [\fB\-123\fR] \fIfile1 file2\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-1" "Suppress column 1 (lines present only in \fIfile1\fP)" +.FL "\-2" "Suppress column 2 (lines present only in \fIfile2\fP)" +.FL "\-3" "Suppress column 3 (lines present in both files)" +.SH EXAMPLES +.EX "comm file1 file2" "Print all three columns" +.EX "comm \-12 file1 file2" "Print only lines common to both files" +.SH DESCRIPTION +.PP +Two sorted files are read and compared. +A three column listing is produced. +Files only in +.I file1 +are in column 1; +files only in +.I file2 +are in column 2; +files common to both files are in column 3. +The file name \- means \fIstdin\fR. +.SH "SEE ALSO" +.BR cmp (1), +.BR diff (1), +.BR sort (1). diff --git a/man/man1/compress.1 b/man/man1/compress.1 new file mode 100644 index 000000000..833430375 --- /dev/null +++ b/man/man1/compress.1 @@ -0,0 +1,42 @@ +.TH COMPRESS 1 +.SH NAME +compress, uncompress, zcat \- compress a file using modified Lempel-Ziv coding +.SH SYNOPSIS +\fBcompress\fR [\fB\-cdfv\fR]\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Put output on \fIstdout\fR instead of on \fIfile.Z\fR" +.FL "\-d" "Decompress instead of compress" +.FL "\-f" "Force output even if there is no saving" +.FL "\-v" "Verbose mode" +.SH EXAMPLES +.EX "compress outfile" "Compress 1 file" +.EX "compress x y z" "Compress 3 files to \fIx.Z\fR, \fIy.Z\fR, and \fIz.Z\fR" +.EX "compress \-d file.Z" "Decompress \fIfile.Z\fR to \fIfile\fR" +.SH DESCRIPTION +.PP +The listed files (or \fIstdin\fR, if none are given) are compressed +using the Ziv-Lempel algorithm. If the output is smaller than the input, +the output is put on \fIfile.Z\fR or \fIstdout\fR if no files are listed. +If \fIcompress\fR is linked to \fIuncompress\fR, the latter is the same +as giving the \fB\-d\fP flag. +Similarly, a link to \fIzcat\fR decompresses to \fIstdout\fR. +The +\s-2MINIX\s+2 +version of \fIcompress\fR uses 13-bit compression. +This means that when compressing files on other systems for transmission to +\s-2MINIX\s+2, +be sure that only 13-bit compression is used. +On many systems, the default is 16-bit (too big). +.SH "SEE ALSO" +.BR tar (1). diff --git a/man/man1/cp.1 b/man/man1/cp.1 new file mode 100644 index 000000000..511628b99 --- /dev/null +++ b/man/man1/cp.1 @@ -0,0 +1,223 @@ +.TH CP 1 +.SH NAME +cp, mv, rm, ln, cpdir, clone \- copy, move, remove, link +.SH SYNOPSIS +.B cp +.RB [ \-pifsmrRvx ] +.I file1 file2 +.br +.B cp +.RB [ \-pifsrRvx ] +.IR file " ... " dir +.PP +.B mv +.RB [ \-ifsmvx ] +.I file1 file2 +.br +.B mv +.RB [ \-ifsvx ] +.IR file " ... " dir +.PP +.B rm +.RB [ \-ifrRvx ] +.IR file " ..." +.PP +.B ln +.RB [ \-ifsSmrRvx ] +.I file1 file2 +.br +.B ln +.RB [ \-ifsSrRvx ] +.IR file " ... " dir +.PP +.B cpdir +.RB [ \-ifvx ] +.I file1 file2 +.PP +.B clone +.RB [ \-ifsSvx ] +.I file1 file2 +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The utilities +.BR cp , +.BR mv , +.BR rm , +and +.B ln +do basic file management: copying, renaming or moving, deletion, and +creating links. (The +.B cpdir +and +.B clone +utilities are easy to use aliases for copying or linking whole trees. +They are the same as +.B cp \-psmr +and +.BR "ln \-fmr" ) +.PP +The first synopsis form of the utilities +.BR cp , +.BR mv , +and +.B ln +is used if only two arguments are given, and the second argument is not a +directory. The source and target file are then the two files given. +.PP +If the second synopsis form is used then the last argument must be a +directory. Each of the files is copied, moved or linked into this directory. +.PP +A file is by default copied by +.B cp +without looking at its type, so symlinks are followed and devices are opened +and read from or written to. Links between files are ignored. This +behavior can be changed by using the proper options. +.PP +The +.B mv +utility uses the +.BR rename (2) +call to rename or move files. If source and target are on different devices +however, then +.B mv +will use +.B cp \-pr +to copy the files or directory trees. +.PP +Each utility continues with the next file on errors, except on I/O errors. +.SH OPTIONS +.TP +.B \-p +Copy the file attributes like mode, owner, group and time of last +modification. Normally only the mode is copied to a new file with the file +creation mask applied. Setuid bits are cleared if setting the ownership +fails. +.TP +.B \-i +Ask if ok to overwrite, replace or remove. +.B Mv +and +.B rm +will ask this automatically if interactive and the target file is writable. +.B Cp +will fail if the target cannot be written, +.B ln +will always fail if the target exists. +.TP +.B \-f +Makes +.B cp +remove a target file before copying if it is not writable, +.B mv +removes an existing target without asking, +.B rm +does not report any errors, and +.B ln +removes an existing target file before linking. The last of +.B \-i +and +.B \-f +wins for +.B mv +if both flags are set, the other utilities do something sensible, like asking +before forcefully removing. +.TP +.B \-s +Make a symlink instead of a normal link. For utilities other than +.B ln +this flag means "copy similar". The modified time is always copied for +.B cp \-s +and the other attributes are copied if a new file is created. The normal +\s-2POSIX\s+2 required patronizing like applying the file creation mask or +clearing setuid bits is not done. +.TP +.B \-S +Make a symlink if a normal link cannot be made because source and target are +on different devices. The symlink is required to really refer back to the +source, meaning that a/b must exist in the call +.BR "ln \-S a/b c/d" , +and that the symlink from c/d must lead back to a/b. So the symlink will be +created as if +.B "ln \-s ../a/b c/d" +was called. If the target is a full path, but the source is not then an +error will be given saying that this is "too difficult." +.TP +.B \-m +Merge trees. The first synopsis form is assumed, and the files from one +tree are merged into the other. There is no "if it's a directory the put +it into that directory" trickery here. +.TP +.BR \-r ", " \-R +Recursively copy, remove, or link. If the source is a directory then the +files in this directory are copied to similarly named files in the target +directory. Special files are copied as new special files, they are not read +or written. Symlinks are still expanded and the link structure ignored with +.BR \-R . +The +.B \-r +flag does copy symlinks as symlinks and keeps the link structure intact. +(Note that +.B \-R +is invented by \s-2POSIX\s+2 as a replacement for the classic +.B \-r +option of older copy commands that did read special files. The standard +says that +.B \-r +is implementation defined, so that's why this flag is better than +.B \-R +in this implementation of +.BR cp .) +For +.B rm +and +.B ln +both flags mean the same. +.B Ln +will recursively link the files in the trees, except symlinks, they are +copied. If symlinks are created with +.B ln \-rs +or +.B ln \-rS +then they are required "to work" as described with the +.B \-S +flag. +.TP +.B \-v +Verbose. Show what is done on standard output. +.TP +.B \-x +Do not cross mount points. Empty directories will be created if the source +directory is a mount point on a copy, move or link. A mount point will not +be removed or traversed recursively. This flag allows one to copy the root +device, e.g. +.BR "cpdir \-x / /mnt" . +.SH "SEE ALSO" +.BR cat (1), +.BR mkdir (1), +.BR rmdir (1), +.BR mkdir (2), +.BR rmdir (2), +.BR link (2), +.BR unlink (2), +.BR rename (2), +.BR open (2), +.BR read (2), +.BR write (2), +.BR opendir (3). +.SH NOTES +All the utilities described are links to the same program. +.SH BUGS +.B Mv +should first copy a tree across devices and then remove the source tree if +there was no error. Instead, each file in the tree is copied and +immediately removed. On error you may be left with two half-filled trees, +together containing all of the files. You may have to restart the move with +.BR "mv \-m" . +.PP +.B Rm +should be able to remove arbitrarily deep trees. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/crc.1 b/man/man1/crc.1 new file mode 100644 index 000000000..b81617b8a --- /dev/null +++ b/man/man1/crc.1 @@ -0,0 +1,29 @@ +.TH CRC 1 +.SH NAME +crc \- print the checksum of the file data +.SH SYNOPSIS +\fBcrc \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "crc *.c" "Print checksums of all the C programs" +.SH DESCRIPTION +.PP +The checksum of each argument is computed and printed, along with the file +length and its name, one file per line. +This program is useful for seeing if a file transmitted to another machine +has arrived correctly. +It is conceptually similar to \fIsum\fR, except that it uses a stronger +checksum algorithm and also prints the length. +.SH "SEE ALSO" +.BR cksum (1), +.BR sum (1). diff --git a/man/man1/crontab.1 b/man/man1/crontab.1 new file mode 100644 index 000000000..3f57fbc0f --- /dev/null +++ b/man/man1/crontab.1 @@ -0,0 +1,93 @@ +.TH CRONTAB 1 +.SH NAME +crontab \- User crontab manipulation +.SH SYNOPSIS +.B crontab \-c +.RI [ user ] +.I file +.br +.B crontab \-l +.RI [ user ] +.br +.B crontab \-r +.RI [ user ] +.br +.B crontab \-p +.SH DESCRIPTION +The +.B crontab +program allows users to manipulate their personal crontab files. These +files are hidden in +.BI /usr/spool/crontabs/ user +where +.I user +is the login name of a given user. The system daemon +.B cron +uses these crontabs, among others, to run tasks that are to be repeated at +regular intervals. See +.BR crontab (5) +on what a good crontab file should look like. +.PP +Only the superuser can specify a user name to manipulate the crontab of a +given user. Any other user can only touch their own crontab file. +.SH OPTIONS +.TP +\fB\-c\fR [\fIuser\fR] \fIfile\fR +Install +.I file +as the crontab file of +.IR user . +.TP +\fB\-l\fR [\fIuser\fR] +List the crontab file of +.I user +to standard output. +.TP +\fB\-r\fR [\fIuser\fR] +Remove the crontab file of +.IR user . +.TP +\fB\-p\fR +Tell cron to reload its tables. Useful for system administrators to signal +a change to any of the system crontab files. Changes made by the +.B crontab +program are signalled automatically. (Mnemonic: \-p = "ping".) +.SH FILES +.TP \w'/usr/spool/crontabs/user'u+5n +.BI /usr/spool/crontabs/ user +Per user personal crontab file. +.SH "SEE ALSO" +.BR crontab (5), +.BR cron (8). +.SH DIAGNOSTICS +.B Crontab +preparses a new crontab and only installs it if correct. All errors are +sent to standard error, messages about installing a new table and telling +.B cron +to reload are sent to standard output. +.SH BUGS +.B Crontab +misses a +.B \-e +option that other implementations of this command allow one to edit the +current crontab and install the result. Seems quite handy until you try to +install a new crontab from an automated script. That's why this command +has a +.B \-c +option that installs a prepared crontab file. Use +.PP +.RS +.nf +crontab \-l >/tmp/tab +${EDITOR\-vi} /tmp/tab +crontab \-c /tmp/tab +.fi +.RE +.PP +to get the same effect as +.BR "crontab \-e" . +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: crontab.1,v 1.3 2000/07/17 18:51:04 philip Exp $ diff --git a/man/man1/ctags.1 b/man/man1/ctags.1 new file mode 100644 index 000000000..7aa317586 --- /dev/null +++ b/man/man1/ctags.1 @@ -0,0 +1,84 @@ +.TH CTAGS 1 +.SH NAME +ctags - Generates "tags" and (optionally) "refs" files +.SH SYNOPSIS +\fBctags\fP [\fB-stvra\fP] \fIfilesnames\fP... +.SH DESCRIPTION +\fIctags\fP generates the "tags" and "refs" files +from a group of C source files. +The "tags" file is used by Elvis' ":tag" command, +control-] command, +and -t option. +The "refs" file is sometimes used by the \fIref(1)\fP program. +.PP +Each C source file is scanned for #define statements and +global function definitions. +The name of the macro or function becomes the name of a tag. +For each tag, a line is added to the "tags" file which contains: +.RS +.nf + - the name of the tag + - a tab character + - the name of the file containing the tag + - a tab character + - a way to find the particular line within the file. +.RE +.fi +.PP +The filenames list will typically be the names of all C source +files in the current directory, like this: +.RS +.nf +$ ctags -stv *.[ch] +.RE +.fi +.SH OPTIONS +.IP \fB-t\fR +Include typedefs. +A tag will be generated for each user-defined type. +Also tags will be generated for struct and enum names. +Types are considered to be global if they are defined in a header file, +and static if they are defined in a C source file. +.IP \fB-v\fR +Include variable declarations. +A tag will be generated for each variable, except for those that are declared +inside the body of a function. +.IP \fB-s\fR +Include static tags. +\fICtags\fR will normally put global tags in the "tags" file, and silently ignore +the static tags. +This flag causes both global and static tags to be added. +The name of a static tag is generated by prefixing the name of the declared +item with the name of the file where it is defined, with a colon in between. +For example, "static foo(){}" in "bar.c" results in a tag named "bar.c:foo". +.IP \fB-r\fP +This causes \fIctags\fP to generate both "tags" and "refs". +Without \fB-r\fP, it would only generate "tags". +.IP \fB-a\fR +Append to "tags", and maybe "refs". +Normally, \fIctags\fR overwrites these files each time it is invoked. +This flag is useful when you have to many files in the current directory +for you to list them on a single command-line; +it allows you to split the arguments among several invocations. +.SH FILES +.IP tags +A cross-reference that lists each tag name, the name of the source file that +contains it, and a way to locate a particular line in the source file. +.IP refs +The "refs" file contains the definitions for each tag in the "tags" file, +and very little else. +This file can be useful, for example, when licensing restrictions prevent +you from making the source code to the standard C library readable by everybody, +but you still everybody to know what arguments the library functions need. +.SH BUGS +.PP +\fIctags\fR is sensitive to indenting and line breaks. +Consequently, it might not discover all of the tags in a file that +is formatted in an unusual way. +.SH "SEE ALSO" +elvis(1), refs(1) +.SH AUTHOR +.nf +Steve Kirkendall +kirkenda@cs.pdx.edu +.fi diff --git a/man/man1/cut.1 b/man/man1/cut.1 new file mode 100644 index 000000000..63a580832 --- /dev/null +++ b/man/man1/cut.1 @@ -0,0 +1,46 @@ +.TH CUT 1 +.SH NAME +cut \- select out columns of a file +.SH SYNOPSIS +\fBcut [ \fB \-b \fR|\fB \-c\fR] \fIlist\fR [\fIfile...\fR]\fR +.br +\fBcut \-f \fIlist\fR [\fB\-d \fIdelim\fR] [\fB \-s\fR]\fR [\fIfile...\fR]" +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-b" "Cut specified bytes" +.FL "\-c" "Select out specific characters" +.FL "\-d" "Change the column delimiter to \fIdelim\fR" +.FL "\-f" "Select out specific fields that are separated by the delimiter character ( see \fIdelim\fR)" +.FL "\-i" "Runs of delimiters count as one" +.FL "\-s" "Suppres lines with no delimiter characters, when used with the \-f option. Lines with no delimiters are passwd through untouched" +.SH EXAMPLES +.EX "cut \-f 2 file" "Extract field 2" +.EX "cut \-c 1\-2,5 file" "Extract character columns 1, 2, and 5" +.EX "cut \-c 1\-5,7\- file" "Extract all columns except 6" +.SH DESCRIPTION +.PP +\fICut\fR extracts one or more fields or columns from a file and writes them on +standard output. +If the \fB\-f\fR flag is used, the fields are separated by a delimiter +character, normally a tab, but can be changed using the \fB\-d\fR flag. +If the \fB\-c\fR flag is used, specific columns can be specified. +The list can be comma or BLANK separated. The \fB\-f\fR and +\fB\-c\fR flags are mutually exclusive. +Note: The POSIX1003.2 standard requires the option \-b to cut out +specific bytes in a file. It is intended for systems with multi byte +characters (e.g. kanji), since MINIX uses only one byte characters, +this option is equivalent to \-c. For the same reason, the option +\-n has no effect and is not listed in this manual page. +.SH "SEE ALSO" +.BR sed (1), +.BR awk (9). diff --git a/man/man1/date.1 b/man/man1/date.1 new file mode 100644 index 000000000..f772b69b7 --- /dev/null +++ b/man/man1/date.1 @@ -0,0 +1,78 @@ +.TH DATE 1 +.SH NAME +date \- print or set the date and time +.SH SYNOPSIS +\fBdate [\fB\-qsuS\fR] [\fB\-r\fI seconds\fR] +[[\fIMMDDYY\fR]\fIhhmm\fR[\fIss\fR]] [\fI+format\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-q" "Read the date from \fIstdin\fR" +.FL "\-s" "Set the time (implicit for \fB\-q\fR or a date string)" +.FL "\-u" "Print the date as GMT" +.FL "\-S" "Date within Eternal September" +.FL "\-r" "Use this number of seconds instead of current time" +.SH EXAMPLES +.EX "date" "Print the date and time" +.EX "date 0221921610" "Set date to Feb 21, 1992 at 4:10 p.m." +.SH DESCRIPTION +.PP +With the \fB\-q\fR flag or a numeric argument, +.I date +sets the GMT time and date. +.I MMDDYY +refers to the month, day, and year; +.I hhmmss +refers to the hour, minute and second. +Each of the six fields must be exactly two digits, no more and no less. +.I date +always display the date and time, with the default format for the system. +The \fB\-u\fR flag request GMT time instead of local time. +A format may be specified with a + followed by a printf-like string with +the following options: +.ta 0.25i +.nf +.PP + %% % character + %A Name of the day + %B Name of the month + %D mm/dd/yy + %H Decimal hour on 2 digits + %I Decimal hour modulo 12 on 2 digits + %M Decimal minute on 2 digits + %S Decimal seconds on 2 digits + %T HH:MM:SS + %U Decimal week number, Sunday being first day of week + %W Decimal week number, Monday being first day of week + %X Same as %T + %Y Decimal year on 4 digits + %Z Time Zone (if any) + %a Abbreviated name of the day + %b Abbreviated name of the month + %c Appropriate date & time (default format) + %d Decimal day of the month on 2 digits + %e Same as %d, but a space replaces leading 0 + %h Same as %b + %j Decimal dey of the year on 3 digits + %m Decimal month on 2 digits + %n Newline character + %p AM or PM + %r 12-hour clock time with AM/PM + %s Number of seconds since the epoch + %t Tab character + %w Decimal day of the week (0=Sunday) + %x Same as %D + %y Decimal year on 2 digits +.SH "SEE ALSO" +.BR time (2), +.BR ctime (3), +.BR readclock (8). diff --git a/man/man1/dd.1 b/man/man1/dd.1 new file mode 100644 index 000000000..c1bc6ba6a --- /dev/null +++ b/man/man1/dd.1 @@ -0,0 +1,62 @@ +.TH DD 1 +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +\fBdd\fR [\fIoption = value\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "dd if=/dev/fd0 of=/dev/fd1" "Copy disk 0 to disk 1" +.EX "dd if=x of=y bs=1w skip=4" "Copy \fIx\fP to \fIy\fP, skipping 4 words" +.EX "dd if=x of=y count=3" "Copy three 512\-byte blocks" +.SH DESCRIPTION +.PP +This command is intended for copying partial files. +The block size, skip count, and number of blocks to copy can be specified. +The options are: +.PP +.ta 0.25i 1.5i + \fBif\fR = file \- Input file (default is \fIstdin\fR) +.br + \fBof\fR = file \- Output file (default is standard output) +.br + \fBibs\fR = n \- Input block size (default 512 bytes) +.br + \fBobs\fR = n \- Output block size (default is 512 bytes) +.br + \fBbs\fR = n \- Block size; sets \fIibs\fP and \fIobs\fP (default is 512 bytes) +.br + \fBskip\fR = n \- Skip \fIn\fP input blocks before reading +.br + \fBseek\fR = n \- Skip \fIn\fP output blocks before writing +.br + \fBcount\fR = n \- Copy only \fIn\fP input blocks +.br + \fBconv = lcase\fR \- Convert upper case letters to lower case +.br + \fBconv = ucase\fR \- Convert lower case letters to upper case +.br + \fBconv = swab\fR \- Swap every pair of bytes +.br + \fBconv = noerror\fR \- Ignore errors and just keep going +.br + \fBconv = silent\fR \- Suppress statistics (Minix specific flag) +.PP +Where sizes are expected, they are in bytes. +However, the letters \fBw\fR, \fBb\fR, or \fBk\fR may be appended to the +number to indicate words (2 bytes), blocks (512 bytes), or K +(1024 bytes), respectively. +When +.I dd +is finished, it reports the number of full and partial blocks read and written. +.SH "SEE ALSO" +.BR vol (1). diff --git a/man/man1/df.1 b/man/man1/df.1 new file mode 100644 index 000000000..7c9d7575c --- /dev/null +++ b/man/man1/df.1 @@ -0,0 +1,75 @@ +.TH DF 1 +.SH NAME +df \- report on free disk space +.SH SYNOPSIS +\fBdf\fP [\fB\-ikP\fP] [\fB\-t\fP \fItype\fP] [\fIfile\fP ...] +.SH DESCRIPTION +.B Df +lists the amount of free space on the currently mounted devices (no arguments), +or the devices given as arguments. If the argument is not a device then the +device it resides on is listed. +.SH OPTIONS +Without options, +.B df +will give a listing like this: +.sp +.nf +.if t .ft C +Filesystem 1k-Blocks free used % FUsed% Mounted on +/dev/c0d0p1s0 1440 635 805 56% 26% / +/dev/c0d0p1s1 32768 32390 378 2% 1% /tmp +/dev/c0d0p1s2 784657 517809 266848 35% 29% /usr +.if t .ft R +.fi +.PP +The +.B \-i +option shifts the focus to the files: +.sp +.nf +.if t .ft C +Filesystem Files free used % BUsed% Mounted on +/dev/c0d0p1s0 1024 759 265 26% 56% / +/dev/c0d0p1s1 5472 5468 4 1% 2% /tmp +/dev/c0d0p1s2 65535 46734 18801 29% 35% /usr +.if t .ft R +.fi +.PP +Option +.B \-P +makes +.B df +use \s-2POSIX\s+2 defined output in 512 byte units: +.sp +.nf +.if t .ft C +Filesystem 512-blocks Used Available Capacity Mounted on +/dev/c0d0p1s0 2880 1628 1252 57% / +/dev/c0d0p1s1 65536 756 64780 2% /tmp +/dev/c0d0p1s2 1569314 533748 1035566 35% /usr +.if t .ft R +.fi +.PP +With +.B \-k +1024 byte units would be used. +.PP +The +.B \-t +option limits +.BR df 's +output to file systems of the given +.IR type . +.SH FILES +.TP 15n +.B /etc/mtab +List of mounted file systems. +.SH "SEE ALSO" +.BR du (1), +.BR fstab (5). +.SH BUGS +Default output should also be in 512 byte units says \s-2POSIX\s+2. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) +.\" +.\" $PchId: df.1,v 1.5 1998/07/27 19:48:47 philip Exp $ diff --git a/man/man1/dhrystone.1 b/man/man1/dhrystone.1 new file mode 100644 index 000000000..5825d9ad2 --- /dev/null +++ b/man/man1/dhrystone.1 @@ -0,0 +1,29 @@ +.TH DHRYSTONE 1 +.SH NAME +dhrystone \- integer benchmark +.SH SYNOPSIS +\fBdhrystone\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "dhrystone" "Run the dhrystone benchmark" +.SH DESCRIPTION +.PP +Many years ago, a floating-point benchmark called \fIwhetstone\fR was +popular for benchmarking FORTRAN programs. +Nowadays, an integer benchmark called \fIdhrystone\fR is widely used +for benchmarking UNIX systems. +This is it. +Be warned, however, that \fIdhrystone\fR is entirely CPU bound, and +goes blindingly fast on machines with high-speed caches. +Although this is a good measure for programs that spend most of their +time in some inner loop, it is a poor benchmark for I/O bound applications. diff --git a/man/man1/diff.1 b/man/man1/diff.1 new file mode 100644 index 000000000..3fe3dccb4 --- /dev/null +++ b/man/man1/diff.1 @@ -0,0 +1,47 @@ +.TH DIFF 1 +.SH NAME +diff \- print differences between two files +.SH SYNOPSIS +\fBdiff \fR [\fB\-c \fR|\fB \-e \fR|\fB \-C \fIn\fR\] [\fB\-br\fR]\fIfile1 file2\fR\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-C \fIn" "Produce output that contains \fIn\fR lines of context" +.FL "\-b" "Ignore white space when comparing" +.FL "\-c" "Produce output that contains three lines of context" +.FL "\-e" "Produce an \fIed\fR-script to convert \fIfile1\fR into \fIfile2\fR" +.FL "\-r" "Apply \fIdiff\fR recursively to files and directories of the same name, when \fIfile1\fR and \fIfile2\fR are both directories" +.SH EXAMPLES +.EX "diff file1 file2" "Print differences between 2 files" +.EX "diff -C 0 file1 file2" "Same as above" +.EX "diff -C 3 file1 file2" "Output three lines of context with every difference encountered" +.EX "diff -c file1 file2" Same as above" +.EX "diff /etc /dev" "Compares recursively the directories \fI/etc\fR and \fI/dev\fR" +.EX "diff passwd /etc" "Compares \fI./passwd\fR to \fI/etc/passwd" +.SH DESCRIPTION +.PP +\fIDiff\fR compares two files and generates a list of lines telling how +the two files differ. Lines may not be longer than 128 characters. +If the two arguments on the command line are both directories, +\fIdiff\fR recursively steps through all subdirectories comparing +files of the same name. If a file name is found only in one directory, +a diagnostic message is written to \fIstdout\fR. A file that is of +either block special, character special or FIFO special type, cannot +be compared to any other file. +On the other hand, if there is one directory and one file given on the +command line, \fIdiff\fR tries to compare the file with the same name +as \fIfile\fR in the directory \fIdirectory\fR. +.SH "SEE ALSO" +.BR cdiff (1), +.BR cmp (1), +.BR comm (1), +.BR patch (1). diff --git a/man/man1/dosdir.1 b/man/man1/dosdir.1 new file mode 100644 index 000000000..9b6292535 --- /dev/null +++ b/man/man1/dosdir.1 @@ -0,0 +1,44 @@ +.TH DOSDIR 1 +.SH NAME +dosdir \- list an MS-DOS directory [IBM] +.SH SYNOPSIS +\fBdosdir\fR [\fB\-lr\fR] \fIdrive\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-l" "Long listing" +.FL "\-r" "Recursively descend and print subdirectories" +.SH EXAMPLES +.EX "dosdir \-l A" "List root directory on drive A" +.EX "dosdir \-r C x/y" "Recursively list directory \fIx/y\fR" +.EX "dosdir \-r fd1" "List device \fI/dev/fd1\fR" +.SH DESCRIPTION +.PP +.I Dosdir +reads standard IBM PC diskettes or hard disk partitions in +\s-2MS-DOS\s+2 format and lists their contents on standard output. +Directory names should contain slashes to separate components, even though +\s-2MS-DOS\s+2 uses backslashes. +The names +.I dosdir , +.I dosread , +and +.I doswrite +are all links to the same program. +The program sees which function to perform by seeing how it was called. +A drive code of +.I A +causes the program to use \fI/dev/dosA\fR, for example, +a link to \fI/dev/fd0\fR. +Similarly, to have hard disk partition 1 be DOS drive C, \fI/dev/dosC\fR +could be a link to \fI/dev/hd1\fR, and so on for other drive codes. +A normal device name may also be used instead of a drive code. diff --git a/man/man1/dosread.1 b/man/man1/dosread.1 new file mode 100644 index 000000000..51f6df18c --- /dev/null +++ b/man/man1/dosread.1 @@ -0,0 +1,30 @@ +.TH DOSREAD 1 +.SH NAME +dosread \- read a file from an MS-DOS diskette [IBM] +.SH SYNOPSIS +\fBdosread\fR [\fB\-a\fR] \fIdrive \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "ASCII file" +.SH EXAMPLES +.EX "dosread C g/adv >adv" "Read file \fIg/adv\fR from hard disk" +.EX "dosread \-a A prog.c >x" "Read ASCII file \fIprog.c\fR from drive A" +.SH DESCRIPTION +.PP +.I Dosread +reads one \s-2MS-DOS\s+2 file and writes it on standard output. +The file name must use slash, not backslash as a separator. +ASCII files have the final CTRL-Z stripped, and carriage return plus +line feed are mapped to line feed only, the usual +\s-2MINIX\s+2 +convention. See \fBdosdir\fR on the use of single letter drive codes. diff --git a/man/man1/doswrite.1 b/man/man1/doswrite.1 new file mode 100644 index 000000000..51960c2f8 --- /dev/null +++ b/man/man1/doswrite.1 @@ -0,0 +1,28 @@ +.TH DOSWRITE 1 +.SH NAME +doswrite \- write a file onto an MS-DOS diskette [IBM] +.SH SYNOPSIS +\fBdoswrite\fR [\fB\-a\fR] \fIdrive \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "ASCII file" +.SH EXAMPLES +.EX "doswrite A x/y &2 +.SH BUGS +The octal character escape mechanism (\e0\fIdigits\fR) differs from the +C language mechanism. +.SH AUTHOR +Kenneth Almquist. diff --git a/man/man1/ed.1 b/man/man1/ed.1 new file mode 100644 index 000000000..6d6dd1a9f --- /dev/null +++ b/man/man1/ed.1 @@ -0,0 +1,69 @@ +.TH ED 1 +.SH NAME +ed \- editor +.SH SYNOPSIS +\fBed \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-" "Suppress line/byte count messages (for in scripts)" +.SH EXAMPLES +.EX "ed prog.c" "Edit \fIprog.c\fR" +.EX "echo '1,$p' | ed - file" "Odd way to write 'cat file'" +.SH DESCRIPTION +.PP +\fIEd\fR is functionally equivalent to the standard V7 editor, ed. +It supports the following commands: +.PP +.nf +.ta 0.5i 0.95i + (.) a: append + (.,.) c: change + (.,.) d: delete + e: edit new file" + f: print name of edited file" + (1,$) g: global command + (.) i: insert + (.,.+1) j: join lines together + (.) k: mark + (.) l: print with special characters in octal + (.,.) m: move + (.,.) p: print + q: quit editor" + (.) r: read in new file + (.,.) s: substitute + (1,$) v: like g, except select lines that do not match + (1,$) w: write out edited file +.fi +Many of the commands can take one or two addresses, as indicated above. The +defaults are shown in parentheses. Thus \fIa\fR appends to the current +line, and \fIg\fR works on the whole file as default. +The dot refers to the current line. +Below is a sample editing session with comments given following the # symbol. +.PP +.nf +.ta 0.5i 2.5i + ed prog.c # Edit prog.c + 3,20p # Print lines 3 through 20 + /whole/ # Find next occurence of \fIwhole\fR + s/whole/while/ # Replace \fIwhole\fR by \fIwhile\fR + g/Buf/s//BUF/g # Replace \fIBuf\fR by \fIBUF\fR everywhere + w # Write the file back + q # Exit the editor +.fi +\fIEd\fR is provided for its sentimental value. +If you want a line-oriented editor, try \fIex\fR. +If you want a good editor, use \fIelle\fR, \fIelvis\fR, or \fImined\fR. +.SH "SEE ALSO" +.BR elvis (1), +.BR elle (9), +.BR mined (9). diff --git a/man/man1/eject.1 b/man/man1/eject.1 new file mode 100644 index 000000000..5c3f15001 --- /dev/null +++ b/man/man1/eject.1 @@ -0,0 +1,24 @@ +.TH EJECT 1 +.SH NAME +eject \- eject removable media +.SH SYNOPSIS +.B eject +.I device +.SH DESCRIPTION +.B Eject +tells a device to eject removable media, usually a floppy or CD-ROM. +.B Eject +invokes the +.B DIOCEJECT +ioctl on the device. The media will then be ejected, or allowed to be +removed. The call will fail if the device is still in use. +.PP +Tapes can't be unloaded with this command, use +.B mt offline +instead. +.SH "SEE ALSO" +.BR mt (1), +.BR hd (4), +.BR sd (4). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/elvis.1 b/man/man1/elvis.1 new file mode 100644 index 000000000..80a75b828 --- /dev/null +++ b/man/man1/elvis.1 @@ -0,0 +1,100 @@ +.TH ELVIS 1 +.SH NAME +elvis, ex, vi \- The editor +.SH SYNOPSIS +\fBelvis\fP [\fIflags\fP] [\fB+\fP\fIcmd\fP] [\fIfiles\fP...] +.SH DESCRIPTION +\fBElvis\fP is a text editor which emulates \fBvi\fP/\fBex\fP. +.PP +On systems which pass the program name as an argument, such as Unix and Minix, +you may also install \fBelvis\fP under the names "ex", "vi", "view", and "input". +These extra names would normally be links to elvis; +see the "ln" shell command. +.PP +When \fBelvis\fP is invoked as "vi", +it behaves exactly as though it was invoked as "elvis". +However, if you invoke \fBelvis\fP as "view", +then the readonly option is set as though you had given it the "-R" flag. +If you invoke \fBelvis\fP as "ex", +then \fBelvis\fP will start up in the colon command mode +instead of the visual command mode, +as though you had given it the "-e" flag. +If you invoke \fBelvis\fP as "input" or "edit", +then \fBelvis\fP will start up in input mode, +as though the "-i" flag was given. +.SH OPTIONS +.IP \fB-r\fP +To the real vi, this flag means that a previous edit should be recovered. +\fBElvis\fP, though, has a separate program, called \fIelvrec\fP(1), for recovering +files. +When you invoke \fBelvis\fP with -r, \fBelvis\fP will tell you to run \fBelvrec\fP. +.IP \fB-R\fP +This sets the "readonly" option, +so you won't accidentally overwrite a file. +.IP "\fB-t\fP \fItag\fP" +This causes \fBelvis\fP to start editing at the given tag. +.IP "\fB-m\fP [\fIfile\fP]" +\fBElvis\fP will search through \fIfile\fP for something that looks like +an error message from a compiler. +It will then begin editing the source file that caused the error, +with the cursor sitting on the line where the error was detected. +If you don't explicitly name a \fIfile\fP, then "errlist" is assumed. +.IP \fB-e\fP +\fBElvis\fP will start up in colon command mode. +.IP \fB-v\fP +\fBElvis\fP will start up in visual command mode. +.IP \fB-i\fP +\fBElvis\fP will start up in input mode. +.IP "\fB-w\fR \fIwinsize\fR" +Sets the "window" option's value to \fIwinsize\fR. +.IP "\fB+\fP\fIcommand\fP or \fB-c\fP \fIcommand\fP" +If you use the +\fIcommand\fP parameter, +then after the first file is loaded +\fIcommand\fP is executed as an EX command. +A typical example would be "elvis +237 foo", +which would cause \fBelvis\fP to start editing foo and +then move directly to line 237. +The "-c \fIcommand\fP" variant was added for UNIX SysV compatibility. +.SH FILES +.IP /tmp/elv* +During editing, +\fBelvis\fP stores text in a temporary file. +For UNIX, this file will usually be stored in the /tmp directory, +and the first three characters will be "elv". +For other systems, the temporary files may be stored someplace else; +see the version-specific section of the documentation. +.IP tags +This is the database used by the \fB:tags\fP command and the \fB-t\fP option. +It is usually created by the \fBctags\fP(1) program. +.IP ".exrc or elvis.rc" +On UNIX-like systems, a file called ".exrc" in your home directory +is executed as a series of \fBex\fR commands. +A file by the same name may be executed in the current directory, too. +On non-UNIX systems, ".exrc" is usually an invalid file name; +there, the initialization file is called "elvis.rc" instead. +.SH "SEE ALSO" +.BR ctags (1), +.BR ref (1), +.BR virec (1), +.BR elvis (9). +.PP +\fIElvis - A Clone of Vi/Ex\fP, the complete \fBelvis\fP documentation. +.SH BUGS +There is no LISP support. +Certain other features are missing, too. +.PP +Auto-indent mode is not quite compatible with the real vi. +Among other things, 0^D and ^^D don't do what you might expect. +.PP +Long lines are displayed differently. +The real vi wraps long lines onto multiple rows of the screen, +but \fBelvis\fP scrolls sideways. +.SH AUTHOR +.nf +Steve Kirkendall +kirkenda@cs.pdx.edu +.fi +.PP +Many other people have worked to port \fBelvis\fP to various operating systems. +To see who deserves credit, run the \fB:version\fP command from within \fBelvis\fP, +or look in the system-specific section of the complete documentation. diff --git a/man/man1/elvrec.1 b/man/man1/elvrec.1 new file mode 100644 index 000000000..b541c2ed1 --- /dev/null +++ b/man/man1/elvrec.1 @@ -0,0 +1,47 @@ +.TH ELVREC 1 +.SH NAME +elvrec - Recover the modified version of a file after a crash +.SH SYNOPSIS +.nf +\fBelvrec\fP [\fIpreservedfile\fP [\fInewfile\fR]] +.fi +.SH DESCRIPTION +.PP +If you're editing a file when \fIelvis\fP dies, the system crashes, or power fails, +the most recent version of your text will be preserved. +The preserved text is stored in a special directory; it does NOT overwrite +your text file automatically. +.PP +The \fIelvrec\fP program locates the preserved version of a given file, +and writes it over the top of your text file -- or to a new file, if you prefer. +The recovered file will have nearly all of your changes. +.PP +To see a list of all recoverable files, run \fIelvrec\fP with no arguments. +.SH FILES +.IP /usr/preserve/p* +The text that was preserved when \fIelvis\fP died. +.IP /usr/preserve/Index +A text file which lists the names of all preserved files, and the names +of the /usr/preserve/p* files which contain their preserved text. +.SH BUGS +.PP +\fIelvrec\fP is very picky about filenames. +You must tell it to recover the file using exactly the same pathname as +when you were editing it. +The simplest way to do this is to go into the same directory that you were +editing, and invoke \fIelvrec\fP with the same filename as \fIelvis\fP. +If that doesn't work, then try running \fIelvrec\fP with no arguments, +to see exactly which pathname it is using for the desired file. +.PP +Due to the permissions on the /usr/preserve directory, on UNIX systems +\fIelvrec\fP must be run as superuser. +This is accomplished by making the \fIelvrec\fP executable be owned by "root" +and setting its "set user id" bit. +.PP +If you're editing a nameless buffer when \fIelvis\fP dies, then \fIelvrec\fP +will pretend that the file was named "foo". +.SH AUTHOR +.nf +Steve Kirkendall +kirkenda@cs.pdx.edu +.fi diff --git a/man/man1/env.1 b/man/man1/env.1 new file mode 100644 index 000000000..18628c8cb --- /dev/null +++ b/man/man1/env.1 @@ -0,0 +1,93 @@ +.TH ENV 1 +.SH NAME +env \- set environment for command +.SH SYNOPSIS +.B env +.RB [ \-ia ] +.RI [ name\fB=\fIvalue "] ..." +.RI [ utility +.RI [ argument "...]]" +.SH DESCRIPTION +.B Env +modifies its environment according to the +.IB name = value +arguments, and executes +.I utility +with the given arguments and the modified environment. +.PP +If no utility is specified then the modified environment is printed as +.IB name = value +strings, one per line. +.SH OPTIONS +.TP +.B \-i +Use exactly the environment specified by the arguments; the inherited +environment is ignored. +.TP +.B \-a +Specify all arguments for the utility, i.e. the first of the arguments is +used as +.BR "argv[0]" , +the program name. Normally the program name is +.I utility +itself. +.SH ENVIRONMENT +.TP 8n +.B PATH +The path used to find utility. It is as modified by +.BR env , +i.e. +.B not +the inherited +.BR PATH . +.SH "SEE ALSO" +.BR sh (1), +.BR execvp (3), +.BR environ (5). +.SH DIAGNOSTICS +The return code is +.B 0 +after successfully printing the environment, +.B 1 +on an error within +.BR env , +.B 126 +if the +.I utility +could not be executed, or +.B 127 +if +.I utility +could not be found. Appropriate diagnostic messages are printed on standard +error. +If +.I utility +can be executed then it replaces +.BR env , +so the return code is then the return code of +.IR utility . +.SH NOTES +When run from the standard shell +.B env +is only useful with options or without arguments. Otherwise the shell can +do exactly what +.B env +can do, simply omit the word "env" on the command line. +.PP +One interesting use of +.B env +is with #! on the first line of a script to forge a PATH search for an +interpreter. For example: +.PP +.RS +#!/usr/bin/env perl +.RE +.PP +This will find the Perl interpreter if it is within the user's PATH. Most +UNIX-like systems have +.B env +in /usr/bin, but +.B perl +may be anywhere. +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/expand.1 b/man/man1/expand.1 new file mode 100644 index 000000000..8e29f0ba0 --- /dev/null +++ b/man/man1/expand.1 @@ -0,0 +1,28 @@ +.TH EXPAND 1 +.SH NAME +expand \- convert tabs to spaces +.SH SYNOPSIS +\fBexpand\fR [\fB\-\fIt1,t2, ...\fR]\fR [\fIfile\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-\fIt\fR" "Tab stop positions" +.SH EXAMPLES +.EX "expand \-16,32,48,64" "Expand \fIstdin\fR with tabs every 16 columns" +.SH DESCRIPTION +.PP +\fIExpand\fR replaces tabs in the named files with the equivalent numbers +of spaces. If no files are listed, \fIstdin\fR is given. If only one +tab is given, the rest are multiples of it. The default is a tab every 8 +spaces. +.SH "SEE ALSO" +.BR unexpand (1). diff --git a/man/man1/expr.1 b/man/man1/expr.1 new file mode 100644 index 000000000..18a46085b --- /dev/null +++ b/man/man1/expr.1 @@ -0,0 +1,243 @@ +.TH EXPR 1 +.SH NAME \" Copyright (C) 1989 by Kenneth Almquist. +expr, test, [ \- evaluate expressions +.SH SYNOPSIS +.B expr +.I expression +.br +.B test +.I expression +.br +.B [ +.I expression +.B ] +.SH DESCRIPTION +.B Expr +evaluates the expression and prints the result. +.B Test +evaluates the expression without printing the result. +The ``['' +command is a synonym for +.BR test ; +when invoked under this name +the last argument to +.B expr +must be a ``]'', which is deleted and not considered part of the expression. +.PP +Three data types may occur in the +.IR expression : +string, integer, and boolean. +The rules for conversion are as follows: +.sp +.nr i 2 +.ta \nii +.in +\nii +.ti -\nii +\fIstring\fR\->\fIinteger\fR Done via +.BR atoi (3). +.ti -\nii +\fIinteger\fR\->\fIstring\fR Convert to decimal representation. +.ti -\nii +\fIstring\fR\->\fIboolean\fR "" \-> false, everything else to true. +.ti -\nii +\fIboolean\fR\->\fIstring\fR false \-> "", true \-> "true". +.ti -\nii +\fIinteger\fR\->\fIboolean\fR 0 \-> false, everything else to true. +.ti -\nii +\fIboolean\fR\->\fIinteger\fR false \-> 0, true \-> 1. +.in -\nii +.PP +Any argument to +.B expr +which is not a legal operator is treated as a string operand of type +.BR string . +.PP +As a special case, if +.I expression +is omitted, the result is false. +.PP +We now list the operators. The syntax +.sp +.ti +8 +\fIinteger\fB op \fIinteger\fR \-> \fIboolean\fB (3)\fR +.sp +means that \fBop\fR is a binary operator which takes operands of type +\fIinteger\fR and produces a result of type \fIboolean\fR. +The ``(3)'' means that the priority of \fBop\fR is 3. +Operands are automatically converted to the appropriate type. The type +\fIany\fR is used for operator that take operands of any type. +.nr p 1 +.de b +.TP 0.5i +\fI\\$1\fB \\$2 \fI\\$3\fR \-> \\fI\\$4\\fR (\\np) +.. +.de u +.TP 0.5i +\\$1 \fI\\$2\fR \-> \\fI\\$3\\fR (\\np) +.. +.b any \-o any any +Returns the value of the left hand operand if the left hand operand +would yield +.B true +if converted to type +.BR boolean , +and the value of the right hand operand otherwise. +The right hand operand is evaluated only if necessary. +``|'' is a synonym for ``\-o''. +.nr p \np+1 +.b any -a any any +Returns the value of the left hand operand if the left hand operand +would yield +.B false +if converted to type +.BR boolean , +and the value of the right hand operand otherwise. +The right hand operand is evaluated only if necessary. +``&'' is a synonym for ``\-a''. +.nr p \np+1 +.u ! boolean boolean +Returns true if the operand is false, and false if the operand is true. +.nr p \np+1 +.b string = string boolean +True if the two strings are equal. +.b string != string boolean +True if the two strings are not equal. +.b integer \-eq integer boolean +True if the two operands are equal. +.b integer \-ne integer boolean +True if the two operands are not equal. +.b integer \-gt integer boolean +True if the first operand is greater than the second one. +.b integer \-lt integer boolean +True if the first operand is less than the second one. +.b integer \-ge integer boolean +True if the first operand is greater than or equal to the second one. +.b integer \-le integer boolean +True if the first operand is less than or equal to the second one. +.nr p \np+1 +.b integer + integer integer +Add two integers. +.b integer \- integer integer +Subtract two integers. +.nr p \np+1 +.b integer * integer integer +Multiply two integers. ``*'' is special to the shell, so you generally +have to write this operator as ``\e*''. +.b integer / integer integer +Divide two integers. +.b integer % integer integer +Returns the remainder when the first operand is divided by the second one. +.nr p \np+1 +.b string : string "integer or string" +The second operand is interpreted as a regular expression (as in the +System V +.B ed +program). +This operator attempts to match part (or all) of the first operand +with the regular expression. The match must start at the beginning of +the first operand. +If the regular expression contains \e( \e) pairs, then the result +of this operator is the string which is matched by the regular expression +between these pairs, or the null string if no match occurred. Otherwise, +the result is the number of characters matched by the regular expression, +or zero if no no match occurred. +.nr p \np+1 +.u \-n string integer +Returns the number of characters in the string. +.u \-z string boolean +Returns true if the string contains zero characters. +.u \-t integer boolean +Returns true if the specified file descriptor is associated with a tty. +.PP +The remaining operators all deal with files. Except as noted, they return +false if the +specified file does not exist. The ones dealing with permission use +the effective user and group ids of the shell. +.u \-r string boolean +True if you have read permission on the file. +.u \-w string boolean +True if you have write permission on the file. +.u \-x string boolean +True if you have execute permission on the file. +.u \-f string boolean +True if the file is a regular file. +.u \-d string boolean +True if the file is a directory. +.u \-c string boolean +True if the file is a character special file. +.u \-b string boolean +True if the file is a block special file. +.u \-p string boolean +True if the file is a named pipe (i.e. a fifo). +.u \-u string boolean +True if the file is setuid. +.u \-g string boolean +True if the file is setgid. +.u \-k string boolean +True if the file has the sticky bit set. +.u \-s string "integer or boolean" +Returns the size of the file, or 0 if the file does not exist. +.u \-h string boolean +True if the file is a symlink. This is the only file test operator that +does not follow symlinks, all others do. So ``\-d'' and ``\-h'' +are both true on a symlink pointing to a directory. +``\-L'' is a synonym for ``\-h''. +.SH "EXIT CODE" +0 if the result of +.I expression +would be +.B true +if the result were converted to +.BR boolean . +.br +1 if the result of +.I expression +would be +.B false +if the result were converted to +.BR boolean . +.br +2 if +.I expression +is syntactically incorrect. +.SH EXAMPLES +.TP 0.5i +filesize=`expr \-s file` +Sets the shell variable +.I filesize +to the size of +.IR file . +.TP 0.5i +if [ \-s file ]; then command; fi +Execute +.I command +if +.I file +exists and is not empty. +.TP 0.5i +x=`expr "$x" : '.\\{4\\}\\(.\\{0,3\\}\\)'` +Sets +.I x +to the substring of +.I x +beginning after the fourth character of +.I x +and continuing for three characters or until the end of the string, +whichever comes first. +.TP 0.5i +x=`expr X"$x" : X'.\\{4\\}\\(.\\{0,3\\}\\)'` +This example is the same as the previous one, but it uses a leading +``X'' to make things work when the value of +.I x +looks like an operator. +.SH BUGS +The relational operators of the System V +.B expr +command are not implemented. +.PP +Certain features of this version of +.B expr +are not present in System V, so care should be used when writing +portable code. +.SH COPYRIGHT +Kenneth Almquist. diff --git a/man/man1/factor.1 b/man/man1/factor.1 new file mode 100644 index 000000000..fe5a3d95f --- /dev/null +++ b/man/man1/factor.1 @@ -0,0 +1,22 @@ +.TH FACTOR 1 +.SH NAME +factor \- factor an integer less than 2**31 +.SH SYNOPSIS +\fBfactor \fInumber\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "factor 450180" "Print the prime factors of 450180" +.SH DESCRIPTION +.PP +\fIFactor\fR prints the prime factors of its argument in increasing order. +Each factor is printed as many times as it appears in the number. diff --git a/man/man1/fgrep.1 b/man/man1/fgrep.1 new file mode 100644 index 000000000..26c94a8b9 --- /dev/null +++ b/man/man1/fgrep.1 @@ -0,0 +1,35 @@ +.TH FGREP 1 +.SH NAME +fgrep \- fixed grep +.SH SYNOPSIS +\fBfgrep\fR [\fB\-cfhlnsv\fR]\fR [\fIstring_file\fR] [\fIstring\fR] [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Count matching lines and only print count, not the lines" +.FL "\-f" "Take strings from file named in following argument" +.FL "\-h" "Omit file headers from printout" +.FL "\-l" "List file names once only" +.FL "\-n" "Each line is preceded by its line number" +.FL "\-s" "Status only, no output" +.FL "\-v" "Print only lines not matching" +.SH EXAMPLES +.EX "fgrep % prog.c" "Print lines containing % sign" +.EX "fgrep \-f pattern prog.c" "Take strings from \fIpattern\fR" +.SH DESCRIPTION +.PP +\fIFgrep\fR is essentially the same as grep, except that it only searches +for lines containing literal strings (no wildcard characters). The pattern +may consist of several lines with one string to search on each line. +.SH "SEE ALSO" +.BR cgrep (1), +.BR grep (1). diff --git a/man/man1/file.1 b/man/man1/file.1 new file mode 100644 index 000000000..fd1394ec6 --- /dev/null +++ b/man/man1/file.1 @@ -0,0 +1,24 @@ +.TH FILE 1 +.SH NAME +file \- make a guess as to a file's type based on contents +.SH SYNOPSIS +\fBfile \fIname ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "file a.out ar.h" "Guess at types" +.SH DESCRIPTION +.PP +\fIFile\fR reads the first block of a file and tries to make an +intelligent guess about what kind of file it is. +It understands about archives, C +source programs, executable binaries, shell scripts, and English text. diff --git a/man/man1/find.1 b/man/man1/find.1 new file mode 100644 index 000000000..cf76d2ff9 --- /dev/null +++ b/man/man1/find.1 @@ -0,0 +1,84 @@ +.TH FIND 1 +.SH NAME +find \- find files meeting a given condition +.SH SYNOPSIS +\fBfind \fIdirectory \fIexpression\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "find / \-name a.out \-print" "Print all \fIa.out\fR paths" +.EX "find /usr/ast ! \-newer f \-ok rm {} \e;" "Ask before removing" +.EX "find /usr \-size +20 \-exec mv {} /big \e^;" "move files > 10k" +.EX "find / \e( \-name a.out \-o \-name \(fm*.o\(fm \e) \-exec rm {} \e;" "2 conds" +.SH DESCRIPTION +.PP +\fIFind\fR descends the file tree starting at the given directory checking +each file in that directory and its subdirectories against a predicate. +If the predicate is true, an action is taken. The predicates may be +connected by \fB\-a\fR (Boolean and), \fB\-o\fR (Boolean or) and ! +(Boolean negation). +Each predicate is true under the conditions specified below. The integer +\fIn\fR may also be +\fIn\fR to mean any value greater than \fIn\fR, +\fI\-n\fR to mean any value less than +\fIn\fR, or just \fIn\fR for exactly \fIn\fR. +.PP +.RS +.ta +\w'\-mtime nmm'u +.in +\w'\-mtime nmm'u +.ti -\w'\-mtime nmm'u +\-name s true if current filename is \fIs\fR (include shell wild cards) +.ti -\w'\-mtime nmm'u +\-size n true if file size is \fIn\fR blocks +.ti -\w'\-mtime nmm'u +\-inum n true if the current file's i-node number is \fIn\fR +.ti -\w'\-mtime nmm'u +\-mtime n true if modification time relative to today (in days) is \fIn\fR +.ti -\w'\-mtime nmm'u +\-links n true if the number of links to the file is \fIn\fR +.ti -\w'\-mtime nmm'u +\-newer f true if the file is newer than \fIf\fR +.ti -\w'\-mtime nmm'u +\-perm n true if the file's permission bits = \fIn\fR (\fIn\fR is in octal) +.ti -\w'\-mtime nmm'u +\-user u true if the uid = \fIu\fR (a numerical value, not a login name) +.ti -\w'\-mtime nmm'u +\-group g true if the gid = \fIg\fR (a numerical value, not a group name) +.ti -\w'\-mtime nmm'u +\-type x where \fIx\fR is \fBbcdfug\fR (block, char, dir, regular file, setuid, setgid) +.ti -\w'\-mtime nmm'u +\-xdev do not cross devices to search mounted file systems +.in -\w'\-mtime nmm'u +.fi +.RE +.PP +Following the expression can be one of the following, telling what to do +when a file is found: +.PP +.RS +.ta +\w'\-mtime nmm'u +.in +\w'\-mtime nmm'u +.ti -\w'\-mtime nmm'u +\-print print the file name on standard output +.ti -\w'\-mtime nmm'u +\-print0 print the file name terminated by a null character, to be +used with +.BR "xargs \-0" . +(Minix extension). +.ti -\w'\-mtime nmm'u +\-exec execute a command, {} stands for the file name +.ti -\w'\-mtime nmm'u +\-ok prompts before executing the command +.in -\w'\-mtime nmm'u +.RE +.SH "SEE ALSO" +.BR test (1), +.BR xargs (1). diff --git a/man/man1/finger.1 b/man/man1/finger.1 new file mode 100644 index 000000000..fe64472dd --- /dev/null +++ b/man/man1/finger.1 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)finger.1 6.4 (Berkeley) 5/10/86 +.\" +.TH FINGER 1 "May 10, 1986" +.UC 4 +.SH NAME +finger \- user information lookup program +.SH SYNOPSIS +.B finger +[ +options +] name ... +.SH DESCRIPTION +By default +.B finger +lists the login name, full name, terminal name and write status +(as a `*' before the terminal name if write permission is denied), +idle time, login time, and office location and phone number +(if they are known) for each current UNIX user. +(Idle time is minutes if it is a single integer, hours and minutes if a ':' +is present, or days and hours if a 'd' is present.) +.PP +A longer format also exists and is used by +.B finger +whenever a list of people's names is given. (Account names as well as +first and last names of users are accepted.) +This format is multi-line, and includes all the information described above +as well as the user's home +directory and login shell, any plan which the person has placed in the file +.B \&.plan +in their home +directory, and the project on which they are working from the file +.B \&.project +also in the home directory. +.PP +.B Finger +may be used to lookup users on a remote machine. The format is to specify +the user as ``user@host.'' If the user name is left off, the +standard format listing is provided on the remote machine. +.PP +.B Finger +options include: +.TP +.B \-m +Match arguments only on user name. +.TP +.B \-l +Force long output format. +.TP +.B \-p +Suppress printing of the +.B \&.plan +files +.TP +.B \-s +Force short output format. +.SH FILES +.ta 2i +/etc/utmp who file +.br +/etc/passwd for users names, offices, ... +.br +/usr/adm/lastlog last login times +.br +~/.plan plans +.br +~/.project projects +.SH "SEE ALSO" +.BR chfn (1), +.BR w (1), +.BR who (1). +.SH AUTHOR +Earl T. Cohen +.SH BUGS +Only the first line of the +.B .project +file is printed. +.PP +There is no way to pass arguments to the remote machine as +.B finger +uses an internet standard port. diff --git a/man/man1/flex.1 b/man/man1/flex.1 new file mode 100644 index 000000000..b89f90c1f --- /dev/null +++ b/man/man1/flex.1 @@ -0,0 +1,779 @@ +.TH FLEX 1 "26 May 1990" "Version 2.3" +.SH NAME +flex, lex - fast lexical analyzer generator +.SH SYNOPSIS +.B flex +.B [-bcdfinpstvFILT8 -C[efmF] -Sskeleton] +.I [filename ...] +.SH DESCRIPTION +.I flex +is a tool for generating +.I scanners: +programs which recognized lexical patterns in text. +.I flex +reads +the given input files, or its standard input if no file names are given, +for a description of a scanner to generate. The description is in +the form of pairs +of regular expressions and C code, called +.I rules. flex +generates as output a C source file, +.B lex.yy.c, +which defines a routine +.B yylex(). +This file is compiled and linked with the +.B -lfl +library to produce an executable. When the executable is run, +it analyzes its input for occurrences +of the regular expressions. Whenever it finds one, it executes +the corresponding C code. +.LP +For full documentation, see +.B flexdoc(1). +This manual entry is intended for use as a quick reference. +.SH OPTIONS +.I flex +has the following options: +.TP +.B -b +Generate backtracking information to +.I lex.backtrack. +This is a list of scanner states which require backtracking +and the input characters on which they do so. By adding rules one +can remove backtracking states. If all backtracking states +are eliminated and +.B -f +or +.B -F +is used, the generated scanner will run faster. +.TP +.B -c +is a do-nothing, deprecated option included for POSIX compliance. +.IP +.B NOTE: +in previous releases of +.I flex +.B -c +specified table-compression options. This functionality is +now given by the +.B -C +flag. To ease the the impact of this change, when +.I flex +encounters +.B -c, +it currently issues a warning message and assumes that +.B -C +was desired instead. In the future this "promotion" of +.B -c +to +.B -C +will go away in the name of full POSIX compliance (unless +the POSIX meaning is removed first). +.TP +.B -d +makes the generated scanner run in +.I debug +mode. Whenever a pattern is recognized and the global +.B yy_flex_debug +is non-zero (which is the default), the scanner will +write to +.I stderr +a line of the form: +.nf + + --accepting rule at line 53 ("the matched text") + +.fi +The line number refers to the location of the rule in the file +defining the scanner (i.e., the file that was fed to flex). Messages +are also generated when the scanner backtracks, accepts the +default rule, reaches the end of its input buffer (or encounters +a NUL; the two look the same as far as the scanner's concerned), +or reaches an end-of-file. +.TP +.B -f +specifies (take your pick) +.I full table +or +.I fast scanner. +No table compression is done. The result is large but fast. +This option is equivalent to +.B -Cf +(see below). +.TP +.B -i +instructs +.I flex +to generate a +.I case-insensitive +scanner. The case of letters given in the +.I flex +input patterns will +be ignored, and tokens in the input will be matched regardless of case. The +matched text given in +.I yytext +will have the preserved case (i.e., it will not be folded). +.TP +.B -n +is another do-nothing, deprecated option included only for +POSIX compliance. +.TP +.B -p +generates a performance report to stderr. The report +consists of comments regarding features of the +.I flex +input file which will cause a loss of performance in the resulting scanner. +.TP +.B -s +causes the +.I default rule +(that unmatched scanner input is echoed to +.I stdout) +to be suppressed. If the scanner encounters input that does not +match any of its rules, it aborts with an error. +.TP +.B -t +instructs +.I flex +to write the scanner it generates to standard output instead +of +.B lex.yy.c. +.TP +.B -v +specifies that +.I flex +should write to +.I stderr +a summary of statistics regarding the scanner it generates. +.TP +.B -F +specifies that the +.I fast +scanner table representation should be used. This representation is +about as fast as the full table representation +.RB ( \-f ), +and for some sets of patterns will be considerably smaller (and for +others, larger). See +.B flexdoc(1) +for details. +.IP +This option is equivalent to +.B -CF +(see below). +.TP +.B -I +instructs +.I flex +to generate an +.I interactive +scanner, that is, a scanner which stops immediately rather than +looking ahead if it knows +that the currently scanned text cannot be part of a longer rule's match. +Again, see +.B flexdoc(1) +for details. +.IP +Note, +.B -I +cannot be used in conjunction with +.I full +or +.I fast tables, +i.e., the +.B -f, -F, -Cf, +or +.B -CF +flags. +.TP +.B -L +instructs +.I flex +not to generate +.B #line +directives in +.B lex.yy.c. +The default is to generate such directives so error +messages in the actions will be correctly +located with respect to the original +.I flex +input file, and not to +the fairly meaningless line numbers of +.B lex.yy.c. +.TP +.B -T +makes +.I flex +run in +.I trace +mode. It will generate a lot of messages to +.I stdout +concerning +the form of the input and the resultant non-deterministic and deterministic +finite automata. This option is mostly for use in maintaining +.I flex. +.TP +.B -8 +instructs +.I flex +to generate an 8-bit scanner. +On some sites, this is the default. On others, the default +is 7-bit characters. To see which is the case, check the verbose +.B (-v) +output for "equivalence classes created". If the denominator of +the number shown is 128, then by default +.I flex +is generating 7-bit characters. If it is 256, then the default is +8-bit characters. +.TP +.B -C[efmF] +controls the degree of table compression. +.IP +.B -Ce +directs +.I flex +to construct +.I equivalence classes, +i.e., sets of characters +which have identical lexical properties. +Equivalence classes usually give +dramatic reductions in the final table/object file sizes (typically +a factor of 2-5) and are pretty cheap performance-wise (one array +look-up per character scanned). +.IP +.B -Cf +specifies that the +.I full +scanner tables should be generated - +.I flex +should not compress the +tables by taking advantages of similar transition functions for +different states. +.IP +.B -CF +specifies that the alternate fast scanner representation (described in +.B flexdoc(1)) +should be used. +.IP +.B -Cm +directs +.I flex +to construct +.I meta-equivalence classes, +which are sets of equivalence classes (or characters, if equivalence +classes are not being used) that are commonly used together. Meta-equivalence +classes are often a big win when using compressed tables, but they +have a moderate performance impact (one or two "if" tests and one +array look-up per character scanned). +.IP +A lone +.B -C +specifies that the scanner tables should be compressed but neither +equivalence classes nor meta-equivalence classes should be used. +.IP +The options +.B -Cf +or +.B -CF +and +.B -Cm +do not make sense together - there is no opportunity for meta-equivalence +classes if the table is not being compressed. Otherwise the options +may be freely mixed. +.IP +The default setting is +.B -Cem, +which specifies that +.I flex +should generate equivalence classes +and meta-equivalence classes. This setting provides the highest +degree of table compression. You can trade off +faster-executing scanners at the cost of larger tables with +the following generally being true: +.nf + + slowest & smallest + -Cem + -Cm + -Ce + -C + -C{f,F}e + -C{f,F} + fastest & largest + +.fi +.IP +.B -C +options are not cumulative; whenever the flag is encountered, the +previous -C settings are forgotten. +.TP +.B -Sskeleton_file +overrides the default skeleton file from which +.I flex +constructs its scanners. You'll never need this option unless you are doing +.I flex +maintenance or development. +.SH SUMMARY OF FLEX REGULAR EXPRESSIONS +The patterns in the input are written using an extended set of regular +expressions. These are: +.nf + + x match the character 'x' + . any character except newline + [xyz] a "character class"; in this case, the pattern + matches either an 'x', a 'y', or a 'z' + [abj-oZ] a "character class" with a range in it; matches + an 'a', a 'b', any letter from 'j' through 'o', + or a 'Z' + [^A-Z] a "negated character class", i.e., any character + but those in the class. In this case, any + character EXCEPT an uppercase letter. + [^A-Z\\n] any character EXCEPT an uppercase letter or + a newline + r* zero or more r's, where r is any regular expression + r+ one or more r's + r? zero or one r's (that is, "an optional r") + r{2,5} anywhere from two to five r's + r{2,} two or more r's + r{4} exactly 4 r's + {name} the expansion of the "name" definition + (see above) + "[xyz]\\"foo" + the literal string: [xyz]"foo + \\X if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', + then the ANSI-C interpretation of \\x. + Otherwise, a literal 'X' (used to escape + operators such as '*') + \\123 the character with octal value 123 + \\x2a the character with hexadecimal value 2a + (r) match an r; parentheses are used to override + precedence (see below) + + + rs the regular expression r followed by the + regular expression s; called "concatenation" + + + r|s either an r or an s + + + r/s an r but only if it is followed by an s. The + s is not part of the matched text. This type + of pattern is called as "trailing context". + ^r an r, but only at the beginning of a line + r$ an r, but only at the end of a line. Equivalent + to "r/\\n". + + + r an r, but only in start condition s (see + below for discussion of start conditions) + r + same, but in any of start conditions s1, + s2, or s3 + + + <> an end-of-file + <> + an end-of-file when in start condition s1 or s2 + +.fi +The regular expressions listed above are grouped according to +precedence, from highest precedence at the top to lowest at the bottom. +Those grouped together have equal precedence. +.LP +Some notes on patterns: +.IP - +Negated character classes +.I match newlines +unless "\\n" (or an equivalent escape sequence) is one of the +characters explicitly present in the negated character class +(e.g., "[^A-Z\\n]"). +.IP - +A rule can have at most one instance of trailing context (the '/' operator +or the '$' operator). The start condition, '^', and "<>" patterns +can only occur at the beginning of a pattern, and, as well as with '/' and '$', +cannot be grouped inside parentheses. The following are all illegal: +.nf + + foo/bar$ + foo|(bar$) + foo|^bar + foobar + +.fi +.SH SUMMARY OF SPECIAL ACTIONS +In addition to arbitrary C code, the following can appear in actions: +.IP - +.B ECHO +copies yytext to the scanner's output. +.IP - +.B BEGIN +followed by the name of a start condition places the scanner in the +corresponding start condition. +.IP - +.B REJECT +directs the scanner to proceed on to the "second best" rule which matched the +input (or a prefix of the input). +.B yytext +and +.B yyleng +are set up appropriately. Note that +.B REJECT +is a particularly expensive feature in terms scanner performance; +if it is used in +.I any +of the scanner's actions it will slow down +.I all +of the scanner's matching. Furthermore, +.B REJECT +cannot be used with the +.I -f +or +.I -F +options. +.IP +Note also that unlike the other special actions, +.B REJECT +is a +.I branch; +code immediately following it in the action will +.I not +be executed. +.IP - +.B yymore() +tells the scanner that the next time it matches a rule, the corresponding +token should be +.I appended +onto the current value of +.B yytext +rather than replacing it. +.IP - +.B yyless(n) +returns all but the first +.I n +characters of the current token back to the input stream, where they +will be rescanned when the scanner looks for the next match. +.B yytext +and +.B yyleng +are adjusted appropriately (e.g., +.B yyleng +will now be equal to +.I n +). +.IP - +.B unput(c) +puts the character +.I c +back onto the input stream. It will be the next character scanned. +.IP - +.B input() +reads the next character from the input stream (this routine is called +.B yyinput() +if the scanner is compiled using +.B C++). +.IP - +.B yyterminate() +can be used in lieu of a return statement in an action. It terminates +the scanner and returns a 0 to the scanner's caller, indicating "all done". +.IP +By default, +.B yyterminate() +is also called when an end-of-file is encountered. It is a macro and +may be redefined. +.IP - +.B YY_NEW_FILE +is an action available only in <> rules. It means "Okay, I've +set up a new input file, continue scanning". +.IP - +.B yy_create_buffer( file, size ) +takes a +.I FILE +pointer and an integer +.I size. +It returns a YY_BUFFER_STATE +handle to a new input buffer large enough to accomodate +.I size +characters and associated with the given file. When in doubt, use +.B YY_BUF_SIZE +for the size. +.IP - +.B yy_switch_to_buffer( new_buffer ) +switches the scanner's processing to scan for tokens from +the given buffer, which must be a YY_BUFFER_STATE. +.IP - +.B yy_delete_buffer( buffer ) +deletes the given buffer. +.SH VALUES AVAILABLE TO THE USER +.IP - +.B char *yytext +holds the text of the current token. It may not be modified. +.IP - +.B int yyleng +holds the length of the current token. It may not be modified. +.IP - +.B FILE *yyin +is the file which by default +.I flex +reads from. It may be redefined but doing so only makes sense before +scanning begins. Changing it in the middle of scanning will have +unexpected results since +.I flex +buffers its input. Once scanning terminates because an end-of-file +has been seen, +.B +void yyrestart( FILE *new_file ) +may be called to point +.I yyin +at the new input file. +.IP - +.B FILE *yyout +is the file to which +.B ECHO +actions are done. It can be reassigned by the user. +.IP - +.B YY_CURRENT_BUFFER +returns a +.B YY_BUFFER_STATE +handle to the current buffer. +.SH MACROS THE USER CAN REDEFINE +.IP - +.B YY_DECL +controls how the scanning routine is declared. +By default, it is "int yylex()", or, if prototypes are being +used, "int yylex(void)". This definition may be changed by redefining +the "YY_DECL" macro. Note that +if you give arguments to the scanning routine using a +K&R-style/non-prototyped function declaration, you must terminate +the definition with a semi-colon (;). +.IP - +The nature of how the scanner +gets its input can be controlled by redefining the +.B YY_INPUT +macro. +YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its +action is to place up to +.I max_size +characters in the character array +.I buf +and return in the integer variable +.I result +either the +number of characters read or the constant YY_NULL (0 on Unix systems) +to indicate EOF. The default YY_INPUT reads from the +global file-pointer "yyin". +A sample redefinition of YY_INPUT (in the definitions +section of the input file): +.nf + + %{ + #undef YY_INPUT + #define YY_INPUT(buf,result,max_size) \\ + { \\ + int c = getchar(); \\ + result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \\ + } + %} + +.fi +.IP - +When the scanner receives an end-of-file indication from YY_INPUT, +it then checks the +.B yywrap() +function. If +.B yywrap() +returns false (zero), then it is assumed that the +function has gone ahead and set up +.I yyin +to point to another input file, and scanning continues. If it returns +true (non-zero), then the scanner terminates, returning 0 to its +caller. +.IP +The default +.B yywrap() +always returns 1. Presently, to redefine it you must first +"#undef yywrap", as it is currently implemented as a macro. It is +likely that +.B yywrap() +will soon be defined to be a function rather than a macro. +.IP - +YY_USER_ACTION +can be redefined to provide an action +which is always executed prior to the matched rule's action. +.IP - +The macro +.B YY_USER_INIT +may be redefined to provide an action which is always executed before +the first scan. +.IP - +In the generated scanner, the actions are all gathered in one large +switch statement and separated using +.B YY_BREAK, +which may be redefined. By default, it is simply a "break", to separate +each rule's action from the following rule's. +.SH FILES +.TP +.I flex.skel +skeleton scanner. +.TP +.I lex.yy.c +generated scanner (called +.I lexyy.c +on some systems). +.TP +.I lex.backtrack +backtracking information for +.B -b +flag (called +.I lex.bck +on some systems). +.TP +.B -lfl +library with which to link the scanners. +.SH "SEE ALSO" +.LP +flexdoc(1), lex(1), yacc(1), sed(1), awk(1). +.LP +M. E. Lesk and E. Schmidt, +.I LEX - Lexical Analyzer Generator +.SH DIAGNOSTICS +.I reject_used_but_not_detected undefined +or +.LP +.I yymore_used_but_not_detected undefined - +These errors can occur at compile time. They indicate that the +scanner uses +.B REJECT +or +.B yymore() +but that +.I flex +failed to notice the fact, meaning that +.I flex +scanned the first two sections looking for occurrences of these actions +and failed to find any, but somehow you snuck some in (via a #include +file, for example). Make an explicit reference to the action in your +.I flex +input file. (Note that previously +.I flex +supported a +.B %used/%unused +mechanism for dealing with this problem; this feature is still supported +but now deprecated, and will go away soon unless the author hears from +people who can argue compellingly that they need it.) +.LP +.I flex scanner jammed - +a scanner compiled with +.B -s +has encountered an input string which wasn't matched by +any of its rules. +.LP +.I flex input buffer overflowed - +a scanner rule matched a string long enough to overflow the +scanner's internal input buffer (16K bytes - controlled by +.B YY_BUF_MAX +in "flex.skel"). +.LP +.I scanner requires -8 flag - +Your scanner specification includes recognizing 8-bit characters and +you did not specify the -8 flag (and your site has not installed flex +with -8 as the default). +.LP +.I +fatal flex scanner internal error--end of buffer missed - +This can occur in an scanner which is reentered after a long-jump +has jumped out (or over) the scanner's activation frame. Before +reentering the scanner, use: +.nf + + yyrestart( yyin ); + +.fi +.LP +.I too many %t classes! - +You managed to put every single character into its own %t class. +.I flex +requires that at least one of the classes share characters. +.SH AUTHOR +Vern Paxson, with the help of many ideas and much inspiration from +Van Jacobson. Original version by Jef Poskanzer. +.LP +See flexdoc(1) for additional credits and the address to send comments to. +.SH DEFICIENCIES / BUGS +.LP +Some trailing context +patterns cannot be properly matched and generate +warning messages ("Dangerous trailing context"). These are +patterns where the ending of the +first part of the rule matches the beginning of the second +part, such as "zx*/xy*", where the 'x*' matches the 'x' at +the beginning of the trailing context. (Note that the POSIX draft +states that the text matched by such patterns is undefined.) +.LP +For some trailing context rules, parts which are actually fixed-length are +not recognized as such, leading to the abovementioned performance loss. +In particular, parts using '|' or {n} (such as "foo{3}") are always +considered variable-length. +.LP +Combining trailing context with the special '|' action can result in +.I fixed +trailing context being turned into the more expensive +.I variable +trailing context. For example, this happens in the following example: +.nf + + %% + abc | + xyz/def + +.fi +.LP +Use of unput() invalidates yytext and yyleng. +.LP +Use of unput() to push back more text than was matched can +result in the pushed-back text matching a beginning-of-line ('^') +rule even though it didn't come at the beginning of the line +(though this is rare!). +.LP +Pattern-matching of NUL's is substantially slower than matching other +characters. +.LP +.I flex +does not generate correct #line directives for code internal +to the scanner; thus, bugs in +.I flex.skel +yield bogus line numbers. +.LP +Due to both buffering of input and read-ahead, you cannot intermix +calls to routines, such as, for example, +.B getchar(), +with +.I flex +rules and expect it to work. Call +.B input() +instead. +.LP +The total table entries listed by the +.B -v +flag excludes the number of table entries needed to determine +what rule has been matched. The number of entries is equal +to the number of DFA states if the scanner does not use +.B REJECT, +and somewhat greater than the number of states if it does. +.LP +.B REJECT +cannot be used with the +.I -f +or +.I -F +options. +.LP +Some of the macros, such as +.B yywrap(), +may in the future become functions which live in the +.B -lfl +library. This will doubtless break a lot of code, but may be +required for POSIX-compliance. +.LP +The +.I flex +internal algorithms need documentation. diff --git a/man/man1/flexdoc.1 b/man/man1/flexdoc.1 new file mode 100644 index 000000000..a38a14c36 --- /dev/null +++ b/man/man1/flexdoc.1 @@ -0,0 +1,2441 @@ +.TH FLEX 1 "26 May 1990" "Version 2.3" +.SH NAME +flexdoc - fast lexical analyzer generator +.SH SYNOPSIS +.B flex +.B [-bcdfinpstvFILT8 -C[efmF] -Sskeleton] +.I [filename ...] +.SH DESCRIPTION +.I flex +is a tool for generating +.I scanners: +programs which recognized lexical patterns in text. +.I flex +reads +the given input files, or its standard input if no file names are given, +for a description of a scanner to generate. The description is in +the form of pairs +of regular expressions and C code, called +.I rules. flex +generates as output a C source file, +.B lex.yy.c, +which defines a routine +.B yylex(). +This file is compiled and linked with the +.B -lfl +library to produce an executable. When the executable is run, +it analyzes its input for occurrences +of the regular expressions. Whenever it finds one, it executes +the corresponding C code. +.SH SOME SIMPLE EXAMPLES +.LP +First some simple examples to get the flavor of how one uses +.I flex. +The following +.I flex +input specifies a scanner which whenever it encounters the string +"username" will replace it with the user's login name: +.nf + + %% + username printf( "%s", getlogin() ); + +.fi +By default, any text not matched by a +.I flex +scanner +is copied to the output, so the net effect of this scanner is +to copy its input file to its output with each occurrence +of "username" expanded. +In this input, there is just one rule. "username" is the +.I pattern +and the "printf" is the +.I action. +The "%%" marks the beginning of the rules. +.LP +Here's another simple example: +.nf + + int num_lines = 0, num_chars = 0; + + %% + \\n ++num_lines; ++num_chars; + . ++num_chars; + + %% + main() + { + yylex(); + printf( "# of lines = %d, # of chars = %d\\n", + num_lines, num_chars ); + } + +.fi +This scanner counts the number of characters and the number +of lines in its input (it produces no output other than the +final report on the counts). The first line +declares two globals, "num_lines" and "num_chars", which are accessible +both inside +.B yylex() +and in the +.B main() +routine declared after the second "%%". There are two rules, one +which matches a newline ("\\n") and increments both the line count and +the character count, and one which matches any character other than +a newline (indicated by the "." regular expression). +.LP +A somewhat more complicated example: +.nf + + /* scanner for a toy Pascal-like language */ + + %{ + /* need this for the call to atof() below */ + #include + %} + + DIGIT [0-9] + ID [a-z][a-z0-9]* + + %% + + {DIGIT}+ { + printf( "An integer: %s (%d)\\n", yytext, + atoi( yytext ) ); + } + + {DIGIT}+"."{DIGIT}* { + printf( "A float: %s (%g)\\n", yytext, + atof( yytext ) ); + } + + if|then|begin|end|procedure|function { + printf( "A keyword: %s\\n", yytext ); + } + + {ID} printf( "An identifier: %s\\n", yytext ); + + "+"|"-"|"*"|"/" printf( "An operator: %s\\n", yytext ); + + "{"[^}\\n]*"}" /* eat up one-line comments */ + + [ \\t\\n]+ /* eat up whitespace */ + + . printf( "Unrecognized character: %s\\n", yytext ); + + %% + + main( argc, argv ) + int argc; + char **argv; + { + ++argv, --argc; /* skip over program name */ + if ( argc > 0 ) + yyin = fopen( argv[0], "r" ); + else + yyin = stdin; + + yylex(); + } + +.fi +This is the beginnings of a simple scanner for a language like +Pascal. It identifies different types of +.I tokens +and reports on what it has seen. +.LP +The details of this example will be explained in the following +sections. +.SH FORMAT OF THE INPUT FILE +The +.I flex +input file consists of three sections, separated by a line with just +.B %% +in it: +.nf + + definitions + %% + rules + %% + user code + +.fi +The +.I definitions +section contains declarations of simple +.I name +definitions to simplify the scanner specification, and declarations of +.I start conditions, +which are explained in a later section. +.LP +Name definitions have the form: +.nf + + name definition + +.fi +The "name" is a word beginning with a letter or an underscore ('_') +followed by zero or more letters, digits, '_', or '-' (dash). +The definition is taken to begin at the first non-white-space character +following the name and continuing to the end of the line. +The definition can subsequently be referred to using "{name}", which +will expand to "(definition)". For example, +.nf + + DIGIT [0-9] + ID [a-z][a-z0-9]* + +.fi +defines "DIGIT" to be a regular expression which matches a +single digit, and +"ID" to be a regular expression which matches a letter +followed by zero-or-more letters-or-digits. +A subsequent reference to +.nf + + {DIGIT}+"."{DIGIT}* + +.fi +is identical to +.nf + + ([0-9])+"."([0-9])* + +.fi +and matches one-or-more digits followed by a '.' followed +by zero-or-more digits. +.LP +The +.I rules +section of the +.I flex +input contains a series of rules of the form: +.nf + + pattern action + +.fi +where the pattern must be unindented and the action must begin +on the same line. +.LP +See below for a further description of patterns and actions. +.LP +Finally, the user code section is simply copied to +.B lex.yy.c +verbatim. +It is used for companion routines which call or are called +by the scanner. The presence of this section is optional; +if it is missing, the second +.B %% +in the input file may be skipped, too. +.LP +In the definitions and rules sections, any +.I indented +text or text enclosed in +.B %{ +and +.B %} +is copied verbatim to the output (with the %{}'s removed). +The %{}'s must appear unindented on lines by themselves. +.LP +In the rules section, +any indented or %{} text appearing before the +first rule may be used to declare variables +which are local to the scanning routine and (after the declarations) +code which is to be executed whenever the scanning routine is entered. +Other indented or %{} text in the rule section is still copied to the output, +but its meaning is not well-defined and it may well cause compile-time +errors (this feature is present for +.I POSIX +compliance; see below for other such features). +.LP +In the definitions section, an unindented comment (i.e., a line +beginning with "/*") is also copied verbatim to the output up +to the next "*/". Also, any line in the definitions section +beginning with '#' is ignored, though this style of comment is +deprecated and may go away in the future. +.SH PATTERNS +The patterns in the input are written using an extended set of regular +expressions. These are: +.nf + + x match the character 'x' + . any character except newline + [xyz] a "character class"; in this case, the pattern + matches either an 'x', a 'y', or a 'z' + [abj-oZ] a "character class" with a range in it; matches + an 'a', a 'b', any letter from 'j' through 'o', + or a 'Z' + [^A-Z] a "negated character class", i.e., any character + but those in the class. In this case, any + character EXCEPT an uppercase letter. + [^A-Z\\n] any character EXCEPT an uppercase letter or + a newline + r* zero or more r's, where r is any regular expression + r+ one or more r's + r? zero or one r's (that is, "an optional r") + r{2,5} anywhere from two to five r's + r{2,} two or more r's + r{4} exactly 4 r's + {name} the expansion of the "name" definition + (see above) + "[xyz]\\"foo" + the literal string: [xyz]"foo + \\X if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', + then the ANSI-C interpretation of \\x. + Otherwise, a literal 'X' (used to escape + operators such as '*') + \\123 the character with octal value 123 + \\x2a the character with hexadecimal value 2a + (r) match an r; parentheses are used to override + precedence (see below) + + + rs the regular expression r followed by the + regular expression s; called "concatenation" + + + r|s either an r or an s + + + r/s an r but only if it is followed by an s. The + s is not part of the matched text. This type + of pattern is called as "trailing context". + ^r an r, but only at the beginning of a line + r$ an r, but only at the end of a line. Equivalent + to "r/\\n". + + + r an r, but only in start condition s (see + below for discussion of start conditions) + r + same, but in any of start conditions s1, + s2, or s3 + + + <> an end-of-file + <> + an end-of-file when in start condition s1 or s2 + +.fi +The regular expressions listed above are grouped according to +precedence, from highest precedence at the top to lowest at the bottom. +Those grouped together have equal precedence. For example, +.nf + + foo|bar* + +.fi +is the same as +.nf + + (foo)|(ba(r*)) + +.fi +since the '*' operator has higher precedence than concatenation, +and concatenation higher than alternation ('|'). This pattern +therefore matches +.I either +the string "foo" +.I or +the string "ba" followed by zero-or-more r's. +To match "foo" or zero-or-more "bar"'s, use: +.nf + + foo|(bar)* + +.fi +and to match zero-or-more "foo"'s-or-"bar"'s: +.nf + + (foo|bar)* + +.fi +.LP +Some notes on patterns: +.IP - +A negated character class such as the example "[^A-Z]" +above +.I will match a newline +unless "\\n" (or an equivalent escape sequence) is one of the +characters explicitly present in the negated character class +(e.g., "[^A-Z\\n]"). This is unlike how many other regular +expression tools treat negated character classes, but unfortunately +the inconsistency is historically entrenched. +Matching newlines means that a pattern like [^"]* can match an entire +input (overflowing the scanner's input buffer) unless there's another +quote in the input. +.IP - +A rule can have at most one instance of trailing context (the '/' operator +or the '$' operator). The start condition, '^', and "<>" patterns +can only occur at the beginning of a pattern, and, as well as with '/' and '$', +cannot be grouped inside parentheses. A '^' which does not occur at +the beginning of a rule or a '$' which does not occur at the end of +a rule loses its special properties and is treated as a normal character. +.IP +The following are illegal: +.nf + + foo/bar$ + foobar + +.fi +Note that the first of these, can be written "foo/bar\\n". +.IP +The following will result in '$' or '^' being treated as a normal character: +.nf + + foo|(bar$) + foo|^bar + +.fi +If what's wanted is a "foo" or a bar-followed-by-a-newline, the following +could be used (the special '|' action is explained below): +.nf + + foo | + bar$ /* action goes here */ + +.fi +A similar trick will work for matching a foo or a +bar-at-the-beginning-of-a-line. +.SH HOW THE INPUT IS MATCHED +When the generated scanner is run, it analyzes its input looking +for strings which match any of its patterns. If it finds more than +one match, it takes the one matching the most text (for trailing +context rules, this includes the length of the trailing part, even +though it will then be returned to the input). If it finds two +or more matches of the same length, the +rule listed first in the +.I flex +input file is chosen. +.LP +Once the match is determined, the text corresponding to the match +(called the +.I token) +is made available in the global character pointer +.B yytext, +and its length in the global integer +.B yyleng. +The +.I action +corresponding to the matched pattern is then executed (a more +detailed description of actions follows), and then the remaining +input is scanned for another match. +.LP +If no match is found, then the +.I default rule +is executed: the next character in the input is considered matched and +copied to the standard output. Thus, the simplest legal +.I flex +input is: +.nf + + %% + +.fi +which generates a scanner that simply copies its input (one character +at a time) to its output. +.SH ACTIONS +Each pattern in a rule has a corresponding action, which can be any +arbitrary C statement. The pattern ends at the first non-escaped +whitespace character; the remainder of the line is its action. If the +action is empty, then when the pattern is matched the input token +is simply discarded. For example, here is the specification for a program +which deletes all occurrences of "zap me" from its input: +.nf + + %% + "zap me" + +.fi +(It will copy all other characters in the input to the output since +they will be matched by the default rule.) +.LP +Here is a program which compresses multiple blanks and tabs down to +a single blank, and throws away whitespace found at the end of a line: +.nf + + %% + [ \\t]+ putchar( ' ' ); + [ \\t]+$ /* ignore this token */ + +.fi +.LP +If the action contains a '{', then the action spans till the balancing '}' +is found, and the action may cross multiple lines. +.I flex +knows about C strings and comments and won't be fooled by braces found +within them, but also allows actions to begin with +.B %{ +and will consider the action to be all the text up to the next +.B %} +(regardless of ordinary braces inside the action). +.LP +An action consisting solely of a vertical bar ('|') means "same as +the action for the next rule." See below for an illustration. +.LP +Actions can include arbitrary C code, including +.B return +statements to return a value to whatever routine called +.B yylex(). +Each time +.B yylex() +is called it continues processing tokens from where it last left +off until it either reaches +the end of the file or executes a return. Once it reaches an end-of-file, +however, then any subsequent call to +.B yylex() +will simply immediately return, unless +.B yyrestart() +is first called (see below). +.LP +Actions are not allowed to modify yytext or yyleng. +.LP +There are a number of special directives which can be included within +an action: +.IP - +.B ECHO +copies yytext to the scanner's output. +.IP - +.B BEGIN +followed by the name of a start condition places the scanner in the +corresponding start condition (see below). +.IP - +.B REJECT +directs the scanner to proceed on to the "second best" rule which matched the +input (or a prefix of the input). The rule is chosen as described +above in "How the Input is Matched", and +.B yytext +and +.B yyleng +set up appropriately. +It may either be one which matched as much text +as the originally chosen rule but came later in the +.I flex +input file, or one which matched less text. +For example, the following will both count the +words in the input and call the routine special() whenever "frob" is seen: +.nf + + int word_count = 0; + %% + + frob special(); REJECT; + [^ \\t\\n]+ ++word_count; + +.fi +Without the +.B REJECT, +any "frob"'s in the input would not be counted as words, since the +scanner normally executes only one action per token. +Multiple +.B REJECT's +are allowed, each one finding the next best choice to the currently +active rule. For example, when the following scanner scans the token +"abcd", it will write "abcdabcaba" to the output: +.nf + + %% + a | + ab | + abc | + abcd ECHO; REJECT; + .|\\n /* eat up any unmatched character */ + +.fi +(The first three rules share the fourth's action since they use +the special '|' action.) +.B REJECT +is a particularly expensive feature in terms scanner performance; +if it is used in +.I any +of the scanner's actions it will slow down +.I all +of the scanner's matching. Furthermore, +.B REJECT +cannot be used with the +.I -f +or +.I -F +options (see below). +.IP +Note also that unlike the other special actions, +.B REJECT +is a +.I branch; +code immediately following it in the action will +.I not +be executed. +.IP - +.B yymore() +tells the scanner that the next time it matches a rule, the corresponding +token should be +.I appended +onto the current value of +.B yytext +rather than replacing it. For example, given the input "mega-kludge" +the following will write "mega-mega-kludge" to the output: +.nf + + %% + mega- ECHO; yymore(); + kludge ECHO; + +.fi +First "mega-" is matched and echoed to the output. Then "kludge" +is matched, but the previous "mega-" is still hanging around at the +beginning of +.B yytext +so the +.B ECHO +for the "kludge" rule will actually write "mega-kludge". +The presence of +.B yymore() +in the scanner's action entails a minor performance penalty in the +scanner's matching speed. +.IP - +.B yyless(n) +returns all but the first +.I n +characters of the current token back to the input stream, where they +will be rescanned when the scanner looks for the next match. +.B yytext +and +.B yyleng +are adjusted appropriately (e.g., +.B yyleng +will now be equal to +.I n +). For example, on the input "foobar" the following will write out +"foobarbar": +.nf + + %% + foobar ECHO; yyless(3); + [a-z]+ ECHO; + +.fi +An argument of 0 to +.B yyless +will cause the entire current input string to be scanned again. Unless you've +changed how the scanner will subsequently process its input (using +.B BEGIN, +for example), this will result in an endless loop. +.IP - +.B unput(c) +puts the character +.I c +back onto the input stream. It will be the next character scanned. +The following action will take the current token and cause it +to be rescanned enclosed in parentheses. +.nf + + { + int i; + unput( ')' ); + for ( i = yyleng - 1; i >= 0; --i ) + unput( yytext[i] ); + unput( '(' ); + } + +.fi +Note that since each +.B unput() +puts the given character back at the +.I beginning +of the input stream, pushing back strings must be done back-to-front. +.IP - +.B input() +reads the next character from the input stream. For example, +the following is one way to eat up C comments: +.nf + + %% + "/*" { + register int c; + + for ( ; ; ) + { + while ( (c = input()) != '*' && + c != EOF ) + ; /* eat up text of comment */ + + if ( c == '*' ) + { + while ( (c = input()) == '*' ) + ; + if ( c == '/' ) + break; /* found the end */ + } + + if ( c == EOF ) + { + error( "EOF in comment" ); + break; + } + } + } + +.fi +(Note that if the scanner is compiled using +.B C++, +then +.B input() +is instead referred to as +.B yyinput(), +in order to avoid a name clash with the +.B C++ +stream by the name of +.I input.) +.IP - +.B yyterminate() +can be used in lieu of a return statement in an action. It terminates +the scanner and returns a 0 to the scanner's caller, indicating "all done". +Subsequent calls to the scanner will immediately return unless preceded +by a call to +.B yyrestart() +(see below). +By default, +.B yyterminate() +is also called when an end-of-file is encountered. It is a macro and +may be redefined. +.SH THE GENERATED SCANNER +The output of +.I flex +is the file +.B lex.yy.c, +which contains the scanning routine +.B yylex(), +a number of tables used by it for matching tokens, and a number +of auxiliary routines and macros. By default, +.B yylex() +is declared as follows: +.nf + + int yylex() + { + ... various definitions and the actions in here ... + } + +.fi +(If your environment supports function prototypes, then it will +be "int yylex( void )".) This definition may be changed by redefining +the "YY_DECL" macro. For example, you could use: +.nf + + #undef YY_DECL + #define YY_DECL float lexscan( a, b ) float a, b; + +.fi +to give the scanning routine the name +.I lexscan, +returning a float, and taking two floats as arguments. Note that +if you give arguments to the scanning routine using a +K&R-style/non-prototyped function declaration, you must terminate +the definition with a semi-colon (;). +.LP +Whenever +.B yylex() +is called, it scans tokens from the global input file +.I yyin +(which defaults to stdin). It continues until it either reaches +an end-of-file (at which point it returns the value 0) or +one of its actions executes a +.I return +statement. +In the former case, when called again the scanner will immediately +return unless +.B yyrestart() +is called to point +.I yyin +at the new input file. ( +.B yyrestart() +takes one argument, a +.B FILE * +pointer.) +In the latter case (i.e., when an action +executes a return), the scanner may then be called again and it +will resume scanning where it left off. +.LP +By default (and for purposes of efficiency), the scanner uses +block-reads rather than simple +.I getc() +calls to read characters from +.I yyin. +The nature of how it gets its input can be controlled by redefining the +.B YY_INPUT +macro. +YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its +action is to place up to +.I max_size +characters in the character array +.I buf +and return in the integer variable +.I result +either the +number of characters read or the constant YY_NULL (0 on Unix systems) +to indicate EOF. The default YY_INPUT reads from the +global file-pointer "yyin". +.LP +A sample redefinition of YY_INPUT (in the definitions +section of the input file): +.nf + + %{ + #undef YY_INPUT + #define YY_INPUT(buf,result,max_size) \\ + { \\ + int c = getchar(); \\ + result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \\ + } + %} + +.fi +This definition will change the input processing to occur +one character at a time. +.LP +You also can add in things like keeping track of the +input line number this way; but don't expect your scanner to +go very fast. +.LP +When the scanner receives an end-of-file indication from YY_INPUT, +it then checks the +.B yywrap() +function. If +.B yywrap() +returns false (zero), then it is assumed that the +function has gone ahead and set up +.I yyin +to point to another input file, and scanning continues. If it returns +true (non-zero), then the scanner terminates, returning 0 to its +caller. +.LP +The default +.B yywrap() +always returns 1. Presently, to redefine it you must first +"#undef yywrap", as it is currently implemented as a macro. As indicated +by the hedging in the previous sentence, it may be changed to +a true function in the near future. +.LP +The scanner writes its +.B ECHO +output to the +.I yyout +global (default, stdout), which may be redefined by the user simply +by assigning it to some other +.B FILE +pointer. +.SH START CONDITIONS +.I flex +provides a mechanism for conditionally activating rules. Any rule +whose pattern is prefixed with "" will only be active when +the scanner is in the start condition named "sc". For example, +.nf + + [^"]* { /* eat up the string body ... */ + ... + } + +.fi +will be active only when the scanner is in the "STRING" start +condition, and +.nf + + \\. { /* handle an escape ... */ + ... + } + +.fi +will be active only when the current start condition is +either "INITIAL", "STRING", or "QUOTE". +.LP +Start conditions +are declared in the definitions (first) section of the input +using unindented lines beginning with either +.B %s +or +.B %x +followed by a list of names. +The former declares +.I inclusive +start conditions, the latter +.I exclusive +start conditions. A start condition is activated using the +.B BEGIN +action. Until the next +.B BEGIN +action is executed, rules with the given start +condition will be active and +rules with other start conditions will be inactive. +If the start condition is +.I inclusive, +then rules with no start conditions at all will also be active. +If it is +.I exclusive, +then +.I only +rules qualified with the start condition will be active. +A set of rules contingent on the same exclusive start condition +describe a scanner which is independent of any of the other rules in the +.I flex +input. Because of this, +exclusive start conditions make it easy to specify "mini-scanners" +which scan portions of the input that are syntactically different +from the rest (e.g., comments). +.LP +If the distinction between inclusive and exclusive start conditions +is still a little vague, here's a simple example illustrating the +connection between the two. The set of rules: +.nf + + %s example + %% + foo /* do something */ + +.fi +is equivalent to +.nf + + %x example + %% + foo /* do something */ + +.fi +.LP +The default rule (to +.B ECHO +any unmatched character) remains active in start conditions. +.LP +.B BEGIN(0) +returns to the original state where only the rules with +no start conditions are active. This state can also be +referred to as the start-condition "INITIAL", so +.B BEGIN(INITIAL) +is equivalent to +.B BEGIN(0). +(The parentheses around the start condition name are not required but +are considered good style.) +.LP +.B BEGIN +actions can also be given as indented code at the beginning +of the rules section. For example, the following will cause +the scanner to enter the "SPECIAL" start condition whenever +.I yylex() +is called and the global variable +.I enter_special +is true: +.nf + + int enter_special; + + %x SPECIAL + %% + if ( enter_special ) + BEGIN(SPECIAL); + + blahblahblah + ...more rules follow... + +.fi +.LP +To illustrate the uses of start conditions, +here is a scanner which provides two different interpretations +of a string like "123.456". By default it will treat it as +as three tokens, the integer "123", a dot ('.'), and the integer "456". +But if the string is preceded earlier in the line by the string +"expect-floats" +it will treat it as a single token, the floating-point number +123.456: +.nf + + %{ + #include + %} + %s expect + + %% + expect-floats BEGIN(expect); + + [0-9]+"."[0-9]+ { + printf( "found a float, = %f\\n", + atof( yytext ) ); + } + \\n { + /* that's the end of the line, so + * we need another "expect-number" + * before we'll recognize any more + * numbers + */ + BEGIN(INITIAL); + } + + [0-9]+ { + printf( "found an integer, = %d\\n", + atoi( yytext ) ); + } + + "." printf( "found a dot\\n" ); + +.fi +Here is a scanner which recognizes (and discards) C comments while +maintaining a count of the current input line. +.nf + + %x comment + %% + int line_num = 1; + + "/*" BEGIN(comment); + + [^*\\n]* /* eat anything that's not a '*' */ + "*"+[^*/\\n]* /* eat up '*'s not followed by '/'s */ + \\n ++line_num; + "*"+"/" BEGIN(INITIAL); + +.fi +Note that start-conditions names are really integer values and +can be stored as such. Thus, the above could be extended in the +following fashion: +.nf + + %x comment foo + %% + int line_num = 1; + int comment_caller; + + "/*" { + comment_caller = INITIAL; + BEGIN(comment); + } + + ... + + "/*" { + comment_caller = foo; + BEGIN(comment); + } + + [^*\\n]* /* eat anything that's not a '*' */ + "*"+[^*/\\n]* /* eat up '*'s not followed by '/'s */ + \\n ++line_num; + "*"+"/" BEGIN(comment_caller); + +.fi +One can then implement a "stack" of start conditions using an +array of integers. (It is likely that such stacks will become +a full-fledged +.I flex +feature in the future.) Note, though, that +start conditions do not have their own name-space; %s's and %x's +declare names in the same fashion as #define's. +.SH MULTIPLE INPUT BUFFERS +Some scanners (such as those which support "include" files) +require reading from several input streams. As +.I flex +scanners do a large amount of buffering, one cannot control +where the next input will be read from by simply writing a +.B YY_INPUT +which is sensitive to the scanning context. +.B YY_INPUT +is only called when the scanner reaches the end of its buffer, which +may be a long time after scanning a statement such as an "include" +which requires switching the input source. +.LP +To negotiate these sorts of problems, +.I flex +provides a mechanism for creating and switching between multiple +input buffers. An input buffer is created by using: +.nf + + YY_BUFFER_STATE yy_create_buffer( FILE *file, int size ) + +.fi +which takes a +.I FILE +pointer and a size and creates a buffer associated with the given +file and large enough to hold +.I size +characters (when in doubt, use +.B YY_BUF_SIZE +for the size). It returns a +.B YY_BUFFER_STATE +handle, which may then be passed to other routines: +.nf + + void yy_switch_to_buffer( YY_BUFFER_STATE new_buffer ) + +.fi +switches the scanner's input buffer so subsequent tokens will +come from +.I new_buffer. +Note that +.B yy_switch_to_buffer() +may be used by yywrap() to sets things up for continued scanning, instead +of opening a new file and pointing +.I yyin +at it. +.nf + + void yy_delete_buffer( YY_BUFFER_STATE buffer ) + +.fi +is used to reclaim the storage associated with a buffer. +.LP +.B yy_new_buffer() +is an alias for +.B yy_create_buffer(), +provided for compatibility with the C++ use of +.I new +and +.I delete +for creating and destroying dynamic objects. +.LP +Finally, the +.B YY_CURRENT_BUFFER +macro returns a +.B YY_BUFFER_STATE +handle to the current buffer. +.LP +Here is an example of using these features for writing a scanner +which expands include files (the +.B <> +feature is discussed below): +.nf + + /* the "incl" state is used for picking up the name + * of an include file + */ + %x incl + + %{ + #define MAX_INCLUDE_DEPTH 10 + YY_BUFFER_STATE include_stack[MAX_INCLUDE_DEPTH]; + int include_stack_ptr = 0; + %} + + %% + include BEGIN(incl); + + [a-z]+ ECHO; + [^a-z\\n]*\\n? ECHO; + + [ \\t]* /* eat the whitespace */ + [^ \\t\\n]+ { /* got the include file name */ + if ( include_stack_ptr >= MAX_INCLUDE_DEPTH ) + { + fprintf( stderr, "Includes nested too deeply" ); + exit( 1 ); + } + + include_stack[include_stack_ptr++] = + YY_CURRENT_BUFFER; + + yyin = fopen( yytext, "r" ); + + if ( ! yyin ) + error( ... ); + + yy_switch_to_buffer( + yy_create_buffer( yyin, YY_BUF_SIZE ) ); + + BEGIN(INITIAL); + } + + <> { + if ( --include_stack_ptr < 0 ) + { + yyterminate(); + } + + else + yy_switch_to_buffer( + include_stack[include_stack_ptr] ); + } + +.fi +.SH END-OF-FILE RULES +The special rule "<>" indicates +actions which are to be taken when an end-of-file is +encountered and yywrap() returns non-zero (i.e., indicates +no further files to process). The action must finish +by doing one of four things: +.IP - +the special +.B YY_NEW_FILE +action, if +.I yyin +has been pointed at a new file to process; +.IP - +a +.I return +statement; +.IP - +the special +.B yyterminate() +action; +.IP - +or, switching to a new buffer using +.B yy_switch_to_buffer() +as shown in the example above. +.LP +<> rules may not be used with other +patterns; they may only be qualified with a list of start +conditions. If an unqualified <> rule is given, it +applies to +.I all +start conditions which do not already have <> actions. To +specify an <> rule for only the initial start condition, use +.nf + + <> + +.fi +.LP +These rules are useful for catching things like unclosed comments. +An example: +.nf + + %x quote + %% + + ...other rules for dealing with quotes... + + <> { + error( "unterminated quote" ); + yyterminate(); + } + <> { + if ( *++filelist ) + { + yyin = fopen( *filelist, "r" ); + YY_NEW_FILE; + } + else + yyterminate(); + } + +.fi +.SH MISCELLANEOUS MACROS +The macro +.B YY_USER_ACTION +can be redefined to provide an action +which is always executed prior to the matched rule's action. For example, +it could be #define'd to call a routine to convert yytext to lower-case. +.LP +The macro +.B YY_USER_INIT +may be redefined to provide an action which is always executed before +the first scan (and before the scanner's internal initializations are done). +For example, it could be used to call a routine to read +in a data table or open a logging file. +.LP +In the generated scanner, the actions are all gathered in one large +switch statement and separated using +.B YY_BREAK, +which may be redefined. By default, it is simply a "break", to separate +each rule's action from the following rule's. +Redefining +.B YY_BREAK +allows, for example, C++ users to +#define YY_BREAK to do nothing (while being very careful that every +rule ends with a "break" or a "return"!) to avoid suffering from +unreachable statement warnings where because a rule's action ends with +"return", the +.B YY_BREAK +is inaccessible. +.SH INTERFACING WITH YACC +One of the main uses of +.I flex +is as a companion to the +.I yacc +parser-generator. +.I yacc +parsers expect to call a routine named +.B yylex() +to find the next input token. The routine is supposed to +return the type of the next token as well as putting any associated +value in the global +.B yylval. +To use +.I flex +with +.I yacc, +one specifies the +.B -d +option to +.I yacc +to instruct it to generate the file +.B y.tab.h +containing definitions of all the +.B %tokens +appearing in the +.I yacc +input. This file is then included in the +.I flex +scanner. For example, if one of the tokens is "TOK_NUMBER", +part of the scanner might look like: +.nf + + %{ + #include "y.tab.h" + %} + + %% + + [0-9]+ yylval = atoi( yytext ); return TOK_NUMBER; + +.fi +.SH TRANSLATION TABLE +In the name of POSIX compliance, +.I flex +supports a +.I translation table +for mapping input characters into groups. +The table is specified in the first section, and its format looks like: +.nf + + %t + 1 abcd + 2 ABCDEFGHIJKLMNOPQRSTUVWXYZ + 52 0123456789 + 6 \\t\\ \\n + %t + +.fi +This example specifies that the characters 'a', 'b', 'c', and 'd' +are to all be lumped into group #1, upper-case letters +in group #2, digits in group #52, tabs, blanks, and newlines into +group #6, and +.I +no other characters will appear in the patterns. +The group numbers are actually disregarded by +.I flex; +.B %t +serves, though, to lump characters together. Given the above +table, for example, the pattern "a(AA)*5" is equivalent to "d(ZQ)*0". +They both say, "match any character in group #1, followed by +zero-or-more pairs of characters +from group #2, followed by a character from group #52." Thus +.B %t +provides a crude way for introducing equivalence classes into +the scanner specification. +.LP +Note that the +.B -i +option (see below) coupled with the equivalence classes which +.I flex +automatically generates take care of virtually all the instances +when one might consider using +.B %t. +But what the hell, it's there if you want it. +.SH OPTIONS +.I flex +has the following options: +.TP +.B -b +Generate backtracking information to +.I lex.backtrack. +This is a list of scanner states which require backtracking +and the input characters on which they do so. By adding rules one +can remove backtracking states. If all backtracking states +are eliminated and +.B -f +or +.B -F +is used, the generated scanner will run faster (see the +.B -p +flag). Only users who wish to squeeze every last cycle out of their +scanners need worry about this option. (See the section on PERFORMANCE +CONSIDERATIONS below.) +.TP +.B -c +is a do-nothing, deprecated option included for POSIX compliance. +.IP +.B NOTE: +in previous releases of +.I flex +.B -c +specified table-compression options. This functionality is +now given by the +.B -C +flag. To ease the the impact of this change, when +.I flex +encounters +.B -c, +it currently issues a warning message and assumes that +.B -C +was desired instead. In the future this "promotion" of +.B -c +to +.B -C +will go away in the name of full POSIX compliance (unless +the POSIX meaning is removed first). +.TP +.B -d +makes the generated scanner run in +.I debug +mode. Whenever a pattern is recognized and the global +.B yy_flex_debug +is non-zero (which is the default), +the scanner will write to +.I stderr +a line of the form: +.nf + + --accepting rule at line 53 ("the matched text") + +.fi +The line number refers to the location of the rule in the file +defining the scanner (i.e., the file that was fed to flex). Messages +are also generated when the scanner backtracks, accepts the +default rule, reaches the end of its input buffer (or encounters +a NUL; at this point, the two look the same as far as the scanner's concerned), +or reaches an end-of-file. +.TP +.B -f +specifies (take your pick) +.I full table +or +.I fast scanner. +No table compression is done. The result is large but fast. +This option is equivalent to +.B -Cf +(see below). +.TP +.B -i +instructs +.I flex +to generate a +.I case-insensitive +scanner. The case of letters given in the +.I flex +input patterns will +be ignored, and tokens in the input will be matched regardless of case. The +matched text given in +.I yytext +will have the preserved case (i.e., it will not be folded). +.TP +.B -n +is another do-nothing, deprecated option included only for +POSIX compliance. +.TP +.B -p +generates a performance report to stderr. The report +consists of comments regarding features of the +.I flex +input file which will cause a loss of performance in the resulting scanner. +Note that the use of +.I REJECT +and variable trailing context (see the BUGS section in flex(1)) +entails a substantial performance penalty; use of +.I yymore(), +the +.B ^ +operator, +and the +.B -I +flag entail minor performance penalties. +.TP +.B -s +causes the +.I default rule +(that unmatched scanner input is echoed to +.I stdout) +to be suppressed. If the scanner encounters input that does not +match any of its rules, it aborts with an error. This option is +useful for finding holes in a scanner's rule set. +.TP +.B -t +instructs +.I flex +to write the scanner it generates to standard output instead +of +.B lex.yy.c. +.TP +.B -v +specifies that +.I flex +should write to +.I stderr +a summary of statistics regarding the scanner it generates. +Most of the statistics are meaningless to the casual +.I flex +user, but the +first line identifies the version of +.I flex, +which is useful for figuring +out where you stand with respect to patches and new releases, +and the next two lines give the date when the scanner was created +and a summary of the flags which were in effect. +.TP +.B -F +specifies that the +.I fast +scanner table representation should be used. This representation is +about as fast as the full table representation +.RB ( \-f ), +and for some sets of patterns will be considerably smaller (and for +others, larger). In general, if the pattern set contains both "keywords" +and a catch-all, "identifier" rule, such as in the set: +.nf + + "case" return TOK_CASE; + "switch" return TOK_SWITCH; + ... + "default" return TOK_DEFAULT; + [a-z]+ return TOK_ID; + +.fi +then you're better off using the full table representation. If only +the "identifier" rule is present and you then use a hash table or some such +to detect the keywords, you're better off using +.BR \-F . +.IP +This option is equivalent to +.B -CF +(see below). +.TP +.B -I +instructs +.I flex +to generate an +.I interactive +scanner. Normally, scanners generated by +.I flex +always look ahead one +character before deciding that a rule has been matched. At the cost of +some scanning overhead, +.I flex +will generate a scanner which only looks ahead +when needed. Such scanners are called +.I interactive +because if you want to write a scanner for an interactive system such as a +command shell, you will probably want the user's input to be terminated +with a newline, and without +.B -I +the user will have to type a character in addition to the newline in order +to have the newline recognized. This leads to dreadful interactive +performance. +.IP +If all this seems to confusing, here's the general rule: if a human will +be typing in input to your scanner, use +.B -I, +otherwise don't; if you don't care about squeezing the utmost performance +from your scanner and you +don't want to make any assumptions about the input to your scanner, +use +.B -I. +.IP +Note, +.B -I +cannot be used in conjunction with +.I full +or +.I fast tables, +i.e., the +.B -f, -F, -Cf, +or +.B -CF +flags. +.TP +.B -L +instructs +.I flex +not to generate +.B #line +directives. Without this option, +.I flex +peppers the generated scanner +with #line directives so error messages in the actions will be correctly +located with respect to the original +.I flex +input file, and not to +the fairly meaningless line numbers of +.B lex.yy.c. +(Unfortunately +.I flex +does not presently generate the necessary directives +to "retarget" the line numbers for those parts of +.B lex.yy.c +which it generated. So if there is an error in the generated code, +a meaningless line number is reported.) +.TP +.B -T +makes +.I flex +run in +.I trace +mode. It will generate a lot of messages to +.I stdout +concerning +the form of the input and the resultant non-deterministic and deterministic +finite automata. This option is mostly for use in maintaining +.I flex. +.TP +.B -8 +instructs +.I flex +to generate an 8-bit scanner, i.e., one which can recognize 8-bit +characters. On some sites, +.I flex +is installed with this option as the default. On others, the default +is 7-bit characters. To see which is the case, check the verbose +.B (-v) +output for "equivalence classes created". If the denominator of +the number shown is 128, then by default +.I flex +is generating 7-bit characters. If it is 256, then the default is +8-bit characters and the +.B -8 +flag is not required (but may be a good idea to keep the scanner +specification portable). Feeding a 7-bit scanner 8-bit characters +will result in infinite loops, bus errors, or other such fireworks, +so when in doubt, use the flag. Note that if equivalence classes +are used, 8-bit scanners take only slightly more table space than +7-bit scanners (128 bytes, to be exact); if equivalence classes are +not used, however, then the tables may grow up to twice their +7-bit size. +.TP +.B -C[efmF] +controls the degree of table compression. +.IP +.B -Ce +directs +.I flex +to construct +.I equivalence classes, +i.e., sets of characters +which have identical lexical properties (for example, if the only +appearance of digits in the +.I flex +input is in the character class +"[0-9]" then the digits '0', '1', ..., '9' will all be put +in the same equivalence class). Equivalence classes usually give +dramatic reductions in the final table/object file sizes (typically +a factor of 2-5) and are pretty cheap performance-wise (one array +look-up per character scanned). +.IP +.B -Cf +specifies that the +.I full +scanner tables should be generated - +.I flex +should not compress the +tables by taking advantages of similar transition functions for +different states. +.IP +.B -CF +specifies that the alternate fast scanner representation (described +above under the +.B -F +flag) +should be used. +.IP +.B -Cm +directs +.I flex +to construct +.I meta-equivalence classes, +which are sets of equivalence classes (or characters, if equivalence +classes are not being used) that are commonly used together. Meta-equivalence +classes are often a big win when using compressed tables, but they +have a moderate performance impact (one or two "if" tests and one +array look-up per character scanned). +.IP +A lone +.B -C +specifies that the scanner tables should be compressed but neither +equivalence classes nor meta-equivalence classes should be used. +.IP +The options +.B -Cf +or +.B -CF +and +.B -Cm +do not make sense together - there is no opportunity for meta-equivalence +classes if the table is not being compressed. Otherwise the options +may be freely mixed. +.IP +The default setting is +.B -Cem, +which specifies that +.I flex +should generate equivalence classes +and meta-equivalence classes. This setting provides the highest +degree of table compression. You can trade off +faster-executing scanners at the cost of larger tables with +the following generally being true: +.nf + + slowest & smallest + -Cem + -Cm + -Ce + -C + -C{f,F}e + -C{f,F} + fastest & largest + +.fi +Note that scanners with the smallest tables are usually generated and +compiled the quickest, so +during development you will usually want to use the default, maximal +compression. +.IP +.B -Cfe +is often a good compromise between speed and size for production +scanners. +.IP +.B -C +options are not cumulative; whenever the flag is encountered, the +previous -C settings are forgotten. +.TP +.B -Sskeleton_file +overrides the default skeleton file from which +.I flex +constructs its scanners. You'll never need this option unless you are doing +.I flex +maintenance or development. +.SH PERFORMANCE CONSIDERATIONS +The main design goal of +.I flex +is that it generate high-performance scanners. It has been optimized +for dealing well with large sets of rules. Aside from the effects +of table compression on scanner speed outlined above, +there are a number of options/actions which degrade performance. These +are, from most expensive to least: +.nf + + REJECT + + pattern sets that require backtracking + arbitrary trailing context + + '^' beginning-of-line operator + yymore() + +.fi +with the first three all being quite expensive and the last two +being quite cheap. +.LP +.B REJECT +should be avoided at all costs when performance is important. +It is a particularly expensive option. +.LP +Getting rid of backtracking is messy and often may be an enormous +amount of work for a complicated scanner. In principal, one begins +by using the +.B -b +flag to generate a +.I lex.backtrack +file. For example, on the input +.nf + + %% + foo return TOK_KEYWORD; + foobar return TOK_KEYWORD; + +.fi +the file looks like: +.nf + + State #6 is non-accepting - + associated rule line numbers: + 2 3 + out-transitions: [ o ] + jam-transitions: EOF [ \\001-n p-\\177 ] + + State #8 is non-accepting - + associated rule line numbers: + 3 + out-transitions: [ a ] + jam-transitions: EOF [ \\001-` b-\\177 ] + + State #9 is non-accepting - + associated rule line numbers: + 3 + out-transitions: [ r ] + jam-transitions: EOF [ \\001-q s-\\177 ] + + Compressed tables always backtrack. + +.fi +The first few lines tell us that there's a scanner state in +which it can make a transition on an 'o' but not on any other +character, and that in that state the currently scanned text does not match +any rule. The state occurs when trying to match the rules found +at lines 2 and 3 in the input file. +If the scanner is in that state and then reads +something other than an 'o', it will have to backtrack to find +a rule which is matched. With +a bit of headscratching one can see that this must be the +state it's in when it has seen "fo". When this has happened, +if anything other than another 'o' is seen, the scanner will +have to back up to simply match the 'f' (by the default rule). +.LP +The comment regarding State #8 indicates there's a problem +when "foob" has been scanned. Indeed, on any character other +than a 'b', the scanner will have to back up to accept "foo". +Similarly, the comment for State #9 concerns when "fooba" has +been scanned. +.LP +The final comment reminds us that there's no point going to +all the trouble of removing backtracking from the rules unless +we're using +.B -f +or +.B -F, +since there's no performance gain doing so with compressed scanners. +.LP +The way to remove the backtracking is to add "error" rules: +.nf + + %% + foo return TOK_KEYWORD; + foobar return TOK_KEYWORD; + + fooba | + foob | + fo { + /* false alarm, not really a keyword */ + return TOK_ID; + } + +.fi +.LP +Eliminating backtracking among a list of keywords can also be +done using a "catch-all" rule: +.nf + + %% + foo return TOK_KEYWORD; + foobar return TOK_KEYWORD; + + [a-z]+ return TOK_ID; + +.fi +This is usually the best solution when appropriate. +.LP +Backtracking messages tend to cascade. +With a complicated set of rules it's not uncommon to get hundreds +of messages. If one can decipher them, though, it often +only takes a dozen or so rules to eliminate the backtracking (though +it's easy to make a mistake and have an error rule accidentally match +a valid token. A possible future +.I flex +feature will be to automatically add rules to eliminate backtracking). +.LP +.I Variable +trailing context (where both the leading and trailing parts do not have +a fixed length) entails almost the same performance loss as +.I REJECT +(i.e., substantial). So when possible a rule like: +.nf + + %% + mouse|rat/(cat|dog) run(); + +.fi +is better written: +.nf + + %% + mouse/cat|dog run(); + rat/cat|dog run(); + +.fi +or as +.nf + + %% + mouse|rat/cat run(); + mouse|rat/dog run(); + +.fi +Note that here the special '|' action does +.I not +provide any savings, and can even make things worse (see +.B BUGS +in flex(1)). +.LP +Another area where the user can increase a scanner's performance +(and one that's easier to implement) arises from the fact that +the longer the tokens matched, the faster the scanner will run. +This is because with long tokens the processing of most input +characters takes place in the (short) inner scanning loop, and +does not often have to go through the additional work of setting up +the scanning environment (e.g., +.B yytext) +for the action. Recall the scanner for C comments: +.nf + + %x comment + %% + int line_num = 1; + + "/*" BEGIN(comment); + + [^*\\n]* + "*"+[^*/\\n]* + \\n ++line_num; + "*"+"/" BEGIN(INITIAL); + +.fi +This could be sped up by writing it as: +.nf + + %x comment + %% + int line_num = 1; + + "/*" BEGIN(comment); + + [^*\\n]* + [^*\\n]*\\n ++line_num; + "*"+[^*/\\n]* + "*"+[^*/\\n]*\\n ++line_num; + "*"+"/" BEGIN(INITIAL); + +.fi +Now instead of each newline requiring the processing of another +action, recognizing the newlines is "distributed" over the other rules +to keep the matched text as long as possible. Note that +.I adding +rules does +.I not +slow down the scanner! The speed of the scanner is independent +of the number of rules or (modulo the considerations given at the +beginning of this section) how complicated the rules are with +regard to operators such as '*' and '|'. +.LP +A final example in speeding up a scanner: suppose you want to scan +through a file containing identifiers and keywords, one per line +and with no other extraneous characters, and recognize all the +keywords. A natural first approach is: +.nf + + %% + asm | + auto | + break | + ... etc ... + volatile | + while /* it's a keyword */ + + .|\\n /* it's not a keyword */ + +.fi +To eliminate the back-tracking, introduce a catch-all rule: +.nf + + %% + asm | + auto | + break | + ... etc ... + volatile | + while /* it's a keyword */ + + [a-z]+ | + .|\\n /* it's not a keyword */ + +.fi +Now, if it's guaranteed that there's exactly one word per line, +then we can reduce the total number of matches by a half by +merging in the recognition of newlines with that of the other +tokens: +.nf + + %% + asm\\n | + auto\\n | + break\\n | + ... etc ... + volatile\\n | + while\\n /* it's a keyword */ + + [a-z]+\\n | + .|\\n /* it's not a keyword */ + +.fi +One has to be careful here, as we have now reintroduced backtracking +into the scanner. In particular, while +.I we +know that there will never be any characters in the input stream +other than letters or newlines, +.I flex +can't figure this out, and it will plan for possibly needing backtracking +when it has scanned a token like "auto" and then the next character +is something other than a newline or a letter. Previously it would +then just match the "auto" rule and be done, but now it has no "auto" +rule, only a "auto\\n" rule. To eliminate the possibility of backtracking, +we could either duplicate all rules but without final newlines, or, +since we never expect to encounter such an input and therefore don't +how it's classified, we can introduce one more catch-all rule, this +one which doesn't include a newline: +.nf + + %% + asm\\n | + auto\\n | + break\\n | + ... etc ... + volatile\\n | + while\\n /* it's a keyword */ + + [a-z]+\\n | + [a-z]+ | + .|\\n /* it's not a keyword */ + +.fi +Compiled with +.B -Cf, +this is about as fast as one can get a +.I flex +scanner to go for this particular problem. +.LP +A final note: +.I flex +is slow when matching NUL's, particularly when a token contains +multiple NUL's. +It's best to write rules which match +.I short +amounts of text if it's anticipated that the text will often include NUL's. +.SH INCOMPATIBILITIES WITH LEX AND POSIX +.I flex +is a rewrite of the Unix +.I lex +tool (the two implementations do not share any code, though), +with some extensions and incompatibilities, both of which +are of concern to those who wish to write scanners acceptable +to either implementation. At present, the POSIX +.I lex +draft is +very close to the original +.I lex +implementation, so some of these +incompatibilities are also in conflict with the POSIX draft. But +the intent is that except as noted below, +.I flex +as it presently stands will +ultimately be POSIX conformant (i.e., that those areas of conflict with +the POSIX draft will be resolved in +.I flex's +favor). Please bear in +mind that all the comments which follow are with regard to the POSIX +.I draft +standard of Summer 1989, and not the final document (or subsequent +drafts); they are included so +.I flex +users can be aware of the standardization issues and those areas where +.I flex +may in the near future undergo changes incompatible with +its current definition. +.LP +.I flex +is fully compatible with +.I lex +with the following exceptions: +.IP - +The undocumented +.I lex +scanner internal variable +.B yylineno +is not supported. It is difficult to support this option efficiently, +since it requires examining every character scanned and reexamining +the characters when the scanner backs up. +Things get more complicated when the end of buffer or file is reached or a +NUL is scanned (since the scan must then be restarted with the proper line +number count), or the user uses the yyless(), unput(), or REJECT actions, +or the multiple input buffer functions. +.IP +The fix is to add rules which, upon seeing a newline, increment +yylineno. This is usually an easy process, though it can be a drag if some +of the patterns can match multiple newlines along with other characters. +.IP +yylineno is not part of the POSIX draft. +.IP - +The +.B input() +routine is not redefinable, though it may be called to read characters +following whatever has been matched by a rule. If +.B input() +encounters an end-of-file the normal +.B yywrap() +processing is done. A ``real'' end-of-file is returned by +.B input() +as +.I EOF. +.IP +Input is instead controlled by redefining the +.B YY_INPUT +macro. +.IP +The +.I flex +restriction that +.B input() +cannot be redefined is in accordance with the POSIX draft, but +.B YY_INPUT +has not yet been accepted into the draft (and probably won't; it looks +like the draft will simply not specify any way of controlling the +scanner's input other than by making an initial assignment to +.I yyin). +.IP - +.I flex +scanners do not use stdio for input. Because of this, when writing an +interactive scanner one must explicitly call fflush() on the +stream associated with the terminal after writing out a prompt. +With +.I lex +such writes are automatically flushed since +.I lex +scanners use +.B getchar() +for their input. Also, when writing interactive scanners with +.I flex, +the +.B -I +flag must be used. +.IP - +.I flex +scanners are not as reentrant as +.I lex +scanners. In particular, if you have an interactive scanner and +an interrupt handler which long-jumps out of the scanner, and +the scanner is subsequently called again, you may get the following +message: +.nf + + fatal flex scanner internal error--end of buffer missed + +.fi +To reenter the scanner, first use +.nf + + yyrestart( yyin ); + +.fi +.IP - +.B output() +is not supported. +Output from the +.B ECHO +macro is done to the file-pointer +.I yyout +(default +.I stdout). +.IP +The POSIX draft mentions that an +.B output() +routine exists but currently gives no details as to what it does. +.IP - +.I lex +does not support exclusive start conditions (%x), though they +are in the current POSIX draft. +.IP - +When definitions are expanded, +.I flex +encloses them in parentheses. +With lex, the following: +.nf + + NAME [A-Z][A-Z0-9]* + %% + foo{NAME}? printf( "Found it\\n" ); + %% + +.fi +will not match the string "foo" because when the macro +is expanded the rule is equivalent to "foo[A-Z][A-Z0-9]*?" +and the precedence is such that the '?' is associated with +"[A-Z0-9]*". With +.I flex, +the rule will be expanded to +"foo([A-Z][A-Z0-9]*)?" and so the string "foo" will match. +Note that because of this, the +.B ^, $, , /, +and +.B <> +operators cannot be used in a +.I flex +definition. +.IP +The POSIX draft interpretation is the same as +.I flex's. +.IP - +To specify a character class which matches anything but a left bracket (']'), +in +.I lex +one can use "[^]]" but with +.I flex +one must use "[^\\]]". The latter works with +.I lex, +too. +.IP - +The +.I lex +.B %r +(generate a Ratfor scanner) option is not supported. It is not part +of the POSIX draft. +.IP - +If you are providing your own yywrap() routine, you must include a +"#undef yywrap" in the definitions section (section 1). Note that +the "#undef" will have to be enclosed in %{}'s. +.IP +The POSIX draft +specifies that yywrap() is a function and this is very unlikely to change; so +.I flex users are warned +that +.B yywrap() +is likely to be changed to a function in the near future. +.IP - +After a call to +.B unput(), +.I yytext +and +.I yyleng +are undefined until the next token is matched. This is not the case with +.I lex +or the present POSIX draft. +.IP - +The precedence of the +.B {} +(numeric range) operator is different. +.I lex +interprets "abc{1,3}" as "match one, two, or +three occurrences of 'abc'", whereas +.I flex +interprets it as "match 'ab' +followed by one, two, or three occurrences of 'c'". The latter is +in agreement with the current POSIX draft. +.IP - +The precedence of the +.B ^ +operator is different. +.I lex +interprets "^foo|bar" as "match either 'foo' at the beginning of a line, +or 'bar' anywhere", whereas +.I flex +interprets it as "match either 'foo' or 'bar' if they come at the beginning +of a line". The latter is in agreement with the current POSIX draft. +.IP - +To refer to yytext outside of the scanner source file, +the correct definition with +.I flex +is "extern char *yytext" rather than "extern char yytext[]". +This is contrary to the current POSIX draft but a point on which +.I flex +will not be changing, as the array representation entails a +serious performance penalty. It is hoped that the POSIX draft will +be emended to support the +.I flex +variety of declaration (as this is a fairly painless change to +require of +.I lex +users). +.IP - +.I yyin +is +.I initialized +by +.I lex +to be +.I stdin; +.I flex, +on the other hand, +initializes +.I yyin +to NULL +and then +.I assigns +it to +.I stdin +the first time the scanner is called, providing +.I yyin +has not already been assigned to a non-NULL value. The difference is +subtle, but the net effect is that with +.I flex +scanners, +.I yyin +does not have a valid value until the scanner has been called. +.IP - +The special table-size declarations such as +.B %a +supported by +.I lex +are not required by +.I flex +scanners; +.I flex +ignores them. +.IP - +The name +.B FLEX_SCANNER +is #define'd so scanners may be written for use with either +.I flex +or +.I lex. +.LP +The following +.I flex +features are not included in +.I lex +or the POSIX draft standard: +.nf + + yyterminate() + <> + YY_DECL + #line directives + %{}'s around actions + yyrestart() + comments beginning with '#' (deprecated) + multiple actions on a line + +.fi +This last feature refers to the fact that with +.I flex +you can put multiple actions on the same line, separated with +semi-colons, while with +.I lex, +the following +.nf + + foo handle_foo(); ++num_foos_seen; + +.fi +is (rather surprisingly) truncated to +.nf + + foo handle_foo(); + +.fi +.I flex +does not truncate the action. Actions that are not enclosed in +braces are simply terminated at the end of the line. +.SH DIAGNOSTICS +.I reject_used_but_not_detected undefined +or +.I yymore_used_but_not_detected undefined - +These errors can occur at compile time. They indicate that the +scanner uses +.B REJECT +or +.B yymore() +but that +.I flex +failed to notice the fact, meaning that +.I flex +scanned the first two sections looking for occurrences of these actions +and failed to find any, but somehow you snuck some in (via a #include +file, for example). Make an explicit reference to the action in your +.I flex +input file. (Note that previously +.I flex +supported a +.B %used/%unused +mechanism for dealing with this problem; this feature is still supported +but now deprecated, and will go away soon unless the author hears from +people who can argue compellingly that they need it.) +.LP +.I flex scanner jammed - +a scanner compiled with +.B -s +has encountered an input string which wasn't matched by +any of its rules. +.LP +.I flex input buffer overflowed - +a scanner rule matched a string long enough to overflow the +scanner's internal input buffer (16K bytes by default - controlled by +.B YY_BUF_SIZE +in "flex.skel". Note that to redefine this macro, you must first +.B #undefine +it). +.LP +.I scanner requires -8 flag - +Your scanner specification includes recognizing 8-bit characters and +you did not specify the -8 flag (and your site has not installed flex +with -8 as the default). +.LP +.I +fatal flex scanner internal error--end of buffer missed - +This can occur in an scanner which is reentered after a long-jump +has jumped out (or over) the scanner's activation frame. Before +reentering the scanner, use: +.nf + + yyrestart( yyin ); + +.fi +.LP +.I too many %t classes! - +You managed to put every single character into its own %t class. +.I flex +requires that at least one of the classes share characters. +.SH DEFICIENCIES / BUGS +See flex(1). +.SH "SEE ALSO" +.LP +flex(1), lex(1), yacc(1), sed(1), awk(1). +.LP +M. E. Lesk and E. Schmidt, +.I LEX - Lexical Analyzer Generator +.SH AUTHOR +Vern Paxson, with the help of many ideas and much inspiration from +Van Jacobson. Original version by Jef Poskanzer. The fast table +representation is a partial implementation of a design done by Van +Jacobson. The implementation was done by Kevin Gong and Vern Paxson. +.LP +Thanks to the many +.I flex +beta-testers, feedbackers, and contributors, especially Casey +Leedom, benson@odi.com, Keith Bostic, +Frederic Brehm, Nick Christopher, Jason Coughlin, +Scott David Daniels, Leo Eskin, +Chris Faylor, Eric Goldman, Eric +Hughes, Jeffrey R. Jones, Kevin B. Kenny, Ronald Lamprecht, +Greg Lee, Craig Leres, Mohamed el Lozy, Jim Meyering, Marc Nozell, Esmond Pitt, +Jef Poskanzer, Jim Roskind, +Dave Tallman, Frank Whaley, Ken Yap, and those whose names +have slipped my marginal mail-archiving skills but whose contributions +are appreciated all the same. +.LP +Thanks to Keith Bostic, John Gilmore, Craig Leres, Bob +Mulcahy, Rich Salz, and Richard Stallman for help with various distribution +headaches. +.LP +Thanks to Esmond Pitt and Earle Horton for 8-bit character support; +to Benson Margulies and Fred +Burke for C++ support; to Ove Ewerlid for the basics of support for +NUL's; and to Eric Hughes for the basics of support for multiple buffers. +.LP +Work is being done on extending +.I flex +to generate scanners in which the +state machine is directly represented in C code rather than tables. +These scanners may well be substantially faster than those generated +using -f or -F. If you are working in this area and are interested +in comparing notes and seeing whether redundant work can be avoided, +contact Ove Ewerlid (ewerlid@mizar.DoCS.UU.SE). +.LP +This work was primarily done when I was at the Real Time Systems Group +at the Lawrence Berkeley Laboratory in Berkeley, CA. Many thanks to all there +for the support I received. +.LP +Send comments to: +.nf + + Vern Paxson + Computer Science Department + 4126 Upson Hall + Cornell University + Ithaca, NY 14853-7501 + + vern@cs.cornell.edu + decvax!cornell!vern + +.fi diff --git a/man/man1/fmt.1 b/man/man1/fmt.1 new file mode 100644 index 000000000..3c731faf5 --- /dev/null +++ b/man/man1/fmt.1 @@ -0,0 +1,26 @@ +.TH FMT 1 +.SH NAME +fmt - adjust line-length for paragraphs of text +.SH SYNOPSIS +\fBfmt\fP [\-\fIwidth\fP] [\fIfiles\fP]... +.SH DESCRIPTION +\fIfmt\fR is a simple text formatter. +It inserts or deletes newlines, as necessary, to make all lines in a +paragraph be approximately the same width. +It preserves indentation and word spacing. +.PP +The default line width is 72 characters. +You can override this with the \-\fIwidth\fR flag. +If you don't name any files on the command line, +then \fIfmt\fR will read from stdin. +.PP +It is typically used from within \fIvi\fR to adjust the line breaks +in a single paragraph. +To do this, move the cursor to the top of the paragraph, +type "!}fmt", and +hit . +.SH AUTHOR +.nf +Steve Kirkendall +kirkenda@cs.pdx.edu +.fi diff --git a/man/man1/fold.1 b/man/man1/fold.1 new file mode 100644 index 000000000..44a9cabea --- /dev/null +++ b/man/man1/fold.1 @@ -0,0 +1,29 @@ +.TH FOLD 1 +.SH NAME +fold \- fold long lines +.SH SYNOPSIS +\fBfold\fR [\fB\-\fIn\fR]\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-\fIn\fR" "How long should the output lines be" +.SH EXAMPLES +.EX "fold \-60" "Fold \fIstdin\fR to 60 characters" +.EX "fold file" "Fold \fIfile\fP to 80 characters" +.SH DESCRIPTION +.PP +\fIFold\fR takes copies its input from the named file (or \fIstdin\fR, +if none is specified) to standard output. +However, lines longer than the given maximum (default 80) are broken +into multiple lines of the maximum length by inserting new line characters. +.SH "SEE ALSO" +.BR width (1). diff --git a/man/man1/format.1 b/man/man1/format.1 new file mode 100644 index 000000000..7cfbd91e2 --- /dev/null +++ b/man/man1/format.1 @@ -0,0 +1,67 @@ +.TH FORMAT 1 +.SH NAME +format \- format a PC floppy diskette +.SH SYNOPSIS +.B format +.RB [ \-v ] +.I device +.RI [ media-size +.RI [ drive-size ]] +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Format +allows a user with read-write permission to +.I device +to format a floppy. Either one of the special floppy devices must be used, +see +.BR fd (4), +or an automatic device may be used with the size of the floppy specified on +the command line. Two sizes must be given when formatting a low density +diskette in a high density drive. For example: +.PP +.RS +.ft B +.nf +format /dev/at1 +format /dev/fd1 1200 +format /dev/fd1 360 1200 +.fi +.ft P +.RE +.PP +The first two commands format a 1.2M diskette, the last formats a 360k +diskette in a 1.2M drive. A 1.44M drive knows when it's dealing with a low +density floppy, so all these commands format a 720k diskette: +.PP +.RS +.ft B +.nf +format /dev/fd0 720 +format /dev/fd0 720 1440 +format /dev/ps0 +.fi +.ft P +.RE +.PP +No sizes may be specified when using a special floppy device, a size must be +specified when using an automatic device. +.SH OPTIONS +.TP +.B \-v +Verify the process by reading each track after formatting it. Formatting is +normally blind, the controller has no idea whether it succeeds or not. Use +.B \-v +on a new box of cheap diskettes, or on a diskette that may have gone bad. +Verifying will increase formatting time by 50%. +.SH "SEE ALSO" +.BR mkfs (1), +.BR fd (4). +.SH DIAGNOSTICS +Numbers will be printed on standard output to show that it is busy. The +locations of bad sectors are printed on standard error when verifying. The +exit code is zero unless there are too many bad spots. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/fortune.1 b/man/man1/fortune.1 new file mode 100644 index 000000000..f9d0ab402 --- /dev/null +++ b/man/man1/fortune.1 @@ -0,0 +1,23 @@ +.TH FORTUNE 1 +.SH NAME +fortune \- print a fortune +.SH SYNOPSIS +\fBfortune\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "fortune" "Print a fortune" +.SH DESCRIPTION +.PP +\fIFortune\fR prints a fortune at random from the fortunes file, +\fI/usr/lib/fortune.dat\fR. This file consists of pieces +of text separated by a line containing only %%. diff --git a/man/man1/fsck.1 b/man/man1/fsck.1 new file mode 100644 index 000000000..11bca3488 --- /dev/null +++ b/man/man1/fsck.1 @@ -0,0 +1,51 @@ +.TH FSCK 1 +.SH NAME +fsck, fsck1 \- perform file system consistency check +.SH SYNOPSIS +\fBfsck\fR [\fB\-aclmrs\fR]\fR [\fIdevice\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "Automatically repair inconsistencies" +.FL "\-c" "Check and list only the specified i-nodes +.FL "\-l" "List the files and directories in the filesytem +.FL "\-r" "Prompt user for repairs if inconsistencies are found +.FL "\-s" "List the superblock of the file system" +.SH EXAMPLES +.EX "fsck /dev/hd4" "Check file system on \fI/dev/hd4\fR" +.EX "fsck \-a /dev/at0" "Automatically fix errors on \fI/dev/at0\fR" +.EX "fsck \-l /dev/fd0" "List the contents of \fI/dev/fd0\fR" +.EX "fsck \-c 2 3 /dev/hd3" "Check and list \fI/dev/hd3\fR i-nodes 2 & 3" +.SH DESCRIPTION +.PP +\fIFsck\fR performs consistency checks on the file systems which reside +on the specified devices. +\fIFsck1\fR is an alternate version for use on obsolete V1 file systems. +When either the \fB\-a\fR or \fB\-r\fR flags are given, the file system +will be repaired if errors are found. +Before running \fIfsck\fR on a mounted file system, it must first be unmounted. +Trying to repair a mounted file system is dangerous and should not be +attempted. +.PP +To repair the root file system (which cannot be unmounted), first +type CTRL-F9 at the console to kill any and all processes. Log back in +as \fBroot\fR, type \fIsync\fR to force any buffered changes to disk, +run \fIfsck\fR on the root file system and immediately reboot the +computer by typing \fIreboot\fR. +.PP +It is necessary to kill all processes before repairing the root file system +to prevent them from modifying any disk blocks while \fIfsck\fR is running. +This is only necessary for the root file system, any other file system can +simply be unmounted before it is checked. +.SH "SEE ALSO" +.BR mkfs (1), +.BR mount (1). diff --git a/man/man1/grep.1 b/man/man1/grep.1 new file mode 100644 index 000000000..7c79b59c7 --- /dev/null +++ b/man/man1/grep.1 @@ -0,0 +1,50 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for lines containing a given pattern +.SH SYNOPSIS +\fBgrep\fR [\fB\-elnsv\fR] \fIpattern\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-e" "\fB\-e \fIpattern\fR is the same as \fIpattern\fP +.FL "\-c" "Print a count of lines matched" +.FL "\-i" "Ignore case" +.FL "\-l" "Print file names, no lines" +.FL "\-n" "Print line numbers" +.FL "\-s" "Status only, no printed output" +.FL "\-v" "Select lines that do not match" +.SH EXAMPLES +.EX "grep mouse file " "Find lines in \fIfile\fP containing \fImouse\fP" +.EX "grep [0\-9] file" "Print lines containing a digit" +.SH DESCRIPTION +.PP +.I Grep +searches one or more files (by default, \fIstdin\fR) and selects out +all the lines that match the pattern. +All the regular expressions accepted by +.I ed +and +.I mined +are allowed. +In addition, + can be used instead of \(** to mean 1 or more occurrences, +? can be used to mean 0 or 1 occurrences, and +| can be used between two regular expressions to mean either +one of them. +Parentheses can be used for grouping. +If a match is found, exit status 0 is returned. +If no match is found, exit status 1 is returned. +If an error is detected, exit status 2 is returned. +.SH "SEE ALSO" +.BR cgrep (1), +.BR fgrep (1), +.BR sed (1), +.BR awk (9). diff --git a/man/man1/head.1 b/man/man1/head.1 new file mode 100644 index 000000000..a4acc0542 --- /dev/null +++ b/man/man1/head.1 @@ -0,0 +1,28 @@ +.TH HEAD 1 +.SH NAME +head \- print the first few lines of a file +.SH SYNOPSIS +\fBhead\fR [\fB\-\fIn\fR]\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-\fIn\fR" "How many lines to print" +.SH EXAMPLES +.EX "head \-6" "Print first 6 lines of \fIstdin\fR" +.EX "head \-1 file1 file2" "Print first line of two files" +.SH DESCRIPTION +.PP +The first few lines of one or more files are printed. +The default count is 10 lines. +The default file is \fIstdin\fR. +.SH "SEE ALSO" +.BR tail (1). diff --git a/man/man1/host.1 b/man/man1/host.1 new file mode 100644 index 000000000..751dbe301 --- /dev/null +++ b/man/man1/host.1 @@ -0,0 +1,207 @@ +.\" ++Copyright++ 1993 +.\" - +.\" Copyright (c) 1993 +.\" 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. +.\" - +.\" Portions Copyright (c) 1993 by Digital Equipment Corporation. +.\" +.\" 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, and that +.\" the name of Digital Equipment Corporation not be used in advertising or +.\" publicity pertaining to distribution of the document or software without +.\" specific, written prior permission. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL +.\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT +.\" CORPORATION 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. +.\" - +.\" --Copyright-- +.\" $Id$ +.TH HOST 1 +.SH NAME +host \- look up host names using domain server +.SH SYNOPSIS +host [-l] [-v] [-w] [-r] [-d] [-t querytype] [-a] host [ server ] +.SH DESCRIPTION +.I Host +looks for information about Internet hosts. It gets this information +from a set of interconnected servers that are spread across the +country. By default, it simply converts between host names and +Internet addresses. However with the -t or -a options, it can be used +to find all of the information about this host that is maintained +by the domain server. +.PP +The arguments can be either host names or host numbers. The program +first attempts to interpret them as host numbers. If this fails, +it will treat them as host names. A host number consists of +first decimal numbers separated by dots, e.g. 128.6.4.194 +A host name +consists of names separated by dots, e.g. topaz.rutgers.edu. +Unless the name ends in a dot, the local domain +is automatically tacked on the end. Thus a Rutgers user can say +"host topaz", and it will actually look up "topaz.rutgers.edu". +If this fails, the name is tried unchanged (in this case, "topaz"). +This same convention is used for mail and other network utilities. +The actual suffix to tack on the end is obtained +by looking at the results of a "hostname" call, and using everything +starting at the first dot. (See below for a description of +how to customize the host name lookup.) +.PP +The first argument is the host name you want to look up. +If this is a number, an "inverse query" is done, i.e. the domain +system looks in a separate set of databases used to convert numbers +to names. +.PP +The second argument is optional. It +allows you to specify a particular server to query. If you don't +specify this argument, the default server (normally the local machine) +is used. +.PP +If a name is specified, you may see output of three different kinds. +Here is an example that shows all of them: +.br + % host sun4 +.br + sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU +.br + ATHOS.RUTGERS.EDU has address 128.6.5.46 +.br + ATHOS.RUTGERS.EDU has address 128.6.4.4 +.br + ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU +.br +The user has typed the command "host sun4". The first line indicates +that the name "sun4.rutgers.edu" is actually a nickname. The official +host name is "ATHOS.RUTGERS.EDU'. The next two lines show the +address. If a system has more than one network interface, there +will be a separate address for each. The last line indicates +that ATHOS.RUTGERS.EDU does not receive its own mail. Mail for +it is taken by ARAMIS.RUTGERS.EDU. There may be more than one +such line, since some systems have more than one other system +that will handle mail for them. Technically, every system that +can receive mail is supposed to have an entry of this kind. If +the system receives its own mail, there should be an entry +the mentions the system itself, for example +"XXX mail is handled by XXX". However many systems that receive +their own mail do not bother to mention that fact. If a system +has a "mail is handled by" entry, but no address, this indicates +that it is not really part of the Internet, but a system that is +on the network will forward mail to it. Systems on Usenet, Bitnet, +and a number of other networks have entries of this kind. +.PP +There are a number of options that can be used before the +host name. Most of these options are meaningful only to the +staff who have to maintain the domain database. +.PP +The option -w causes host to wait forever for a response. Normally +it will time out after around a minute. +.PP +The option -v causes printout to be in a "verbose" format. This +is the official domain master file format, which is documented +in the man page for "named". Without this option, output still follows +this format in general terms, but some attempt is made to make it +more intelligible to normal users. Without -v, +"a", "mx", and "cname" records +are written out as "has address", "mail is handled by", and +"is a nickname for", and TTL and class fields are not shown. +.PP +The option -r causes recursion to be turned off in the request. +This means that the name server will return only data it has in +its own database. It will not ask other servers for more +information. +.PP +The option -d turns on debugging. Network transactions are shown +in detail. +.PP +The option -t allows you to specify a particular type of information +to be looked up. The arguments are defined in the man page for +"named". Currently supported types are a, ns, md, mf, cname, +soa, mb, mg, mr, null, wks, ptr, hinfo, minfo, mx, uinfo, +uid, gid, unspec, and the wildcard, which may be written +as either "any" or "*". Types must be given in lower case. +Note that the default is to look first for "a", and then "mx", except +that if the verbose option is turned on, the default is only "a". +.PP +The option -a (for "all") is equivalent to "-v -t any". +.PP +The option -l causes a listing of a complete domain. E.g. +.br + host -l rutgers.edu +.br +will give a listing of all hosts in the rutgers.edu domain. The -t +option is used to filter what information is presented, as you +would expect. The default is address information, which also +include PTR and NS records. The command +.br + host -l -v -t any rutgers.edu +.br +will give a complete download of the zone data for rutgers.edu, +in the official master file format. (However the SOA record is +listed twice, for arcane reasons.) NOTE: -l is implemented by +doing a complete zone transfer and then filtering out the information +the you have asked for. This command should be used only if it +is absolutely necessary. +.SH CUSTOMIZING HOST NAME LOOKUP +In general, if the name supplied by the user does not +have any dots in it, a default domain is appended to the end. +This domain can be defined in /etc/resolv.conf, but is normally derived +by taking the local hostname after its first dot. The user can override +this, and specify a different default domain, using the environment +variable +.IR LOCALDOMAIN . +In addition, the user can supply his own abbreviations for host names. +They should be in a file consisting of one line per abbreviation. +Each line contains an abbreviation, a space, and then the full +host name. This file must be pointed to by an environment variable +.IR HOSTALIASES , +which is the name of the file. +.SH "See Also" +named (8) +.SH BUGS +Unexpected effects can happen when you type a name that is not +part of the local domain. Please always keep in mind the +fact that the local domain name is tacked onto the end of every +name, unless it ends in a dot. Only if this fails is the name +used unchanged. +.PP +The -l option only tries the first name server listed for the +domain that you have requested. If this server is dead, you +may need to specify a server manually. E.g. to get a listing +of foo.edu, you could try "host -t ns foo.edu" to get a list +of all the name servers for foo.edu, and then try "host -l foo.edu xxx" +for all xxx on the list of name servers, until you find one that +works. diff --git a/man/man1/hostaddr.1 b/man/man1/hostaddr.1 new file mode 100644 index 000000000..775cecf3e --- /dev/null +++ b/man/man1/hostaddr.1 @@ -0,0 +1,43 @@ +.TH HOSTADDR 1 +.SH NAME +hostaddr \- show ethernet address, IP address or hostname +.SH SYNOPSIS +.B hostaddr +.RB [ \-eiah ] +.RB [ \-E +.IR eth-device ] +.RB [ \-I +.IR ip-device ] +.SH DESCRIPTION +Without any of the +.B \-eia +options, +.B hostaddr +shows the ethernet address, IP address and hostname of the local host on one +line in the given order. With options only the wanted fields are shown, +still in the same order, not in option order. +.SH OPTIONS +.TP +.B \-e +Show the ethernet address. +.TP +.B \-i +Show the IP address. +.TP +.B \-a +Show the fully qualified hostname. The IP address is shown if it +can't be translated to a host name. This usually indicates that the +DNS reverse address translation tables are incomplete or that +the name daemon couldn't be contacted. +.TP +.B \-h +Set the hostname of the machine if the caller is the superuser. (Used at +boot time by the network initialization scripts.) +.SH "SEE ALSO" +.BR ifconfig (8), +.BR dhcpd (8), +.BR nonamed (8), +.BR inet (8), +.BR boot (8). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/id.1 b/man/man1/id.1 new file mode 100644 index 000000000..ba3d6a311 --- /dev/null +++ b/man/man1/id.1 @@ -0,0 +1,29 @@ +.TH ID 1 +.SH NAME +id \- print the uid and gid +.SH SYNOPSIS +\fBid\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "id" "Print the uid and gid" +.SH DESCRIPTION +.PP +\fIId\fR prints the current uid and gid, both numerically and symbolically. +If the effective uid and gid are different from the real ones, all of them +are printed. +.PP +Under Minix-vmd the supplementary group IDs are also printed. +.SH "SEE ALSO" +.BR getuid (2), +.BR getgid (2), +.BR getgroups (2). diff --git a/man/man1/ifdef.1 b/man/man1/ifdef.1 new file mode 100644 index 000000000..d4b631a21 --- /dev/null +++ b/man/man1/ifdef.1 @@ -0,0 +1,44 @@ +.TH IFDEF 1 +.SH NAME +ifdef \- remove #ifdefs from a file +.SH SYNOPSIS +\fBifdef \fR[\fB\-t\fR] [\fB\-d\fIsymbol\fR] [\fB\-D\fIsymbol\fR] [\fB\-U\fIsymbol\fR] [\fB\-I\fIsymbol\fR] [file]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-D" "Define symbol permanently" +.FL "\-I" "Ignore symbol" +.FL "\-U" "Undefine symbol permanently" +.FL "\-d" "Define symbol. It may be #undef'ed later" +.FL "\-t" "Produce a table of the symbols on \fIstdout\fR" +.SH EXAMPLES +.EX "ifdef \-DUNIX file.c >newfile.c" "Define \fIUNIX\fR" +.EX "ifdef \-D_MINIX \-UDOS y.c "Define \fI_MINIX\fR, undefine \fIDOS\fR" +.SH DESCRIPTION +.PP +\fIIfdef\fR +allows conditional code [ #ifdef ... #endif ] +to be selectively removed from C files, but at the same time leaving +all other C preprocessor commands intact such as #define, #include etc. +Input to +.I ifdef +is either the file named as the last argument, or \fIstdin\fR if no file +is named. +Output goes to \fIstdout\fR. +.PP +Symbols may be defined with the \fB\-d\fR or \fB\-D\fR flags just like +\fIcpp\fR, except that the latter option ignores subsequent \fI#undefs\fR. +It is not permitted to give values to symbols. +Similarly, \fB\-U\fR undefines a symbol and ignores subsequent +\fI#defines\fRs. +Symbols defined with \fB\-I\fR are ignored; any \fI#ifdef\fR using an +ignored symbol will be left intact. diff --git a/man/man1/install.1 b/man/man1/install.1 new file mode 100644 index 000000000..081dd6ac4 --- /dev/null +++ b/man/man1/install.1 @@ -0,0 +1,177 @@ +.TH INSTALL 1 +.SH NAME +install \- install files +.SH SYNOPSIS +.in +5 +.ti -5 +.B install +.RB [ \-lcsz\fIN\fP "] [" \-o +.IR owner ] +.RB [ \-g +.IR group ] +.RB [ \-m +.IR mode ] +.RB [ \-S +.IR stack ] +.RI [ file1 ] +.I file2 +.br +.ti -5 +.B install +.RB [ \-lcsz\fIN\fP "] [" \-o +.IR owner ] +.RB [ \-g +.IR group ] +.RB [ \-m +.IR mode ] +.RB [ \-S +.IR stack ] +.IR file " ... " dir +.br +.ti -5 +.B install \-d +.RB [ \-o +.IR owner ] +.RB [ \-g +.IR group ] +.RB [ \-m +.IR mode ] +.I directory +.in -5 +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Install +puts executables, manual pages, and library files in their proper place +in the bin, man, and lib directories. The first two forms of the +command are like +.BR cp (1) +copying either one file to another or copying several files to a +directory. The "\fB\-d\fP" form is like +.BR mkdir (1) +with the +.B \-p +flag. +.I File1 +may be omitted if neither +.B \-l +nor +.B \-c +is given to change the attributes of +.IR file2 . +.PP +Attributes are always copied from the source file, use the options to change. +Note that the source file's attributes are changed with the destination file +if they are linked. So copy the file if you change it in a way that makes +it read-only. You would otherwise not be able to compile a command again. +.SH OPTIONS +.TP +.B \-l +Link the destination to the source file instead of copying it. This is done +to either save space on a file system with both the source and the bin +directories on it, or to install synonyms to a command. +.TP +.B \-c +Copy the source file to its proper place. This option is the default if +.B \-l +is not given. With +.BR \-l , +the file is copied if the link fails. +.TP +.B \-s +Strip the destination file of its symbol table, +.I if +it is an executable, and +.I if +it is actually copied. It has no effect on a link or a non-executable. +.TP +.B \-z +Compress the executable using +.BR compress (1) +and prepend a header line that calls +.BR zexec (1) +to decompress and execute the binary. This will on average save 40% disk +space at the expense of a slower startup time. Like +.B \-s +the file must be actually copied for the flag to have effect. +.TP +.BI \- N +Use +.BI "gzip \-" N +to compress the binary. You may see up to 60% space savings, but it will +take much longer. +.I N +is a digit from 1 to 9 telling the compression effort, see +.BR gzip (1). +.TP +.B \-d +Make a directory, usually to install files in a separate directory in a +library. Intermediate directories in the path are created with the same +attributes as the final directory. Only the attributes of the final +directory are set if the directory exists. +.TP +.BI \-o " owner" +Set the owner of the target. This only works if the invoker is the +super-user, or if +.B install +is run setuid root and the invoker is a member of group zero. If +.B \-o +is omitted then the ownership is copied from the source file, or set to +the id of the invoker if a directory is made. +.TP +.BI \-g " group" +Like +.BR \-o , +but for the group ownership of the target. +.TP +.BI \-m " mode" +.I Mode +is an octal number that specifies the mode the target should get. The +default is the source file's mode with a +.B chmod a+rX +applied to it, or 755 for a new directory. Implies +.BR "\-o 0" , +or +.BR "\-g 0" +if a file is to be set-uid or set-gid and the invoker has permission to +change ownership. This trick allows a group 0 member to install third party +software, even though it expects to be installed by root. +.TP +.BI \-S " stack" +Sets the maximum amount of heap + stack that an executable may have when +running. The argument is a C-style decimal, octal or hexadecimal +number, optionally followed by the multipliers +.BR m , +.BR k , +.BR w , +and +.B b +for mega (1024*1024), kilo (1024), "word" (2 or 4), and byte (1). Uppercase +.B M +is also accepted for those who know what S.I. means. The compilers use +.B \-S 32kw +by default, that translates to 64kb for an 8086, and 128kb for other +architectures. This option is ignored on a non-executable. +.SH "SEE ALSO" +.BR ln (1), +.BR cp (1), +.BR strip (1), +.BR compress (1), +.BR gzip (1), +.BR zexec (1), +.BR chown (8), +.BR chgrp (1), +.BR chmod (1), +.BR chmem (1), +.BR mkdir (1). +.SH BUGS +Uppercase +.BR K , +.BR W , +and +.B B +are also accepted for those who don't know what S.I. means. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/isodir.1 b/man/man1/isodir.1 new file mode 100644 index 000000000..2c80815d0 --- /dev/null +++ b/man/man1/isodir.1 @@ -0,0 +1,29 @@ +.TH ISODIR 1 +.SH NAME +isodir \- list ISO9660 or High Sierra directories +.SH SYNOPSIS +\fBisodir\fP \-[\fBlr\fP] \fIinput_file\fP [\fIdir\fP] +.SH DESCRIPTION +\fBIsodir\fP reads directories on a file system in ISO9660 or High Sierra +Group format (usually residing on cdrom) and lists their contents on +standard output. Directory names should contain slashes to separate +components. The names \fBisodir\fP, \fBisoread\fP, and \fBisoinfo\fP are all +links to the same program. The program sees which function to perform by +looking how it was called. +.PP +.IP \-l +Lists all info on files and directories (size, date, time) +.IP \-r +Recursively descend and print subdirectories +.IP \-B +List the byte offset and size of a file or directory. (Useful in scripts that +want to operate on an ISO image file. To add a Minix partition table, for +instance.) +.SH "BUGS" +Only Interchange level-1 is supported. The Red Rock extensions and Interchange +level-2 are not implemented. +.SH "SEE ALSO" +.BR isoread (1), +.BR isoinfo (1). +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/isoinfo.1 b/man/man1/isoinfo.1 new file mode 100644 index 000000000..495297052 --- /dev/null +++ b/man/man1/isoinfo.1 @@ -0,0 +1,19 @@ +.TH ISOINFO 1 +.SH NAME +isoinfo \- list an ISO9660 or High Sierra volume descriptor +.SH SYNOPSIS +\fBisoinfo\fP [\fIinput_file\fP] +.SH DESCRIPTION +\fBIsoinfo\fP reads the volume descriptor from an ISO9660 or High Sierra +Group file system (usually residing on cdrom) and lists its contents on +standard output. \fBisodir\fP, \fBisoread\fP, and \fBisoinfo\fP are all +links to the same program. The program sees which function to perform by +looking how it was called. +.SH "BUGS" +Only Interchange level-1 is supported. The Red Rock extensions and Interchange +level-2 are not implemented. +.SH "SEE ALSO" +.BR isodir (1), +.BR isoread (1). +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/isoread.1 b/man/man1/isoread.1 new file mode 100644 index 000000000..52d2b1df3 --- /dev/null +++ b/man/man1/isoread.1 @@ -0,0 +1,27 @@ +.TH ISOREAD 1 +.SH NAME +isoread \- read a file in ISO9660 or High Sierra format +.SH SYNOPSIS +\fBisoread\fP \-[\fBa\fP] [\fIinput_file\fP] \fIfile\fP +.SH DESCRIPTION +\fBIsoread\fP reads a file in ISO9660 or High Sierra Group format (usually +residing on cdrom) and lists its contents on standard output. The file path +should contain slashes to separate components. The names \fBisodir\fP, +\fBisoread\fP, and \fBisoinfo\fP are all links to the same program. The +program sees which function to perform by looking how it was called. +.PP +.IP \-a +(ASCII) -- convert MS-DOS text files to UNIX-style text files by dropping +the ^M at the end of each line. +.IP \-B +List the byte offset and size of a file. (Useful in scripts that +want to operate on an ISO image file. To add a Minix partition table, for +instance.) +.SH "BUGS" +Only Interchange level-1 is supported. The Red Rock extensions and Interchange +level-2 are not implemented. +.SH "SEE ALSO" +.BR isodir (1), +.BR isoinfo (1). +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/join.1 b/man/man1/join.1 new file mode 100644 index 000000000..afa9c99a7 --- /dev/null +++ b/man/man1/join.1 @@ -0,0 +1,118 @@ +.\" @(#)join.1 6.1 (Berkeley) 4/29/85 +.\" +.TH JOIN 1 "April 29, 1985" +.AT 3 +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.B join +.RB [ \-a\fIn ] +.RB [ \-e +.IR s ] +.RB [ \-o +.IR list ] +.RB [ \-t\fIc ] +file1 file2 +.SH DESCRIPTION +.B Join +forms, on the standard output, +a join +of the two relations specified by the lines of +.I file1 +and +.IR file2 . +If +.I file1 +is `\-', the standard input is used. +.PP +.I File1 +and +.I file2 +must be sorted in increasing ASCII collating +sequence on the fields +on which they are to be joined, +normally the first in each line. +.PP +There is one line in the output +for each pair of lines in +.I file1 +and +.I file2 +that have identical join fields. +The output line normally consists of the common field, +then the rest of the line from +.IR file1 , +then the rest of the line from +.IR file2 . +.PP +Fields are normally separated by blank, tab or newline. +In this case, multiple separators count as one, and +leading separators are discarded. +.PP +These options are recognized: +.TP +.BI \-a n +In addition to the normal output, +produce a line for each unpairable line in file +.IR n , +where +.I n +is 1 or 2. +.TP +.BI \-e " s" +Replace empty output fields by string +.IR s . +.ig +.TP +.BI \-j "n m" +Join on the +.IR m th +field of file +.IR n . +If +.I n +is missing, use the +.IR m th +field in each file. +.. +.TP +.BI \-o " list" +Each output line comprises the fields specified in +.IR list , +each element of which has the form +.IR n . m , +where +.I n +is a file number and +.I m +is a field number. +.PP +.TP +.BI \-t c +Use character +.I c +as a separator (tab character). +Every appearance of +.I c +in a line is significant. +.SH "SEE ALSO" +.BR sort (1), +.BR comm (1), +.BR awk (1). +.SH BUGS +With default field separation, +the collating sequence is that of +.BR "sort \-b" ; +with +.BR \-t , +the sequence is that of a plain sort. +.PP +The conventions of +.BR join , +.BR sort , +.BR comm , +.BR uniq , +.BR look +and +.BR awk (1) +are wildly incongruous. diff --git a/man/man1/kill.1 b/man/man1/kill.1 new file mode 100644 index 000000000..a93a2c967 --- /dev/null +++ b/man/man1/kill.1 @@ -0,0 +1,35 @@ +.TH KILL 1 +.SH NAME +kill \- send a signal to a process +.SH SYNOPSIS +\fBkill\fR [\fB\-\fIn\fR] \fIprocess\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-\fIn\fR" "Signal number to send" +.FL "\-\fINAME\fR" "Named signal to send" +.SH EXAMPLES +.EX "kill 35" "Send signal 15 to process 35" +.EX "kill \-9 40" "Send signal 9 to process 40" +.EX "kill \-2 0" "Send signal 2 to whole terminal process group" +.EX "kill \-HUP -123" "Send a hangup to process group 123" +.SH DESCRIPTION +.PP +A signal is sent to a given process. +By default signal 15 (SIGTERM) is sent. +Process 0 means all the processes in the sender's process group. +A process group can be signalled by the negative value of the process +group ID. +Signals may be numerical, or the name of the signal without \fBSIG\fP. +.SH "SEE ALSO" +.BR kill (2), +.BR sigaction (2). diff --git a/man/man1/last.1 b/man/man1/last.1 new file mode 100644 index 000000000..d1a135c93 --- /dev/null +++ b/man/man1/last.1 @@ -0,0 +1,44 @@ +.TH LAST 1 +.SH NAME +last, uptime \- display recent on-line session records, show uptime +.SH SYNOPSIS +\fBlast\fR [\fB\-f \fIfile\fR]\fR [\fB\-r\fR] [\fB\-\fIn\fR] [\fIname\fR] [\fItty\fR] ...\fR +.br +\fBuptime\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-f" "Use \fIfile\fR instead of /usr/adm/wtmp" +.FL "\-r" "Search backwards only to last reboot" +.FL "\-u" "Print uptime since last reboot" +.FL "\-\fIn\fP" "Print a maximum of \fIn\fR lines" +.SH EXAMPLES +.EX "last reboot" "When was the system last rebooted?" +.EX "last ast" "When was the last login for ast?" +.EX "last \-10 tty00 tty01" "Display last 10 logins on tty00 or tty01" +.EX "uptime" "Display uptime (likewise \fBlast \-u\fR)" +.SH DESCRIPTION +.PP +.I Last +Searches backward through the login administration file (default is +\fI/usr/adm/wtmp\fR), printing information about previous logins and +reboots. +During a long search, the SIGQUIT signal (CTRL-\\) causes \fIlast\fR to +display how far back it has gone; it then continues. +.PP +.IR Uptime , +an alias for +.IR "last \-u" , +displays the time the system is running since the last reboot. +.SH "SEE ALSO" +.BR who (1), +.BR utmp (5). diff --git a/man/man1/leave.1 b/man/man1/leave.1 new file mode 100644 index 000000000..d1ec8452f --- /dev/null +++ b/man/man1/leave.1 @@ -0,0 +1,26 @@ +.TH LEAVE 1 +.SH NAME +leave \- warn when it is time to go home +.SH SYNOPSIS +\fBleave\fR [\fR [\fB+\fR] \fIhh\fR[\fB:\fR]\fImm\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "leave 1500" "Issue a warning at 2:55 p.m." +.EX "leave 10:00" "Issue a warning at 9:55 a.m." +.EX "leave + 30" "Issue a warning in 25 minutes" +.SH DESCRIPTION +.PP +\fILeave\fR sets an alarm clock to a specified time and issues a warning +5 minutes before, 1 minute before, and at the time to leave. +It then keeps issuing warnings every minute for 10 minutes, then quits. +If no time is provided, the program prompts for one. diff --git a/man/man1/loadfont.1 b/man/man1/loadfont.1 new file mode 100644 index 000000000..ea055e472 --- /dev/null +++ b/man/man1/loadfont.1 @@ -0,0 +1,37 @@ +.TH LOADFONT 1 +.SH NAME +loadfont \- load a font into the video card +.SH SYNOPSIS +\fBloadfont \fIfontfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "loadfont iso1.fnt" "Loads the ISO 8859-1 (Latin-1) font" +.SH DESCRIPTION +.PP +.I Loadfont +loads a custom font into the video card (EGA or VGA). The font character +size has to be 8x16 pixels and the font file must contain 256 characters for +a total size of 4 kilobytes. +.PP +.I Loadfont +together with +.I loadkeys +allow the console and keyboard to be customized to national conventions. +.PP +If it exists, the file +.I /etc/font +is loaded as a custom font by +.B /usr/etc/rc +at boot time. +.SH "SEE ALSO" +.BR console (4). diff --git a/man/man1/loadkeys.1 b/man/man1/loadkeys.1 new file mode 100644 index 000000000..55d01a5f8 --- /dev/null +++ b/man/man1/loadkeys.1 @@ -0,0 +1,30 @@ +.TH LOADKEYS 1 +.SH NAME +loadkeys \- load a keyboard map into the keyboard driver +.SH SYNOPSIS +\fBloadkeys \fImapfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "loadkeys spanish.map" "Load a map for a Spanish keyboard" +.SH DESCRIPTION +.PP +.I Loadkeys +changes the key number to character mapping. This is necessary for national +keyboards that have different symbols on the keys that the standard U.S. +English keyboard. The file +.I /etc/keymap +is the first thing loaded by +.I /etc/rc +at boot time if it exists. +.SH "SEE ALSO" +.BR console (4). diff --git a/man/man1/login.1 b/man/man1/login.1 new file mode 100644 index 000000000..b49f64b6c --- /dev/null +++ b/man/man1/login.1 @@ -0,0 +1,28 @@ +.TH LOGIN 1 +.SH NAME +login \- log into the computer +.SH SYNOPSIS +\fBlogin\fR [\fIuser\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "login ast" "Login as ast" +.SH DESCRIPTION +.PP +\fILogin\fR allows a logged in user to login as someone else without first +logging out. +If a password is needed, \fIlogin\fR will prompt for it. +.SH "SEE ALSO" +.BR su (1), +.BR init (8), +.BR getty (8), +.BR rlogin (1). diff --git a/man/man1/look.1 b/man/man1/look.1 new file mode 100644 index 000000000..61429f975 --- /dev/null +++ b/man/man1/look.1 @@ -0,0 +1,38 @@ +.TH LOOK 1 +.SH NAME +look \- find lines in a sorted list +.SH SYNOPSIS +.B look +.RB [ \-df ] +.I string +.RI [ file ] +.SH DESCRIPTION +.B Look +consults a sorted file and prints all lines that begin with +.IR string . +It uses binary search. The options +.B \-d +and +.B \-f +affect comparisons as in +.BR sort (1). +If no file is specified, +.B /usr/lib/dict/words +is assumed with collating sequence +.BR \-df . +.SH OPTIONS +.TP 5 +.B \-d +Dictionary order: compare letters, digits and whitespace. +.TP 5 +.B \-f +Fold. Upper case letters compare equal to lower case. +.SH FILES +.TP 25 +.B /usr/lib/dict/words +Sorted list of English words. +.SH "SEE ALSO" +.BR sort (1), +.BR spell (1). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/lp.1 b/man/man1/lp.1 new file mode 100644 index 000000000..a316d4fc9 --- /dev/null +++ b/man/man1/lp.1 @@ -0,0 +1,59 @@ +.TH LP 1 +.SH NAME +lp, lpd \- copy a file to the line printer +.SH SYNOPSIS +.B lp +.RI [ file " ...]" +.SH DESCRIPTION +Each file argument to +.B lp +is send to the line printer to be printed. Standard input is read and +printed if there are no arguments. +.B Lp +executes +.B /usr/lib/lpd +with each file as input. +.B Lpd +puts the file in +.B /usr/spool/lpd +and starts printing the jobs on +.B /dev/lp +unless another +.B lpd +is already running. If +.B lpd +finds any character in the input that it doesn't know how to handle then it +will print the rest of the file without any special treatment. This also +means that no formfeed is sent after the file has been printed to force out +the page. +.B Lpd +simply assumes that you know what you are doing. (dumb, eh?) +.PP +Note: Don't do anything with a file until it is printed, +.B lpd +only makes a copy of a file in the spool directory when it is not world +readable. If it can be read then it is printed directly. +.SH FILES +.TP 20 +.BI /usr/spool/lpd/job XXXXX +Information about a job. +.TP +.BI /usr/spool/lpd/tmp XXXXX +Associated file to be printed. +.TP +.B /etc/termcap +The 'lp' entry describes the printer by the "li#" and "co#" fields. By +default 66 lines (li#66), and 80 columns (co#80). +.SH "SEE ALSO" +.BR lp (4), +.BR termcap (5), +.BR termcap (7). +.SH BUGS +Not spooling a world readable file may not be such a smart idea. +.PP +A formfeed should be printed and the printer reset after a job full of escape +codes, but this may cost paper. +.PP +No banner page. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/ls.1 b/man/man1/ls.1 new file mode 100644 index 000000000..0bbd07a6e --- /dev/null +++ b/man/man1/ls.1 @@ -0,0 +1,164 @@ +.TH LS 1 +.SH NAME +ls \- list the contents of a directory +.SH SYNOPSIS +\fBls\fP [\fB\-acdfghilpqrstu1ACDFLMRTX\fP] [\fIname\fP...] +.SH DESCRIPTION +For each file argument, list it. For each directory argument, list its +contents. The current working directory is listed when no files are named. +Information is printed multicolumn on terminals, single column if the output +is redirected. The options control what information is shown and how. +.PP +.B Ls +has two sources other then the command line to draw options from, one is +the environment variable +.B LSOPTS +that is scanned for option letters when the output of +.B ls +is displayed on a terminal. The other is the name of +.B ls +itself. If +.B ls +is linked to another name, then all the characters after the l are used as +flags too, except that d, f, r, t and x are translated to D, F, R, T and X. +Useful links are +.BR ll , +.BR lf , +.B lm +and +.BR lx . +.PP +Files whose names start with a dot are by default not listed. +.PP +Note that standard Minix doesn't have symbolic links or sockets and +.B \-u +and +.B \-c +are no-ops on a V1 file system, since only modified times are stored in V1 +inodes. +.SH OPTIONS +.TP +.B \-a +All entries are listed, even +.B . +and +.B .. +.TP +.B \-c +Use inode changed time for sorting, listing or searching. +.TP +.B \-d +Do not list contents of directories, but list the directory itself. +.TP +.B \-f +Do not sort (should also be: treat a file as a directory, but that +can't be implemented portably). +.TP +.B \-g +Suppress the owner name on a long listing (implies +.BR \-l ). +.TP +.B \-h +Show file sizes in kilo, mega or gigabytes. +.TP +.B \-i +I-node number printed in the first column. +.TP +.B \-l +Long listing: mode, links, owner, group, size and time. +.RB ( "ls \-lC" +uses columns in a wide enough window!) +.TP +.B \-n +Print numerical user and group id's. +.TP +.B \-p +Mark directories with a '\fB/\fP'. +.TP +.B \-q +Print nongraphic characters as '\fB?\fP' (default on terminals). +.TP +.B \-r +Reverse the sort order. +.TP +.B \-s +Give the size in kilobytes in the first +.RB ( \-s ) +or second column +.RB ( \-is ). +.TP +.B \-t +Sort by time (modified time default), latest first. +.TP +.B \-u +Use last accessed time for sorting, listing or searching. +.TP +.B \-1 +Print in one column. +.TP +.B \-A +List all entries, but not +.B . +and +.B .. +(This is the default for privileged users.) +.TP +.B \-C +Print multicolumn (default on terminals). +.TP +.B \-D +Distinguish files by type, i.e. regular files together, directories +together, etc. +.TP +.B \-F +Mark directories with a '\fB/\fP', executables with a '\fB*\fP', \s-2UNIX\s+2 +domain sockets with a '\fB=\fP', named pipes with a '\fB|\fP' and symbolic +links with a '\fB@\fP' behind the name. +.TP +.B \-L +Print the file referenced by a symbolic link instead of the link. +.TP +.B \-M +List mode before name (implies +.BR \-C ). +.TP +.B \-R +List directory trees recursively. +.TP +.B \-T +Print file times in a long format, e.g. "Oct 24 21:37:41 1996". +.TP +.B \-X +Print crunched mode and size before name (implies +.BR \-C ). +Only the rwx permissions that its caller has on the file are shown, but they +are in upper case if the caller owns the file and has given the permission +to the callers group or other users. The size is listed in bytes (<= 5K), +or rounded up kilo, mega or gigabytes. +.SH "SEE ALSO" +.BR du (1), +.BR stat (1), +.BR stat (2). +.SH BUGS +Having to type +.B ls \-C +when viewing files through +.BR more (1). +.PP +Is only portable to systems with the same +.B st_mode +(see +.BR stat (2)). +.PP +The +.B LSOPTS +variable and the +.BR -D , +.B -M +and +.B -X +flags are not found on other +.B ls +implementations. (They have their own nonstandard flags.) +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/mail.1 b/man/man1/mail.1 new file mode 100644 index 000000000..46c580fc1 --- /dev/null +++ b/man/man1/mail.1 @@ -0,0 +1,98 @@ +.TH MAIL 1 +.SH NAME +mail \- send and receive electronic mail +.SH SYNOPSIS +\fBmail\fR [\fB\-epqr\fR] [\fB\-f\fR \fIfile\fR] +.br +\fBmail\fR [\fB\-dtv\fR] [\fB\-s\fR \fIsubject\fR] \fIuser\fR [...] +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-e" "Exit with status TRUE or FALSE to indicate if there is mail in mailbox" +.FL "\-p" "Print all mail and then exit" +.FL "\-q" "Quit program if SIGINT received" +.FL "\-r" "Reverse print order, i.e., print oldest first" +.FL "\-f" "Use \fIfile\fR instead of \fI/usr/spool/mail/user\fR as mailbox" +.PP +.FL "\-d" "Force use of the shell variable \fIMAILER\fR" +.FL "\-t" "Show distribution list as Dist: header in message" +.FL "\-v" "Verbose mode (passed on to \fIMAILER\fR)" +.FL "\-s" "Use Subject: \fIsubject\fR" +.SH EXAMPLES +.EX "mail ast" "Send a message to \fIast\fR" +.EX "mail" "Read your mail" +.EX "cat mail.cdiff | mail -s ''Here's the diff!'' asw " "Pipe program output to mail with a subject line" +.EX "mail -f /usr/spool/mail/asw" "How root can read asw's mail" +.SH DESCRIPTION +.PP +\fIMail\fR is an extremely simple electronic mail program. It can be used +to send or receive email on a single +\s-2MINIX\s+2 +system, in which case it functions +as user agent and local delivery agent. +If the flag \fIMAILER\fR is defined in \fImail.c\fR, +it can also call a trans\%port agent to handle remote mail as well. +No such agent is supplied with +\s-2MINIX\s+2. +.PP +When called by \fIuser\fR with no arguments, it examines the mailbox +\fI/usr/spool/mail/user\fR, prints one message (depending on the \fB\-r\fR +flag), and waits for one of the following commands: +.PP +.nf +.ta 0.25i 1.25i + Go to the next message + \- Print the previous message + !command Fork off a shell and execute \fIcommand\fR + CTRL-D Update the mailbox and quit (same as q) + d Delete the current message and go to the next one + q Update the mailbox and quit (same as CTRL-D) + p Print the current message again + s [\fIfile\fR] Save message in the named file + x Exit without updating the mailbox +.PP +.PP +To send mail, the program is called with the name of one or more recipients as +arguments. The mail is sent, along with a postmark line containing the date. +For local delivery, a file named after each recipient in the directory +\fI/usr/spool/mail\fR must be writable. If a spool file does not exist for +a recipient it will be created. +.PP +If the directory \fI/usr/spool/mail\fR does not exist then the mail is +dumped on the console, so that system programs have a way to notify +a user on a system that does not have a mail spool. +.PP +The received mail contains a To: header showing the recipient. If there +are multiple recipients and the \fB\-t\fR option is specified each recipient +will also see a Dist: header line showing the other recipients. +.PP +The \fB\-s\fR option allows a subject to be specified. The subject must be +quoted if it contains spaces. If no subject is specified the mail +will be delivered with Subject: No subject. +.SH NOTES +The \fB\-s\fR option was added to make this simple mail program +consistent with mail programs found in other *nix variants. Many +programs, including the version of cron distributed with Minix releases +2.0.3 and later, report their outcome by piping output to the mail +program in order to send a mail message to root in lieu of writing a +log file. Such programs often expect the mail program to accept a +subject line using this option. +.SH BUGS +If an external \fIMAILER\fR is used it is likely the conditional code +supporting this will need some editing to be made to work correctly. +.SH AUTHOR +The original mail program for Minix was written by Peter B. Housel. +The -e and -t options were added by C. W. Rose. The -s option was added +by A. S. Woodhull. This man page revised by ASW 2003-07-18. + + + diff --git a/man/man1/make.1 b/man/man1/make.1 new file mode 100644 index 000000000..a29c5cc98 --- /dev/null +++ b/man/man1/make.1 @@ -0,0 +1,76 @@ +.TH MAKE 1 +.SH NAME +make \- a program for maintaining large programs +.SH SYNOPSIS +\fBmake\fR [\fB\-f \fIfile\fR]\fR [\fB\-adeiknpqrst\fR] [\fIoption\fR] ... [\fItarget\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-f" "Use \fIfile\fP as the makefile" +.FL "\-d" "Print debugging information" +.FL "\-e" "Environment overrides makefile macros" +.FL "\-i" "Ignore status returned by commands" +.FL "\-k" "On error, skip to next command" +.FL "\-n" "Report, but do not execute" +.FL "\-p" "Print macros and targets" +.FL "\-q" "Question up-to-dateness of target" +.FL "\-r" "Rule inhibit; do not use default rules" +.FL "\-s" "Silent mode" +.FL "\-t" "Touch files instead of making them" +.SH EXAMPLES +.EX "make kernel" "Make \fIkernel\fP up to date" +.EX "make \-n \-f mfile" "Tell what needs to be done" +.SH DESCRIPTION +.PP +.I Make +is a program that is normally used for developing large programs consisting of +multiple files. +It keeps track of which object files depend on which source and header files. +When called, it does the minimum amount of recompilation to bring the target +file up to date. +.PP +The file dependencies are expected in +.I makefile +or +.I Makefile , +unless another file is specified with \fB\-f\fR. +.I Make +has some default rules built in, for example, it knows how to make +.I .o +files +from +.I .c +files. +Here is a sample +.I makefile . +.PP +.nf +.ta +0.2i +\w'program:'u+1m +\w'cc \-o program head.o tail.o'u+2m + d=/user/ast # \fId\fP is a macro + program: head.o tail.o # \fIprogram\fR depends on these + cc \-o program head.o tail.o # tells how to make \fIprogram\fP + echo Program done. # announce completion + head.o: $d/def.h head.c # \fIhead.o\fP depends on these +.br + tail.o: $d/var.h tail.c # \fItail.o\fP depends on these +.PP +.fi +A complete description of \fImake\fR would require too much space here. +Many books on +\s-2UNIX\s+2 +discuss +.I make . +Study the numerous \fIMakefiles\fR in the +\s-2MINIX\s+2 +source tree for examples. +.SH "SEE ALSO" +.BR cc (1). diff --git a/man/man1/makewhatis.1 b/man/man1/makewhatis.1 new file mode 100644 index 000000000..dce01769b --- /dev/null +++ b/man/man1/makewhatis.1 @@ -0,0 +1,27 @@ +.TH MAKEWHATIS 1 +.SH NAME +makewhatis \- build the whatis(5) database +.SH SYNOPSIS +.B makewhatis +.I directory +.SH DESCRIPTION +.B Makewhatis +makes the +.BR whatis (5) +database in the given manual page directory. This database is used by +.BR man (1) +to map titles to manual page names and by +.BR whatis (1) +to give one line descriptions. See +.BR whatis (5) +for a desciption of what a whatis database should look like and the +restrictions that are placed on the NAME sections so that +.B makewhatis +can make whatis lines out of the manual pages. +.SH "SEE ALSO" +.BR whatis (5). +.SH BUGS +Removing only font and size changes from the NAME section is often not +enough. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/man.1 b/man/man1/man.1 new file mode 100644 index 000000000..ac353a931 --- /dev/null +++ b/man/man1/man.1 @@ -0,0 +1,201 @@ +.TH MAN 1 +.SH NAME +man \- display online manual pages +.SH SYNOPSIS +.B man +.RB [ \-antkfq ] +.RB [ \-M +.IR path ] +.RB [ \-s +.IR section ] +.IR title " ..." +.SH DESCRIPTION +.B Man +displays the online manual pages for the specified titles in the specified +sections. The sections are as follows: +.PP +.TP +.B 1 +User Commands +.br +Generic commands such as +.BR ls , +.BR cp , +.BR grep . +.TP +.B 2 +System Calls +.br +Low level routines that directly interface with the kernel. +.TP +.B 3 +Library Routines +.br +Higher level C language subroutines. +.TP +.B 4 +Device Files +.br +Describes devices in +.BR /dev . +.TP +.B 5 +File Formats +.br +Formats of files handled by various utilities and subroutines. +.TP +.B 6 +Games +.br +It's not \s-2UNIX\s+2 without an adventure game. +.TP +.B 7 +Miscellaneous +.br +Macro packages, miscellaneous tidbits. +.TP +.B 8 +System Utilities +.br +Commands for the System Administrator. +.TP +.B 9 +Documents +.br +Larger manuals explaining some commands in more detail. +.PP +(If you are new to Minix then try +.BR "man hier" , +it will show you around the file system and give you many pointers to other +manual pages.) +.PP +By default, +.B man +will try the following files in a manual page directory for the command +.BR "man \-s 1 ls" : +.PP +.RS +.ft B +.nf +cat1/ls.1 +cat1/ls.1.Z +man1/ls.1 +man1/ls.1.Z +.fi +.ft P +.RE +.PP +Files in the man[1\-8] directories are formatted with +.BR "nroff \-man" . +Those in man9 are formatted with +.BR "nroff \-mnx" . +Files in the cat? directories are preformatted. Files with names ending in +.B .Z +are decompressed first with +.B zcat +(see +.BR compress (1)). +The end result is presented to the user using a pager if displaying on +the screen. +.PP +For each manual page directory in its search path, +.B man +will first try all the subdirectories of the manual page directory for +the files above, and then the directory itself. The directory +.B /usr/man +contains the standard manual pages, with manual pages for optional +packages installed in a subdirectory of /usr/man, with the same +structure as /usr/man. The directory +.B /usr/local/man +contains manual pages for locally added software. By default +/usr/local/man is searched first, then /usr/man. +.PP +A title is not simply used as a filename, because several titles may +refer to the same manual page. Each manual page directory contains a +database of titles in the +.BR whatis (5) +file that is created by +.BR makewhatis (1) +from the NAME sections of all the manual pages. A title is searched in +this database and the first title on a whatis line is used as a filename. +.SH OPTIONS +The options may be interspersed with the titles to search, and take effect +for the titles after them. +.TP +.B \-a +Show all the manual pages or one line descriptions with the given title in +all the specified sections in all the manual directories in the search path. +Normally only the first page found is shown. +.TP +.B \-n +Use +.B nroff \-man +to format manual pages (default). +.TP +.B \-t +Use +.B troff \-man +to format manual pages. +.TP +.B \-f +Use +.BR whatis (1) +to show a one line description of the title from the +.BR whatis (5) +file. +.TP +.B \-k +Use +.BR apropos (1) +to show all the one line descriptions of the title anywhere in the +.BR whatis (5) +files (implies +.BR \-a ). +.TP +.B \-q +Quietly check if all requested manual pages exist. No output, no errors, +just an exit code. +.TP +.BI \-M " path" +Use +.I path +as the search path for manual directories. +.TP +.BI \-s " section" +.I Section +is the section number the page is to be found in, or a comma separated +list of sections to use. Normally all sections are searched. The +search is always in numerical order no matter what your section list looks +like. A single digit is treated as a section number without the +.B \-s +for compatibility with BSD-style +.B man +commands. +.SH ENVIRONMENT +.TP 15n +.B MANPATH +This is a colon separated list of directories to search for manual +pages, by default +.BR /usr/local/man:/usr/man . +.TP +.B PAGER +The program to use to display the manual page or one line descriptions on +the screen page by page. By default +.BR more . +.SH FILES +.TP 25n +/usr/man/whatis +One of the +.BR whatis (5) +databases. +.SH "SEE ALSO" +.BR nroff (1), +.BR troff (1), +.BR more (1), +.BR whatis (1), +.BR makewhatis (1), +.BR catman (1), +.BR whatis (5), +.BR man (7). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/mesg.1 b/man/man1/mesg.1 new file mode 100644 index 000000000..7eb7a9dd2 --- /dev/null +++ b/man/man1/mesg.1 @@ -0,0 +1,38 @@ +.\" @(#)mesg.1 6.1 (Berkeley) 4/29/85 +.\" +.TH MESG 1 "April 29, 1985" +.AT 3 +.SH NAME +mesg \- permit or deny messages +.SH SYNOPSIS +.B mesg +[ +.B n +] [ +.B y +] +.SH DESCRIPTION +.B Mesg +with argument +.B n +forbids messages via +.B write +and +.BR talk (1) +by revoking non-user +write permission on the user's terminal. +.B Mesg +with argument +.B y +reinstates permission. +All by itself, +.B mesg +reports the current state without changing it. +.SH FILES +/dev/tty* +.SH "SEE ALSO" +.BR write (1), +.BR talk (1). +.SH DIAGNOSTICS +Exit status is 0 if messages are receivable, +1 if not, 2 on error. diff --git a/man/man1/mixer.1 b/man/man1/mixer.1 new file mode 100644 index 000000000..e3c2297f9 --- /dev/null +++ b/man/man1/mixer.1 @@ -0,0 +1,24 @@ +.TH MIXER 1 +.SH NAME +mixer \- manipulate mixer settings on a sound card +.SH SYNOPSIS +\fBmixer\fP [\-\fBr\fP] +.SH DESCRIPTION +\fBMixer\fP, invoked without arguments, turns the screen into a sound mixer. +Levels can be changed with the cursor-left and cursor-right keys. Input and +output settings can be toggled with the space bar. For every sound source +there are two, or one when mono, sliders. +The input controls have only effect when recording with the Dac. These +settings can also be used to switch the left and right channels or, when +both channels are enabled on both Dac channels, record in mono. +To exit the mixer use the 'e' key. + +Mixer settings can be stored and restored with the 's' (store) and 'r' keys. +When the store function is used \fBMixer\fP will write the settings to a file +in the user's home directory called \fI\.mixer\fP. The restore function reads +this file to restore saved settings. +.SH OPTIONS +.IP \-r +restore settings saved in \fI\.mixer\fP and exit immediately +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/mkdir.1 b/man/man1/mkdir.1 new file mode 100644 index 000000000..8e7e21b8a --- /dev/null +++ b/man/man1/mkdir.1 @@ -0,0 +1,33 @@ +.TH MKDIR 1 +.SH NAME +mkdir \- make a directory +.SH SYNOPSIS +\fBmkdir [\fB\-p\fR] [\fB\-m \fImode\fR] \fIdirectory ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-m" "Create directory with mode" +.FL "\-p" "Create missing intermediate directories" +.SH EXAMPLES +.EX "mkdir dir" "Create \fIdir\fP in the current directory" +.EX "mkdir \-p /user/ast/dir" "Create the \fI/user/ast\fP and \fI/user/ast/dir\fP" +.SH DESCRIPTION +.PP +The specified directory or directories are created and initialized. If any +intermediate directory is missing and \fB\-p\fR is specified, the missing +component will be created and no error displayed if directory already +exists. If the \fB\-m\fR flag is used, this will be equivalent to a chmod +on the directory after its creation. +.SH "SEE ALSO" +.BR chmod (1), +.BR rmdir (1), +.BR mkdir (2). diff --git a/man/man1/mkfifo.1 b/man/man1/mkfifo.1 new file mode 100644 index 000000000..d0d4380ca --- /dev/null +++ b/man/man1/mkfifo.1 @@ -0,0 +1,30 @@ +.TH MKFIFO 1 +.SH NAME +mkfifo \- make a named pipe +.SH SYNOPSIS +\fBmkfifo [\fB\-m \fImode\fR] \fIfifo ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-m" "Create fifo with specified mode" +.SH EXAMPLES +.EX "mkfifo pipe" "Create \fIpipe\fP in the current directory" +.EX "mkfifo -m a+w systatus" "Create the \fIsystatus\fP writable by all" +.SH DESCRIPTION +.PP +The specified fifo special files are created. +If the \fB\-m\fR flag is used, this will be equivalent to a chmod +on the fifo special file after its creation. +.SH "SEE ALSO" +.BR chmod (1), +.BR mknod (2), +.BR mknod (8). diff --git a/man/man1/mkfs.1 b/man/man1/mkfs.1 new file mode 100644 index 000000000..82765d045 --- /dev/null +++ b/man/man1/mkfs.1 @@ -0,0 +1,88 @@ +.TH MKFS 1 +.SH NAME +mkfs \- make a file system +.SH SYNOPSIS +\fBmkfs \fR[\fB\-Ldot\fR] [\fB\-B \fIblocksize\fR] [\fB\-i \fIinodes\fR] [\fB\-b \fIblocks\fR] \fIspecial \fIprototype\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-L" "Make a listing on standard output" +.FL "\-d" "Use mod time of \fImkfs\fR binary for all files" +.FL "\-o" "Use a drive other than 0 or 1 (safety precaution)" +.FL "\-t" "Do not test if file system fits on the medium" +.FL "\-1" "Make a version 1 file system (for backward compatibility)" +.FL "\-i" "Number of i-nodes (files)" +.FL "\-B" "Filesystem block size (in bytes)" +.FL "\-b" "Filesystem size (in blocks)" +.SH EXAMPLES +.EX "mkfs /dev/fd1 proto" "Make a file system on \fI/dev/fd1\fR" +.EX "mkfs -b 360 /dev/fd1" "Make empty 360 block file system" +.EX "mkfs /dev/fd1 360" "Alternate way to specify the size" +.SH DESCRIPTION +.PP +.I Mkfs +builds a file system and copies specified files to it. +The prototype file tells which directories and files to copy to it. +If the prototype file cannot be opened, and its name is just a string of +digits, an empty file system will be made with the specified number of +blocks. +A sample prototype file follows. +The text following the \fI#\fR sign in the example below is comment. +In real prototype files, comments are not allowed. +.PP +.nf +.ta 0.20i 0.70i 1.10i 3i 3.5i 4i + boot # boot block file (ignored) + 360 63 # blocks and i-nodes + d--755 1 1 # root directory + bin d--755 \|2 1 # bin dir: mode (755), uid (2), gid (1) + sh \|---755 2 1 /user/bin/shell # shell has mode \fIrwxr-xr-x\fP + mv -u-755 2 1 /user/bin/mv # u = SETUID bit + login -ug755 2 1 /user/bin/login # SETUID and SETGID + $ # end of \fI/bin\fP + dev d--755 2 1 # special files: tty (char), fd0 (block) + tty c--777 2 1 4 0 # uid=2, gid=1, major=4, minor=0 + fd0 b--644 2 1 2 0 360 # uid, gid, major, minor, blocks + $ # end of \fI/dev\fP + user d--755 12 1 # user dir: mode (755), uid (12), gid (1) + ast d--755 12 1 # \fI/user/ast\fP + $ # \fI/user/ast\fP is empty + $ # end of \fI/user\fP + $ # end of root directory +.PP +.fi +The first entry on each line (except the first 3 and the $ lines, which +terminate directories) is the name the file or directory will get on the +new file system. +Next comes its mode, with the first character being +\fB\-dbc\fR for regular files, directories, block special files and character +special files, respectively. +The next two characters are used to specify the SETUID and SETGID bits, as +shown above. +The last three characters of the mode are the +.I rwx +protection bits. +.PP +Following the mode are the uid and gid. +For special files, the major and minor devices are needed. +.PP +The maximum size of a file system is 1 Gb for a version 2 file system, +and 64 Mb for a version 1 file system. Alas the 8086 +.I fsck +runs out of memory on a V2 file system larger than 128 Mb, so for the 8086 +version of +\s-2MINIX\s+2 +you have to limit yourself to file systems of that size. +.SH "SEE ALSO" +.BR mkproto (1), +.BR fsck (1), +.BR mount (1). diff --git a/man/man1/mkproto.1 b/man/man1/mkproto.1 new file mode 100644 index 000000000..f53389dec --- /dev/null +++ b/man/man1/mkproto.1 @@ -0,0 +1,36 @@ +.TH MKPROTO 1 +.SH NAME +mkproto \- create a MINIX prototype file +.SH SYNOPSIS +\fBmkproto \fR[\fB\-b \fIn\fR] [\fB\-d \fIstr\fR] [\fB\-g \fIn\fR] [\fB\-i \fIn\fR] [\fB\-p \fInnn\fR] [\fB\-s\fR] [\fB\-t \fIroot\fR] [\fB\-u \fIn\fR] \fIsource_directory\fR [\fIprototype_file\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-b" "Number of blocks in the prototype is \fIn\fR" +.FL "\-d" "Indent the prototype file using \fIstr\fR instead of tab" +.FL "\-g" "Use \fIn\fR as the gid for all files and directories" +.FL "\-i" "Number of i-nodes in the prototype is \fIn\fR" +.FL "\-p" "Use \fInnn\fR (3 octal digits) as the protection mode" +.FL "\-s" "Use the same uid, gid and mode as the source files have" +.FL "\-t" "Use the string \fIroot\fR as the path prefix for every file" +.FL "\-u" "Use \fIn\fR as the uid for all files and directories" +.SH EXAMPLES +.EX "mkproto \-b360" "Make a 360K prototype of this directory" +.EX "mkproto \-u2 \-g1 \-p644" "Give all files uid 2, gid 1 and mode 644" +.SH DESCRIPTION +.PP +\fIMkproto\fR creates an \fImkfs\fR prototype file for the specified +source-directory. +The prototype file is either written to \fIstdout\fR or, if specified, +the proto-file. +.SH "SEE ALSO" +.BR mkfs (1). diff --git a/man/man1/modem.1 b/man/man1/modem.1 new file mode 100644 index 000000000..5593b9720 --- /dev/null +++ b/man/man1/modem.1 @@ -0,0 +1,39 @@ +.TH MODEM 1 +.SH NAME +modem \- switch the modem and getty state +.SH SYNOPSIS +\fBmodem \fR[\fB\-o\fR] [\fB\-i \fInum\fR] \fBtty\fIn\fR\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-o" "Turn getty off and set modem to dialout" +.FL "\-i" "Set line to dialin" +.SH EXAMPLES +.EX "modem \-o tty00" "Set tty00 to dialout" +.EX "modem \-i2 tty00" "Set tty00 to dialin (2 rings)" +.SH DESCRIPTION +.PP +The \fIgetty\fR program allows a terminal port to be used for both dialin and +dialout. +This little program switches the getty state, and also sends +some commands to the modem attached to the specified line. +If the \fB\-o\fR flag is presnt, \fImodem\fR will put the +getty process (if any) connected to the specified line into +SUSPEND state, which means that it +will not pay attention to that line until it is reset to RESTART state. +Also, \fImodem\fR will send some (Hayes) +commands to the attached modem to disable the auto-nanswer mode. +The \fB\-i\fR flag specifies the number of times the telephone has to +ring before the modem may answer the call (to give the operator a chance). +.SH "SEE ALSO" +.BR term (1), +.BR getty (8). diff --git a/man/man1/mount.1 b/man/man1/mount.1 new file mode 100644 index 000000000..7ef18fd15 --- /dev/null +++ b/man/man1/mount.1 @@ -0,0 +1,44 @@ +.TH MOUNT 1 +.SH NAME +mount \- mount a file system +.SH SYNOPSIS +\fBmount [\fB\-r\fR] \fIspecial \fIfile\fR +.br +\fBmount [\fB\-s\fR] \fIswapfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-r" "File system is mounted read-only" +.FL "\-s" "Mount swap space" +.SH EXAMPLES +.EX "mount /dev/fd1 /user" "Mount diskette 1 on \fI/user\fP" +.SH DESCRIPTION +.PP +The file system contained on the special file is mounted on \fIfile\fP. +In the example above, the root directory of the file system in drive 1 +can be accessed as +.B /user +after the mount. +When the file system is no longer needed, it must be unmounted before being +removed from the drive. +.PP +With the +.B \-s +flag a device or file is mounted as swap space. +.SH "SEE ALSO" +.BR df (1), +.BR mkfs (1), +.BR fsck (1), +.BR mkswap (8), +.BR umount (1), +.BR mount (2), +.BR fstab (5). diff --git a/man/man1/mt.1 b/man/man1/mt.1 new file mode 100644 index 000000000..5e1c13332 --- /dev/null +++ b/man/man1/mt.1 @@ -0,0 +1,109 @@ +.TH MT 1 +.SH NAME +mt \- magnetic tape control +.SH SYNOPSIS +.B mt +.RB [ \-f +.IR device ] +.RI [ count ] +.SH DESCRIPTION +.B Mt +is a user interface to the magnetic tape commands described in +.BR mtio (4). +It allows one to space a tape forwards or backwards, write end of file +markers, etc. +.PP +With the +.B \-f +option a tape device can be named, otherwise the environment variable +.B TAPE +is used if set. Standard input is used if the tape name is a dash (\-). The +.I count +argument is used to tell how many blocks or files to space or how many file +markers to write. It may be a C-style decimal, octal or hexadecimal constant, +by default "1". +.PP +.I Command +is the action to perform, it may be one of the following, or any +unambiguous prefix (like +.B st +for +.BR status ): +.TP 15 +.B eof, weof +Write +.I count +end-of-file markers. +.TP +.B fsf +Forward space +.I count +file markers. +.TP +.B fsr +Forward space +.I count +records. (The size of a record depends on the tape, and may even be +variable, depending on the size of the writes.) +.TP +.B bsf +Backwards space +.I count +files. The count may be zero to backspace to the start of the current file. +(A tape device need not support backwards movement, or may be very slow +doing it. Rewinding and forward spacing may be better.) +.TP +.B bsr +Backwards space +.I count +records. The tape is positioned after the last block of the previous file +if you hit a filemark when spacing backwards. The block count is set to -1 +to indicate that the driver has no idea where it is on the previous file. +.TP +.B eom +Forward space to the end of media. +.TP +.B rewind +Rewind the tape. +.TP +.B offline, rewoffl +Rewind and take offline. This may cause some drives to eject the tape. +.TP +.B status +Shows the status of the drive, the sense key of the last SCSI error, +current file number, current record number, residual count if the last +command that encountered end-of-file, and the current block size. +.TP +.B retension +Removes tape tension by winding and rewinding the tape completely. +.TP +.B erase +Erases the tape completely and rewinds it. +.TP +.B density +Sets the density code to read or write the tape to +.IR count . +Density codes supported depend on the drive. This command need not be +used if the drive senses the proper density on read and can only write +one density. +.TP +.B blksize, blocksize +Sets the block size used to read or write the tape to +.IR count . +This command may be used to select a fixed block size for a variable block +size tape. This will speed up I/O for small block sizes. Use a zero +.I count +to use variable sized blocks again. +.SH ENVIRONMENT +.TP 15n +.B TAPE +Tape drive to use if set. +.SH FILES +.TP 15n +.B /dev/nrst4 +Default tape device. +.SH "SEE ALSO" +.BR mtio (4), +.BR st (4). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/nm.1 b/man/man1/nm.1 new file mode 100644 index 000000000..a615c03c2 --- /dev/null +++ b/man/man1/nm.1 @@ -0,0 +1,40 @@ +.TH NM 1 +.SH NAME +nm \- print name list +.SH SYNOPSIS +\fBnm\fR [\fB\-dgnopru\fR]\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-d" "Print the offsets in decimal instead of in hex" +.FL "\-g" "Print only external symbols" +.FL "\-n" "Sort numerically rather than alphabetically" +.FL "\-o" "Prepend file name to each line rather than only once" +.FL "\-p" "Do not sort, print in symbol-table order" +.FL "\-r" "Sort in reverse order" +.FL "\-u" "Print only undefined symbols" +.SH EXAMPLES +.EX "nm \-n a.out" "Print all symbols in numerical order" +.EX "nm \-dg a.out" "Print globals alphabetically in decimal" +.SH DESCRIPTION +.PP +\fINm\fR prints the symbol table of executable files when it is available. +If no file is given, the symbols in \fIa.out\fR are used. +The format of the table +is somewhat compatible with the one produced by \fIasld\fR when used with +the \fB\-s\fR option. The symbol table can be added with \fIast\fR. +Assembly language files do not have symbol tables. +.SH "SEE ALSO" +.BR anm (1), +.BR asize (1), +.BR ar (1), +.BR size (1). diff --git a/man/man1/od.1 b/man/man1/od.1 new file mode 100644 index 000000000..12107beae --- /dev/null +++ b/man/man1/od.1 @@ -0,0 +1,38 @@ +.TH OD 1 +.SH NAME +od \- octal dump +.SH SYNOPSIS +\fBod\fR [\fB\-bcdhox\fR]\fR [\fIfile\fR] [ [\fB+\fR] \fIoffset\fR [\fB.\fR][\fBb\fR]\fR ]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-b" "Dump bytes in octal" +.FL "\-c" "Dump bytes as ASCII characters" +.FL "\-d" "Dump words in decimal" +.FL "\-h" "Print addresses in hex (default is octal)" +.FL "\-o" "Dump words in octal (default)" +.FL "\-v" "Verbose (list duplicate lines)" +.FL "\-x" "Dump words in hex" +.SH EXAMPLES +.EX "od \-ox file" "Dump \fIfile\fP in octal and hex" +.EX "od \-d file +1000" "Dump \fIfile\fP starting at byte 01000" +.EX "od \-c file +10.b" "Dump \fIfile\fP starting at block 10" +.SH DESCRIPTION +.PP +.I Od +dumps a file in one or more formats. +If \fIfile\fP is missing, \fIstdin\fR is dumped. +The \fIoffset\fP argument tells +.I od +to skip a certain number of bytes or blocks before starting. +The offset is in octal bytes, unless it is followed by a +\&'.\&' for decimal or \fBb\fP for blocks or both. diff --git a/man/man1/passwd.1 b/man/man1/passwd.1 new file mode 100644 index 000000000..17fb8ce67 --- /dev/null +++ b/man/man1/passwd.1 @@ -0,0 +1,44 @@ +.TH PASSWD 1 +.SH NAME +passwd, chfn, chsh \- change a login password, full name or shell +.SH SYNOPSIS +\fBpasswd\fR [\fIuser\fR]\fR +.br +\fBchfn\fR [\fIuser\fR] \fIfullname\fR\fR +.br +\fBchsh\fR [\fIuser\fR] \fIshell\fR\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "passwd" "Change current user's password" +.EX "passwd ast" "Change ast's password (super\-user only)" +.EX "chsh /usr/bin/mail" "For those who only read mail" +.EX "chfn 'Jane Doe'" "Current user is Jane Doe" +.SH DESCRIPTION +.PP +.I Passwd +is used to change your password. +It prompts for the old and new passwords. +It asks for the new password twice, to reduce the effect of a typing error. +.I Chfn +changes the full name (GECOS field) in the password file. +.I Chsh +changes your login shell. +Do not forget to copy the modified password file back to the root file system, +or the changes will be lost when the system is rebooted. +.SH "SEE ALSO" +.BR login (1), +.BR su (1), +.BR crypt (3), +.BR getpwent (3), +.BR passwd (5), +.BR adduser (8). diff --git a/man/man1/paste.1 b/man/man1/paste.1 new file mode 100644 index 000000000..31db29a43 --- /dev/null +++ b/man/man1/paste.1 @@ -0,0 +1,40 @@ +.TH PASTE 1 +.SH NAME +paste \- paste multiple files together +.SH SYNOPSIS +\fBpaste\fR [\fB\-s\fR]\fR [\fB\-d\fI list\fR] \fIfile...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-d" "Set delimiter used to separate columns to \fIlist\fR. +.FL "\-s" "Print files sequentially, file \fIk\fR on line \fIk\fR. +.SH EXAMPLES +.EX "paste file1 file2" "Print \fIfile1\fR in col 1, \fIfile2\fR in col 2" +.EX "paste \-s f1 f2" "Print \fIf1\fR on line 1 and \fIf2\fR on line 2" +.EX "paste -d : file1 file2" "Print the lines separated by a colon" +.SH DESCRIPTION +.PP +\fIPaste\fR concatenates corresponding lines of the given input files +and writes them to standard output. The lines of the different files +are separated by the delimiters given with the option \-s\fR. If +no list is given, a tab is substituted for every linefeed, except the last one. +If end-of-file is hit on an input file, subsequent lines are empty. +Suppose a set of \fIk\fR files each has one word per line. +Then the \fIpaste\fR output will have \fIk\fR columns, +with the contents of file \fIj\fR in column \fIj\fR. +If the \fB\-s\fR flag is given, then the first +file is on line 1, the second file on line 2, etc. +In effect, \fB\-s\fR turns the output sideways. +.PP +If a list of delimiters is given, they are used in turn. The C escape +sequences \\n, \\t, \\\\, and \\0 are used for linefeed, tab, backslash, and +the null string, respectively. diff --git a/man/man1/patch.1 b/man/man1/patch.1 new file mode 100644 index 000000000..25cd85d07 --- /dev/null +++ b/man/man1/patch.1 @@ -0,0 +1,555 @@ +.\" -*- nroff -*- +.rn '' }` +'\" $Header$ +'\" +'\" $Log$ +'\" Revision 1.1 2005/05/02 13:01:39 beng +'\" Added man pages. +'\" +'\" Revision 2.0.1.2 88/06/22 20:47:18 lwall +'\" patch12: now avoids Bell System Logo +'\" +'\" Revision 2.0.1.1 88/06/03 15:12:51 lwall +'\" patch10: -B switch was contributed. +'\" +'\" Revision 2.0 86/09/17 15:39:09 lwall +'\" Baseline for netwide release. +'\" +'\" Revision 1.4 86/08/01 19:23:22 lwall +'\" Documented -v, -p, -F. +'\" Added notes to patch senders. +'\" +'\" Revision 1.3 85/03/26 15:11:06 lwall +'\" Frozen. +'\" +'\" Revision 1.2.1.4 85/03/12 16:14:27 lwall +'\" Documented -p. +'\" +'\" Revision 1.2.1.3 85/03/12 16:09:41 lwall +'\" Documented -D. +'\" +'\" Revision 1.2.1.2 84/12/05 11:06:55 lwall +'\" Added -l switch, and noted bistability bug. +'\" +'\" Revision 1.2.1.1 84/12/04 17:23:39 lwall +'\" Branch for sdcrdcf changes. +'\" +'\" Revision 1.2 84/12/04 17:22:02 lwall +'\" Baseline version. +'\" +.de Sh +.br +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +'\" +'\" Set up \*(-- to give an unbreakable dash; +'\" string Tr holds user defined translation string. +'\" Bell System Logo is used as a dummy character. +'\" +'\" Shut up a groff -ww warning. +'\".if \n(.g .if !dTr .ds Tr +'\".ie n \{\ +.tr \(*W-\*(Tr +'\".ds -- \(*W- +'\".if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +'\".if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +.ds L' ' +.ds R' ' +'\"'br \} +'\".el \{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds L' ` +.ds R' ' +'\"'br\} +.TH PATCH 1 LOCAL +.SH NAME +patch - apply a diff file to an original +.SH SYNOPSIS +.B patch +[options] [origfile [patchfile]] [+ [options] [origfile]]... +.sp +but usually just +.sp +.B patch + +sets the maximum fuzz factor. +This switch only applies to context diffs, and causes +.I patch +to ignore up to that many lines in looking for places to install a hunk. +Note that a larger fuzz factor increases the odds of a faulty patch. +The default fuzz factor is 2, and it may not be set to more than +the number of lines of context in the context diff, ordinarily 3. +.TP 5 +.B \-l +causes the pattern matching to be done loosely, in case the tabs and +spaces have been munged in your input file. +Any sequence of whitespace in the pattern line will match any sequence +in the input file. +Normal characters must still match exactly. +Each line of the context must still match a line in the input file. +.TP 5 +.B \-n +forces +.I patch +to interpret the patch file as a normal diff. +.TP 5 +.B \-N +causes +.I patch +to ignore patches that it thinks are reversed or already applied. +See also +.B \-R . +.TP 5 +.B \-o +causes the next argument to be interpreted as the output file name. +.TP 5 +.B \-p +sets the pathname strip count, +which controls how pathnames found in the patch file are treated, in case +the you keep your files in a different directory than the person who sent +out the patch. +The strip count specifies how many slashes are to be stripped from +the front of the pathname. +(Any intervening directory names also go away.) +For example, supposing the filename in the patch file was +.sp + /u/howard/src/blurfl/blurfl.c +.sp +setting +.B \-p +or +.B \-p0 +gives the entire pathname unmodified, +.B \-p1 +gives +.sp + u/howard/src/blurfl/blurfl.c +.sp +without the leading slash, +.B \-p4 +gives +.sp + blurfl/blurfl.c +.sp +and not specifying +.B \-p +at all just gives you "blurfl.c", unless all of the directories in the +leading path (u/howard/src/blurfl) exist and that path is relative, +in which case you get the entire pathname unmodified. +Whatever you end up with is looked for either in the current directory, +or the directory specified by the +.B \-d +switch. +.TP 5 +.B \-r +causes the next argument to be interpreted as the reject file name. +.TP 5 +.B \-R +tells +.I patch +that this patch was created with the old and new files swapped. +(Yes, I'm afraid that does happen occasionally, human nature being what it +is.) +.I Patch +will attempt to swap each hunk around before applying it. +Rejects will come out in the swapped format. +The +.B \-R +switch will not work with ed diff scripts because there is too little +information to reconstruct the reverse operation. +.Sp +If the first hunk of a patch fails, +.I patch +will reverse the hunk to see if it can be applied that way. +If it can, you will be asked if you want to have the +.B \-R +switch set. +If it can't, the patch will continue to be applied normally. +(Note: this method cannot detect a reversed patch if it is a normal diff +and if the first command is an append (i.e. it should have been a delete) +since appends always succeed, due to the fact that a null context will match +anywhere. +Luckily, most patches add or change lines rather than delete them, so most +reversed normal diffs will begin with a delete, which will fail, triggering +the heuristic.) +.TP 5 +.B \-s +makes +.I patch +do its work silently, unless an error occurs. +.TP 5 +.B \-S +causes +.I patch +to ignore this patch from the patch file, but continue on looking +for the next patch in the file. +Thus +.sp + patch -S + -S + +sets internal debugging flags, and is of interest only to +.I patch +patchers. +.SH AUTHOR +Larry Wall +.br +with many other contributors. +.SH ENVIRONMENT +.TP +.B TMPDIR +Directory to put temporary files in; default is /tmp. +.TP +.B SIMPLE_BACKUP_SUFFIX +Extension to use for backup file names instead of \*(L".orig\*(R" or +\*(L"~\*(R". +.TP +.B VERSION_CONTROL +Selects when numbered backup files are made. +.SH FILES +$TMPDIR/patch* +.SH SEE ALSO +diff(1) +.SH NOTES FOR PATCH SENDERS +There are several things you should bear in mind if you are going to +be sending out patches. +First, you can save people a lot of grief by keeping a patchlevel.h file +which is patched to increment the patch level as the first diff in the +patch file you send out. +If you put a Prereq: line in with the patch, it won't let them apply +patches out of order without some warning. +Second, make sure you've specified the filenames right, either in a +context diff header, or with an Index: line. +If you are patching something in a subdirectory, be sure to tell the patch +user to specify a +.B \-p +switch as needed. +Third, you can create a file by sending out a diff that compares a +null file to the file you want to create. +This will only work if the file you want to create doesn't exist already in +the target directory. +Fourth, take care not to send out reversed patches, since it makes people wonder +whether they already applied the patch. +Fifth, while you may be able to get away with putting 582 diff listings into +one file, it is probably wiser to group related patches into separate files in +case something goes haywire. +.SH DIAGNOSTICS +Too many to list here, but generally indicative that +.I patch +couldn't parse your patch file. +.PP +The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in +the patch file and that +.I patch +is attempting to intuit whether there is a patch in that text and, if so, +what kind of patch it is. +.PP +.I Patch +will exit with a non-zero status if any reject files were created. +When applying a set of patches in a loop it behooves you to check this +exit status so you don't apply a later patch to a partially patched file. +.SH CAVEATS +.I Patch +cannot tell if the line numbers are off in an ed script, and can only detect +bad line numbers in a normal diff when it finds a \*(L"change\*(R" or +a \*(L"delete\*(R" command. +A context diff using fuzz factor 3 may have the same problem. +Until a suitable interactive interface is added, you should probably do +a context diff in these cases to see if the changes made sense. +Of course, compiling without errors is a pretty good indication that the patch +worked, but not always. +.PP +.I Patch +usually produces the correct results, even when it has to do a lot of +guessing. +However, the results are guaranteed to be correct only when the patch is +applied to exactly the same version of the file that the patch was +generated from. +.SH BUGS +Could be smarter about partial matches, excessively \&deviant offsets and +swapped code, but that would take an extra pass. +.PP +If code has been duplicated (for instance with #ifdef OLDCODE ... #else ... +#endif), +.I patch +is incapable of patching both versions, and, if it works at all, will likely +patch the wrong one, and tell you that it succeeded to boot. +.PP +If you apply a patch you've already applied, +.I patch +will think it is a reversed patch, and offer to un-apply the patch. +This could be construed as a feature. +.rn }` '' diff --git a/man/man1/playwave.1 b/man/man1/playwave.1 new file mode 100644 index 000000000..e3f5c783e --- /dev/null +++ b/man/man1/playwave.1 @@ -0,0 +1,16 @@ +.TH PLAYWAVE 1 +.SH NAME +playwave \- play an audio file in MicroSoft PCM wave format +.SH SYNOPSIS +\fBplaywave\fP [\-\fBi\fP] file +.SH DESCRIPTION +\fBPlaywave\fP writes the samples in a wave file to \fI/dev/audio\fP. +The wave file must be in Microsoft PCM format. +.SH OPTIONS +.IP \-i +display information about wave file +.SH BUGS +The highest sample rate that can be used depends on the speed of the system +and the size of the DMA buffer used in the driver. (/usr/src/kernel/sb16.h) +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/postmort.1 b/man/man1/postmort.1 new file mode 100644 index 000000000..348c679e8 --- /dev/null +++ b/man/man1/postmort.1 @@ -0,0 +1,37 @@ +.TH POSTMORT 1 +.SH NAME +postmort \- perform post-mortem on PC Minix core files +.SH SYNOPSIS +\fBpostmort\fR [\fB\-dpt\fR] \fB\-c \fIcorefile \fB\-s \fIsymbfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Use the named corefile" +.FL "\-d" "Dump all text symbols and segment data" +.FL "\-p" "Display the kernel process table" +.FL "\-s" "Use the named symbol file" +.FL "\-t" "Display a stack backtrace" +.SH EXAMPLES +.EX "postmort" "display the data from the file 'core'" +.SH DESCRIPTION +.PP +.I Postmort +does a simple static analysis of a PC Minix core file; +By default, it looks for the +file 'core' in the local directory and loads that for analysis; it +also searches for the file 'symbol.out', and if that fails 'a.out', +expecting them to contain symbol information for the core file. +It is not a fatal error if the symbol files don't exist. +.PP +The stack backtrace is slightly tricky, and may go on longer +than is really justified, since there's no easy way for it to +know when to stop. Treat its results with caution. diff --git a/man/man1/pr.1 b/man/man1/pr.1 new file mode 100644 index 000000000..396cf28ea --- /dev/null +++ b/man/man1/pr.1 @@ -0,0 +1,37 @@ +.TH PR 1 +.SH NAME +pr \- print a file +.SH SYNOPSIS +\fBpr\fR [\fB\-Mfnt\fR]\fR [\fB\-h \fIn\fR] [\fB\-l \fIn\fR] [\fB\-w \fIn\fR] [\fB\-\fRcolumns\fR] [\fB+\fIpage\fR] [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-M" "Use MINIX style line number" +.FL "\-f" "Do not fold long lines" +.FL "\-h" "Take next argument as page header" +.FL "\-l" "Sets page length in lines" +.FL "\-n" "Number the output lines" +.FL "\-t" "Do not print page header or trailer" +.FL "\-w" "Sets line length in characters" +.SH EXAMPLES +.EX "pr \-w85 \-l60 file" "Use 85 character line, 60 line page" +.EX "pr \-3 file" "List \fIfile\fP three columns to a page" +.EX "pr +4 file" "Start printing with page 4" +.SH DESCRIPTION +.PP +.I Pr +formats one or more files for printing. +If no files are specified, \fIstdin\fR is printed. +Options are provided for setting the width and height of the page, the +number of columns to use (default 1), and the page to start with, among others. +.SH "SEE ALSO" +.BR lp (1). diff --git a/man/man1/prep.1 b/man/man1/prep.1 new file mode 100644 index 000000000..805dafca4 --- /dev/null +++ b/man/man1/prep.1 @@ -0,0 +1,27 @@ +.TH PREP 1 +.SH NAME +prep \- prepare a text file for statistical analysis +.SH SYNOPSIS +\fBprep\fR [\fIfile\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "prep infile >outfile" "Prepare \fIinfile\fR" +.SH DESCRIPTION +.PP +\fIPrep\fR strips off most of the troff commands from a text file and then +outputs all the words, one word per line, in the order they occur in the file. +This file can then be sorted and compared to a dictionary (as a spelling +checker), or used for statistical analyses. +.SH "SEE ALSO" +.BR nroff (1), +.BR spell (1). diff --git a/man/man1/ps.1 b/man/man1/ps.1 new file mode 100644 index 000000000..7971c4df8 --- /dev/null +++ b/man/man1/ps.1 @@ -0,0 +1,68 @@ +.TH PS 1 +.SH NAME +ps \- process status +.SH SYNOPSIS +\fBps \fR[\fB\-alxU\fR] [\fBkernel mm fs\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "Print all processes with controlling terminals" +.FL "\-l" "Give long listing" +.FL "\-x" "Include processes without a terminal" +.SH EXAMPLES +.EX "ps \-axl" "Print all processes and tasks in long format" +.SH DESCRIPTION +.PP +\fIPs\fR prints the status of active processes. Normally only the caller's own +processes are listed in short format (the PID, TTY, TIME and CMD fields as +explained below). The long listing contains: +.PP +.ta 0.5i 1.0i + F Kernel flags: + 001: free slot + 002: no memory map + 004: sending; + 010: receiving + 020: inform on pending signals + 040: pending signals + 100: being traced. +.PP + S + State: + R: runnable + W: waiting (on a message) + S: sleeping (i.e.,suspended on MM or FS) + Z: zombie + T: stopped +.PP + UID, PID, PPID, PGRP + The user, process, parent process and process group ID's. +.PP + SZ + Size of the process in kilobytes. +.PP + RECV + Process/task on which a receiving process is waiting or sleeping. +.PP + TTY + Controlling tty for the process. +.PP + TIME + Process' cumulative (user + system) execution time. +.PP + CMD Command line arguments of the process. +.PP +.PP +The files \fI/dev/{mem,kmem}\fR are used to read the system tables and command +line arguments from. Terminal names in \fI/dev\fR are used to generate the +mnemonic names in the TTY column, so \fIps\fR is independent of terminal naming +conventions. diff --git a/man/man1/pwd.1 b/man/man1/pwd.1 new file mode 100644 index 000000000..42283bb56 --- /dev/null +++ b/man/man1/pwd.1 @@ -0,0 +1,23 @@ +.TH PWD 1 +.SH NAME +pwd \- print working directory +.SH SYNOPSIS +\fBpwd\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "pwd " "Print the name of the working directory" +.SH DESCRIPTION +.PP +The full path name of the current working directory is printed. +.SH "SEE ALSO" +.BR getcwd (3). diff --git a/man/man1/rcp.1 b/man/man1/rcp.1 new file mode 100644 index 000000000..e7100d8d9 --- /dev/null +++ b/man/man1/rcp.1 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rcp.1c 6.4 (Berkeley) 5/12/86 +.\" +.TH RCP 1 "May 12, 1986" +.UC 5 +.SH NAME +rcp \- remote file copy +.SH SYNOPSIS +.B rcp +.RB [ \-p ] +.I file1 file2 +.br +.B rcp +.RB [ \-pr ] +.I file +\&... +.I directory +.SH DESCRIPTION +.B Rcp +copies files between machines. Each +.I file +or +.I directory +argument is either a remote file name of the +form ``rhost:path'', or a local file name (containing no `:' characters, +or a `/' before any `:'s). +.PP +If the +.B \-r +option +is specified and any of the source files are directories, +.B rcp +copies each subtree rooted at that name; in this case +the destination must be a directory. +.PP +By default, the mode and owner of +.I file2 +are preserved if it already existed; otherwise the mode of the source file +modified by the +.BR umask (2) +on the destination host is used. +The +.B \-p +option causes +.B rcp +to attempt to preserve (duplicate) in its copies the modification +times and modes of the source files, ignoring the +.BR umask . +.PP +If +.I path +is not a full path name, it is interpreted relative to +your login directory on +.IR rhost . +A +.I path +on a remote host may be quoted (using \e, ", or \(aa) +so that the metacharacters are interpreted remotely. +.PP +.B Rcp +does not prompt for passwords; your current local user name +must exist on +.I rhost +and allow remote command execution via +.BR rsh (1). +.PP +.B Rcp +handles third party copies, where neither source nor target files +are on the current machine. +Hostnames may also take the form ``rname@rhost'' to use +.I rname +rather than the current user name on the remote host. +The destination hostname may also take the form ``rhost.rname'' to +support destination machines that are running 4.2BSD +versions of +.BR rcp . +.SH SEE ALSO +.BR cp (1), +.BR ftp (1), +.BR rsh (1), +.BR rlogin (1). +.SH BUGS +Doesn't detect all cases where the target of a copy might +be a file in cases where only a directory should be legal. +.br +Is confused by any output generated by commands in a +\&.profile, or \&.*shrc file on the remote host. diff --git a/man/man1/readall.1 b/man/man1/readall.1 new file mode 100644 index 000000000..285f48e0a --- /dev/null +++ b/man/man1/readall.1 @@ -0,0 +1,36 @@ +.TH READALL 1 +.SH NAME +readall \- read a device quickly to check for bad blocks +.SH SYNOPSIS +\fBreadall\fR [\fB\-bt\fR] \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-b" "Produce shell script on \fIstdout\fR that calls \fIbadblocks\fR" +.FL "\-t" "Just print device size" +.SH EXAMPLES +.EX "readall /dev/hd0" "Read all of \fI/dev/hd0\fR" +.EX "readall -b /dev/hd1 >s" "Generate shell script on \fIs\fR" +.SH DESCRIPTION +.PP +\fIReadall\fR reads all of the named device in large chunks. +It reports about blocks that it cannot read. +Unlike \fIdiskcheck\fR, it does not attempt to write on +the disk, making it safer to use when one is worried about a sick system. +When the \fB\-b\fR flag is given, the output is a shell script that +calls the \fIbadblocks\fR program to marked all the bad blocks. +Whenever installing +\s-2MINIX\s+2, +it is wise to run \fIreadall\fR with the \fB\-b\fR flag first on all +the hard disks. +.SH "SEE ALSO" +.BR badblocks (8). diff --git a/man/man1/readfs.1 b/man/man1/readfs.1 new file mode 100644 index 000000000..f46bdd85c --- /dev/null +++ b/man/man1/readfs.1 @@ -0,0 +1,31 @@ +.TH READFS 1 +.SH NAME +readfs \- read a MINIX file system +.SH SYNOPSIS +\fBreadfs\fR [\fB\-il\fR] \fIblock_special\fR [\fIdir\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-i" "Give information about the file, but do not extract files" +.FL "\-l" "List the files extracted on standard output" +.SH EXAMPLES +.EX "readfs \-l /dev/fd0" "List contents of diskette" +.SH DESCRIPTION +.PP +\fIReadfs\fR reads a diskette containing a +\s-2MINIX\s+2 +file system. It can +extract all the files from it, give a listing of them, or both. The files +extracted can be put in a user-specified directory (default: current +directory). If subdirectories are needed, they will be created automatically. +.SH "SEE ALSO" +.BR mkproto (1). diff --git a/man/man1/recwave.1 b/man/man1/recwave.1 new file mode 100644 index 000000000..b9f4c30b9 --- /dev/null +++ b/man/man1/recwave.1 @@ -0,0 +1,20 @@ +.TH RECWAVE 1 +.SH NAME +recwave \- record an audio file in MicroSoft PCM wave format +.SH SYNOPSIS +\fBrecwave\fP [\-\fBb\fP \-\fBs\fP \-\fBr\fP] file +.SH DESCRIPTION +\fBRecwav\fP takes samples from \fI/dev/audio\fP and writes them to \fIfile\fP +in Microsoft PCM wave format. +.SH OPTIONS +.IP \-b +number of bits to use for one sample. Must be 8 or 16, default is 8 +.IP \-s +enable stereo sampling. 0 = mono (default), 1 = stereo +.IP \-r +sample rate in samples/sec. 4000 - 44100 (default 22050) +.SH BUGS +The highest sample rate that can be used depends on the speed of the system +and the size of the DMA buffer used in the driver. (/usr/src/kernel/sb16.h) +.SH AUTHOR +Michel R. Prevenier (mrpreve@cs.vu.nl) diff --git a/man/man1/ref.1 b/man/man1/ref.1 new file mode 100644 index 000000000..e7d2e178f --- /dev/null +++ b/man/man1/ref.1 @@ -0,0 +1,88 @@ +.TH REF 1 +.SH NAME +ref - Display a C function header +.SH SYNOPSIS +\fBref\fR [-t] [-c \fIclass\fR]... [-f \fIfile\fR]... \fItag\fR +.SH DESCRIPTION +\fIref\fP quickly locates and displays the header of a function. +To do this, \fIref\fR +looks in the "tags" file for the line that describes the function, and then +scans the source file for the function. +When it locates the function, it displays an introductory comment +(if there is one), the function's declaration, and the declarations of all +arguments. +.SH "SEARCH METHOD" +.PP +\fIref\fR uses a fairly sophisticated tag look-up algorithm. +If you supply a filename via \fB-f\fR \fIfile\fR, then elvis first scans +the tags file for a static tag from that file. +This search is limited to the tags file in the current directory. +.PP +If you supply a classname via \fB-c\fR \fIclass\fR, then elvis searches +for a tag from that class. +This search is not limited to the current directory; +You can supply a list of directories in the environment variable \fITAGPATH\fR, +and \fIref\fR will search through the "tags" file in each directory until it finds +a tag in the desired class. +.PP +If that fails, \fIref\fR will then try to look up an ordinary global tag. +This search checks all of the directories listed in \fITAGPATH\fR, too. +.PP +If you've given the \fB-t\fR flag, then \fIref\fR will simply output the tag line that +it found, and then exit. +Without \fB-t\fR, though, \fIref\fR will search for the tag line. +It will try to open the source file, which should be in the same directory +as the tags file where the tag was discovered. +If the source file doesn't exist, or is unreadable, then \fIref\fR will try to open +a file called "\fIrefs\fR" in that directory. +Either way, \fIref\fR will try to locate the tag, and display whatever it finds. +.SH "INTERACTION WITH ELVIS" +.PP +\fIref\fP is used by \fIelvis\fR' shift-K command. +If the cursor is located on a word such as "splat", in the file "foo.c", +then \fIelvis\fR will invoke \fIref\fR with the command "ref -f foo.c splat". +.PP +If \fIelvis\fR has been compiled with the -DEXTERNAL_TAGS flag, then \fIelvis\fR will +use \fIref\fR \fB\fRto scan the tags files. +This is slower than the built-in tag searching, but it allows \fIelvis\fR to access +the more sophisticated tag lookup provided by \fIref\fR. +Other than that, external tags should act exactly like internal tags. +.SH OPTIONS +.IP \fB-t\fR +Output tag info, instead of the function header. +.IP "\fB-f\fR \fIfile\fR" +The tag might be a static function in \fIfile\fR. +You can use several -f flags to have \fIref\fR consider static tags from more than one file. +.IP "\fB-c\fR \fIclass\fR" +The tag might be a member of class \fIclass\fR. +You can use several -c flags to have \fIref\fR consider tags from more than one class. +.SH FILES +.IP \fBtags\fR +List of function names and their locations, generated by \fIctags\fR. +.IP \fBrefs\fR +Function headers extracted from source files (optional). +.SH ENVIRONMENT +.IP \fBTAGPATH\fR +List of directories to be searched. +The elements in the list are separated by either +semicolons (for MS-DOS, Atari TOS, and AmigaDos), or +by colons (every other operating system). +For each operating system, \fIref\fR has a built-in default which is probably +adequate. +.SH NOTES +.PP +You might want to generate a "tags" file the directory that contains the +source code for standard C library on your system. +If licensing restrictions prevent you from making the library source readable +by everybody, then you can have \fIctags\fR generate a "refs" file, +and make "refs" readable by everybody. +.PP +If your system doesn't come with the library source code, then perhaps you +can produce something workable from the \fIlint\fR libraries. +.SH "SEE ALSO" +elvis(1), ctags(1) +.SH AUTHOR +.nf +Steve Kirkendall +kirkenda@cs.pdx.edu +.fi diff --git a/man/man1/remsync.1 b/man/man1/remsync.1 new file mode 100644 index 000000000..de11332df --- /dev/null +++ b/man/man1/remsync.1 @@ -0,0 +1,184 @@ +.TH REMSYNC 1 +.SH NAME +remsync - remotely synchronize file trees +.SH SYNOPSIS +.B remsync +.B \-sxv +.I tree +.RI [ state-file ] +.br +.B remsync +.B \-duxvD +.I tree +.RI [ state-file +.RI [ diff-file ]] +.br +.B remsync +.RB [ \-xv ] +.I tree +.RI [ diff-file ] +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Remsync +synchronizes file trees of distant machines, i.e. machines that do not have +a fast network between them. It accomplishes this in three steps: +.PP +.RS +Create a state file containing a description of the machine to be updated. +.RE +.PP +.RS +Compute a file of differences on the source machine using the state file to +compare the two file trees. +.RE +.PP +.RS +Update the target machine using the data in the differences file. +.RE +.PP +This process requires that you move two files, a state file from the target +machine to the source machine, and a differences file from the source +machine to the target machine. The state file is an ASCII file that may be +edited, usually to make +.B remsync +ignore some files or file trees. +.PP +The argument +.I tree +may be a single file or a directory. A directory is traversed recursively. +The +.I state-file +and +.I diff-file +arguments may be of any file type. The differences file contains an end +marker, so it may be followed by trailing junk. Standard input or +output is used if these arguments are omitted or replaced by a minus +sign. +.SS "State file format" +A state file has a line for each file in a tree. A line looks like this +formally for a simple file: +.PP +.RS +.I "name mode owner group length date" +.RI [ link-number +.RB [ last ]] +.RE +.PP +The best way to show how each type of file is represented is by example: +.PP +.RS +.nf +.ta +10 +8 +4 +4 +6 +12 +4 +/ d755 0 0 +bin d755 2 0 +.in +2 +[ 644 2 0 233 759160857 1 +cat 755 2 0 3772 768742021 +test 755 2 0 233 759160857 1 last +.in -2 +dev d755 0 0 +.in +2 +fd0 b666 0 0 200 +console c600 10 0 400 +sd2 b600 0 0 a02 +fifo p700 2 0 +.in -2 +opt -> usr/opt +usr ignore (Cross-device link) +.fi +.RE +.PP +The root of the tree is always represented by a /, no matter what type of +file it may be. Directory entries of the root follow at the same level. +Files in subdirectories are indented by two spaces. (Eight spaces are +replaced by a TAB.) Normal files have their length and modified time in the +state file, devices have their device number in hex, etc. If files are hard +linked to each other then they all get an extra "link number" to bind them +together. The last link is marked with the word +.BR last . +.PP +One usually only modifies a state file to ignore differences between two +files. One does this by replacing the file attributes with the word +.BR ignore . +.RB ( Remsync +generates this keyword too, with the reason why added in parentheses.) +.SH OPTIONS +.TP +.B \-s +Generate a state file. +.TP +.B \-d +Generate a differences file. (The default is to apply a differences file.) +.TP +.B \-u +Only add new files or update files with newer versions. +.TP +.B \-x +Do not cross device boundaries. This allows one to operate on the root file +system for instance ignoring the +.B /usr +file system. +.TP +.B \-D +Debug differences file generation. With this flag no file contents are +added to the differences file. The result is then human readable. +.TP +.B \-v +Lists the commands added to the differences file, or the actions done +applying a differences file. The output looks like \s-2UNIX\s+2 commands +except for the words "add", "restore" and "update" indicating addition of a +new file, replacing a file with an older version, or replacement by a newer +version. +.SH EXAMPLES +Actions taken by the author to update his notebook "finiah" from his main +machine "darask": +.PP +.RS +.nf +finiah# remsync -s /usr /tmp/finiah.state +.SP +Edit the state file to ignore .Xauthority files and /usr/var. +.SP +finiah# tar cvf /dev/fd0 /tmp/finiah.state +.SP +darask# tar xvf /dev/fd0 +.br +darask# remsync -dv /usr /tmp/finiah.state | vol 1440 /dev/fd0 +.SP +finiah# vol 1440 /dev/fd0 | remsync -v /usr +.fi +.RE +.PP +One could add a file compression/decompression program between +.B remsync +and +.BR vol , +to reduce the number of floppies to move about, but that actually slows +things down! (Note that one only needs to shuffle two floppies about if the +two machines are adjacent. To update a remote machine it does make sense to +use compression to reduce the number of floppies to carry.) +.SH "SEE ALSO" +.BR synctree (1), +.BR vol (1), +.BR tar (1). +.SH NOTES +Nothing stops you from using +.B remsync +over a fast network of course. +.B Synctree +can be a bit tedious if you only want to ignore a few files. Editing a +state file is then easier. +.SH BUGS +Files are overwritten, not removed, when they are updated. This means +that links outside the tree are also updated. The less desirable +alternative to this is to break the link before the update. +.PP +The verbose option may say that a link is to be created when making a +differences file. The link is often already there when the update takes +place, so no action is taken, and thus no talk about it. So you may miss a +few mutterings about links if you compare the messages. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/rget.1 b/man/man1/rget.1 new file mode 100644 index 000000000..e0b1c09d3 --- /dev/null +++ b/man/man1/rget.1 @@ -0,0 +1,169 @@ +.TH RGET 1 +.SH NAME +rget, rput \- network pipe +.SH SYNOPSIS +.B rget +.RB [ \-lcio ] +.RB [ \-h +.IR host ] +.I key +.RI [ command +.RI [ arg " ...]]" +.br +.B rput +.RB [ \-lcio ] +.RB [ \-h +.IR host ] +.I key +.RI [ command +.RI [ arg " ...]]" +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.de XS \" Example start +.SP +.in +4m +.nf +.. +.de XE \" Example end +.fi +.in -4m +.SP +.. +.B Rput +and +.B rget +set up a TCP/IP channel to connect two processes together. They can looked +upon as a remote pipe. Consider the well known method of copying a +directory tree with +.BR tar : +.XS +(cd src && tar cf \- .) | (cd dst && tar xfp \-) +.XE +If the directory tree is to be copied to another machine then one can +use the following command on the source machine: +.XS +cd src && rput foo tar cf \- . +.XE +And on the destination machine: +.XS +cd dst && rget \-h \fIsource-machine\fP foo tar xfp \- +.XE +The +.I key +is either a port number in C style decimal, octal or hex, or a random string +that is hashed to a port number. +.B Rput +uses this port number to open a TCP socket that +.B rget +using the same +.I key +can connect to. +It is customary to start +.B rput +first, although +.B rget +will retry for 2 minutes trying to connect to the remote +.BR rput. +.PP +After the connection is established either utility will execute +.I command +with the given arguments with the TCP channel as either standard output +(rput) or standard input (rget). +.B Rput +and +.B rget +do not stay around for the command to finish, they simply overlay themselves +with the command. If no command is given then they will themselves copy +standard input into the TCP channel (rput), or output from the TCP channel +to standard output (rget). So these two commands have the same effect: +.XS +rput foo tar cf \- . +tar cf \- . | rput foo +.XE +The second form has two processes copying data instead of just +.B tar +directly writing its output into the TCP channel. There is a better way to +waste processor cycles, namely to save bandwidth: +.XS +cd src && tar cf \- . | rput foo compress +.SP +cd dst && rget \-h \fIsource-machine\fP foo uncompress | tar xfp \- +.XE +.B Rput +and +.B rget +can be very useful in the windowed environments we use these days. The +.B rput +can be typed into the window that has a shell running on one machine, and +the +.B rget +is then typed into the window that has a shell running on another machine. +This is easier than one of the two well known forms that use +.BR rsh : +.XS +cd src && tar cf \- . | rsh dest-machine "cd dst && tar xfp \-" +.SP +cd dst && rsh source-machine "cd src && tar cf \- ." | tar xfp \- +.XE +Especially since these forms require that one must be able to use +.B rsh +without a password, which may not always be the case. +.PP +The +.I key +can be any string of characters of any length. If its a number then it is +used directly as the port number. Otherwise the characters binary values +are multiplied together, bit 15 is set and the result is truncated to 16 +bits to make it a port number in the anonymous port space (32768 \- 65535). +The port may be in-use on the source machine, but there is a small chance +of this happening, and if so simply choose another key. (So if you use +.B rput +and +.B rget +in an unattended script then you should reserve a port number, otherwise +a connection can't be guaranteed.) +.SH OPTIONS +.TP +.B \-lcio +These flags allow one to reverse the default connect/listen or input/output +direction of +.BR rput +and +.BR rget . +Reversing the connection may be necessary if one of the two systems filters +out connections to unknown ports. For example: +.XS +rput \-c \-h \fIdestination-machine\fP foo tar cf \- . +.SP +rget \-l foo tar xfp \- +.XE +The +.B \-io +options can be used to choose which of standard input or output should be +tied to the socket. It's even possible to tie both input and output to the +socket with +.BR \-io, +but only when executing a command. This is probably the only use for these +options, because one usually chooses the direction with the mnemonic put/get +names. +.TP +.BI \-h " host" +The name of the remote host that a connection must be made to. It must be +used with the program that is doing the connect, usually +.BR rget . +This option is currently mandatory. The author is planning to increase +ease of use by letting the programs find each other with UDP broadcasts +or multicasts. +.SH "SEE ALSO" +.BR rsh (1). +.SH DIAGNOSTICS +.TP 5 +rput: Address in use +If the port computed out of +.I key +is already in use. +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/rlogin.1 b/man/man1/rlogin.1 new file mode 100644 index 000000000..be09733e6 --- /dev/null +++ b/man/man1/rlogin.1 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rlogin.1c 6.8 (Berkeley) 5/12/86 +.\" +.TH RLOGIN 1 "May 12, 1986" +.UC 5 +.SH NAME +rlogin \- remote login +.SH SYNOPSIS +.B rlogin +.RB [ \-8EL ] +.RB [ \-e +.IR char ] +.RB [ \-l +.IR username ] +.I rhost +.br +.I rhost +.RB [ \-8EL ] +.RB [ \-e +.IR char ] +.RB [ \-l +.IR username ] +.SH DESCRIPTION +.B Rlogin +connects your terminal on the current local host system +.I lhost +to the remote host system +.I rhost. +.PP +Each host has a file +.B /etc/hosts.equiv +which contains a list of \fIrhost\fR's with which it shares account names. +(The host names must be the standard names as described in +.BR rsh (1).) +When you +.B rlogin +as the same user on an equivalent host, you don't need +to give a password. +Each user may also have a private equivalence list in a file \&.rhosts +in his login directory. Each line in this file should contain an \fIrhost\fP +and a \fIusername\fP separated by a space, giving additional cases +where logins without passwords are to be permitted. +If the originating user is not equivalent to the remote user, then +a login and password will be prompted for on the remote machine as in +.BR login (1). +To avoid some security problems, the \&.rhosts file must be owned by +either the remote user or root. +.PP +The remote terminal type is the same as your local +terminal type (as given in your environment TERM variable). +The terminal or window size is also copied to the remote system +if the server supports the option, +and changes in size are reflected as well. +All echoing takes place at the remote site, so that (except for +delays) the rlogin is transparent. Flow control via ^S and ^Q and +flushing of input and output on interrupts are handled properly. +The optional argument +.B \-8 +allows an eight-bit input data path at all times; +otherwise parity bits are stripped except when the remote side's +stop and start characters are other than ^S/^Q. +The argument +.B \-L +allows the rlogin session to be run in litout mode. +A line of the form ``~.'' disconnects from the remote host, where +``~'' is the escape character. +Similarly, the line ``~^Z'' (where ^Z, control-Z, is the suspend character) +will suspend the rlogin session. +Substitution of the delayed-suspend character (normally ^Y) +for the suspend character suspends the send portion of the rlogin, +but allows output from the remote system. +A different escape character may +be specified by the +.B \-e +option. +There is no space separating this option flag and the argument +character. With the +.B \-E +option the escape can be turned off. +.SH SEE ALSO +.BR rsh (1), +.BR rhosts (5). +.SH BUGS +More of the environment should be propagated. diff --git a/man/man1/rmdir.1 b/man/man1/rmdir.1 new file mode 100644 index 000000000..acf68eb49 --- /dev/null +++ b/man/man1/rmdir.1 @@ -0,0 +1,27 @@ +.TH RMDIR 1 +.SH NAME +rmdir \- remove a directory +.SH SYNOPSIS +\fBrmdir \fIdirectory ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "rmdir /user/ast/foobar" "Remove directory \fIfoobar\fP" +.EX "rmdir /user/ast/f*" "Remove 0 or more directories" +.SH DESCRIPTION +.PP +The specified directories are removed. +Ordinary files are not removed. +The directories must be empty. +.SH "SEE ALSO" +.BR mkdir (1), +.BR rmdir (2). diff --git a/man/man1/rsh.1 b/man/man1/rsh.1 new file mode 100644 index 000000000..65e36bef8 --- /dev/null +++ b/man/man1/rsh.1 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rsh.1c 6.1 (Berkeley) 4/29/85 +.\" +.TH RSH 1 "April 29, 1985" +.UC 5 +.SH NAME +rsh \- remote shell +.SH SYNOPSIS +.B rsh +.RB [ \-n ] +.RB [ \-l +.IR username ] +.I host +.RI [ command ] +.br +.I host +.RB [ \-n ] +.RB [ \-l +.IR username ] +.RI [ command ] +.SH DESCRIPTION +.B Rsh +connects to the specified +.IR host , +and executes the specified \fIcommand\fR. +.B Rsh +copies its standard input to the remote command, the standard +output of the remote command to its standard output, and the +standard error of the remote command to its standard error. +Interrupt, quit and terminate signals are propagated to the remote +command; \fBrsh\fP normally terminates when the remote command does. +.PP +The remote username used is the same as your local username, +unless you specify a different remote name with the +.B \-l +option. +This remote name must be equivalent (in the sense of +.BR rlogin (1)) +to the originating account; no provision +is made for specifying a password with a command. +.PP +If you omit +.IR command , +then instead of executing a single command, you will be logged in +on the remote host using +.BR rlogin (1). +.PP +Shell metacharacters which are not quoted are interpreted +on local machine, while quoted metacharacters are interpreted on +the remote machine. +Thus the command +.PP +.RS +rsh otherhost cat remotefile >> localfile +.RE +.PP +appends the remote file +.I remotefile +to the localfile +.IR localfile , +while +.PP +.RS +rsh otherhost cat remotefile ">>" otherremotefile +.RE +.PP +appends +.I remotefile +to +.IR otherremotefile . +.SH OPTIONS +.TP +.BI \-l " username" +Specify the remote user name. +.TP +.B \-n +Connect standard input of the remote command to /dev/null. Do this if +.B rsh +should not inadvertently read from standard input. +.SH SEE ALSO +.BR rcp (1), +.BR rlogin (1), +.BR rhosts (5). +.SH BUGS +You cannot run an interactive command +(like +.BR rogue (6) +or +.BR vi (1)); +use +.BR rlogin (1). diff --git a/man/man1/rz.1 b/man/man1/rz.1 new file mode 100644 index 000000000..0f5a518ae --- /dev/null +++ b/man/man1/rz.1 @@ -0,0 +1,95 @@ +.TH RZ 1 +.SH NAME +rz \- receive a file using the zmodem protocol +.SH SYNOPSIS +\fBrz\fR [\-\fBabepqvy\fR]\fR [\fB\-t \fItimeout\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "CP/M to UNIX conventions" +.FL "\-b" "Binary file" +.FL "\-e" "Escape for all control characters" +.FL "\-p" "Protect file if it already exists" +.FL "\-q" "Quiet; opposite of verbose" +.FL "\-t" "Set \fItimeout\fR in tenths of a second" +.FL "\-v" "Verbose; opposite of quiet" +.FL "\-y" "Yes, clobber existing files" +.SH EXAMPLES +.EX "rz /dev/tty01" "Receive a file" +.SH DESCRIPTION +.PP +The XMODEM, YMODEM, and ZMODEM family of file transfer programs are widely +used on personal computers. +\s-2MINIX\s+2 +supports ZMODEM, the most advanced of the set. +The programs \fIsz\fR and \fIrz\fR are used for sending and receiving, +respectively. +.PP +\fIRz\fR and \fIsz\fR are programs that uses an error correcting protocol to +transfer files over a dial-in serial port from a variety of programs +running under various operating systems. +\fIRz\fR (Receive ZMODEM) receives files with the ZMODEM batch +protocol. Pathnames are supplied by the sending program, +and directories are made if necessary (and possible). +The meanings of the available options are: +.in +0.25i +.ti -0.25i +.B \-a +.br +Convert files to +\s-2UNIX\s+2 +conventions by stripping carriage +returns and all characters beginning with the first +Control Z (CP/M end of file). +.ti -0.25i +.B \-b +.br +Binary (tell it like it is) file transfer override. +.ti -0.25i +.B \-c +.br +Request 16 bit CRC. XMODEM file transfers default to 8 +bit checksum. YMODEM and ZMODEM normally use 16 bit CRC. +.ti -0.25i +.B \-D +.br +Output file data to /dev/null; for testing. +.ti -0.25i +.B \-e +.br +Force sender to escape all control characters; normally +XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped. +.ti -0.25i +.B \-p +.br +Protect: skip file if destination file exists. +.ti -0.25i +.B \-q +.br +Quiet suppresses verbosity. +.ti -0.25i +.B \-t +.br +Change timeout tenths of seconds (timeout follows flag). +.ti -0.25i +.B \-v +.br +Verbose causes a list of file names to be appended to \fI/tmp/rzlog\fR. +More v's generate more output. +.ti -0.25i +.B \-y +.br +Yes, clobber any existing files with the same name. +.in -0.25i +.SH "SEE ALSO" +.BR sz (1), +.BR term (1). diff --git a/man/man1/sed.1 b/man/man1/sed.1 new file mode 100644 index 000000000..cc87bbea7 --- /dev/null +++ b/man/man1/sed.1 @@ -0,0 +1,390 @@ +.TH sed 1 "November 19, 1995" +.SH NAME +sed \- the stream editor +.SH SYNOPSIS +.B sed +.RB [ \-n ] +.RB [ \-g ] +.RB [ \-e +.IR script ] +.RB [ \-f +.IR sfile ] +.RI [ file " ...]" +.SH DESCRIPTION +Sed copies the named files (standard input default) to the standard +output, edited according to a script of commands. +.P +An +.B \-e +option supplies a single edit command from the next argument; +if there are several of these they are executed in the order in which +they appear. If there is just one +.B \-e +option and no +.BR \-f "'s," +the +.B \-e +flag may be omitted. +.P +An +.B \-f +option causes commands to be taken from the file "sfile"; if +there are several of these they are executed in the order in which +they appear; +.B \-e +and +.B \-f +commands may be mixed. +.P +The +.B \-g +option causes +.B sed +to act as though every substitute command +in the script has a +.B g +suffix. +.P +The +.B \-n +option suppresses the default output. +.P +A script consists of commands, one per line, of the following form: +.PP + [address [, address] ] function [arguments] +.PP +Normally +.B sed +cyclically copies a line of input into a current text +buffer, then applies all commands whose addresses select the buffer in +sequence, then copies the buffer to standard output and clears it. +.P +The +.B \-n +option suppresses normal output (so that only +.B p +and +.B w +output is done). Also, some commands +.RB ( n , +.BR N ) +do their own line reads, and some others +.RB ( d , +.BR D ) +cause all commands following in the script to be skipped (the +.B D +command also suppresses the clearing of the current text +buffer that would normally occur before the next cycle). +.P +It is also helpful to know that there's a second buffer (called the `hold +space' that can be copied or appended to or from or swapped with +the current text buffer. +.P +An address is: a decimal numeral (which matches the line it numbers where line +numbers start at 1 and run cumulatively across files), or a `$' that addresses +the last line of input, or a context address, which is a `/regular +expression/', in the style of +.BR ed (1) +modified thus: +.P +.TP 5 +(1) +The escape sequence `\en' matches a newline embedded in the buffer, +and `\et' matches a tab. +.TP 5 +(2) +A command line with no addresses selects every buffer. +.TP 5 +(3) +A command line with one address selects every buffer that matches +that address. +.TP 5 +(4) +A command line with two addresses selects the inclusive range from +the first input buffer that matches the first address through the +next input buffer that matches the second. (If the second address +is a number less than or equal to the line number first selected, +only one line is selected.) Once the second address is matched +.B sed +starts looking for the first one again; thus, any number of these +ranges will be matched. +.P +The negation operator '!' can prefix a command to apply it to every +line not selected by the address(es). +.P +In the following list of functions, the maximum number of addresses +permitted for each function is indicated in parentheses. +.P +An argument denoted "text" consists of one or more lines, with all +but the last ending with `\e' to hide the newline. +.P +Backslashes in text are treated like backslashes in the replacement +string of an +.B s +command and may be used to protect initial whitespace (blanks and tabs) +against the stripping that is done on every line of the script. +.P +An argument denoted "rfile" or "wfile" must be last on the command +line. Each wfile is created before processing begins. There can be at +most 10 distinct wfile arguments. +.ta +\w'nm'u +\w'"command"m'u +.TP 5 +a "text" (1) +Append. Place text on output before reading the next input line. +.TP 5 +b "label" (2) +Branch to the `:' command bearing the label. If no label is given, +branch to the end of the script. +.TP 5 +c "text" (2) +Change. Delete the current text buffer. With 0 or 1 address, or at +the end of a 2-address range, place text on the output. Start the next +cycle. +.TP 5 +d (2) +Delete the current text buffer. Start the next cycle. +.TP 5 +D (2) +Delete the first line of the current text buffer (all chars up to the +first newline). Start the next cycle. +.TP 5 +g (2) +Replace the contents of the current text buffer with the contents of +the hold space. +.TP 5 +G (2) +Append the contents of the hold space to the current text buffer. +.TP 5 +h (2) +Copy the current text buffer into the hold space. +.TP 5 +H (2) +Append a copy of the current text buffer to the hold space. +.TP 5 +i "text" (1) +Insert. Place text on the standard output. +.TP 5 +l (2) +List. Sends the pattern space to standard output. A "w" option may +follow as in the +.B s +command below. Non-printable characters expand to: +.sp .4v +.in +3 +.nf +.ta +\w'xxxn'u +\w'nnnn'u +\w'backspace 'u +\eb \-\- backspace (ASCII 08) +\et \-\- tab (ASCII 09) +\en \-\- newline (ASCII 10) +\er \-\- return (ASCII 13) +\ee \-\- escape (ASCII 27) +\exx \-\- the ASCII character corresponding to 2 hex digits xx. +.fi +.in -3 +.ta +\w'nm'u +\w'"command"m'u +.TP 5 +n (2) +Copy the current text buffer to standard output. Read the next line +of input into it. +.TP 5 +N (2) +Append the next line of input to the current text buffer, inserting +an embedded newline between the two. The current line number changes. +.TP 5 +p (2) +Print. Copy the current text buffer to the standard output. +.TP 5 +P (2) +Copy the first line of the current text buffer (all chars up to the +first newline) to standard output. +.TP 5 +q (1) +Quit. Branch to the end of the script. Do not start a new cycle. +.TP 5 +r "rfile" (1) +Read the contents of rfile. Place them on the output before reading +the next input line. +.TP 5 +s /regular-expression/replacement/flags\0\0\0\0\0\0(2) +Substitute the replacement for instances of the regular expression +in the current text buffer. Any character may be used instead of `/'. +For a fuller description see ed (1). +Flags is zero or more of the following: +.sp .4v +.ta +\w'gm'u +\w'nnm'u +.in +\w'gmnnm'u +.ti -\w'gmnnm'u +g \-\- Global. Substitute for all nonoverlapping instances of +the string rather than just the first one. +.sp .4v +.ti -\w'gmnnm'u +p \-\- Print the pattern space if a replacement was made. +.sp .4v +.ti -\w'gmnnm'u +w \-\- Write. Append the current text buffer to a file argument +as in a w command if a replacement is made. Standard output is used if no +file argument is given +.in -\w'gmnnm'u +.ta +\w'nm'u +\w'"command"m'u +.TP 5 +t "label" (2) +Branch-if-test. Branch to the +.B : +command with the given label if any +substitutes have been made since the most recent read of an input line +or execution of a +.B t +or +.BR T . +If no label is given, branch to the end of the script. +.TP 5 +T "label" (2) +Branch-on-error. Branch to the +.B : +command with the given label if no substitutes have succeeded since the +last input line or +.B t +or +.B T +command. Branch to the end of the script if no label is given. +.TP 5 +w "wfile" (2) +Write. Append the current text buffer to wfile. +.TP 5 +W "wfile" (2) +Write first line. Append first line of the current text buffer +to wfile. +.TP 5 +x (2) +Exchange the contents of the current text buffer and hold space. +.TP 5 +y /string1/string2/\0\0\0\0\0\0(2) +Translate. Replace each occurrence of a character in string1 with +the corresponding character in string2. The lengths of these strings +must be equal. +.TP 5 +! "command" (2) +All-but. Apply the function (or group, if function is +.BR { ) +only to lines not selected by the address(es). +.TP 5 +: "label" (0) +This command does nothing but hold a label for +.B b +and +.B t +commands to branch to. +.TP 5 += (1) +Place the current line number on the standard output as a line. +.TP 5 +{ (2) +Execute the following commands through a matching `}' only when the +current line matches the address or address range given. +.P +An empty command is ignored. +.P +.SH PORTABILITY +This tool was reverse-engineered from BSD 4.1 UNIX +.BR sed , +and (as far +as the author's knowledge and tests can determine) is compatible with +it. All documented features of BSD 4.1 sed are supported. +.P +One undocumented feature (a leading 'n' in the first comment having +the same effect as an +.B \-n +command-line option) has been omitted. +.P +The following bugs and limitations have been fixed: +.TP 5 +\(bu +There is no hidden length limit (40 in BSD sed) on +.B w +file names. +.TP 5 +\(bu +There is no limit (8 in BSD sed) on the length of labels. +.TP 5 +\(bu +The exchange command now works for long pattern and hold spaces. +.P +The following enhancements to existing commands have been made: +.TP 5 +\(bu +.BR a , +.B i +commands don't insist on a leading backslash-\en in the text. +.TP 5 +\(bu +.BR r , +.B w +commands don't insist on whitespace before the filename. +.TP 5 +\(bu +The +.BR g , +.B p +and +.B P +options on +.B s +commands may be given in any order. +.P +Some enhancements to regular-expression syntax have been made: +.TP 5 +\(bu +\et is recognized in REs (and elsewhere) as an escape for tab. +.TP 5 +\(bu +In an RE, + calls for 1..n repeats of the previous pattern. +.P +The following are completely new features: +.TP 5 +\(bu +The +.B l +command (list, undocumented and weaker in BSD) +.TP 5 +\(bu +The +.B W +command (write first line of pattern space to file). +.TP 5 +\(bu +The +.B T +command (branch on last substitute failed). +.TP 5 +\(bu +Trailing comments are now allowed on command lines. +.P +In addition, +.BR sed "'s" +error messages have been made more specific and informative. +.P +The implementation is also significantly smaller and faster than +BSD 4.1 sed. It uses only the standard I/O library and exit(3). +.P +.SH NOTE +.P +This is a freeware component of the GNU and MINIX operating systems. +The user is hereby granted permission to use, modify, reproduce and +distribute it subject to the following conditions: +.P +1. The authorship notice appearing in each source file may not be +altered or deleted. +.P +2. The object form may not be distributed without source. +.P +.SH SEE ALSO +.P +.BR cgrep (1), +.BR fgrep (1), +.BR grep (1), +.BR lex (1), +.BR regexp (5), +.BR awk (9). +.P +.SH AUTHOR +Eric S. Raymond diff --git a/man/man1/shar.1 b/man/man1/shar.1 new file mode 100644 index 000000000..190f8f1ef --- /dev/null +++ b/man/man1/shar.1 @@ -0,0 +1,40 @@ +.TH SHAR 1 +.SH NAME +shar \- shell archiver +.SH SYNOPSIS +\fBshar \fIfile ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "shar *.c >s" "Collect C programs in shell archive" +.EX "sh 4 chars in \fIa.out\fR" +.EX "strings \- /bin/sh" "Search entire shell file (text and data)" +.SH DESCRIPTION +.PP +\fIStrings\fR looks for sequences of ASCII characters followed by a zero +byte. +These are usually strings. This program is typically used to help identify +unknown binary programs diff --git a/man/man1/strip.1 b/man/man1/strip.1 new file mode 100644 index 000000000..1da56c56b --- /dev/null +++ b/man/man1/strip.1 @@ -0,0 +1,24 @@ +.TH STRIP 1 +.SH NAME +strip \- remove symbol table from executable file +.SH SYNOPSIS +\fBstrip\fR [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "strip a.out" "Remove symbols from \fIa.out\fR" +.SH DESCRIPTION +.PP +For each file argument, \fIstrip\fR removes the symbol table. +Strip makes a copy of the file being stripped, so links are lost. +.SH "SEE ALSO" +.BR install (1). diff --git a/man/man1/stty.1 b/man/man1/stty.1 new file mode 100644 index 000000000..355f3453b --- /dev/null +++ b/man/man1/stty.1 @@ -0,0 +1,250 @@ +.TH STTY 1 +.SH NAME +stty \- set terminal parameters +.SH SYNOPSIS +.de SP +.if t .sp 0.4 +.if n .sp +.. +.in +4n +.ti -4n +.B stty +.RB [ \-ag] +.SP +.ti -4n +.B stty +.I encoded-form +.SP +.ti -4n +.B stty +.I speed +.B ispeed +.I speed +.B ospeed +.I speed +.B "cs5 cs6 cs7 cs8" +.RB [ \- ] parenb +.RB [ \- ] parodd +.RB [ \- ] hupcl +.RB [ \- ] cstopb +.RB [ \- ] cread +.RB [ \- ] clocal +.RB [ \- ] ignbrk +.RB [ \- ] brkint +.RB [ \- ] ignpar +.RB [ \- ] parmrk +.RB [ \- ] inpck +.RB [ \- ] istrip +.RB [ \- ] inlcr +.RB [ \- ] igncr +.RB [ \- ] icrnl +.RB [ \- ] ixon +.RB [ \- ] ixoff +.RB [ \- ] ixany +.RB [ \- ] opost +.RB [ \- ] onlcr +.RB [ \- ] xtabs +.RB [ \- ] onoeot +.RB [ \- ] isig +.RB [ \- ] icanon +.RB [ \- ] iexten +.RB [ \- ] echo +.RB [ \- ] echoe +.RB [ \- ] echok +.RB [ \- ] echonl +.RB [ \- ] noflsh +.RB [ \- ] tostop +.RB [ \- ] lflusho +.BR eof =\fIc +.BR eol =\fIc +.BR erase =\fIc +.BR erase =\fIc +.BR intr =\fIc +.BR kill =\fIc +.BR quit =\fIc +.BR susp =\fIc +.BR start =\fIc +.BR stop =\fIc +.BR rprnt =\fIc +.BR lnext =\fIc +.BR flush =\fIc +.BR min =\fIn +.BR time =\fIn +.B rows +.I n +.B cols +.I n +.B xpixels +.I n +.B ypixels +.I n +.B cooked +.B raw +.RB [ \- ] evenp +.RB [ \- ] parity +.RB [ \- ] oddp +.RB [ \- ] nl +.B ek +.B sane +.in -4n +.SH DESCRIPTION +.B Stty +shows or changes the parameters of the terminal connected to standard input. +.B Stty +takes a myriad of arguments most of which are mapped directly to +the flags and special characters described in +.BR tty (4), +so we won't describe them here. +.PP +.B Stty +has three forms of operation. First, without any arguments +.B stty +shows all terminal attributes that are different from the default state. +Option +.B \-a +makes +.B stty +print all terminal attributes, and +.B \-g +lets +.B stty +print the attributes in a special encoded form, a simple row of colon separated +hexadecimal numbers. +.PP +In the second form of operation +.B stty +takes an encoded form as produced by the +.B \-g +option and sets the terminals attributes to its decoded value. +.PP +In the third form +.B stty +interprets a series of flags and parameters settings and modifies the +terminal attributes accordingly. Flags can be given as +.B icanon +or +.B \-icanon +for instance, either setting or clearing the +.B ICANON +flag. +Special character values can by set like +.B "intr=^C" +for example, which sets the interrupt character to CTRL-C. You can either +use a real CTRL-C, or the two characters `^' and `C'. In any case +it is probably necessary to use quotes to guard it from the shell: +.BR "intr='^C'" . +.PP +A number alone is interpreted as a baud rate setting for both the input and +output rate. The input or the output rate can be set separately with use +of the +.B ispeed +and +.B ospeed +prefixes to the number. The character size can be set with +.BR cs5 , +.BR cs6 , +.BR cs7 +or +.BR cs8 . +.PP +The +.B MIN +and +.B TIME +value, the number of rows and columns, and the xpixels and ypixels of the +window can also be set using one of the keywords +.BR min , +.BR time , +.BR rows , +.BR cols , +.BR xpixels +or +.BR ypixels , +followed by a decimal number that is the value of the setting. +.PP +.B Stty +accepts several keywords that are not named by corresponding flags or +parameters in +.BR tty (4). +They set several attributes at once: +.TP +.B cooked +Same as +.BR "icrnl ixon opost onlcr isig icanon iexten echo" , +setting all the attributes that are needed for line oriented mode. +.TP +.B raw +Same as +.BR "\-icrnl \-ixon \-opost \-onlcr \-isig \-icanon \-iexten \-echo" , +setting all the attributes for a raw data channel. +.TP +.B evenp parity +These synonyms are equal to +.BR "cs7 parenb \-parodd" , +setting the line to 7 bits even parity. +.TP +.B oddp +Same as +.BR "cs7 parenb parodd" , +setting the line to 7 bits odd parity. +.TP +.B "\-parity \-evenp \-oddp" +All synonyms for +.BR "cs8 \-parenb" , +setting the line to 8 bits, no parity. +.TP +.B nl +Same as +.BR icrnl , +setting carriage return to line feed input translation. +.TP +.B \-nl +Same as +.BR "\-icrnl \-inlcr \-igncr" , +disabling any carriage return or line feed handling. +.TP +.B ek +Set the +.B ERASE +and +.B KILL +special characters back to the default. +.TP +.B sane +Set all attributes to the default except things like the line speed and +parity, because their "sane" value is probably what it is right now. +The default values are compiled into +.B stty +from the include file. Use +.B "stty sane; stty -a" +to know what they are. +.SH FILES +.TP 15n +.B /etc/ttytab +The +.B init +field of this file may contain an +.B stty +command to set the attributes to match an attached RS232 terminal or modem. +.SH "SEE ALSO" +.BR tty (4), +.BR ttytab (5). +.SH NOTES +The +.BR cooked , +.BR raw , +.BR rows , +.BR cols , +.BR xpixels +and +.BR ypixels +keywords are Minix additions beyond the keywords defined by POSIX. +.B Rows +and +.B cols +are common UNIX extensions, however. +There are more Minix specific flags that match the Minix specific attributes +described in +.BR tty (4). +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/su.1 b/man/man1/su.1 new file mode 100644 index 000000000..0b212e099 --- /dev/null +++ b/man/man1/su.1 @@ -0,0 +1,58 @@ +.TH SU 1 +.SH NAME +su \- temporary become superuser or another user +.SH SYNOPSIS +.B su +.RB [ \- [ e ]] +.RI [ user +.RI [ shell-arguments " ...]]" +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Su +can be used to temporarily run a shell under the identity of the superuser +or another user. Unless the caller is a member of the operator group, one +is prompted for the password of the user-to-be. Calls that need a password +are logged, whether they succeed or not. The default user is +.BR root . +Further arguments are handed to the shell. By default the shell started is +the shell of the invoker, and the environment is passed on as is. +.PP +The activities of +.B su +are logged through +.BR syslog (3) +under Minix-vmd. +.SH OPTIONS +.TP +.B \- +Constructs a new environment consisting of the +.BR PATH , +.BR USER , +.BR LOGNAME , +.BR HOME , +.BR SHELL , +.BR TERM , +.BR TERMCAP , +and +.BR TZ +variables. The environment is the same as on a normal login, except that +.BR TERM , +.B TERMCAP +and +.B TZ +are copied from the current environment if set. The current working +directory is changed to the user home directory, the shell of the user-to-be +is run, and it is started as a login shell, with the first character a minus +sign. +.TP +.B \-e +Like above, but the shell is started normally, not as a login shell. +.SH "SEE ALSO" +.BR sh (1), +.BR login (1), +.BR syslog (3). +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/sum.1 b/man/man1/sum.1 new file mode 100644 index 000000000..19c0d8a86 --- /dev/null +++ b/man/man1/sum.1 @@ -0,0 +1,29 @@ +.TH SUM 1 +.SH NAME +sum \- compute the checksum and block count of a file +.SH SYNOPSIS +\fBsum \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "sum /user/ast/xyz" "Checksum \fI/user/ast/xyz" +.SH DESCRIPTION +.PP +.I Sum +computes the checksum of one or more files. +It is most often used to see if a file copied from another machine has +been correctly received. +This program works best when both machines use the same checksum algorithm. +See also \fIcrc\fR. +.SH "SEE ALSO" +.BR cksum (1), +.BR crc (1). diff --git a/man/man1/svc.1 b/man/man1/svc.1 new file mode 100644 index 000000000..562ad8f3c --- /dev/null +++ b/man/man1/svc.1 @@ -0,0 +1,47 @@ +.TH SVC 1 +.SH NAME +svc, ci, co, svclog \- shell version control system +.SH SYNOPSIS +\fBci\fR [\fB\-lu\fR]\fR \fIfile\fR +.br +\fBco\fR [\fB\-l\fR]\fR [\fB\-r \fIrev\fR] \fIfile\fR +.br +\fBsvclog \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-l" "For \fIci\fR, checkin, checkout again, and lock file" +.FL "\-l" "For \fIco\fR, checkout file and then lock the archive" +.FL "\-u" "After checking in, do not delete the file" +.FL "\-r" "Check out revision \fIrev\fR instead most recent revision +.SH EXAMPLES +.EX "ci \-u file" "Check in \fIfile\fR" +.EX "co \-l file" "Check out \fIfile\fR and lock archive" +.EX "co \-r 2 file" "Check out version 2" +.SH DESCRIPTION +.PP +\fISvc\fR is the Shell Version Control system, patterned on RCS. +It maintains a sequence of versions in archive files, so that new versions +can be checked in (added to the archive), and old versions can be checked +out (made available). +To create an archive for \fIfile\fR, check it in with the \fB\-u\fR flag. +This action will prompt for a log message and then create an archive called +\fIfile,S\fR in the current directory, or in the subdirectory \fISVC\fR if +it exists. +The file will not be deleted, but will be made unwritable. +.PP +To update the file, check it out with the \fB\-l\fR flag. +Then modify it, and check it back in, giving a new message when prompted. +After this process has been repeated many times, the archive will contain +the entire history. +Any version can be checked out using the \fB\-r\fR flag. +To get a printout of the history, use \fIsvclog\fR. diff --git a/man/man1/synctree.1 b/man/man1/synctree.1 new file mode 100644 index 000000000..aed74a1ab --- /dev/null +++ b/man/man1/synctree.1 @@ -0,0 +1,76 @@ +.TH SYNCTREE 1 +.SH NAME +synctree \- synchronize directory trees. +.SH SYNOPSIS +.nf +\fBsynctree\fP [\fB\-iuf\fP] [[\fIuser1\fP@]\fImachine1\fP:]\fIdir1\fP [[\fIuser2\fP@]\fImachine2\fP:]\fIdir2\fP +.fi +.SH DESCRIPTION +.B Synctree +synchronizes the directory tree rooted at \fIdir2\fP with \fIdir1\fP. It +walks recursively through both trees, and deletes and adds files in +\fIdir2\fP to make it equal to \fIdir1\fP. Mode, owner and group are set for +each file unless the \fB\-u\fP flag is given. In its normal mode of operation, +synctree will ask if it may delete or add directories assuming that you don't +want to. Non-directories are simply deleted or added, but synctree will ask if +it needs to update a normal file with a default answer of 'y'. Simply typing +return will choose the default answer, typing end-of-file is like typing +return to this question and all other questions. +.PP +You can specify a hostname and user-id to be used to access \fIdir1\fP or +\fIdir2\fP. Synctree will use \fBrsh\fP(1) to run a copy of itself on +the remote machine. The call interface mimics that of \fBrcp\fP(1), but +you can use more than one user@machine prefix if you want to make things +really interesting. +.PP +Hard links are enforced, an update is done by first deleting the old file +so that links to unknown files are broken. Links to files within \fIdir2\fP +will be restored. +.PP +If either directory contains the file \fB.backup\fP, then this file will +be used as an alternate inode table. This allows one to make a backup copy +of a file tree full of special files and differing user-ids on a remote +machine under an unpriviledged user-id. +.PP +.SH OPTIONS +.TP 5 +.B \-i +Ask for permission (with default answer 'n') to delete or +add any file or directory. +.TP 5 +.B \-u +Only install newer files, i.e. merge the directory trees. +.TP 5 +.B \-f +Don't ask, think 'yes' on any question. +.SH "SEE ALSO" +.BR remsync (1), +.BR cpdir (1), +.BR rsh (1), +.BR rcp (1), +.BR perror (3). +.SH DIAGNOSTICS +Messages may come from three different processes. One named "Slave" running +in \fIdir1\fP, one named "Master" running in \fIdir2\fP, and synctree itself +in a mediator role. The mediator will also perform the task of either the +master or the slave if one of them is running locally. You need to know this +to interpret the error messages coming from one of these processes. The +messages are normally based on \fBperror\fP(3). Failure to contact a remote +machine will be reported by \fBrsh\fP. \fBSynctree\fP should have a zero +exit status if no errors have been encountered. +.SH BUGS +Directory \fIdir2\fP will be created without asking. +.PP +The master and slave processes get their error output mixed up sometimes +(nice puzzle). +.PP +The local and remote machine must use the same file type encoding. +.PP +The link replacement strategy may lead to lack of space on a small device. +Let \fBsynctree\fP run to completion and then rerun it to pick up the pieces. +.PP +Letting the local process keep its "synctree" name may be a mistake. +.PP +It talks too much. +.SH AUTHOR +Kees J. Bot, (kjb@cs.vu.nl) diff --git a/man/man1/sysenv.1 b/man/man1/sysenv.1 new file mode 100644 index 000000000..e5d62905c --- /dev/null +++ b/man/man1/sysenv.1 @@ -0,0 +1,27 @@ +.TH SYSENV 1 +.SH NAME +sysenv \- request system boot parameter +.SH SYNOPSIS +.B sysenv +.RI [ boot-variable "] ..." +.SH DESCRIPTION +.B Sysenv +requests the value of one or more boot variables. For example +.B "sysenv\ memory" +returns the list of free memory at system startup. Note that some +parameters have undergone "device translation" from a device name to +a decimal device number. +.PP +If no variable names are given then the entire boot environment is +listed. +.SH "SEE ALSO" +.BR svrctl (2), +.BR monitor (8), +.BR boot (8). +.SH DIAGNOSTICS +Exit code 0 with the variable's value printed to standard output if all +requested variables exist in the boot environment, exit code 1 on any +weird error, exit code 2 if one of the variables is not set, and exit +code 3 if both kind of errors occurred. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/sz.1 b/man/man1/sz.1 new file mode 100644 index 000000000..50b08fd69 --- /dev/null +++ b/man/man1/sz.1 @@ -0,0 +1,235 @@ +.TH SZ 1 +.SH NAME +sz \- send a file using the zmodem protocol +.SH SYNOPSIS +\fBsz\fR [\fB\-LNbdefnopqruvy+\fR]\fR [\fB\-ci \fIcommand\fR] [\fB\-Ll\fR n\fR] [\fB\-t \fItimeout\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-L" "Use \fIn\fR-byte packets" +.FL "\-N" "Overwrite if source is newer/longer" +.FL "\-b" "Binary file" +.FL "\-c" "Send command for execution" +.FL "\-d" "Convert dot to slash in names" +.FL "\-e" "Escape for all control characters" +.FL "\-f" "Send full path name" +.FL "\-i" "Send command and return immediately" +.FL "\-l" "Flow control every \fIn\fR packets" +.FL "\-n" "Overwrite destination if source is newer" +.FL "\-o" "Use old (16-bit) checksum" +.FL "\-p" "Protect file if it already exists" +.FL "\-q" "Quiet; opposite of verbose" +.FL "\-r" "Resume interrupt file transfer" +.FL "\-t" "Set \fItimeout\fR in tenths of a second" +.FL "\-u" "Unlink file after successful transmission" +.FL "\-v" "Verbose; opposite of quiet" +.FL "\-y" "Yes, clobber existing files" +.FL "\-+" "Append to an existing file" +.SH EXAMPLES +.EX "sz file /dev/tty01" "Send \fIfile\fR" +.SH DESCRIPTION +.PP +XMODEM, YMODEM, and ZMODEM are a family of protocols that are widely used +is the \s-2MS-DOS\s0 world for transferring information reliably from one +computer to another. In all of these protocols, a series of bytes are sent +from one computer to the other, and then an acknowledgement is sent back +to confirm correct reception. Checksums are used to detect errors so that +transmission is reliable even in the face of noisy telephone lines. +\fISz\fR is a program that sends a file sent from another computer using the +zmodem protocol. +The file can be received using \fIrz\fR. +.PP +\fISz\fR uses the ZMODEM error correcting +protocol to send one or more files over a dial-in serial +port to a variety of programs running under +\s-2MINIX\s+2, +\s-2UNIX\s+2, +\s-2MS-DOS\s0, \s-2CP/M\s0, \s-2VMS\s0, and other operating systems. +It is the successor to XMODEM and YMODEM. +.PP +ZMODEM greatly simplifies file transfers compared to XMODEM. +In addition to a friendly user interface, ZMODEM provides +Personal Computer and other users an efficient, accurate, +and robust file transfer method. +.PP +ZMODEM provides complete end-to-end data integrity between +application programs. ZMODEM's 32 bit CRC catches errors +that sneak into even the most advanced networks. +.PP +Output from another program may be piped to \fIsz\fR for +transmission by denoting standard input with \-: +.PP +.B " ""ls \-l | sz \-" +.PP +The program output is transmitted with the filename \fIsPID.sz\fR +where PID is the process ID of the \fIsz\fR program. If the +environment variable \fIONAME\fR is set, that is used instead. In +this case, the command: +.PP +.B " ""ls \-l | ONAME=con sz \-ay \-" +.PP +will send a \&'file\&' to the PC-DOS console display. +The \fB\-y\fR option instructs the receiver to open the file for writing +unconditionally. +The \fB\-a\fR option causes the receiver to +convert +\s-2UNIX\s+2 +newlines to PC-DOS carriage returns and linefeeds. +On +\s-2UNIX\s+2 +systems, additional information about the file is +transmitted. If the receiving program uses this +information, the transmitted file length controls the exact +number of bytes written to the output dataset, and the +modify time and file mode are set accordingly. +.PP +If \fIsz\fR is invoked with $SHELL set and if that variable +contains the string \fIrsh\fR or \fIrksh\fR (restricted shell), \fIsz\fR +operates in restricted mode. Restricted mode restricts +pathnames to the current directory and \fIPUBDIR\fR (usually +\fI/usr/spool/uucppublic\fR) and/or subdirectories thereof. +.PP +The options and flags available are: +.in +0.25i +.ti -0.25i +.B \-+ +.br +Instruct the receiver to append transmitted data to an existing file. +.ti -0.25i +.B \-a +.br +Convert NL characters in the transmitted file to CR/LF. +This is done by the sender for XMODEM and YMODEM, by the receiver for ZMODEM. +.ti -0.25i +.B \-b +.br +Binary override: transfer file without any translation. +.ti -0.25i +.B \-c +.br +Send COMMAND (follows \fIc\fR) to the receiver for execution, return with +COMMAND's exit status. +.ti -0.25i +.B \-d +.br +Change all instances of \&'.\&' to \&'/\&' in the transmitted +pathname. Thus, C.omenB0000 (which is unacceptable to +\s-2MS-DOS\s0 or CP/M) is transmitted as C/omenB0000. If the +resultant filename has more than 8 characters in the +stem, a \&'.\&' is inserted to allow a total of eleven. +.ti -0.25i +.B \-e +.br +Escape all control characters; normally XON, XOFF, DLE, +CR-@-CR, and Ctrl-X are escaped. +.ti -0.25i +.B \-f +.br +Send Full pathname. Normally directory prefixes are stripped from +the transmitted filename. +.ti -0.25i +.B \-i +.br +Send COMMAND (follows \fIi\fR) to the receiver for execution, return +Immediately upon the receiving program's successful reception of the command. +.ti -0.25i +.B \-L +.br +Use ZMODEM sub-packets of length \fIn\fR (follows \fIL\fR). +A larger \fIn\fR (32 <= \fIn\fR <= 1024) gives slightly higher throughput, a +smaller one speeds error recovery. The default is 128 below 300 +baud, 256 above 300 baud, or 1024 above 2400 baud. +.ti -0.25i +.B \-l +.br +Wait for the receiver to acknowledge correct data every +\fIn\fR (32 <= \fIn\fR <= 1024) characters. +This may be used to avoid network overrun when XOFF flow control is lacking. +.ti -0.25i +.B \-n +.br +Send each file if destination file does not exist. +Overwrite destination file if source file is newer than the destination file. +.ti -0.25i +.B \-N +.br + Send each file if destination file does not exist. Overwrite destination +file if source file is newer or longer than the destination file. +.ti -0.25i +.B \-o +.br +Disable automatic selection of 32 bit CRC. +.ti -0.25i +.B \-p +.br +Protect existing destination files by skipping transfer if the destination +file exists. +.ti -0.25i +.B \-q +.br +Quiet suppresses verbosity. +.ti -0.25i +.B \-r +.br +Resume interrupted file transfer. If the source file is longer than the +destination file, the transfer commences at the offset in the source file +that equals the length of the destination file. +.ti -0.25i +.B \-t +.br +Change timeout. +The timeout, in tenths of seconds, follows, the \fB\-t\fR flag. +.ti -0.25i +.B \-u +.br +Unlink the file after successful transmission. +.ti -0.25i +.B \-w +.br +Limit the transmit window size to \fIn\fR bytes (\fIn follows \fB(enw\fR). +.ti -0.25i +.B \-v +.br +Verbose causes a list of file names to be appended to \fI/tmp/szlog\fR. +.ti -0.25i +.B \-y +.br +Instruct a ZMODEM receiving program to overwrite any existing file with the +same name. +.ti -0.25i +.B \-Y +.br +Instruct a ZMODEM receiving program to overwrite any existing file with the +same name, and to skip any source files that do have a file with the same +pathname on the destination system. +.in -0.25i +.SS "Examples" +.PP +Below are some examples of the use of \fIsz\fR. +.PP +.B " ""sz \-a \d\s+2*\s0\u.c" +.PP +This single command transfers all .c files in the current +directory with conversion (\fB\-a\fR) to end-of-line +conventions appropriate to the receiving environment. +.sp +.B " ""sz \-Yan \d\s+2*\s0\u.c \d\s+2*\s0\u.h" +.PP +.LP +Send only the \fI.c\fR and \fI.h\fR files that exist on both systems, +and are newer on the sending system than the corresponding +version on the receiving system, converting +\s-2MINIX\s+2 +to \s-2MS-DOS\s0 text format. +.SH "SEE ALSO" +.BR rz (1), +.BR term (1). diff --git a/man/man1/tail.1 b/man/man1/tail.1 new file mode 100644 index 000000000..5ee9f7fec --- /dev/null +++ b/man/man1/tail.1 @@ -0,0 +1,34 @@ +.TH TAIL 1 +.SH NAME +tail \- print the last few lines of a file +.SH SYNOPSIS +\fBtail\fR [\fB\-c \fIn\fR] [\fB\-f] [\fB\-n \fIn\fR] [\fIfile\fR] ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "The count refers to characters" +.FL "\-f" "On FIFO or special file, keep reading after EOF" +.FL "\-n" "The count refers to lines" +.SH EXAMPLES +.EX "tail \-n 6" "Print last 6 lines of \fIstdin\fR" +.EX "tail \-c 20 file" "Print the last 20 characters of \fIfile\fR" +.EX "tail \-n 1 file1 file2" "Print last line of two files" +.EX "tail \-n +8 file" "Print the tail starting with line 8" +.SH DESCRIPTION +.PP +The last few lines of one or more files are printed. +The default count is 10 lines. +The default file is \fIstdin\fR. +If the value of \fIn\fR for the \fB\-c\fR or \fB\-n\fR flags starts with +a + sign, counting starts at the beginning, rather than the end of the file. +.SH "SEE ALSO" +.BR head (1). diff --git a/man/man1/tar.1 b/man/man1/tar.1 new file mode 100644 index 000000000..1a58c9a4b --- /dev/null +++ b/man/man1/tar.1 @@ -0,0 +1,49 @@ +.TH TAR 1 +.SH NAME +tar \- tape archiver +.SH SYNOPSIS +\fBtar\fR [\fBFcotvxp\fR]\fR [\fBf\fR] \fItarfile \fIfile ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "F" "Force tar to continue after an error" +.FL "c" "Create a new archive; add named files" +.FL "o" "Set uid/gid to original values on extraction" +.FL "f" "Next argument is name of tarfile" +.FL "t" "Print a table listing the archive's contents" +.FL "v" "Verbose mode-tell what is going on as it happens" +.FL "x" "The named files are extracted from the archive" +.FL "p" "Restore file modes, ignore creation mask" +.FL "D" "Directory only, do not recurse" +.SH EXAMPLES +.EX "tar c /dev/fd1 ." "Back up current directory to \fI/dev/fd1\fR" +.EX "tar xv /dev/fd1 file1 file2" "Extract two files from the archive" +.EX "tar cf \- | (cd dest; tar xf \-)" "Copy current directory to \fIdest\fR" +.SH DESCRIPTION +.PP +\fITar\fR is a POSIX-compatible archiver, except that it does not use tape. +It's primary advantage over +.I ar +is that the +.I tar +format is somewhat more standardized than the +.I ar +format, making it theoretically possible to transport +\s-2MINIX\s+2 +files to another computer, but do not bet on it. +If the target machine runs +\&MS-DOS , +try +.I doswrite . +.SH "SEE ALSO" +.BR compress (1), +.BR vol (1). diff --git a/man/man1/tee.1 b/man/man1/tee.1 new file mode 100644 index 000000000..aaaa98418 --- /dev/null +++ b/man/man1/tee.1 @@ -0,0 +1,29 @@ +.TH TEE 1 +.SH NAME +tee \- divert stdin to a file +.SH SYNOPSIS +\fBtee\fR [\fB\-ai\fR] \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "Append to the files, rather than overwriting" +.FL "\-i" "Ignore interrupts" +.SH EXAMPLES +.EX "cat file1 file2 | tee x" "Save and display two files" +.EX "pr file | tee x | lp" "Save the output of \fIpr\fP on \fIx\fP" +.SH DESCRIPTION +.PP +.I Tee +copies \fIstdin\fR to standard output. +It also makes copies on all the files listed as arguments. +.SH "SEE ALSO" +.BR cat (1). diff --git a/man/man1/telnet.1 b/man/man1/telnet.1 new file mode 100644 index 000000000..ca391df6c --- /dev/null +++ b/man/man1/telnet.1 @@ -0,0 +1,587 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)telnet.1c 6.5 (Berkeley) 5/10/86 +.\" +.TH TELNET 1 "May 10, 1986" +.UC 5 +.SH NAME +telnet \- user interface to the \s-1TELNET\s0 protocol +.SH SYNOPSIS +telnet [ +.I host +[ +.I port +] ] +.SH DESCRIPTION +.I Telnet +is used to communicate with another host using the +.B TELNET +protocol. +If +.I telnet +is invoked without arguments, it enters command mode, +indicated by its prompt (\*(lqtelnet>\*(rq). +In this mode, it accepts and executes the commands listed below. +If it is invoked with arguments, it performs an +.B open +command (see below) with those arguments. +.PP +Once a connection has been opened, +.I telnet +enters an input mode. +The input mode entered will be either \*(lqcharacter at a time\*(rq +or \*(lqline by line\*(rq +depending on what the remote system supports. +.PP +In \*(lqcharacter at a time\*(rq mode, most +text typed is immediately sent to the remote host for processing. +.PP +In \*(lqline by line\*(rq mode, all text is echoed locally, +and (normally) only completed lines are sent to the remote host. +The \*(lqlocal echo character\*(rq (initially \*(lq^E\*(rq) may be used +to turn off and on the local echo +(this would mostly be used to enter passwords +without the password being echoed). +.PP +In either mode, if the +.I localchars +toggle is TRUE (the default in line mode; see below), +the user's +.IR quit , +.IR intr , +and +.I flush +characters are trapped locally, and sent as +.B TELNET +protocol sequences to the remote side. +There are options (see +.B toggle +.I autoflush +and +.B toggle +.I autosynch +below) +which cause this action to flush subsequent output to the terminal +(until the remote host acknowledges the +.B TELNET +sequence) and flush previous terminal input +(in the case of +.I quit +and +.IR intr ). +.PP +While connected to a remote host, +.I telnet +command mode may be entered by typing the +.I telnet +\*(lqescape character\*(rq (initially \*(lq^]\*(rq). +When in command mode, the normal terminal editing conventions are available. +.PP +.B COMMANDS +.PP +The following commands are available. +Only enough of each command to uniquely identify it need be typed +(this is also true for arguments to the +.BR mode , +.BR set , +.BR toggle , +and +.B display +commands). +.PP +.TP +.B open \fIhost\fP \fR[\fP \fIport\fP \fR]\fP +.br +Open a connection to the named host. +If no port number +is specified, +.I telnet +will attempt to contact a +.B TELNET +server at the default port. +The host specification may be either a host name (see +.IR hosts (5)) +or an Internet address specified in the \*(lqdot notation\*(rq (see +.IR inet (3N)). +.TP +.B close +.br +Close a +.B TELNET +session and return to command mode. +.TP +.B quit +.br +Close any open +.B TELNET +session and exit +.IR telnet . +An end of file (in command mode) will also close a session and exit. +.TP +.B z +.br +Suspend +.IR telnet . +This command only works when the user is using the +.IR csh (1). +.TP +.B mode \fItype\fP +.br +.I Type +is either +.I line +(for \*(lqline by line\*(rq mode) +or +.I character +(for \*(lqcharacter at a time\*(rq mode). +The remote host is asked for permission to go into the requested mode. +If the remote host is capable of entering that mode, the requested +mode will be entered. +.TP +.B status +.br +Show the current status of +.IR telnet . +This includes the peer one is connected to, as well +as the current mode. +.TP +.B display \fR[\fP \fIargument...\fP \fR]\fP +.br +Displays all, or some, of the +.B set +and +.B toggle +values (see below). +.TP +.B ? \fR[\fP \fIcommand\fP \fR]\fP +.br +Get help. With no arguments, +.I telnet +prints a help summary. +If a command is specified, +.I telnet +will print the help information for just that command. +.TP +.B send \fIarguments\fP +.br +Sends one or more special character sequences to the remote host. +The following are the arguments which may be specified +(more than one argument may be specified at a time): +.RS +.TP +.I escape +.br +Sends the current +.I telnet +escape character (initially \*(lq^]\*(rq). +.TP +.I synch +.br +Sends the +.B TELNET SYNCH +sequence. +This sequence causes the remote system to discard all previously typed +(but not yet read) input. +This sequence is sent as TCP urgent +data (and may not work if the remote system is a 4.2 BSD system -- if +it doesn't work, a lower case \*(lqr\*(rq may be echoed on the terminal). +.TP +.I brk +.br +Sends the +.B TELNET BRK +(Break) sequence, which may have significance to the remote +system. +.TP +.I ip +.br +Sends the +.B TELNET IP +(Interrupt Process) sequence, which should cause the remote +system to abort the currently running process. +.TP +.I ao +.br +Sends the +.B TELNET AO +(Abort Output) sequence, which should cause the remote system to flush +all output +.B from +the remote system +.B to +the user's terminal. +.TP +.I ayt +.br +Sends the +.B TELNET AYT +(Are You There) +sequence, to which the remote system may or may not choose to respond. +.TP +.I ec +.br +Sends the +.B TELNET EC +(Erase Character) +sequence, which should cause the remote system to erase the last character +entered. +.TP +.I el +.br +Sends the +.B TELNET EL +(Erase Line) +sequence, which should cause the remote system to erase the line currently +being entered. +.TP +.I ga +.br +Sends the +.B TELNET GA +(Go Ahead) +sequence, which likely has no significance to the remote system. +.TP +.I nop +.br +Sends the +.B TELNET NOP +(No OPeration) +sequence. +.TP +.I ? +.br +Prints out help information for the +.B send +command. +.RE +.TP +.B set \fIargument value\fP +.br +Set any one of a number of +.I telnet +variables to a specific value. +The special value \*(lqoff\*(rq turns off the function associated with +the variable. +The values of variables may be interrogated with the +.B display +command. +The variables which may be specified are: +.RS +.TP +.I echo +.br +This is the value (initially \*(lq^E\*(rq) which, when in +\*(lqline by line\*(rq mode, toggles between doing local echoing +of entered characters (for normal processing), and suppressing +echoing of entered characters (for entering, say, a password). +.TP +.I escape +.br +This is the +.I telnet +escape character (initially \*(lq^[\*(rq) which causes entry +into +.I telnet +command mode (when connected to a remote system). +.TP +.I interrupt +.br +If +.I telnet +is in +.I localchars +mode (see +.B toggle +.I localchars +below) +and the +.I interrupt +character is typed, a +.B TELNET IP +sequence (see +.B send +.I ip +above) +is sent to the remote host. +The initial value for the interrupt character is taken to be +the terminal's +.B intr +character. +.TP +.I quit +.br +If +.I telnet +is in +.I localchars +mode (see +.B toggle +.I localchars +below) +and the +.I quit +character is typed, a +.B TELNET BRK +sequence (see +.B send +.I brk +above) +is sent to the remote host. +The initial value for the quit character is taken to be +the terminal's +.B quit +character. +.TP +.I flushoutput +.br +If +.I telnet +is in +.I localchars +mode (see +.B toggle +.I localchars +below) +and the +.I flushoutput +character is typed, a +.B TELNET AO +sequence (see +.B send +.I ao +above) +is sent to the remote host. +The initial value for the flush character is taken to be +the terminal's +.B flush +character. +.TP +.I erase +.br +If +.I telnet +is in +.I localchars +mode (see +.B toggle +.I localchars +below), +.B and +if +.I telnet +is operating in \*(lqcharacter at a time\*(rq mode, then when this +character is typed, a +.B TELNET EC +sequence (see +.B send +.I ec +above) +is sent to the remote system. +The initial value for the erase character is taken to be +the terminal's +.B erase +character. +.TP +.I kill +.br +If +.I telnet +is in +.I localchars +mode (see +.B toggle +.I localchars +below), +.B and +if +.I telnet +is operating in \*(lqcharacter at a time\*(rq mode, then when this +character is typed, a +.B TELNET EL +sequence (see +.B send +.I el +above) +is sent to the remote system. +The initial value for the kill character is taken to be +the terminal's +.B kill +character. +.TP +.I eof +.br +If +.I telnet +is operating in \*(lqline by line\*(rq mode, entering this character +as the first character on a line will cause this character to be +sent to the remote system. +The initial value of the eof character is taken to be the terminal's +.B eof +character. +.RE +.TP +.B toggle \fIarguments...\fP +.br +Toggle (between +TRUE +and +FALSE) +various flags that control how +.I telnet +responds to events. +More than one argument may be specified. +The state of these flags may be interrogated with the +.B display +command. +Valid arguments are: +.RS +.TP +.I localchars +.br +If this is +TRUE, +then the +.IR flush , +.IR interrupt , +.IR quit , +.IR erase , +and +.I kill +characters (see +.B set +above) are recognized locally, and transformed into (hopefully) appropriate +.B TELNET +control sequences +(respectively +.IR ao , +.IR ip , +.IR brk , +.IR ec , +and +.IR el ; +see +.B send +above). +The initial value for this toggle is TRUE in \*(lqline by line\*(rq mode, +and FALSE in \*(lqcharacter at a time\*(rq mode. +.TP +.I autoflush +.br +If +.I autoflush +and +.I localchars +are both +TRUE, +then when the +.IR ao , +.IR intr , +or +.I quit +characters are recognized (and transformed into +.B TELNET +sequences; see +.B set +above for details), +.I telnet +refuses to display any data on the user's terminal +until the remote system acknowledges (via a +.B TELNET +.I Timing Mark +option) +that it has processed those +.B TELNET +sequences. +The initial value for this toggle is TRUE if the terminal user had not +done an "stty noflsh", otherwise FALSE (see +.IR stty(1)). +.TP +.I autosynch +If +.I autosynch +and +.I localchars +are both +TRUE, +then when either the +.I intr +or +.I quit +characters is typed (see +.B set +above for descriptions of the +.I intr +and +.I quit +characters), the resulting +.B TELNET +sequence sent is followed by the +.B TELNET SYNCH +sequence. +This procedure +.B should +cause the remote system to begin throwing away all previously +typed input until both of the +.B TELNET +sequences have been read and acted upon. +The initial value of this toggle is FALSE. +.TP +.I crmod +.br +Toggle carriage return mode. +When this mode is enabled, most carriage return characters received from +the remote host will be mapped into a carriage return followed by +a line feed. +This mode does not affect those characters typed by the user, only +those received from the remote host. +This mode is not very useful unless the remote host +only sends carriage return, but never line feed. +The initial value for this toggle is FALSE. +.TP +.I debug +.br +Toggles socket level debugging (useful only to the +.IR super user ). +The initial value for this toggle is FALSE. +.TP +.I options +.br +Toggles the display of some internal +.I telnet +protocol processing (having to do with +.B TELNET +options). +The initial value for this toggle is FALSE. +.TP +.I netdata +.br +Toggles the display of all network data (in hexadecimal format). +The initial value for this toggle is FALSE. +.TP +.I ? +.br +Displays the legal +.B toggle +commands. +.RE +.SH BUGS +.PP +There is no adequate way for dealing with flow control. +.PP +On some remote systems, echo has to be turned off manually when in +\*(lqline by line\*(rq mode. +.PP +There is enough settable state to justify a +.RI . telnetrc +file. +.PP +No capability for a +.RI . telnetrc +file is provided. +.PP +In \*(lqline by line\*(rq mode, the terminal's +.I eof +character is only recognized (and sent to the remote system) +when it is the first character on a line. diff --git a/man/man1/template.1 b/man/man1/template.1 new file mode 100644 index 000000000..23ac5da09 --- /dev/null +++ b/man/man1/template.1 @@ -0,0 +1,46 @@ +.TH TEMPLATE 1 +.SH NAME +template, blueprint \- a blueprint for making manual pages +.SH SYNOPSIS +.B template +.RB [ \-az ] +.RI [ arguments " ...]" +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Template +shows what a manual page should look like. Options for instance: +.SH OPTIONS +.TP +.B \-a +Use boldface for characters that have to be typed as is. +.TP +.B \-z +Italics for variable +.IR arguments . +.SH ENVIRONMENT +.TP 15n +.B MANPATH +The path to knowledge. +.SH FILES +.TP 25n +.B /usr/man/template.1 +This file. +.SH "SEE ALSO" +.BR man (7). +.SH DIAGNOSTICS +man: No manual on template. +.SH NOTES +Use at your own risk. +.SH BUGS +A lot. The +.BR whatis (5) +database is usually generated automatically on most +systems. This fails if the "NAME" section has more n/troff fluff than just +an "\e" before the '\-', or is more than one line. Apply the KISS +principle, try to use a minimum of smart macros, match your .RS and .RE's, +etc. +.SH AUTHOR +Kees J. Bot diff --git a/man/man1/term.1 b/man/man1/term.1 new file mode 100644 index 000000000..4f69be683 --- /dev/null +++ b/man/man1/term.1 @@ -0,0 +1,70 @@ +.TH TERM 1 +.SH NAME +term \- turn PC into a dumb terminal [IBM] +.SH SYNOPSIS +.in +.5i +.ti -.5i +\fBterm\fR [\fIbaudrate\fR]\fR [\fIparity\fR] [\fIbits_per_character\fR] +[\fB\-\fIdial_string\fR] [\fB\-c\fIkcmd\fR] [\fIdevice\fR]\fR +.in -.5i +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "term 2400" "Talk to modem at 2400 baud" +.EX "term 1200 7 even" "1200 baud, 7 bits/char, even parity" +.EX "term 8 9600 /dev/tty01" "9600 baud, 8 bits/char, no parity, use tty01" +.EX "term -atdt12345 /dev/tty01" "Start with a command to dial out" +.EX "term -cH'echo Hello World!' ..." "Bind a shell command to the 'H' key" +.SH DESCRIPTION +.PP +\fITerm\fR allows +\s-2MINIX\s+2 +to talk to a terminal or modem over RS232 +port 1. The program first sets the baudrate, parity and character length, +and then forks. +The parent sits in a loop copying from \fIstdin\fR (usually the console's +keyboard), to the terminal or modem (\fI/dev/tty00\fR). +The child sits in a loop +copying from the terminal or modem (\fI/dev/tty00\fR) to standard output. +Thus when +RS232 port 1 is connected to a modem, every keystroke typed on the keyboard +is sent to the modem, and every character arriving from the modem is displayed. +Standard input and output may be redirected, to provide a primitive file +transfer program, with no checking. Any argument that starts with +.B \-at +is sent out to the modem, usually to dial out. \fITerm\fP accepts +several commands that are formed by typing the escape character, CTRL-], +and a letter. Type CTRL-]? to see a list of commands. The subshell command +is very important, it allows you to type in a ZMODEM command to transfer +data. Do not quit \fIterm\fR to do this, or your modem line will be reset! +\fITerm\fP keeps the modem line open on file descriptor 9 while running the +subshell, so you can type +.PP +.in +.5i +<&9 >&9 +.in -.5i +.PP +at the end of your ZMODEM command to connect it to the modem. With +.BI \-c kcmd +arguments you can bind shell commands to keys. The character just after +.BR \-c +is the key to use, the rest of the characters form the command to bind to the +key. This command also has the modem open on file descriptor 9. +.LP +Important note: to use \fIterm\fR, it is essential that +\fI/etc/ttytab\fR is configured so +that there is no login session started on the modem line. +If there is, both the login session and +term will try to read from the modem, and nothing will work. +.SH "SEE ALSO" +.BR rz (1), +.BR sz (1). diff --git a/man/man1/termcap.1 b/man/man1/termcap.1 new file mode 100644 index 000000000..cec4c98e8 --- /dev/null +++ b/man/man1/termcap.1 @@ -0,0 +1,26 @@ +.TH TERMCAP 1 +.SH NAME +termcap \- print the current termcap entry +.SH SYNOPSIS +\fBtermcap\fR [\fItype\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "termcap" "Print the termcap entry" +.SH DESCRIPTION +.PP +\fITermcap\fR reads the /etc/termcap entry corresponding to the +terminal type +supplied as the argument. If none is given, the current $TERM is used. +It then prints out all the parameters that apply. +.SH "SEE ALSO" +.BR termcap (3). diff --git a/man/man1/tget.1 b/man/man1/tget.1 new file mode 100644 index 000000000..f70c97b83 --- /dev/null +++ b/man/man1/tget.1 @@ -0,0 +1,68 @@ +.TH TGET 1 +.SH NAME +tget \- get termcap values +.SH SYNOPSIS +.B tget +.RB [ \-flag +.IR id ] +.RB [ \-num +.IR id ] +.RB [ \-str +.IR id ] +.RB [ \-goto +.IR "col line" ] +.RB [[ \-echo ] +.IR string ] +.SH DESCRIPTION +.B Tget +allows shell scripts access to the +.BR termcap (3) +functions. Flags, numbers and strings can be queried from the termcap +database under the entry denoted by the environment variable +.BR $TERM . +.SH OPTIONS +.TP +.BI \-flag " id" +Set the exit status to zero if the flag +.I id +is set. All other options except +.B \-echo +set the exit status to +.I id +being available or not. The last option sets the final exit code. +.TP +.BI \-num " id" +Print the value of the numeric variable +.IR id . +.TP +.BI \-str " id" +Print the value of the string variable +.IR id . +.TP +.BI \-goto " col line" +Generates instructions to go to the given column and line if the +.B cm +capability exists. +.TP +.BI \-echo " string" +Prints +.IR string . +Any other argument that does not start with a dash is also printed. +.SH EXAMPLE +Try this: +.B "tget -str so 'Reverse Video' -str se" +.SH ENVIRONMENT +.TP 15n +.B TERM +Terminal type. +.TP +.B TERMCAP +Path to the termcap database, by default /etc/termcap:/usr/etc/termcap. +.SH "SEE ALSO" +.BR termcap (3). +.SH DIAGNOSTICS +.B Tget +will fail immediately with a descriptive message if the termcap entry +can't be found. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/time.1 b/man/man1/time.1 new file mode 100644 index 000000000..db0c42623 --- /dev/null +++ b/man/man1/time.1 @@ -0,0 +1,26 @@ +.TH TIME 1 +.SH NAME +time \- report how long a command takes +.SH SYNOPSIS +\fBtime \fIcommand\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "time a.out" "Report how long \fIa.out\fR takes" +.EX "time ls \-l *.c" "Report how long \fIls\fR takes" +.SH DESCRIPTION +.PP +The command is executed and the real time, user time, and system time (in +hours, minutes, and seconds) are printed. +Shell scripts cannot be timed. +.SH "SEE ALSO" +.BR times (2). diff --git a/man/man1/touch.1 b/man/man1/touch.1 new file mode 100644 index 000000000..36d40905f --- /dev/null +++ b/man/man1/touch.1 @@ -0,0 +1,31 @@ +.TH TOUCH 1 +.SH NAME +touch \- update a file's time of last modification +.SH SYNOPSIS +\fBtouch\fR [\fB\-c\fR] \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Do not create the file" +.SH EXAMPLES +.EX "touch *.h" "Make the \fI.h\fP files look recent" +.SH DESCRIPTION +############ NEXT ENTRY HAS NOT BEEN CHECKED ############# +.PP +The time of last modification is set to the current time. +This command is mostly used to trick +.I make +into thinking that a file is more recent than it really is. +If the file being touched does not exist, it is created, unless the \fB\-c\fR +flag is present. +.SH "SEE ALSO" +.BR utime (2). diff --git a/man/man1/tr.1 b/man/man1/tr.1 new file mode 100644 index 000000000..ffff98b1a --- /dev/null +++ b/man/man1/tr.1 @@ -0,0 +1,47 @@ +.TH TR 1 +.SH NAME +tr \- translate character codes +.SH SYNOPSIS +\fBtr\fR [\fB\-cds\fR]\fR [\fIstring1\fR] [\fIstring2\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Complement the set of characters in \fIstring1\fR" +.FL "\-d" "Delete all characters specified in \fIstring1\fR" +.FL "\-s" "Squeeze all runs of characters in \fIstring1\fR to one character" +.SH EXAMPLES +.EX "tr \(fmA\-Z\(fm \(fma\-z\(fm y " "Convert upper case to lower case" +.EX "tr \-d \(fm0123456789\(fm f2 " "Delete all digits from \fIf1\fR" +.SH DESCRIPTION +.PP +.I Tr +performs simple character translation. +When no flag is specified, each character in +.I string1 +is mapped onto the corresponding character in +.I string2 . +.PP +There are two types of +.I tr +out there, one that requires [ and ] for character classes, and one that does +not. Here is what the example above would look like for a +.I tr +that needs the brackets: +.PP +.RS +.B "tr \(fm[A\-Z]\(fm \(fm[a\-z]\(fm y" +.RE +.PP +Use [ and ] if you want to be portable, because a +.I tr +that doesn't need them will still accept the syntax and mindlessly +translate [ into [ and ] into ]. diff --git a/man/man1/true.1 b/man/man1/true.1 new file mode 100644 index 000000000..ab4b835af --- /dev/null +++ b/man/man1/true.1 @@ -0,0 +1,24 @@ +.TH TRUE 1 +.SH NAME +true, false \- exit with the value true or false +.SH SYNOPSIS +\fBtrue\fR +.br +\fBfalse\fR +.SH EXAMPLES +.ta +20n +.ft B +.nf +while true \fR# List the directory until DEL is hit\fP +do ls \-l +done +.fi +.ft P +.SH DESCRIPTION +These commands return the value +.I true +or +.I false . +They are used for shell programming. +.SH "SEE ALSO" +.BR sh (1). diff --git a/man/man1/tsort.1 b/man/man1/tsort.1 new file mode 100644 index 000000000..193174e41 --- /dev/null +++ b/man/man1/tsort.1 @@ -0,0 +1,23 @@ +.TH TSORT 1 +.SH NAME +tsort \- topological sort [IBM] +.SH SYNOPSIS +\fBtsort \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "lorder *.s | tsort" "Give library ordering" +.EX "ar cr libc.a \`lorder *.s | tsort\`" "Build library" +.SH DESCRIPTION +.PP +\fITsort\fR accepts a file of lines containing ordered pairs and builds a +total ordering from the partial orderings. diff --git a/man/man1/tty.1 b/man/man1/tty.1 new file mode 100644 index 000000000..71b455f34 --- /dev/null +++ b/man/man1/tty.1 @@ -0,0 +1,26 @@ +.TH TTY 1 +.SH NAME +tty \- print the device name of this tty +.SH SYNOPSIS +\fBtty \fR[\fB\-s\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-s" "Silent mode, only the exit status is affected." +.SH EXAMPLES +.EX "tty " "Print the tty name" +.SH DESCRIPTION +.PP +Print the name of the controlling tty. If the flag \fB\-s\fR is given, +\fItty\fR is equivalent to the call \fBtest \-t 0\fR. +.SH "SEE ALSO" +.BR ttyname (3). diff --git a/man/man1/umount.1 b/man/man1/umount.1 new file mode 100644 index 000000000..2900d092e --- /dev/null +++ b/man/man1/umount.1 @@ -0,0 +1,35 @@ +.TH UMOUNT 1 +.SH NAME +umount \- unmount a mounted file system +.SH SYNOPSIS +\fBumount \fR[\fB\-s\fR] \fIspecial\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-s" "Unmount swapspace instead of a file system" +.SH EXAMPLES +.EX "umount /dev/fd1" "Unmount diskette 1" +.SH DESCRIPTION +.PP +A mounted file system is unmounted after the cache has been flushed to disk. +A diskette should never be removed while it is mounted. +If this happens, and is discovered before another diskette is inserted, the +original one can be replaced without harm. +Attempts to unmount a file system holding working directories or open files +will be rejected with a \&'device busy\&' message. +.PP +With the +.B \-s +flag one can unmount swap space. +.SH "SEE ALSO" +.BR mount (1), +.BR umount (2). diff --git a/man/man1/uname.1 b/man/man1/uname.1 new file mode 100644 index 000000000..748f83561 --- /dev/null +++ b/man/man1/uname.1 @@ -0,0 +1,41 @@ +.TH UNAME 1 +.SH NAME +uname, arch \- system info +.SH SYNOPSIS +\fBuname\fR [\fB\-snrvmpa\fR]\fR +.br +\fBarch\fR [\fB\-snrvmpa\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-s" "System name" +.FL "\-n" "Node/network name" +.FL "\-r" "Operating system release" +.FL "\-v" "Operating system version" +.FL "\-m" "Machine type" +.FL "\-p" "Processor family" +.FL "\-a" "Short for \fB\-snrvm\fR" +.SH EXAMPLES +.EX "uname -n" "Print the name of the system" +.EX "arch" "Print the name of the system architecture" +.SH DESCRIPTION +.PP +\fIUname\fP and \fIarch\fP give information about the system. The options +indicate which information strings must be printed. These strings are always +in the same order. \fIUname\fP and \fIarch\fP only differ w.r.t. the default +string to print, \fB\-s\fP and \fB\-p\fP respectively. +.PP +The strings are compiled into the commands except for the node name, it is +obtained from the file \fI/etc/hostname.file\fP. \fBUname \-m\fP should +return the actual machine type, not the same string as with \fB\-p\fP. +.SH "SEE ALSO" +.BR uname (3). diff --git a/man/man1/unexpand.1 b/man/man1/unexpand.1 new file mode 100644 index 000000000..9a7a596f7 --- /dev/null +++ b/man/man1/unexpand.1 @@ -0,0 +1,28 @@ +.TH UNEXPAND 1 +.SH NAME +unexpand \- convert spaces to tabs +.SH SYNOPSIS +\fBunexpand\fR [\fB\-a\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-a" "All spaces are unexpanded" +.SH EXAMPLES +.EX "unexpand oldfile >newfile" "Convert leading spaces to tabs" +.SH DESCRIPTION +.PP +\fIUnexpand\fR replaces spaces in the named files with tabs. +If no files are listed, \fIstdin\fR is given. +The \fB\-a\fR flag is used to force all sequences of spaces to be +expanded, instead of just leading spaces (the default). +.SH "SEE ALSO" +.BR expand (1). diff --git a/man/man1/uniq.1 b/man/man1/uniq.1 new file mode 100644 index 000000000..6ac015a34 --- /dev/null +++ b/man/man1/uniq.1 @@ -0,0 +1,36 @@ +.TH UNIQ 1 +.SH NAME +uniq \- delete consecutive identical lines in a file +.SH SYNOPSIS +\fBuniq\fR [\fB\-cdu\fR]\fR [\fB\-\fIn\fR] [\fB+\fIn\fR] [\fIinput [\fIoutput\fR]\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Give count of identical lines in the input" +.FL "\-d" "Only duplicate lines are written to output" +.FL "\-u" "Only unique lines are written to output" +.FL "\-\fIn\fR" "Skip the first \fIn\fR columns when matching" +.FL "+\fIn\fR" "Skip the first \fIn\fR fields when matching" +.SH EXAMPLES +.EX "uniq +2 file" "Ignore first 2 fields when comparing" +.EX "uniq \-d inf outf" "Write duplicate lines to \fIoutf\fP" +.SH DESCRIPTION +.PP +.I Uniq +examines a file for consecutive lines that are identical. +All but duplicate entries are deleted, and the file is written to output. +The +\fIn\fR option skips the first \fIn\fR fields, where a field is defined +as a run of characters separated by white space. +The \-\fIn\fP option skips the first \fIn\fR spaces. +Fields are skipped first. +.SH "SEE ALSO" +.BR sort (1). diff --git a/man/man1/uud.1 b/man/man1/uud.1 new file mode 100644 index 000000000..c885dadc7 --- /dev/null +++ b/man/man1/uud.1 @@ -0,0 +1,33 @@ +.TH UUD 1 +.SH NAME +uud, uudecode \- decode a binary file encoded with uue +.SH SYNOPSIS +\fBuud\fR [\fB\-n\fR]\fR [\fB\-s \fIsrcdir\fR] [\fB\-t \fIdstdir/\fR] \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-n" "Do not verify checksums" +.FL "\-s" "Name of directory where \fI.uue\fR file is" +.FL "\-t" "Name of directory where output goes" +.SH EXAMPLES +.EX "uud file.uue " "Re-create the original file" +.EX "uud \- x" "Encode \fIfile\fR and write on \fIstdout\fR" +.EX "uue \-800 file" "Output on \fIfile.uaa\fR, \fIfile.uab\fR etc." +.SH DESCRIPTION +.PP +\fIUuencode\fR is a famous program that converts an arbitrary (usually binary) +file to an encoding using only 64 ASCII characters. +\fIUudecode\fR converts it back to the original file. +The \fIuue\fR and \fIuud\fR programs are the +\s-2MINIX\s+2 +versions of these programs, and are compatible with the \s-2UNIX\s0 ones. +The files produced can even be sent successfully over BITNET, which is +notorious for mangling files. +It is possible to have \fIuue\fR automatically split the encoded file up +into small chunks. +The output files then get the suffixes \fI.uaa\fR, \fI.uab\fR, etc., instead +of \fI.uue\fR. +When \fIuud\fR is given \fIfile.uaa\fR to decode, it automatically includes +the subsequent pieces. +The encoding takes 3 bytes (24 bits) from the input file and renders it +as 4 bytes in the output file. +.SH "SEE ALSO" +.BR btoa (1), +.BR uud (1). diff --git a/man/man1/vol.1 b/man/man1/vol.1 new file mode 100644 index 000000000..484a09a88 --- /dev/null +++ b/man/man1/vol.1 @@ -0,0 +1,125 @@ +.TH VOL 1 +.SH NAME +vol \- split input on or combine output from several volumes +.SH SYNOPSIS +.B vol +.RB [ \-rw1 ] +.RB [ \-b +.IR blocksize ] +.RB [ \-m +.IR multiple ] +.RI [ size ] +.I device +.SH DESCRIPTION +.B Vol +either reads a large input stream from standard input and distributes it +over several volumes or combines volumes and sends them to +standard output. The size of the volumes is determined automatically if +the device supports this, but may be specified before the +argument naming the device if automated detection is not possible or if +only part of the physical volume is used. The direction of the data is +automatically determined by checking whether the input or output of +.B vol +is a file or pipe. Use the +.B \-r +or +.B \-w +flag if you want to specify the direction explicitly, in shell scripts +for instance. +.PP +.B Vol +waits for each new volume to be inserted, typing return makes it continue. +If no size is explicitely given then the size of the device is determined +each time before it is read or written, so it is possible to mix floppies +of different sizes. If the size cannot be determined (probably a tape) then +the device is assumed to be infinitely big. +.B Vol +can be used both for block or character devices. It will buffer the data +and use a block size appropriate for fixed or variable block sized tapes. +.PP +.B Vol +reads or writes 8192 bytes to block devices, usually floppies. Character +devices are read or written using a multiple of 512 bytes. This multiple +has an upper limit of 32767 bytes (16-bit machine), 64 kb (32-bit), or even +1 Mb (32-bit VM). The last partial write to a character device is padded +with zeros to the block size. If a character device is a tape device that +responds to the +.BR mtio (4) +status call then the reported tape block size will be used as the smallest +unit. If the tape is a variable block length device then it is read or +written like a block device, 8192 bytes at the time, with a minimum unit +of one byte. +.PP +All sizes may be suffixed by the letters +.BR M , +.BR k , +.BR b +or +.BR w +to multiply the number by mega, kilo, block (512), or word (2). The volume +size by default in kilobytes if there is no suffix. +.SH OPTIONS +.TP +.B \-rw +Explicitly specify reading or writing. Almost mandatory in scripts. +.TP +.B \-1 +Just one volume, start immediately. +.TP +.BI \-b " blocksize" +Specify the device block size. +.TP +.BI \-m " multiple" +Specify the maximum read or write size of multiple blocks. The +.B \-b +and +.B \-m +options allow one to modify the block size assumptions that are made above. +These assumptions are +.B "\-b 1 \-m 8192" +for block devices or variable length tapes, and +.B "\-b 512 \-m 65536" +for character devices (32 bit machine.) These options will not override the +tape block size found out with an +.BR mtio (4) +call. The multiple may be larger then the default if +.B vol +can allocate the memory required. +.SH EXAMPLES +To back up a tree to floppies as a compressed tarfile: +.PP +.RS +tar cf \- . | compress | vol /dev/fd0 +.RE +.PP +To restore a tree from 720 kb images from possibly bigger floppies: +.PP +.RS +vol 720 /dev/fd0 | uncompress | tar xfp \- +.RE +.PP +Read or write a device with 1024 byte blocks: +.PP +.RS +vol \-b 1k /dev/rsd15 +.RE +.PP +Read or write a variable block length tape using blocking factor 20 as used +by default by many +.BR tar (1) +commands: +.PP +.RS +vol \-m 20b /dev/rst5 +.RE +.PP +Note that +.B \-m +was used in the last example. It sets the size to use to read or write, +.B \-b +sets the basic block size that may be written in multiples. +.SH "SEE ALSO" +.BR dd (1), +.BR tar (1), +.BR mt (1), +.BR mtio (4). diff --git a/man/man1/wc.1 b/man/man1/wc.1 new file mode 100644 index 000000000..fb77f480a --- /dev/null +++ b/man/man1/wc.1 @@ -0,0 +1,30 @@ +.TH WC 1 +.SH NAME +wc \- count characters, words, and lines in a file +.SH SYNOPSIS +\fBwc\fR [\fB\-clw\fR] \fIfile\fR ...\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Print character count" +.FL "\-l" "Print line count" +.FL "\-w" "Print word count" +.SH EXAMPLES +.EX "wc file1 file2" "Print all three counts for both files" +.EX "wc \-l file" "Print line count only" +.SH DESCRIPTION +.PP +.I Wc +reads each argument and computes the number of characters, words and lines +it contains. +A word is delimited by white space (space, tab, or line feed). +If no flags are present, all three counts are printed. diff --git a/man/man1/whatis.1 b/man/man1/whatis.1 new file mode 100644 index 000000000..2a25238c9 --- /dev/null +++ b/man/man1/whatis.1 @@ -0,0 +1,32 @@ +.TH WHATIS 1 +.SH NAME +whatis, apropos \- give single line descriptions for manual pages +.SH SYNOPSIS +.B whatis +.RB [ \-a ] +.I title +.br +.B apropos +.I keyword +.SH DESCRIPTION +.B Whatis +lists the one line description from the +.BR whatis (5) +database describing the title given. It displays all the lines with +the title from the first whatis file that has those titles. It uses the +same search path as +.BR man (1). +.PP +.B Apropos +searches through all whatis files for the given keywords. It lists any +line that has the keyword anywhere on the line. +.SH OPTIONS +.TP +.B \-a +Search all whatis files. +.SH "SEE ALSO" +.BR man (1), +.BR grep (1), +.BR whatis (5). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man1/whereis.1 b/man/man1/whereis.1 new file mode 100644 index 000000000..0e72614b1 --- /dev/null +++ b/man/man1/whereis.1 @@ -0,0 +1,26 @@ +.TH WHEREIS 1 +.SH NAME +whereis \- examine system directories for a given file +.SH SYNOPSIS +\fBwhereis \fIfile\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "whereis stat.h" "Prints: \fI/usr/include/sys/stat.h\fR" +.SH DESCRIPTION +.PP +\fIWhereis\fR searches a fixed set of system +directories, \fI/bin\fR, \fI/lib\fR, \fI/usr/bin\fR, +and others, and prints all occurrences of the argument name in any of them. +.SH "SEE ALSO" +.BR man (1), +.BR which (1). diff --git a/man/man1/which.1 b/man/man1/which.1 new file mode 100644 index 000000000..de6b837d3 --- /dev/null +++ b/man/man1/which.1 @@ -0,0 +1,32 @@ +.TH WHICH 1 +.SH NAME +which \- examine $PATH to see which file will be executed +.SH SYNOPSIS +\fBwhich \fIname\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "which a.out" "Tells which \fIa.out\fR will be executed" +.SH DESCRIPTION +.PP +The $PATH shell variable controls the +\s-2MINIX\s+2 +search rules. +If a command \fIa.out\fR is given, the shell first tries to find an +executable file in the working directory. +If that fails, it looks in various system directories, such as +\fI/bin\fR and \fI/usr/bin\fR. +The\fR which\fR command makes the same search and gives the absolute +path of the program that will be chosen, followed by other occurrences +of the file name along the path. +.SH "SEE ALSO" +.BR man (1). diff --git a/man/man1/who.1 b/man/man1/who.1 new file mode 100644 index 000000000..26fb6c32c --- /dev/null +++ b/man/man1/who.1 @@ -0,0 +1,31 @@ +.TH WHO 1 +.SH NAME +who \- print list of currently logged in users +.SH SYNOPSIS +\fBwho\fR [\fIfile\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "who " "Print user names, terminals and times" +.SH DESCRIPTION +.PP +\fIWho\fR prints a list of currently logged in users. For each one, +the user name, terminal, and login time is printed. +This program gets its information from the file \fI/etc/utmp\fR, which +is updated by init and login. +If the file does not exist, neither of these will create it, and +\fIwho\fR will not work. Note that if you decide to create an empty +\fI/usr/adm/wtmp\fR to enable the login accounting, it will grow forever and +eventually fill up your disk unless you manually truncate it from time to time. +If an optional file name is provided, the logins in that file will be printed. +.SH "SEE ALSO" +.BR utmp (5). diff --git a/man/man1/whoami.1 b/man/man1/whoami.1 new file mode 100644 index 000000000..5c86fc687 --- /dev/null +++ b/man/man1/whoami.1 @@ -0,0 +1,26 @@ +.TH WHOAMI 1 +.SH NAME +whoami \- print current user name +.SH SYNOPSIS +\fBwhoami\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "whoami" "Print user name" +.SH DESCRIPTION +.PP +In case you forget who you are logged in as, \fIwhoami\fR will tell you. If +you use \fIsu\fR to become somebody else, +\fIwhoami\fR will give the current effective user. +.SH "SEE ALSO" +.BR id (1), +.BR who (1). diff --git a/man/man1/write.1 b/man/man1/write.1 new file mode 100644 index 000000000..7bf2aeb5d --- /dev/null +++ b/man/man1/write.1 @@ -0,0 +1,33 @@ +.TH WRITE 1 +.SH NAME +write \- send a message to a logged-in user +.SH SYNOPSIS +\fBwrite\fR [\fB\-cv\fR] \fIuser\fR [\fItty\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH OPTIONS +.FL "\-c" "Use cbreak mode" +.FL "\-v" "Verbose mode" +.SH EXAMPLES +.EX "write ast" "Send a message to ast" +.EX "write ast tty00" "Send a message to ast on tty00" +.SH DESCRIPTION +.PP +\fIWrite\fR lets a user send messages to another logged-in user. +Lines typed by the user appear on the other user's screen a line at a time +(a character at a time in the case of cbreak mode). +The file \fI/usr/adm/wtmp\fR is searched to determine which tty to send to. +If the user is logged onto more than one terminal, the \fItty\fR argument +selects the terminal. Type CTRL- D to terminate the command. +Use ! as a shell escape. +.SH "SEE ALSO" +.BR mail (1). diff --git a/man/man1/xargs.1 b/man/man1/xargs.1 new file mode 100644 index 000000000..f5ca5bcd1 --- /dev/null +++ b/man/man1/xargs.1 @@ -0,0 +1,176 @@ +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" John B. Roll Jr. and the Institute of Electrical and Electronics +.\" Engineers, Inc. +.\" +.\" 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. +.\" +.\" @(#)xargs.1 5.5 (Berkeley) 6/27/91 +.\" +.TH XARGS 1 "June 27, 1991" +.UC 7 +.SH NAME +xargs \- construct argument list(s) and execute utility. +.SH SYNOPSIS +.B xargs +.RB [ \-ft0 ] +.RB [[ \-x ] +.B \-n +.IR number ] +.RB [ \-s +.IR size ] +.RI [ utility +.RI [ argument " ...]]" +.SH DESCRIPTION +The +.B xargs +utility reads space, tab, newline and end-of-file delimited arguments +from the standard input and executes the specified +.I utility +with them as arguments. +.PP +The utility and any arguments specified on the command line are given +to the +.I utility +upon each invocation, followed by some number of the arguments read +from standard input. +The +.I utility +is repeatedly executed until standard input is exhausted. +.PP +Spaces, tabs and newlines may be embedded in arguments using single (`` ' '') +or double (``"'') quotes or backslashes (``\e''). +Single quotes escape all non-single quote characters, excluding newlines, +up to the matching single quote. +Double quotes escape all non-double quote characters, excluding newlines, +up to the matching double quote. +Any single character, including newlines, may be escaped by a backslash. +.PP +The options are as follows: +.TP +.B \-f +Force +.B xargs +to ignore the exit status returned by +.IR utility . +By default, +.B xargs +will exit immediately if +.I utility +exits with a non-zero exit status. +This does not include ignoring +.I utility +exiting due to a signal or without calling +.BR exit (2). +.TP +.BI \-n " number" +Set the maximum number of arguments taken from standard input for each +invocation of the utility. +An invocation of +.I utility +will use less than +.I number +standard input arguments if the number of bytes accumulated (see the +.I \-s +option) exceeds the specified +.I size +or there are fewer than +.I number +arguments remaining for the last invocation of +.IR utility . +The current default value for +.I number +is 5000. +.TP +.BI \-s " size" +Set the maximum number of bytes for the command line length provided to +.IR utility . +The sum of the length of the utility name and the arguments passed to +.I utility +(including NULL terminators) will be less than or equal to this number. +The current default value for +.I size +is ARG_MAX - 2048. +.TP +.B \-t +Echo the command to be executed to standard error immediately before it +is executed. +.TP +.B \-x +Force +.B xargs +to terminate immediately if a command line containing +.I number +arguments will not fit in the specified (or default) command line length. +.TP +.B \-0 +Read null-byte terminated pathnames from standard input as may have been +produced by the +.B \-print0 +option of +.BR find (1). +This is a Minix specific extension to +.BR xargs . +.PP +If no +.I utility +is specified, +.BR echo (1) +is used. +.PP +Undefined behavior may occur if +.I utility +reads from the standard input. +.PP +.B Xargs +exits with an exit status of 0 if no error occurs. +If +.I utility +cannot be invoked, is terminated by a signal or terminates without +calling +.BR exit (2), +.B xargs +exits with an exit status of 127. +If +.I utility +exits with an exit status other than 0, +.B xargs +exits with that exit status. +Otherwise, +.B xargs +exits with an exit status of 1. +.SH "SEE ALSO" +.BR echo (1), +.BR find (1). +.SH STANDARDS +The +.B xargs +utility is expected to be POSIX 1003.2 compliant. diff --git a/man/man1/yacc.1 b/man/man1/yacc.1 new file mode 100644 index 000000000..ad3003ab6 --- /dev/null +++ b/man/man1/yacc.1 @@ -0,0 +1,111 @@ +.\" %W% %R% (Berkeley) %E% +.\" +.TH YACC 1 "July 15, 1990" +.UC 6 +.SH NAME +yacc \- an LALR(1) parser generator +.SH SYNOPSIS +.B yacc [ -dlrtv ] [ -b +.I file_prefix +.B ] [ -p +.I symbol_prefix +.B ] +.I filename +.SH DESCRIPTION +.I Yacc +reads the grammar specification in the file +.I filename +and generates an LR(1) parser for it. +The parsers consist of a set of LALR(1) parsing tables and a driver routine +written in the C programming language. +.I Yacc +normally writes the parse tables and the driver routine to the file +.IR y.tab.c. +.PP +The following options are available: +.RS +.TP +\fB-b \fIfile_prefix\fR +The +.B -b +option changes the prefix prepended to the output file names to +the string denoted by +.IR file_prefix. +The default prefix is the character +.IR y. +.TP +.B -d +The \fB-d\fR option causes the header file +.IR y.tab.h +to be written. +.TP +.B -l +If the +.B -l +option is not specified, +.I yacc +will insert #line directives in the generated code. +The #line directives let the C compiler relate errors in the +generated code to the user's original code. +If the \fB-l\fR option is specified, +.I yacc +will not insert the #line directives. +\&#line directives specified by the user will be retained. +.TP +\fB-p \fIsymbol_prefix\fR +The +.B -p +option changes the prefix prepended to yacc-generated symbols to +the string denoted by +.IR symbol_prefix. +The default prefix is the string +.IR yy. +.TP +.B -r +The +.B -r +option causes +.I yacc +to produce separate files for code and tables. The code file +is named +.IR y.code.c, +and the tables file is named +.IR y.tab.c. +.TP +.B -t +The +.B -t +option changes the preprocessor directives generated by +.I yacc +so that debugging statements will be incorporated in the compiled code. +.TP +.B -v +The +.B -v +option causes a human-readable description of the generated parser to +be written to the file +.IR y.output. +.RE +.PP +If the environment variable TMPDIR is set, the string denoted by +TMPDIR will be used as the name of the directory where the temporary +files are created. +.SH FILES +.IR y.code.c +.br +.IR y.tab.c +.br +.IR y.tab.h +.br +.IR y.output +.br +.IR /tmp/yacc.aXXXXXX +.br +.IR /tmp/yacc.tXXXXXX +.br +.IR /tmp/yacc.uXXXXXX +.SH DIAGNOSTICS +If there are rules that are never reduced, the number of such rules is +reported on standard error. +If there are any LALR(1) conflicts, the number of conflicts is reported +on standard error. diff --git a/man/man1/yap.1 b/man/man1/yap.1 new file mode 100644 index 000000000..eb3e11536 --- /dev/null +++ b/man/man1/yap.1 @@ -0,0 +1,391 @@ +.\" $Header$ +.\" nroff -man yap.1 +.tr ~ +.TH YAP 1 local +.SH NAME +yap, more \- yet another pager +.SH SYNOPSIS +.B yap +.RB [ \-cnuq ] +.RB [ \-\fIn\fP ] +.RB [ +\fIcommand\fP ] +.RI [ file " ...]" +.SH DESCRIPTION +.B Yap +is a program allowing the user to examine a continuous text one screenful at +a time on a video display terminal. +It does so by +pausing after each screenful, waiting for the user to type a command. +The commands are enumerated later. +.BR Yap 's +main feature is, that it can page both forwards and backwards, +even when reading from standard input. +.PP +The command line options are: +.TP +.I \-n +An integer which is the size (in lines) of a page (the initial +.IR page-size . +.TP +.B \-c +Normally, +.B yap +will display each page by beginning at the top of the screen and erasing +each line just before it displays on it. If your terminal cannot erase a line, +.B yap +will clear the screen before it displays a page. +.br +This avoids scrolling the screen, making it easier to read while +.B yap +is writing. +The +.B -c +option causes +.B yap +to scroll the screen instead of beginning at the top of the screen. +This is also done if your terminal cannot either erase a line or clear the +screen. +.TP +.B \-u +Normally, +.B yap +handles underlining such as produced by nroff in a manner appropriate +to the particular terminal: if the terminal can perform underlining well +(t.i., the escape sequences for underlining do not occupy space on the +screen), +.B yap +will underline underlined information in the input. The +.B -u +option supresses this underlining. +.TP +.B \-n +Normally, +.B yap +also recognises escape sequences for stand-out mode or underlining mode +in the input, and knows how much space these escape sequences will +occupy on the screen, so that +.B yap +will not fold lines erroneously. +The +.B -n +option supresses this pattern matching. +.TP +.B \-q +This option will cause +.B yap +to exit only on the "quit" command. +.TP +.BI + command +\fIcommand\fP is taken to be an initial command to +.BR yap . +.PP +.B Yap +looks in the +.B YAP +environment variable +to pre-set flags. +For instance, if you prefer the +.B -c +mode of operation, just set the +.B YAP +environment variable to +.BR -c . +.PP +The commands of +.B yap +can be bound to sequences of keystrokes. +The environment variable +.B YAPKEYS +may contain the bindings in the +form of a list of colon-separated `name=sequence' pairs. +The +.I name +is a short mnemonic for the command, the +.I sequence +is the sequence of keystrokes to be typed to invoke the command. +This sequence may contain a ^X escape, which means control-X, +and a \\X escape, which means X. The latter can be used to get +the characters `^', `\\' and `:' in the sequence. +There are two keymaps available, the default one and a user-defined one. +You can switch between one and the other with the +.I change keymap +command. +.PP +The +.B yap +commands are described below. +The mnemonics for the commands are given in parentheses. The default +key sequences (if any) are given after the mnemonic. +Every command takes an optional integer argument, which may be typed +before the command. Some commands just ignore it. The integer argument +is referred to as +.IR i . +Usually, if +.I i +is not given, it defaults to 1. +.de Nc +.PP +\&\\$1 +.RI ( \\$2 ) +.BR \\$3 +.br +.RS +.. +.de Ec +.RE +.. +.Nc "visit previous file" bf P +Visit the +.IR i -th +previous file given in the command line. +.Ec +.Nc "scroll one line up or go to line" bl "^K ~or~ k" +If +.I i +is not given, scroll one line up. Otherwise, +.I i +will be interpreted as a line number. A page starting with the line +indicated will then be displayed. +.Ec +.Nc "bottom" bot "l ~or~ $" +Go to the last line of the input. +.Ec +.Nc "display previous page" bp - +Display the previous page, consisting of +.I i +lines, (or +.I page-size +lines if no argument is given). +.Ec +.Nc "display previous page and set pagesize" bps Z +Display the previous page, consisting of +.I i +lines, (or +.I page-size +lines if no argument is given). +If +.I i +is given, the +.I page-size +is set to +.IR i . +.Ec +.Nc "scroll up" bs ^B +Scroll up +.I i +lines (or +.I scroll-size +lines if +.I i +is not given. Initially, the +.I scroll-size +is 11). +.Ec +.Nc "search backwards for pattern" bse ? +Search backwards for the +.IR i -th +occurrence of a regular expression which will be prompted for. +If there are less than +.I i +occurrences of the expression, the position in the file remains unchanged. +Otherwise, a page 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 expression. +Erasing back past the first character cancels the search command. +.br +Note: Some systems do not have +.BR regex (3). +On those systems, searches are still supported, but regular expressions +are not. +.Ec +.Nc "skip lines backwards" bsl S +Skip +.I i +lines backwards and display a page. +.Ec +.Nc "skip pages backwards" bsp F +Skip +.I i +pages backwards and display a page. +.Ec +.Nc "scroll up and set scrollsize" bss b +Scroll up +.I i +lines (or +.I scroll-size +lines if +.I i +is not given. +If +.I i +is given, the +.I scroll-size +is set to +.IR i . +.Ec +.Nc "change key map" chm X +Change from the current key map to the other (if there is one). +.Ec +.Nc "exchange current page and mark" exg x +Set the mark to the current page, and display the previously marked +page. +.Ec +.Nc "visit next file" ff N +Visit the +.IR i -th +next file given in the command line. +.Ec +.Nc "scroll one line down or go to line" fl "^J ~or~ ^M ~or~ j" +If +.I i +is not given, scroll one line down. Otherwise, +.I i +will be interpreted as a line number. A page starting with the line +indicated will then be displayed. +.Ec +.Nc "display next page" fp +Display the next page, consisting of +.I i +lines, (or +.I page-size +lines if no argument is given). +.Ec +.Nc "display next page and set pagesize" fps z +Display the next page, consisting of +.I i +lines, (or +.I page-size +lines if no argument is given). +If +.I i +is given, the +.I page-size +is set to +.IR i . +.Ec +.Nc "scroll down" fs ^D +Scroll down +.I i +lines (or +.I scroll-size +lines if no argument is given). +.Ec +.Nc "search forwards for pattern" fse / +Search forwards for the +.IR i -th +occurrence of a regular expression which will be prompted for. +If there are less than +.I i +occurrences of the expression, the position in the file remains unchanged. +Otherwise, a page 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 expression. +Erasing back past the first character cancels the search command. +.br +Note: Some systems do not have +.BR regex (3). +On those systems, searches are still supported, but regular expressions +are not. +.Ec +.Nc "skip lines forwards" fsl s +Skip +.I i +lines and display a page. +.Ec +.Nc "skip pages forwards" fsp f +Skip +.I i +pages and display a page. +.Ec +.Nc "scroll down and set scrollsize" fss d +Scroll down +.I i +lines (or +.I scroll-size +lines if +.I i +is not given. +If +.I i +is given, the +.I scroll-size +is set to +.IR i . +.Ec +.Nc "help" hlp h +Give a short description of all commands that are bound to a key sequence. +.Ec +.Nc "set a mark" mar m +Set a mark on the current page. +.Ec +.Nc "repeat last search" nse n +Search for the +.IR i -th +occurrence of the last regular expression entered, in the direction of the +last search. +.Ec +.Nc "repeat last search in other direction" nsr r +Search for the +.IR i -th +occurrence of the last regular expression entered, but in the other direction. +.Ec +.Nc "quit" qui "Q ~or~ q" +Exit from +.BR yap . +.Ec +.Nc "redraw" red ^L +Redraw the current page. +.Ec +.Nc "repeat" rep . +Repeat the last command. This does not always make sense, so not all +commands can be repeated. +.Ec +.Nc "shell escape" shl ! +Invoke the shell with a command that will be prompted for. +In the command, the characters `%' and `!' are replaced with the +current file name and the previous shell command respectively. +The sequences `\\%' and `\\!' are replaced by `%' and `!' respectively. +The user's erase and kill characters can be used to edit the command. +Erasing back past the first character cancels the command. +.Ec +.Nc "pipe to shell command" pip | +Pipe the current input file into a shell command that will be prompted for. +The comments given in the description of the shell escape command apply here +too. +.Ec +.Nc "go to mark" tom ' +Display the marked page. +.Ec +.Nc "top" top ^^ +Display a page starting with the first line of the input. +.Ec +.Nc "visit file" vis e +Visit a new file. The filename will be prompted for. If you just +type a return, the current file is revisited. +.Ec +.Nc "write input to a file" wrf w +Write the input to a file, whose name will be prompted for. +.Ec +.PP +The commands take effect immediately, i.e., it is not necessary to +type a carriage return. +Up to the time when the command sequence itself is given, +the user may give an interrupt to cancel the command +being formed. +.SH AUTHOR +Ceriel J.H. Jacobs +.SH SEE ALSO +.BR regex (3). +.SH BUGS +.B Yap +will find your terminal very stupid and act like it, +if it has no way of placing the +cursor on the home position, or cannot either +erase a line or +insert one. +.PP +In lines longer than about 2000 characters, a linefeed is silently inserted. +.PP +The percentage, given in the prompt when +.B yap +reads from a file (and knows it), is not always very accurate. diff --git a/man/man1/yes.1 b/man/man1/yes.1 new file mode 100644 index 000000000..d4d51562a --- /dev/null +++ b/man/man1/yes.1 @@ -0,0 +1,25 @@ +.TH YES 1 +.SH NAME +yes \- an endless stream of the same word +.SH SYNOPSIS +\fByes\fR [\fIanswer\fR]\fR +.br +.de FL +.TP +\\fB\\$1\\fR +\\$2 +.. +.de EX +.TP 20 +\\fB\\$1\\fR +# \\$2 +.. +.SH EXAMPLES +.EX "yes | script" "Answer yes to all questions from the script" +.SH DESCRIPTION +.PP +\fIYes\fP sends out an endless stream of y's, each on one line. One +uses it to automatically say "yes" to all questions a command may ask. +This is useful for commands that ask too many "Are you sure?" questions. +The optional argument makes \fIyes\fP use \fIanswer\fP as the word to +print instead of a single y character. diff --git a/man/man2/access.2 b/man/man2/access.2 new file mode 100644 index 000000000..2a09e87a3 --- /dev/null +++ b/man/man2/access.2 @@ -0,0 +1,109 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)access.2 6.5 (Berkeley) 5/22/86 +.\" +.TH ACCESS 2 "May 22, 1986" +.UC 4 +.SH NAME +access \- determine accessibility of file +.SH SYNOPSIS +.ft B +.nf +#include +#include +.PP +.ft B +.ta 1.25i 1.6i +.nf +#define R_OK 4 /* test for read permission */ +#define W_OK 2 /* test for write permission */ +#define X_OK 1 /* test for execute (search) permission */ +#define F_OK 0 /* test for presence of file */ +.PP +.ft B +.nf +int access(const char *\fIpath\fP, mode_t \fImode\fP) +.ft R +.fi +.SH DESCRIPTION +.B Access +checks the given +file +.I path +for accessibility according to +.IR mode , +which is an inclusive or of the bits +.BR R_OK , +.BR W_OK +and +.BR X_OK . +Specifying +.I mode +as +.B F_OK +(i.e., 0) +tests whether the directories leading to the file can be +searched and the file exists. +.PP +The real user ID and the group access list +(including the real group ID) are +used in verifying permission, so this call +is useful to set-UID programs. +.PP +Notice that only access bits are checked. +A directory may be indicated as writable by +.BR access , +but an attempt to open it for writing will fail +(although files may be created there); +a file may look executable, but +.B execve +will fail unless it is in proper format. +.SH "RETURN VALUE +If +.I path +cannot be found or if any of the desired access modes would +not be granted, then a \-1 value is returned; otherwise +a 0 value is returned. +.SH "ERRORS +Access to the file is denied if one or more of the following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EROFS] +Write access is requested for a file on a read-only file system. +.TP 15 +[EACCES] +Permission bits of the file mode do not permit the requested +access, or search permission is denied on a component of the +path prefix. The owner of a file has permission checked with +respect to the ``owner'' read, write, and execute mode bits, +members of the file's group other than the owner have permission +checked with respect to the ``group'' mode bits, and all +others have permissions checked with respect to the ``other'' +mode bits. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.SH "SEE ALSO +.BR chmod (2), +.BR stat (2). diff --git a/man/man2/alarm.2 b/man/man2/alarm.2 new file mode 100644 index 000000000..0ea81f855 --- /dev/null +++ b/man/man2/alarm.2 @@ -0,0 +1,38 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)alarm.3c 6.3 (Berkeley) 5/27/86 +.\" +.TH ALARM 2 "May 27, 1986" +.UC 4 +.SH NAME +alarm \- schedule signal after specified time +.SH SYNOPSIS +.nf +.ft B +#include + +unsigned int alarm(unsigned int \fIseconds\fP) +.ft R +.fi +.SH DESCRIPTION +.B Alarm +causes signal SIGALRM, see +.BR sigaction (2), +to be sent to the invoking process +in a number of seconds given by the argument. +Unless caught or ignored, the signal terminates the process. +.PP +Alarm requests are not stacked; successive calls reset the alarm clock. +If the argument is 0, any alarm request is canceled. +Because of scheduling delays, +resumption of execution of when the signal is +caught may be delayed an arbitrary amount. +.PP +The return value is the amount of time previously remaining in the alarm clock. +.SH "SEE ALSO" +.BR pause (2), +.BR sigsuspend (2), +.BR sigaction (2), +.BR sleep (3). diff --git a/man/man2/brk.2 b/man/man2/brk.2 new file mode 100644 index 000000000..03b657f54 --- /dev/null +++ b/man/man2/brk.2 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)brk.2 6.3 (Berkeley) 5/22/86 +.\" +.TH BRK 2 "May 22, 1986" +.UC 4 +.SH NAME +brk, sbrk \- change data segment size +.SH SYNOPSIS +.nf +#include +.PP +.ft B +int brk(char *\fIaddr\fP) +.PP +.ft B +char *sbrk(int \fIincr\fP) +.fi +.SH DESCRIPTION +.B Brk +sets the system's idea of the lowest data segment +location not used by the program (called the break) +to +.IR addr . +Locations greater than +.I addr +and below the stack pointer +are not in the address space and will thus +cause a memory violation if accessed. +.PP +In the alternate function +.BR sbrk , +.I incr +more bytes are added to the +program's data space and a pointer to the +start of the new area is returned. +.PP +When a program begins execution via +.B execve +the break is set at the +highest location defined by the program +and data storage areas. +Ordinarily, therefore, only programs with growing +data areas need to use +.BR sbrk . +.SH "RETURN VALUE +The address of the new break is returned if +.B brk +succeeds; +.B \-1 +if the program requests more +memory than the system limit. +.B Sbrk +returns +.B \-1 +if the break could not be set. +.SH ERRORS +.B Sbrk +will fail and no additional memory will be allocated if +one of the following are true: +.TP 15 +[ENOMEM] +The maximum possible size of a data segment (as set by +.BR chmem (1)) +was exceeded. +.TP 15 +[ENOMEM] +Insufficient virtual memory space existed +to support the expansion. (Minix-vmd) +.SH "SEE ALSO" +.BR chmem (1), +.BR execve (2), +.BR malloc (3), +.BR end (3). +.SH NOTES +Minix-vmd rounds a small data segment limit up to 3 megabytes. +.SH BUGS +Setting the break may fail due to a temporary lack of +virtual memory under Minix-vmd. It is not possible to distinguish this +from a failure caused by exceeding the maximum size of +the data segment. + +.\" +.\" $PchId: brk.2,v 1.2 2000/08/11 20:05:51 philip Exp $ diff --git a/man/man2/chdir.2 b/man/man2/chdir.2 new file mode 100644 index 000000000..d7b180a7e --- /dev/null +++ b/man/man2/chdir.2 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)chdir.2 6.3 (Berkeley) 8/26/85 +.\" +.TH CHDIR 2 "August 26, 1985" +.UC 4 +.SH NAME +chdir \- change current working directory +.SH SYNOPSIS +.nf +.ft B +#include + +int chdir(const char *\fIpath\fP) +.ft R +.fi +.SH DESCRIPTION +.I Path +is the pathname of a directory. +.B Chdir +causes this directory +to become the current working directory, +the starting point for path names not beginning with ``/''. +.PP +In order for a directory to become the current directory, +a process must have execute (search) access to the directory. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and \fBerrno\fP is set to indicate +the error. +.SH ERRORS +.B Chdir +will fail and the current working directory will be unchanged if +one or more of the following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named directory does not exist. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EACCES] +Search permission is denied for any component of +the path name. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.SH "SEE ALSO" +.BR chroot (2). diff --git a/man/man2/chmod.2 b/man/man2/chmod.2 new file mode 100644 index 000000000..9a30318aa --- /dev/null +++ b/man/man2/chmod.2 @@ -0,0 +1,132 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)chmod.2 6.5 (Berkeley) 5/13/86 +.\" +.TH CHMOD 2 "May 13, 1986" +.UC 4 +.SH NAME +chmod \- change mode of file +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int chmod(const char *\fIpath\fP, mode_t \fImode\fP) +.ig \" You never know +.PP +.ft B +int fchmod(int \fIfd\fP, mode_t \fImode\fP) +.. +.fi +.SH DESCRIPTION +The file whose name +is given by \fIpath\fP +.ig +or referenced by the descriptor +.I fd +.. +has its mode changed to +.IR mode . +Modes are constructed by +.IR or 'ing +together some +combination of the following, defined in +.IR : +.PP +.RS +.nf +.ta \w'S_ISUID\ \ 'u +\w'04000\ \ \ 'u +S_ISUID 04000 set user ID on execution +S_ISGID 02000 set group ID on execution +S_ISVTX 01000 `sticky bit' (see below) +S_IRWXU 00700 read, write, execute by owner +S_IRUSR 00400 read by owner +S_IWUSR 00200 write by owner +S_IXUSR 00100 execute (search on directory) by owner +S_IRWXG 00070 read, write, execute by group +S_IRGRP 00040 read by group +S_IWGRP 00020 write by group +S_IXGRP 00010 execute (search on directory) by group +S_IRWXO 00007 read, write, execute by others +S_IROTH 00004 read by others +S_IWOTH 00002 write by others +S_IXOTH 00001 execute (search on directory) by others +.fi +.RE +.PP +If mode ISVTX (the `sticky bit') is set on a directory, +an unprivileged user may not delete or rename +files of other users in that directory. (Minix-vmd) +.PP +Only the owner of a file (or the super-user) may change the mode. +.PP +Writing or changing the owner of a file +turns off the set-user-id and set-group-id bits +unless the user is the super-user. +This makes the system somewhat more secure +by protecting set-user-id (set-group-id) files +from remaining set-user-id (set-group-id) if they are modified, +at the expense of a degree of compatibility. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +.B Chmod +will fail and the file mode will be unchanged if: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EPERM] +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.ig +.PP +.I Fchmod +will fail if: +.TP 15 +[EBADF] +The descriptor is not valid. +.TP 15 +[EROFS] +The file resides on a read-only file system. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.. +.SH "SEE ALSO" +.BR chmod (1), +.BR open (2), +.BR chown (2), +.BR stat (2). +.SH NOTES +The sticky bit was historically used to lock important executables into +memory. diff --git a/man/man2/chown.2 b/man/man2/chown.2 new file mode 100644 index 000000000..6d854f07c --- /dev/null +++ b/man/man2/chown.2 @@ -0,0 +1,102 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)chown.2 6.6 (Berkeley) 5/22/86 +.\" +.TH CHOWN 2 "May 22, 1986" +.UC 4 +.SH NAME +chown \- change owner and group of a file +.SH SYNOPSIS +.nf +.ft B +int chown(const char *\fIpath\fP, int \fIowner\fP, int \fIgroup\fP) +.ig \" You never know +.PP +.ft B +int fchown(int \fIfd\fP, int \fIowner\fP, int \fIgroup\fP) +.. +.fi +.SH DESCRIPTION +The file +that is named by \fIpath\fP +.ig +or referenced by \fIfd\fP +.. +has its +.I owner +and +.I group +changed as specified. +Only the super-user +may change the owner of the file, +because if users were able to give files away, +they could defeat file-space accounting procedures. +The owner of the file may change the group +to a group of which he is a member. +.PP +On some systems, +.I chown +clears the set-user-id and set-group-id bits +on the file +to prevent accidental creation of +set-user-id and set-group-id programs. +.SH "RETURN VALUE +Zero is returned if the operation was successful; +\-1 is returned if an error occurs, with a more specific +error code being placed in the global variable \fBerrno\fP. +.SH "ERRORS +.B Chown +will fail and the file will be unchanged if: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EPERM] +The effective user ID is not the super-user. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.ig +.PP +.B Fchown +will fail if: +.TP 15 +[EBADF] +.I Fd +does not refer to a valid descriptor. +.TP 15 +[EPERM] +The effective user ID is not the super-user. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.. +.SH "SEE ALSO" +.BR chown (8), +.BR chgrp (1), +.BR chmod (2). diff --git a/man/man2/chroot.2 b/man/man2/chroot.2 new file mode 100644 index 000000000..c88a681fe --- /dev/null +++ b/man/man2/chroot.2 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)chroot.2 6.3 (Berkeley) 8/26/85 +.\" +.TH CHROOT 2 "August 26, 1985" +.UC 5 +.SH NAME +chroot \- change root directory +.SH SYNOPSIS +.nf +.ft B +#include + +int chroot(const char *\fIdirname\fP) +.ft R +.fi +.SH DESCRIPTION +.I Dirname +is the address of the pathname of a directory, terminated by a null byte. +.B Chroot +causes this directory +to become the root directory, +the starting point for path names beginning with ``/''. +.PP +In order for a directory to become the root directory +a process must have execute (search) access to the directory. +.PP +This call is restricted to the super-user. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. Otherwise, +a value of \-1 is returned and \fBerrno\fP is set to indicate an error. +.SH ERRORS +.B Chroot +will fail and the root directory will be unchanged if +one or more of the following are true: +.TP 15 +[ENOTDIR] +A component of the path name is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named directory does not exist. +.TP 15 +[EACCES] +Search permission is denied for any component of the path name. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.SH "SEE ALSO" +.BR chdir (2). diff --git a/man/man2/close.2 b/man/man2/close.2 new file mode 100644 index 000000000..656474064 --- /dev/null +++ b/man/man2/close.2 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)close.2 6.3 (Berkeley) 5/22/86 +.\" +.TH CLOSE 2 "May 22, 1986" +.UC 4 +.SH NAME +close \- delete a descriptor +.SH SYNOPSIS +.nf +.ft B +#include + +int close(int \fId\fP) +.ft R +.fi +.SH DESCRIPTION +The +.B close +call deletes a descriptor from the per-process object +reference table. +If this is the last reference to the underlying object, then +it will be deactivated. +For example, on the last close of a file +the current \fIseek\fP pointer associated with the file is lost; +on the last close of a TCP/IP descriptor +associated naming information and queued data are discarded; +on the last close of a file holding an advisory lock +the lock is released (see further +.BR fcntl (2)). +.PP +A close of all of a process's descriptors is automatic on +.IR exit , +but since +there is a limit on the number of active descriptors per process, +.B close +is necessary for programs that deal with many descriptors. +.PP +When a process forks (see +.BR fork (2)), +all descriptors for the new child process reference the same +objects as they did in the parent before the fork. +If a new process is then to be run using +.BR execve (2), +the process would normally inherit these descriptors. Most +of the descriptors can be rearranged with +.BR dup2 (2) +or deleted with +.B close +before the +.B execve +is attempted, but if some of these descriptors will still +be needed if the +.B execve +fails, it is necessary to arrange for them to be closed if the +.B execve +succeeds. +For this reason, the call ``fcntl(d, F_SETFD, \fIflags\fR)'' is provided, +that can be used to mark a descriptor "close on exec" by setting +the +.B FD_CLOEXEC +flag: +.PP +.RS +fcntl(d, F_SETFD, fcntl(d, F_GETFD) | FD_CLOEXEC); +.RE +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global integer variable +.B errno +is set to indicate the error. +.SH ERRORS +.B Close +will fail if: +.TP 15 +[EBADF] +\fID\fP is not an active descriptor. +.SH "SEE ALSO" +.BR open (2), +.BR pipe (2), +.BR execve (2), +.BR fcntl (2). diff --git a/man/man2/creat.2 b/man/man2/creat.2 new file mode 100644 index 000000000..5ccd2670f --- /dev/null +++ b/man/man2/creat.2 @@ -0,0 +1,142 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)creat.2 6.6 (Berkeley) 5/22/86 +.\" +.TH CREAT 2 "May 22, 1986" +.UC 4 +.SH NAME +creat \- create a new file +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int creat(const char *\fIname\fP, mode_t \fImode\fP) +.ft R +.fi +.SH DESCRIPTION +.ft B +This interface is made obsolete by open(2), it is equivalent to +.ft R +.PP +.RS +open(\fIname\fP, O_WRONLY | O_CREAT | O_TRUNC, \fImode\fP) +.RE +.PP +.B Creat +creates a new file or prepares to rewrite an existing +file called +.IR name , +given as the address of a null-terminated string. +If the file did not exist, it is given +mode +.IR mode , +as modified by the process's mode mask (see +.BR umask (2)). +Also see +.BR chmod (2) +for the +construction of the +.I mode +argument. +.PP +If the file did exist, its mode and owner remain unchanged +but it is truncated to 0 length. +.PP +The file is also opened for writing, and its file descriptor +is returned. +.SH NOTES +The +.I mode +given is arbitrary; it need not allow +writing. +This feature has been used in the past by +programs to construct a simple, exclusive locking +mechanism. It is replaced by the O_EXCL open +mode, or the advisory locking of the +.BR fcntl (2) +facility. +.SH "RETURN VALUE +The value \-1 is returned if an error occurs. Otherwise, +the call returns a non-negative descriptor that only permits +writing. +.SH ERRORS +.I Creat +will fail and the file will not be created or truncated +if one of the following occur: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EACCES] +The file does not exist and the directory +in which it is to be created is not writable. +.TP 15 +[EACCES] +The file exists, but it is unwritable. +.TP 15 +[EISDIR] +The file is a directory. +.TP 15 +[EMFILE] +There are already too many files open. +.TP 15 +[ENFILE] +The system file table is full. +.TP 15 +[ENOSPC] +The directory in which the entry for the new file is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.TP 15 +[ENOSPC] +There are no free inodes on the file system on which the +file is being created. +.ig +.TP 15 +[EDQUOT] +The directory in which the entry for the new file +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.TP 15 +[EDQUOT] +The user's quota of inodes on the file system on +which the file is being created has been exhausted. +.. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[ENXIO] +The file is a character special or block special file, and +the associated device does not exist. +.TP 15 +[EIO] +An I/O error occurred while making the directory entry or allocating the inode. +.TP 15 +[EFAULT] +.I Name +points outside the process's allocated address space. +.SH "SEE ALSO" +.BR open (2), +.BR write (2), +.BR close (2), +.BR chmod (2), +.BR umask (2). diff --git a/man/man2/dup.2 b/man/man2/dup.2 new file mode 100644 index 000000000..6ac0954d4 --- /dev/null +++ b/man/man2/dup.2 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)dup.2 6.3 (Berkeley) 5/13/86 +.\" +.TH DUP 2 "May 13, 1986" +.UC 4 +.SH NAME +dup, dup2 \- duplicate a descriptor +.SH SYNOPSIS +.nf +.ft B +#include + +int dup(int \fIoldd\fP) +int dup2(int \fIoldd\fP, int \fInewd\fP) +.SH DESCRIPTION +.B Dup +duplicates an existing descriptor. +The argument \fIoldd\fP is a small non-negative integer index in +the per-process descriptor table. The value must be less +than OPEN_MAX, the size of the table. +The new descriptor returned by the call, let's name it +.I newd, +is the lowest numbered descriptor that is +not currently in use by the process. +.PP +The object referenced by the descriptor does not distinguish +between references using \fIoldd\fP and \fInewd\fP in any way. +Thus if \fInewd\fP and \fIoldd\fP are duplicate references to an open +file, +.BR read (2), +.BR write (2) +and +.BR lseek (2) +calls all move a single pointer into the file, +and append mode, non-blocking I/O and asynchronous I/O options +are shared between the references. +If a separate pointer into the file is desired, a different +object reference to the file must be obtained by issuing an +additional +.BR open (2) +call. +The close-on-exec flag on the new file descriptor is unset. +.PP +In the second form of the call, the value of +.IR newd +desired is specified. If this descriptor is already +in use, the descriptor is first deallocated as if a +.BR close (2) +call had been done first. +.I Newd +is not closed if it equals +.IR oldd . +.SH "RETURN VALUE +The value \-1 is returned if an error occurs in either call. +The external variable +.B errno +indicates the cause of the error. +.SH "ERRORS +.B Dup +and +.B dup2 +fail if: +.TP 15 +[EBADF] +\fIOldd\fP or +\fInewd\fP is not a valid active descriptor +.TP 15 +[EMFILE] +Too many descriptors are active. +.SH NOTES +.B Dup +and +.B dup2 +are now implemented using the +.B F_DUPFD +function of +.BR fcntl (2), +although the old system call interfaces still exist to support old programs. +.SH "SEE ALSO" +.BR open (2), +.BR close (2), +.BR fcntl (2), +.BR pipe (2). diff --git a/man/man2/execve.2 b/man/man2/execve.2 new file mode 100644 index 000000000..7a3838cdf --- /dev/null +++ b/man/man2/execve.2 @@ -0,0 +1,206 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)execve.2 6.7 (Berkeley) 5/22/86 +.\" +.TH EXECVE 2 "May 22, 1986" +.UC 4 +.SH NAME +execve \- execute a file +.SH SYNOPSIS +.nf +.ft B +#include + +int execve(const char *\fIname\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]) +.ft R +.fi +.SH DESCRIPTION +.B Execve +transforms the calling process into a new process. +The new process is constructed from an ordinary file +called the \fInew process file\fP. +This file is either an executable object file, +or a file of data for an interpreter. +An executable object file consists of an identifying header, +followed by pages of data representing the initial program (text) +and initialized data pages. Additional pages may be specified +by the header to be initialized with zero data. See +.BR a.out (5). +.PP +An interpreter file begins with a line of the form ``#! \fIinterpreter\fP''. +When an interpreter file is +.BR execve\| 'd, +the system \fBexecve\fP\|'s the specified \fIinterpreter\fP, giving +it the name of the originally exec'd file as an argument and +shifting over the rest of the original arguments. +.PP +There can be no return from a successful \fBexecve\fP because the calling +core image is lost. +This is the mechanism whereby different process images become active. +.PP +The argument \fIargv\fP is a null-terminated array of character pointers +to null-terminated character strings. These strings constitute +the argument list to be made available to the new +process. By convention, at least one argument must be present in +this array, and the first element of this array should be +the name of the executed program (i.e., the last component of \fIname\fP). +.PP +The argument \fIenvp\fP is also a null-terminated array of character pointers +to null-terminated strings. These strings pass information to the +new process that is not directly an argument to the command (see +.BR environ (7)). +.PP +Descriptors open in the calling process remain open in +the new process, except for those for which the close-on-exec +flag is set (see +.BR close (2)). +Descriptors that remain open are unaffected by +.BR execve . +.PP +Ignored signals remain ignored across an +.BR execve , +but signals that are caught are reset to their default values. +Blocked signals remain blocked regardless of changes to the signal action. +The signal stack is reset to be undefined (see +.BR sigaction (2) +for more information). +.PP +Each process has +.I real +user and group IDs and an +.I effective +user and group IDs. The +.I real +ID identifies the person using the system; the +.I effective +ID determines his access privileges. +.B Execve +changes the effective user and group ID to +the owner of the executed file if the file has the \*(lqset-user-ID\*(rq +or \*(lqset-group-ID\*(rq modes. The +.I real +user ID is not affected. +.PP +The new process also inherits the following attributes from +the calling process: +.PP +.in +5n +.nf +.ta +2i +process ID see \fBgetpid\fP\|(2) +parent process ID see \fBgetppid\fP\|(2) +process group ID see \fBgetpgrp\fP\|(2) +access groups see \fBgetgroups\fP\|(2) +working directory see \fBchdir\fP\|(2) +root directory see \fBchroot\fP\|(2) +control terminal see \fBtty\fP\|(4) +alarm timer see \fBalarm\fP\|(2) +file mode mask see \fBumask\fP\|(2) +signal mask see \fBsigaction\fP\|(2), \fBsigprocmask\fP\|(2) +.in -5n +.fi +.PP +When the executed program begins, it is called as follows: +.PP +.RS +.ft B +.nf +int main(int \fIargc\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); + +exit(main(\fIargc\fP, \fIargv\fP, \fIenvp\fP)); +.fi +.ft R +.RE +.PP +where +.I argc +is the number of elements in \fIargv\fP +(the ``arg count'') +and +.I argv +is the array of character pointers +to the arguments themselves. +.PP +.I Envp +is a pointer to an array of strings that constitute +the +.I environment +of the process. +A pointer to this array is also stored in the global variable ``environ''. +Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. +The array of pointers is terminated by a null pointer. +The shell +.BR sh (1) +passes an environment entry for each global shell variable +defined when the program is called. +See +.BR environ (7) +for some conventionally +used names. +.SH "RETURN VALUE +If +.B execve +returns to the calling process an error has occurred; the +return value will be \-1 and the global variable +.B errno +will contain an error code. +.SH ERRORS +.B Execve +will fail and return to the calling process if one or more +of the following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The new process file does not exist. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EACCES] +The new process file is not an ordinary file. +.TP 15 +[EACCES] +The new process file mode denies execute permission. +.TP 15 +[ENOEXEC] +The new process file has the appropriate access +permission, but has an invalid magic number in its header. +.TP 15 +[ENOMEM] +The new process requires more (virtual) memory than +is currently available. +.TP 15 +[E2BIG] +The number of bytes in the new process's argument list +is larger than the system-imposed limit ARG_MAX. +The limit in the system as released is 4096 bytes for +16-bit Minix, 16384 bytes for 32-bit Minix, and unlimited for Minix-vmd. +.TP 15 +[EFAULT] +\fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point +to an illegal address. +.TP 15 +[EIO] +An I/O error occurred while reading from the file system. +.SH CAVEATS +If a program is +.I setuid +to a non-super-user, but is executed when +the real \fBuid\fP is ``root'', then the program has some of the powers +of a super-user as well. +.SH "SEE ALSO" +.BR exit (2), +.BR fork (2), +.BR execl (3), +.BR environ (7). diff --git a/man/man2/exit.2 b/man/man2/exit.2 new file mode 100644 index 000000000..6c77067e2 --- /dev/null +++ b/man/man2/exit.2 @@ -0,0 +1,57 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)exit.2 6.4 (Berkeley) 5/22/86 +.\" +.TH EXIT 2 "May 22, 1986" +.UC 4 +.SH NAME +exit, _exit \- terminate a process +.SH SYNOPSIS +.nf +.ft B +void _exit(int \fIstatus\fP) +.fi +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B _exit +terminates a process with the following consequences: +.RS +.SP +All of the descriptors open in the calling process are closed. +This may entail delays, for example, waiting for output to drain; +a process in this state may not be killed, as it is already dying. +.SP +If the parent process of the calling process is executing a +.B wait +or is interested in the SIGCHLD signal (Minix-vmd), +then it is notified of the calling process's termination and +the low-order eight bits of \fIstatus\fP are made available to it; +see +.BR wait (2). +.SP +The parent process ID of all of the calling process's existing child +processes are also set to 1. This means that the initialization process +(see +.BR intro (2)) +inherits each of these processes as well. +.ig +Any stopped children are restarted with a hangup signal (SIGHUP). +.. +.RE +.PP +Most C programs call the library routine +.BR exit (3), +which performs cleanup actions in the standard I/O library before +calling \fI_exit\fP\|. +.SH "RETURN VALUE" +This call never returns. +.SH "SEE ALSO" +.BR fork (2), +.BR sigaction (2), +.BR wait (2), +.BR exit (3). diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 new file mode 100644 index 000000000..60312de50 --- /dev/null +++ b/man/man2/fcntl.2 @@ -0,0 +1,262 @@ +.TH FCNTL 2 +.SH NAME +fcntl \- miscellaneous file descriptor control functions +.SH SYNOPSIS +.nf +.ft B +#include + +int fcntl(int \fIfd\fP, int \fIcmd\fP, \fR[\fP\fIdata\fP\fR]\fP) +.ft P +.fi +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Fcntl() +performs several file descriptor related functions, like duplicating a file +descriptor, setting the "close on exec" attribute, etc. The +.I fd +argument is the file descriptor to operate on, +.I cmd +is the command code of the operation to perform, and +.I data +is an optional argument to give or receive parameters. The command +codes and other symbols and types are declared in . The commands +are: +.SP +.BI "fcntl(" fd ", F_DUPFD, int " fd2 ")" +.RS +Returns a new file descriptor that is a duplicate of file descriptor +.IR fd . +It shares the same file pointer and the same file status flags, but has +separate file descriptor flags that are initially off. The value of the +duplicate file descriptor is the first free file descriptor greater than +or equal to +.IR fd2 . +.RE +.SP +.BI "fcntl(" fd ", F_GETFD)" +.RS +Returns the file descriptor flags associated with file descriptor +.IR fd . +The flags are the "close on exec" flag +.B FD_CLOEXEC +that, when set, causes the file descriptor to be closed when the process +executes another program. The Minix-vmd specific +.B FD_ASYNCHIO +flag marks a file descriptor for asynchronous I/O operation. +.RE +.SP +.BI "fcntl(" fd ", F_SETFD, int " flags ")" +.RS +Set the file descriptor flags of +.I fd +to +.IR flags . +.RE +.SP +.BI "fcntl(" fd ", F_GETFL)" +.RS +Return the file status flags and file access modes associated with the file +associated with file descriptor +.IR fd . +The file status flags are +.B O_NONBLOCK +(non blocking I/O) and +.B O_APPEND +(append mode). The file access modes are +.B O_RDONLY +(read-only), +.B O_WRONLY +(write-only) and +.B O_RDWR +(read-write). These flags are also used in the second argument of +.BR open (2). +.RE +.SP +.BI "fcntl(" fd ", F_SETFL, int " flags ")" +.RS +Set the file status flags of the file referenced by +.I fd +to +.IR flags . +Only +.B O_NONBLOCK +and +.B O_APPEND +may be changed. Access mode flags are ignored. +.RE +.SP +The next four commands use a parameter of type +.B struct flock +that is defined in as: +.SP +.RS +.nf +.ta +4n +8n +12n +struct flock { + short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */ + short l_whence; /* SEEK_SET, SEEK_CUR, or SEEK_END */ + off_t l_start; /* byte offset to start of segment */ + off_t l_len; /* length of segment */ + pid_t l_pid; /* process id of the locks' owner */ +}; +.fi +.RE +.SP +This structure describes a segment of a file. +.B L_type +is the lock operation performed on the file segment: +.B F_RDLCK +to set a read lock, +.B F_WRLCK +to set a write lock, and +.B F_UNLCK +to remove a lock. Several processes may have a read lock on a segment, but +only one process can have a write lock. +.B L_whence +tells if the +.B l_start +offset must be interpreted from the start of the file +.RB ( SEEK_SET ), +the current file position +.RB ( SEEK_CUR ), +or the end of the file +.RB ( SEEK_END ). +This is analogous to the third parameter of +.BR lseek (2). +These +.B SEEK_* +symbols are declared in . +.B L_start +is the starting offset of the segment of the file. +.B L_end +is the length of the segment. If zero then the segment extends until end of +file. +.B L_pid +is the process-id of the process currently holding a lock on the segment. +It is returned by +.BR F_GETLK . +.SP +.BI "fcntl(" fd ", F_GETLK, struct flock *" lkp ")" +.RS +Find out if some other process has a lock on a segment of the file +associated by file descriptor +.I fd +that overlaps with the segment described by the +.B flock +structure pointed to by +.IR lkp . +If the segment is not locked then +.B l_type +is set to +.BR F_UNLCK . +Otherwise an +.B flock +structure is returned through +.I lkp +that describes the lock held by the other process. +.B L_start +is set relative to the start of the file. +.RE +.SP +.BI "fcntl(" fd ", F_SETLK, struct flock *" lkp ")" +.RS +Register a lock on a segment of the file associated with file descriptor +.IR fd . +The file segment is described by the +.B struct flock +pointed to by +.IR lkp . +This call returns an error if any part of the segment is already locked. +.RE +.SP +.BI "fcntl(" fd ", F_SETLKW, struct flock *" lkp ")" +.RS +Register a lock on a segment of the file associated with file descriptor +.IR fd . +The file segment is described by the +.B struct flock +pointed to by +.IR lkp . +This call blocks waiting for the lock to be released if any part of the +segment is already locked. +.RE +.SP +.BI "fcntl(" fd ", F_FREESP, struct flock *" lkp ")" +.RS +This Minix-vmd specific call frees a segment of disk space occupied by the +file associated with file descriptor +.IR fd . +The segment is described by the +.B struct flock +pointed to by +.IR lkp . +The file is truncated in length to the byte position indicated by +.B l_start +if +.B l_len +is zero. If +.B l_len +is nonzero then the file keeps its size, but the freed bytes now read as +zeros. (Other than sharing the flock structure, this call has nothing to do +with locking.) (This call is common among UNIX(-like) systems.) +.RE +.SP +.BI "fcntl(" fd ", F_SEEK, u64_t " pos ")" +.RS +This Minix-vmd specific call sets the file position of the file associated +with file descriptor +.I fd +to the byte offset indicated by the 64-bit number +.IR pos . +This is analogous to the call +.SP +.RS +.BI "lseek(" fd ", " pos ", SEEK_SET)" +.RE +.SP +except that +.B F_SEEK +can be used on devices larger than 4 gigabyte. +.RE +.SH "SEE ALSO" +.BR open (2), +.BR dup (2), +.BR lseek (2), +.BR ftruncate (3), +.BR int64 (3). +.SH DIAGNOSTICS +.B Fcntl +returns a file descriptor, flags, or +.B 0 +to indicate success. On error +.B \-1 +is returned, with +.B errno +set to the appropriate error code. The most notable errors are: +.TP 5 +.B EINTR +If a blocked +.B F_SETLKW +operation is interrupted by a signal that is caught. +.TP +.B EAGAIN +By +.B F_SETLK +if a segment cannot be locked. +.TP +.B EBADF +A bad file descriptor in general, or an attempt to place a write lock on a +file that is not open for writing, etc. +.TP +.B ENOLCK +No locks available, the file system code has run out of internal table +space. +.SH AUTHOR +Kees J. Bot + +.\" +.\" $PchId: fcntl.2,v 1.2 2000/08/11 19:39:51 philip Exp $ diff --git a/man/man2/fork.2 b/man/man2/fork.2 new file mode 100644 index 000000000..abf7af288 --- /dev/null +++ b/man/man2/fork.2 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)fork.2 6.4 (Berkeley) 5/22/86 +.\" +.TH FORK 2 "May 22, 1986" +.UC +.SH NAME +fork \- create a new process +.SH SYNOPSIS +.nf +.ft B +#include +#include + +pid_t fork(void) +.ft R +.fi +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Fork +causes creation of a new process. +The new process (child process) is an exact copy of the +calling process except for the following: +.RS +.SP +The child process has a unique process ID. +.SP +The child process has a different parent process ID (i.e., +the process ID of the parent process). +.SP +The child process has its own copy of the parent's descriptors. +These descriptors reference the same underlying objects, so that, +for instance, file pointers in file objects are shared between +the child and the parent, so that an +.BR lseek (2) +on a descriptor in the child process can affect a subsequent +.B read +or +.B write +by the parent. +This descriptor copying is also used by the shell to +establish standard input and output for newly created processes +as well as to set up pipes. +.SP +The child starts with no pending signals and an inactive alarm timer. +.RE +.SH "RETURN VALUE +Upon successful completion, \fBfork\fP returns a value +of 0 to the child process and returns the process ID of the child +process to the parent process. Otherwise, a value of \-1 is returned +to the parent process, no child process is created, and the global +variable \fBerrno\fP is set to indicate the error. +.SH ERRORS +.B Fork +will fail and no child process will be created if one or more of the +following are true: +.TP 15 +[EAGAIN] +The system-imposed limit on the total +number of processes under execution would be exceeded. +This limit is configuration-dependent. +(The kernel variable NR_PROCS in (Minix), or + (Minix-vmd).) +.TP 15 +[ENOMEM] +There is insufficient (virtual) memory for the new process. +.SH "SEE ALSO" +.BR execve (2), +.BR wait (2). diff --git a/man/man2/getgid.2 b/man/man2/getgid.2 new file mode 100644 index 000000000..002e9b2d4 --- /dev/null +++ b/man/man2/getgid.2 @@ -0,0 +1,34 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getgid.2 6.2 (Berkeley) 1/7/86 +.\" +.TH GETGID 2 "January 7, 1986" +.UC 5 +.SH NAME +getgid, getegid \- get group identity +.SH SYNOPSIS +.nf +.ft B +#include +#include + +gid_t getgid(void) +gid_t getegid(void) +.fi +.SH DESCRIPTION +.B Getgid +returns the real group ID of the current process, +.B getegid +the effective group ID. +.PP +The real group ID is specified at login time. +.PP +The effective group ID is more transient, and determines +additional access permission during execution of a +``set-group-ID'' process, and it is for such processes +that \fBgetgid\fP is most useful. +.SH "SEE ALSO" +.BR getuid (2), +.BR setgid (2). diff --git a/man/man2/getpid.2 b/man/man2/getpid.2 new file mode 100644 index 000000000..3dc6d6dbd --- /dev/null +++ b/man/man2/getpid.2 @@ -0,0 +1,33 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getpid.2 6.3 (Berkeley) 5/13/86 +.\" +.TH GETPID 2 "May 13, 1986" +.UC 4 +.SH NAME +getpid, getppid \- get process identification +.SH SYNOPSIS +.ft B +.nf +#include +#include + +pid_t getpid(void) +pid_t getppid(void) +.fi +.ft R +.SH DESCRIPTION +.B Getpid +returns +the process ID of +the current process. +Most often it is used +to generate uniquely-named temporary files. +.PP +.B Getppid +returns the process ID of the parent +of the current process. +.SH "SEE ALSO +.BR fork (2). diff --git a/man/man2/getuid.2 b/man/man2/getuid.2 new file mode 100644 index 000000000..f8a54c096 --- /dev/null +++ b/man/man2/getuid.2 @@ -0,0 +1,34 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getuid.2 6.3 (Berkeley) 1/7/86 +.\" +.TH GETUID 2 "January 7, 1986" +.UC 4 +.SH NAME +getuid, geteuid \- get user identity +.SH SYNOPSIS +.nf +.ft B +#include +#include + +uid_t getuid(void) +uid_t geteuid(void) +.fi +.SH DESCRIPTION +.B Getuid +returns the real user ID of the current process, +.B geteuid +the effective user ID. +.PP +The real user ID identifies the person who is logged in. +The effective user ID +gives the process additional permissions during +execution of \*(lqset-user-ID\*(rq mode processes, which use +\fBgetuid\fP to determine the real-user-id of the process that +invoked them. +.SH "SEE ALSO" +.BR getgid (2), +.BR setuid (2). diff --git a/man/man2/intro.2 b/man/man2/intro.2 new file mode 100644 index 000000000..a51760924 --- /dev/null +++ b/man/man2/intro.2 @@ -0,0 +1,449 @@ +.\" Copyright (c) 1980,1983,1986 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)intro.2 6.7 (Berkeley) 5/23/86 +.\" +.TH INTRO 2 "June 30, 1986" +.UC 4 +.de en +.HP +\\$1 \\$2 \\$3 +.br +.. +.SH NAME +intro, errno \- introduction to system calls and error numbers +.SH SYNOPSIS +.B "#include " +.SH DESCRIPTION +This section describes all of the system calls. Most +of these calls have one or more error returns. +An error condition is indicated by an otherwise impossible return +value. This is almost always \-1; the individual descriptions +specify the details. +Note that a number of system calls overload the meanings of these +error numbers, and that the meanings must be interpreted according +to the type and circumstances of the call. +.PP +As with normal arguments, all return codes and values from +functions are of type integer unless otherwise noted. +An error number is also made available in the external +variable \fBerrno\fP, which is not cleared +on successful calls. +Thus \fBerrno\fP should be tested only after an error has occurred. +.PP +The following is a complete list of the errors and their +names as given in +.RI < sys/errno.h >: +.en 0 OK "Error 0 +Unused. (The symbol "OK" is only used inside the kernel source.) +.en 1 EPERM "Not owner +Typically this error indicates +an attempt to modify a file in some way forbidden +except to its owner or super-user. +It is also returned for attempts +by ordinary users to do things +allowed only to the super-user. +.en 2 ENOENT "No such file or directory +This error occurs when a file name is specified +and the file should exist but doesn't, or when one +of the directories in a path name does not exist. +.en 3 ESRCH "No such process +The process or process group whose number was given +does not exist, or any such process is already dead. +.en 4 EINTR "Interrupted system call +An asynchronous signal (such as interrupt or quit) +that the user has elected to catch +occurred during a system call. +If execution is resumed +after processing the signal +and the system call is not restarted, +it will appear as if the interrupted system call +returned this error condition. +.en 5 EIO "I/O error +Some physical I/O error occurred during an I/O operation, usually +.B read +or +.BR write . +Operations on file descriptors that refer to devices that are forcefully +taken away or in a bad state will also provoke this error. +.en 6 ENXIO "No such device or address +I/O on a special file refers to a subdevice that does not +exist, +or beyond the limits of the device. +It may also occur when, for example, an illegal tape drive +unit number is selected +or a disk pack is not loaded on a drive. +.en 7 E2BIG "Arg list too long +An argument list longer than ARG_MAX bytes is presented to +.BR execve . +ARG_MAX is set to 4096 bytes for 16-bit Minix, 16384 bytes for 32-bit +Minix, and unlimited for Minix-vmd as these systems are released. +.en 8 ENOEXEC "Exec format error +A request is made to execute a file +that, although it has the appropriate permissions, +does not start with a valid magic number, (see +.BR a.out (5)). +.en 9 EBADF "Bad file number +Either a file descriptor refers to no +open file, +or a read (resp. write) request is made to +a file that is open only for writing (resp. reading). +.en 10 ECHILD "No children +.B Wait +and the process has no +living or unwaited-for children. +.en 11 EAGAIN "Resource temporarily unavailable +In a +.B fork, +the system's process table is full or the user is not allowed to create +any more processes, otherwise an operation that would cause a process to +block was attempted on an object in non-blocking mode (see \fBfcntl\fP(2)). +.en 12 ENOMEM "Not enough core +During an +.B execve +or +.B brk, +a program asks for more (virtual) memory than the system is +able to supply, +or a process size limit would be exceeded. +The maximum size +of the data+stack segment is set by the +.BR chmem (1) +program. For Minix-vmd a small data+stack size is increased to 3 megabytes +when a program is executed. +.en 13 EACCES "Permission denied +An attempt was made to access a file in a way forbidden +by the protection system. Also an attempt to open a device for writing +that is physically write protected. +.en 14 EFAULT "Bad address +An argument of a system call is outside the address space allocated to a +process. +.en 15 ENOTBLK "Block device required +A plain file was mentioned where a block device was required, +e.g., in +.BR mount . +.en 16 EBUSY "Resource busy +An attempt to mount a device that was already mounted or +an attempt was made to dismount a device +on which there is an active file +(open file, current directory, mounted-on file, or active text segment). +A request was made to an exclusive access device that was already in use. +.en 17 EEXIST "File exists +An existing file was mentioned in an inappropriate context, +e.g., +.BR link . +.en 18 EXDEV "Cross-device link +A hard link to a file on another device +was attempted. +.en 19 ENODEV "No such device +An attempt was made to access a device that is not configured by the system, +i.e., there is no driver for the device. +.en 20 ENOTDIR "Not a directory +A non-directory was specified where a directory +is required, +for example, in a path name or +as an argument to +.BR chdir . +.en 21 EISDIR "Is a directory +An attempt to write on a directory. +.en 22 EINVAL "Invalid argument +Some invalid argument: +dismounting a non-mounted +device, +mentioning an unknown signal in +.B signal, +or some other argument inappropriate for the call. +Also set by math functions, (see +.BR math (3)). +.en 23 ENFILE "File table overflow +The system's table of open files is full, +and temporarily no more +.I opens +can be accepted. +.en 24 EMFILE "Too many open files +The limit on the number of open files per process, OPEN_MAX, is reached. +As released, this limit is 20 for Minix, and 30 for Minix-vmd. +.en 25 ENOTTY "Not a typewriter +The file mentioned in an +.B ioctl +is not a terminal or one of the +devices to which this call applies. (Often seen error from programs with +bugs in their error reporting code.) +.en 26 ETXTBSY "Text file busy +Attempt to execute a program that is open for writing. Obsolete under Minix. +.en 27 EFBIG "File too large +The size of a file exceeded the maximum (little over 64 megabytes for +the V2 file system). +.en 28 ENOSPC "No space left on device +A +.B write +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because no more disk blocks are available +on the file system, or the allocation of an inode for a newly +created file failed because no more inodes are available +on the file system. +.en 29 ESPIPE "Illegal seek +An +.B lseek +was issued to a pipe or TCP/IP channel. +This error may also be issued for +other non-seekable devices. +.en 30 EROFS "Read-only file system +An attempt to modify a file or directory +was made +on a device mounted read-only. +.en 31 EMLINK "Too many links +An attempt to make more than a certain number of hard links to a file. The +advertized maximum, LINK_MAX, is 127, but Minix-vmd uses a much larger +maximum of 32767 for the V2 file system. +.en 32 EPIPE "Broken pipe +A write on a pipe or TCP/IP channel for which there is no process +to read the data. +This condition normally generates the signal SIGPIPE; +the error is returned if the signal is caught or ignored. +.en 33 EDOM "Math argument +The argument of a function in the math package +is out of the domain of the function. +.en 34 ERANGE "Result too large +The value of a function in the math package +is unrepresentable within machine precision. +.en 35 EDEADLK "Resource deadlock avoided +A process attempts to place a blocking lock on a file that is already +locked by another process and that process is waiting for the first +process to unlock a file that first process already has a lock on. +(The classic "lock A, lock B" by process 1, and "lock B, lock A" by +process 2.) +.en 36 ENAMETOOLONG "File name too long" +The path name exceeds PATH_MAX characters. PATH_MAX equals 255 as +distributed. +.en 37 ENOLCK "No locks available +The system's table of active locks is full. +.en 38 ENOSYS "Function not implemented +The system call is not supported. Either an old program uses an obsolete +call, or a program for a more capable system is run on a less capable +system. +.en 39 ENOTEMPTY "Directory not empty" +A directory with entries other than \*(lq.\*(rq and \*(lq..\*(rq +was supplied to a remove directory or rename call. +.en 40 ELOOP "Too many symbolic links" +A path name lookup involved more than SYMLOOP symbolic links. SYMLOOP +equals 8 as distributed. +(Minix-vmd) +.en 50 EPACKSIZE "Invalid packet size +.en 51 EOUTOFBUFS "Not enough buffers left +.en 52 EBADIOCTL "Illegal ioctl for device +.en 53 EBADMODE "Bad mode in ioctl +.en 54 EWOULDBLOCK "Would block +.en 55 EBADDEST "Bad destination address +.en 56 EDSTNOTRCH "Destination not reachable +.en 57 EISCONN "Already connected +.en 58 EADDRINUSE "Address in use +.en 59 ECONNREFUSED "Connection refused +.en 60 ECONNRESET "Connection reset +.en 61 ETIMEDOUT "Connection timed out +.en 62 EURG "Urgent data present +.en 63 ENOURG "No urgent data present +.en 64 ENOTCONN "No connection +.en 65 ESHUTDOWN "Already shutdown +.en 66 ENOCONN "No such connection +.en 67 EINPROGRESS "Operation now in progress +.en 68 EALREADY "Operation already in progress +.ig +.en XXX EDQUOT "Disc quota exceeded" +A +.B write +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because the user's quota of disk blocks was +exhausted, or the allocation of an inode for a newly +created file failed because the user's quota of inodes +was exhausted. +.en XXX ESTALE "Stale NFS file handle" +A client referenced a an open file, when the file has been deleted. +.en XXX EREMOTE "Too many levels of remote in path" +An attempt was made to remotely mount a file system into a path which +already has a remotely mounted component. +.. +.SH DEFINITIONS +.TP 5 +Process ID +.br +Each active process in the system is uniquely identified by a positive +integer called a process ID. The range of this ID is from 1 to 29999. +The special process with process ID 1 is +.BR init , +the ancestor of all processes. +.TP 5 +Parent process ID +.br +A new process is created by a currently active process; (see +.BR fork (2)). +The parent process ID of a process is the process ID of its creator, +unless the creator dies, then +.B init +becomes the parent of the orphaned process. +.TP 5 +Process Group ID +.br +Each active process is a member of a process group that is identified by +a positive integer called the process group ID. This is the process +ID of the group leader. This grouping permits the signaling of related +processes (see +.BR kill (2)). +.TP 5 +Real User ID and Real Group ID +.br +Each user on the system is identified by a positive integer +termed the real user ID. +.IP +Each user is also a member of one or more groups. +One of these groups is distinguished from others and +used in implementing accounting facilities. The positive +integer corresponding to this distinguished group is termed +the real group ID. +(Under standard Minix this is the only group a process can be a member of.) +.IP +All processes have a real user ID and real group ID. +These are initialized from the equivalent attributes +of the process that created it. +.TP 5 +Effective User Id, Effective Group Id, and Access Groups +.br +Access to system resources is governed by three values: +the effective user ID, the effective group ID, and the +group access list. +.IP +The effective user ID and effective group ID are initially the +process's real user ID and real group ID respectively. Either +may be modified through execution of a set-user-ID or set-group-ID +file (possibly by one its ancestors) (see +.BR execve (2)). +.IP +The group access list is an additional set of group ID's +used only in determining resource accessibility. Access checks +are performed as described below in ``File Access Permissions''. +The maximum number of additional group ID's is NGROUPS_MAX. +For Minix this is 0, but Minix-vmd supports a list of up to 16 +additional group ID's. (Also known as ``supplemental'' group ID's.) +.TP 5 +Super-user +.br +A process is recognized as a +.I super-user +process and is granted special privileges if its effective user ID is 0. +.TP 5 +Descriptor +.br +An integer assigned by the system when a file or device is referenced +by +.BR open (2), +.BR dup (2) +or +.BR fcntl (2) +which uniquely identifies an access path to that file or device from +a given process or any of its children. +.TP 5 +File Descriptor +Older, and often used name for a descriptor. +.TP 5 +File Name +.br +Names consisting of up to NAME_MAX characters may be used to name +an ordinary file, special file, or directory. NAME_MAX is the maximum +of the maximum file name lengths of the supported file systems. +Excess characters are ignored when too long file names are used for +files in a given file system. +The maximum file name length of the V1 and V2 file systems +is 14 characters. The Minix-vmd "flex" variants of V1 and V2 have a +60 character maximum. +.IP +The characters in a file name may assume any value representable in +eight bits excluding 0 (null) and the ASCII code for / (slash). +.IP +Note that it is generally unwise to use one of \e'"<>();~$^&*|{}[]? +as part of file names because of the special meaning attached to these +characters by the shell. +.TP 5 +Path Name +.br +A path name is a null-terminated character string starting with an +optional slash (/), followed by zero or more directory names separated +by slashes, optionally followed by a file name. +The total length of a path name must be less than PATH_MAX characters +(255 as distributed.) +.IP +If a path name begins with a slash, the path search begins at the +.I root +directory. +Otherwise, the search begins from the current working directory. +A slash by itself names the root directory. A null pathname is +illegal, use "." to refer to the current working directory. +.TP 5 +Directory +.br +A directory is a special type of file that contains entries +that are references to other files. +Directory entries are called links. By convention, a directory +contains at least two links, . and .., referred to as +.I dot +and +.I dot-dot +respectively. Dot refers to the directory itself and +dot-dot refers to its parent directory. +.TP 5 +Root Directory and Current Working Directory +.br +Each process has associated with it a concept of a root directory +and a current working directory for the purpose of resolving path +name searches. A process's root directory need not be the root +directory of the root file system. +.TP 5 +File Access Permissions +.br +Every file in the file system has a set of access permissions. +These permissions are used in determining whether a process +may perform a requested operation on the file (such as opening +a file for writing). Access permissions are established at the +time a file is created. They may be changed at some later time +through the +.BR chmod (2) +call. +.IP +File access is broken down according to whether a file may be: read, +written, or executed. Directory files use the execute +permission to control if the directory may be searched. +.IP +File access permissions are interpreted by the system as +they apply to three different classes of users: the owner +of the file, those users in the file's group, anyone else. +Every file has an independent set of access permissions for +each of these classes. When an access check is made, the system +decides if permission should be granted by checking the access +information applicable to the caller. +.IP +Read, write, and execute/search permissions on +a file are granted to a process if: +.IP +The process's effective user ID is that of the super-user. +.IP +The process's effective user ID matches the user ID of the owner +of the file and the owner permissions allow the access. +.IP +The process's effective user ID does not match the user ID of the +owner of the file, and either the process's effective +group ID matches the group ID +of the file, or the group ID of the file is in +the process's group access list, +and the group permissions allow the access. +.IP +Neither the effective user ID nor effective group ID +and group access list of the process +match the corresponding user ID and group ID of the file, +but the permissions for ``other users'' allow access. +.IP +Otherwise, permission is denied. +.SH SEE ALSO +.BR intro (3), +.BR strerror (3). diff --git a/man/man2/ioctl.2 b/man/man2/ioctl.2 new file mode 100644 index 000000000..3971d87c4 --- /dev/null +++ b/man/man2/ioctl.2 @@ -0,0 +1,69 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)ioctl.2 6.3 (Berkeley) 3/4/86 +.\" +.TH IOCTL 2 "March 4, 1986" +.UC 4 +.SH NAME +ioctl \- control device +.SH SYNOPSIS +.nf +.ft B +#include +#include + +.ta +54n +int ioctl(int \fId\fP, int \fIrequest\fP, void *\fIargp\fP) (Minix) +int ioctl(int \fId\fP, ioreq_t \fIrequest\fP, void *\fIargp\fP) (Minix-vmd) +.DT +.fi +.ft R +.SH DESCRIPTION +.B Ioctl +performs a variety of functions +on open descriptors. In particular, many operating +characteristics of character special files (e.g. terminals) +may be controlled with +.B ioctl +requests. +The writeups of various devices in section 4 discuss how +.B ioctl +applies to them. +.PP +An ioctl +.I request +has encoded in it whether the argument is an \*(lqin\*(rq parameter +or \*(lqout\*(rq parameter, and the size of the argument \fIargp\fP in bytes. +Macros and defines used in specifying an ioctl +.I request +are located in the file +.IR . +.SH "RETURN VALUE +If an error has occurred, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH ERRORS +.B Ioctl +will fail if one or more of the following are true: +.TP 15 +[EBADF] +\fID\fP is not a valid descriptor. +.TP 15 +[ENOTTY] +\fID\fP is not associated with a character +special device. +.TP 15 +[ENOTTY] +The specified request does not apply to the kind +of object that the descriptor \fId\fP references. +.TP 15 +[EINVAL] +\fIRequest\fP or \fIargp\fP is not valid. +.SH "SEE ALSO" +.BR execve (2), +.BR fcntl (2), +.BR mt (4), +.BR tty (4), +.BR intro (4). diff --git a/man/man2/kill.2 b/man/man2/kill.2 new file mode 100644 index 000000000..09b947b2e --- /dev/null +++ b/man/man2/kill.2 @@ -0,0 +1,93 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)kill.2 6.5 (Berkeley) 5/14/86 +.\" +.TH KILL 2 "May 14, 1986" +.UC 4 +.SH NAME +kill \- send signal to a process +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int kill(pid_t \fIpid\fP, int \fIsig\fP) +.ft R +.fi +.SH DESCRIPTION +.B Kill +sends the signal \fIsig\fP +to a process, specified by the process number +.IR pid . +.I Sig +may be one of the signals specified in +.BR sigaction (2), +or it may be 0, in which case +error checking is performed but no +signal is actually sent. +This can be used to check the validity of +.IR pid . +.PP +The sending and receiving processes must +have the same effective user ID, otherwise +this call is restricted to the super-user. +.ig +A single exception is the signal SIGCONT, which may always be sent +to any descendant of the current process. +.. +.PP +If the process number is 0, +the signal is sent to all processes in the +sender's process group. +.PP +If the process number is \-1 +and the user is the super-user, +the signal is broadcast universally +except to +.B init +and the process sending the signal. +If the process number is \-1 +and the user is not the super-user, +the signal is broadcast universally to +all processes with the same uid as the user +except the process sending the signal. +No error is returned if any process could be signaled. +.PP +If the process number is negative but not \-1, +the signal is sent to all processes whose process group ID +is equal to the absolute value of the process number. +.PP +Processes may send signals to themselves. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +.B Kill +will fail and no signal will be sent if any of the following +occur: +.TP 15 +[EINVAL] +\fISig\fP is not a valid signal number. +.TP 15 +[ESRCH] +No process can be found corresponding to that specified by \fIpid\fP. +.TP 15 +[ESRCH] +The process id was given as 0 +but the sending process does not have a process group. +.TP 15 +[EPERM] +The sending process is not the super-user and its effective +user id does not match the effective user-id of the receiving process. +When signaling a process group, this error was returned if any members +of the group could not be signaled. +.SH "SEE ALSO" +.BR getpid (2), +.BR getpgrp (2), +.BR sigaction (2), +.BR raise (3). diff --git a/man/man2/link.2 b/man/man2/link.2 new file mode 100644 index 000000000..33651e578 --- /dev/null +++ b/man/man2/link.2 @@ -0,0 +1,111 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)link.2 6.3 (Berkeley) 8/26/85 +.\" +.TH LINK 2 "August 26, 1985" +.UC 4 +.SH NAME +link \- make a hard link to a file +.SH SYNOPSIS +.nf +.ft B +#include + +int link(const char *\fIname1\fP, const char *\fIname2\fP) +.fi +.ft R +.SH DESCRIPTION +A hard link +to +.I name1 +is created; +the link has the name +.IR name2 . +.I Name1 +must exist. +.PP +With hard links, +both +.I name1 +and +.I name2 +must be in the same file system. +.I Name1 +must not be a directory. +Both the old and the new +.I link +share equal access and rights to +the underlying object. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. Otherwise, +a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +.B Link +will fail and no link will be created if one or more of the following +are true: +.TP 15 +[ENOTDIR] +A component of either path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +A path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +A component of either path prefix does not exist. +.TP 15 +[EACCES] +A component of either path prefix denies search permission. +.TP 15 +[EACCES] +The requested link requires writing in a directory with a mode +that denies write permission. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating one of the pathnames. +(Minix-vmd) +.TP 15 +[ENOENT] +The file named by \fIname1\fP does not exist. +.TP 15 +[EEXIST] +The link named by \fIname2\fP does exist. +.TP 15 +[EPERM] +The file named by \fIname1\fP is a directory and the effective +user ID is not super-user. +.TP 15 +[EXDEV] +The link named by \fIname2\fP and the file named by \fIname1\fP +are on different file systems. +.TP 15 +[ENOSPC] +The directory in which the entry for the new link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.ig +.TP 15 +[EDQUOT] +The directory in which the entry for the new link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to +the file system to make the directory entry. +.TP 15 +[EROFS] +The requested link requires writing in a directory on a read-only file +system. +.TP 15 +[EFAULT] +One of the pathnames specified +is outside the process's allocated address space. +.SH "SEE ALSO" +.BR symlink (2), +.BR unlink (2). diff --git a/man/man2/lseek.2 b/man/man2/lseek.2 new file mode 100644 index 000000000..c1fceff98 --- /dev/null +++ b/man/man2/lseek.2 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)lseek.2 6.3 (Berkeley) 2/24/86 +.\" +.TH LSEEK 2 "February 24, 1986" +.UC 4 +.SH NAME +lseek \- move read/write pointer +.SH SYNOPSIS +.nf +.ft B +#include +#include + +.ta +1.8i +0.6i +#define SEEK_SET 0 /* offset is absolute */ +#define SEEK_CUR 1 /* relative to current position */ +#define SEEK_END 2 /* relative to end of file */ + +off_t lseek(int d, off_t offset, int whence) +.fi +.ft R +.SH DESCRIPTION +The descriptor +.I d +refers to a file or device open for reading and/or writing. +.B Lseek +sets the file pointer of +.I d +as follows: +.IP +If +.I whence +is SEEK_SET, the pointer is set to +.I offset +bytes. +.IP +If +.I whence +is SEEK_CUR, the pointer is set to its current location plus +.IR offset . +.IP +If +.I whence +is SEEK_END, the pointer is set to the size of the +file plus +.IR offset . +.PP +Upon successful completion, the resulting pointer location +as measured in bytes from beginning of the file is returned. +Some devices are incapable of seeking. The value of the pointer +associated with such a device is undefined. +.SH NOTES +Seeking far beyond the end of a file, then writing, +creates a gap or \*(lqhole\*(rq, which occupies no +physical space and reads as zeros. +.SH "RETURN VALUE +Upon successful completion, +the current file pointer value is returned. +Otherwise, +a value of \-1 is returned and \fBerrno\fP is set to indicate +the error. +.SH "ERRORS +.B Lseek +will fail and the file pointer will remain unchanged if: +.TP 15 +[EBADF] +.I Fildes +is not an open file descriptor. +.TP 15 +[ESPIPE] +.I Fildes +is associated with a pipe or a socket. +.TP 15 +[EINVAL] +.I Whence +is not a proper value. +.SH "SEE ALSO" +.BR fcntl (2), +.BR open (2). +.SH BUGS +This document's use of +.I whence +is incorrect English, but maintained for historical reasons. diff --git a/man/man2/mkdir.2 b/man/man2/mkdir.2 new file mode 100644 index 000000000..19f531fa1 --- /dev/null +++ b/man/man2/mkdir.2 @@ -0,0 +1,112 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)mkdir.2 6.4 (Berkeley) 8/26/85 +.\" +.TH MKDIR 2 "August 26, 1985" +.UC 5 +.SH NAME +mkdir \- make a directory file +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int mkdir(const char *\fIpath\fP, mode_t \fImode\fP) +.fi +.ft R +.SH DESCRIPTION +.B Mkdir +creates a new directory file with name +.IR path . +The mode of the new file +is initialized from +.IR mode . +(The protection part of the mode +is modified by the process's mode mask; see +.BR umask (2)). +.PP +The directory's owner ID is set to the process's effective user ID. +The directory's group ID is set to that of the parent directory in +which it is created. +.PP +The low-order 9 bits of mode are modified by the process's +file mode creation mask: all bits set in the process's file mode +creation mask are cleared. See +.BR umask (2). +.SH "RETURN VALUE +A 0 return value indicates success. A \-1 return value +indicates an error, and an error code is stored in +.B errno. +.SH "ERRORS +.B Mkdir +will fail and no directory will be created if: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +A component of the path prefix does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EEXIST] +The named file exists. +.TP 15 +[ENOSPC] +The directory in which the entry for the new directory is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.TP 15 +[ENOSPC] +The new directory cannot be created because there +there is no space left on the file +system that will contain the directory. +.TP 15 +[ENOSPC] +There are no free inodes on the file system on which the +directory is being created. +.ig +.TP 15 +[EDQUOT] +The directory in which the entry for the new directory +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.TP 15 +[EDQUOT] +The new directory cannot be created because the user's +quota of disk blocks on the file system that will +contain the directory has been exhausted. +.TP 15 +[EDQUOT] +The user's quota of inodes on the file system on +which the directory is being created has been exhausted. +.. +.TP 15 +[EIO] +An I/O error occurred while making the directory entry or allocating the inode. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.SH "SEE ALSO" +.BR chmod (2), +.BR stat (2), +.BR umask (2). diff --git a/man/man2/mknod.2 b/man/man2/mknod.2 new file mode 100644 index 000000000..5981492d6 --- /dev/null +++ b/man/man2/mknod.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)mknod.2 6.4 (Berkeley) 5/23/86 +.\" +.TH MKNOD 2 "May 23, 1986" +.UC 4 +.SH NAME +mknod, mkfifo \- make a special file +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +int mknod(const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP) +int mkfifo(const char *\fIpath\fP, mode_t \fImode\fP) +.fi +.ft R +.SH DESCRIPTION +.B Mknod +creates a new file +whose name is +.I path. +The mode of the new file +(including special file bits) +is initialized from +.IR mode , +as defined in +.IR . +(The protection part of the mode +is modified by the process's mode mask (see +.BR umask (2))). +The first block pointer of the i-node +is initialized from +.I dev +and is used to specify which device the special file +refers to. +.PP +If mode indicates a block or character special file, +.I dev +is the device number of a character or block I/O device. +The low eight bits of the device number hold the minor device number +that selects a device among the devices governed by the same driver. +The driver is selected by the major device number, the next eight bits +of the device number. +.PP +If +.I mode +does not indicate a block special or character special device, +.I dev +is ignored. +(For example, when creating a ``fifo'' special file.) +.PP +.B Mknod +may be invoked only by the super-user, +unless it is being used to create a fifo. +.PP +The call +.BI "mkfifo(" path ", " mode ")" +is equivalent to +.PP +.RS +.BI "mknod(" path ", (" mode " & 0777) | S_IFIFO, 0)" +.RE +.SH "RETURN VALUE +Upon successful completion a value of 0 is returned. +Otherwise, a value of \-1 is returned and \fBerrno\fP +is set to indicate the error. +.SH ERRORS +.B Mknod +will fail and the file mode will be unchanged if: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +A component of the path prefix does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EPERM] +The process's effective user ID is not super-user. +.TP 15 +[EIO] +An I/O error occurred while making the directory entry or allocating the inode. +.TP 15 +[ENOSPC] +The directory in which the entry for the new node is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.TP 15 +[ENOSPC] +There are no free inodes on the file system on which the +node is being created. +.ig +.TP 15 +[EDQUOT] +The directory in which the entry for the new node +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.TP 15 +[EDQUOT] +The user's quota of inodes on the file system on +which the node is being created has been exhausted. +.. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EEXIST] +The named file exists. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.SH "SEE ALSO" +.BR chmod (2), +.BR stat (2), +.BR umask (2). diff --git a/man/man2/mount.2 b/man/man2/mount.2 new file mode 100644 index 000000000..d2711355f --- /dev/null +++ b/man/man2/mount.2 @@ -0,0 +1,51 @@ +.TH MOUNT 2 +.SH NAME +mount, umount \- mount or umount a file system +.SH SYNOPSIS +.ft B +.nf +#include +#include + +int mount(char *\fIspecial\fP, char *\fIname\fP, int \fIflag\fP) +int umount(char *\fIname\fP) +.fi +.ft P +.SH DESCRIPTION +.B Mount() +tells the system that the file system +.I special +is to be mounted on the file +.IR name , +effectively overlaying +.I name +with the file tree on +.IR special . +.I Name +may of any type, except that if the root of +.I special +is a directory, then +.I name +must also be a directory. +.I Special +must be a block special file, except for loopback mounts. For loopback +mounts a normal file or directory is used for +.IR special , +which must be seen as the root of a virtual device. +.I Flag +is 0 for a read-write mount, 1 for read-only. +.PP +.B Umount() +removes the connection between a device and a mount point, +.I name +may refer to either of them. If more than one device is mounted on the +same mount point then unmounting at the mount point removes the last mounted +device, unmounting a device removes precisely that device. The unmount will +only succeed if none of the files on the device are in use. +.PP +Both calls may only be executed by the super-user. +.SH "SEE ALSO" +.BR mount (1), +.BR umount (1). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man2/open.2 b/man/man2/open.2 new file mode 100644 index 000000000..f0613eb54 --- /dev/null +++ b/man/man2/open.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)open.2 6.4 (Berkeley) 5/14/86 +.\" +.TH OPEN 2 "May 14, 1986" +.UC 4 +.SH NAME +open \- open a file for reading or writing, or create a new file +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int open(const char *\fIpath\fP, int \fIflags\fP \fR[\fP, mode_t \fImode\fP\fR]\fP) +.ft R +.fi +.SH DESCRIPTION +.B Open +opens the file +.I path +for reading and/or writing, as specified by the +.I flags +argument and returns a descriptor for that file. +The +.I flags +argument may indicate the file is to be +created if it does not already exist (by specifying the +O_CREAT flag), in which case the file is created with mode +.I mode +as described in +.BR chmod (2) +and modified by the process' umask value (see +.BR umask (2)). +.PP +.I Path +is the address of a string of ASCII characters representing +a path name, terminated by a null character. +The flags specified are formed by +.IR or 'ing +the following values +.PP +.RS +.ta +12n +.nf +O_RDONLY open for reading only +O_WRONLY open for writing only +O_RDWR open for reading and writing +O_NONBLOCK do not block on open +O_APPEND append on each write +O_CREAT create file if it does not exist +O_TRUNC truncate size to 0 +O_EXCL error if create and file exists +.fi +.DT +.RE +.PP +Opening a file with O_APPEND set causes each write on the file +to be appended to the end. If O_TRUNC is specified and the +file exists, the file is truncated to zero length. +If O_EXCL is set with O_CREAT, then if the file already +exists, the open returns an error. This can be used to +implement a simple exclusive access locking mechanism. +If O_EXCL is set and the last component of the pathname is +a symbolic link, the open will fail even if the symbolic +link points to a non-existent name. +If the O_NONBLOCK flag is specified and the open call would result +in the process being blocked for some reason, the open returns immediately. +.PP +Upon successful completion a non-negative integer termed a +file descriptor is returned. +The file pointer used to mark the current position within the +file is set to the beginning of the file. +.PP +The new descriptor is set to remain open across +.BR execve +system calls; see +.BR close (2). +.PP +The system imposes a limit on the number of descriptors +open simultaneously by one process. +.SH "ERRORS +The named file is opened unless one or more of the +following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +O_CREAT is not set and the named file does not exist. +.TP 15 +[ENOENT] +A component of the path name that must exist does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EACCES] +The required permissions (for reading and/or writing) +are denied for the named file. +.TP 15 +[EACCES] +O_CREAT is specified, +the file does not exist, +and the directory in which it is to be created +does not permit writing. +.TP 15 +[EACCES] +A device to be opened for writing is physically write protected. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EISDIR] +The named file is a directory, and the arguments specify +it is to be opened for writing. +.TP 15 +[EROFS] +The named file resides on a read-only file system, +and the file is to be modified. +.TP 15 +[EMFILE] +The system limit for open file descriptors per process has already been reached. +.TP 15 +[ENFILE] +The system file table is full. +.TP 15 +[ENXIO] +The named file is a character special or block +special file, and the device associated with this special file +does not exist. +.TP 15 +[ENOSPC] +O_CREAT is specified, +the file does not exist, +and the directory in which the entry for the new file is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.TP 15 +[ENOSPC] +O_CREAT is specified, +the file does not exist, +and there are no free inodes on the file system on which the +file is being created. +.ig +.TP 15 +[EDQUOT] +O_CREAT is specified, +the file does not exist, +and the directory in which the entry for the new fie +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.TP 15 +[EDQUOT] +O_CREAT is specified, +the file does not exist, +and the user's quota of inodes on the file system on +which the file is being created has been exhausted. +.. +.TP 15 +[EIO] +An I/O error occurred while making the directory entry or +allocating the inode for O_CREAT. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EEXIST] +O_CREAT and O_EXCL were specified and the file exists. +.SH "SEE ALSO" +.BR chmod (2), +.BR close (2), +.BR dup (2), +.BR fcntl (2), +.BR lseek (2), +.BR read (2), +.BR write (2), +.BR umask (2). diff --git a/man/man2/pause.2 b/man/man2/pause.2 new file mode 100644 index 000000000..2bdaa3b4f --- /dev/null +++ b/man/man2/pause.2 @@ -0,0 +1,43 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)pause.3c 6.1 (Berkeley) 5/9/85 +.\" +.TH PAUSE 2 "May 9, 1985" +.UC 4 +.SH NAME +pause \- stop until signal +.SH SYNOPSIS +.nf +.ft B +#include + +int pause(void) +.ft R +.fi +.SH DESCRIPTION +.B Pause +never returns normally. +It is used to give up control while waiting for +a signal from +.BR kill (2) +or the alarm timer, see +.BR alarm (2). +Upon termination of a signal handler started during a +.B pause, +the +.B pause +call will return. +.SH "RETURN VALUE +Always returns \-1. +.SH ERRORS +.B Pause +always returns: +.TP 15 +[EINTR] +The call was interrupted. +.SH "SEE ALSO +.BR alarm (2), +.BR kill (2), +.BR sigsuspend (2). diff --git a/man/man2/pipe.2 b/man/man2/pipe.2 new file mode 100644 index 000000000..3cb1107c2 --- /dev/null +++ b/man/man2/pipe.2 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)pipe.2 6.2 (Berkeley) 8/26/85 +.\" +.TH PIPE 2 "August 26, 1985" +.UC 4 +.SH NAME +pipe \- create an interprocess communication channel +.SH SYNOPSIS +.nf +.ft B +#include + +int pipe(int \fIfildes\fP[2]) +.fi +.ft R +.SH DESCRIPTION +The +.B pipe +system call +creates an I/O mechanism called a pipe. +The file descriptors returned can +be used in read and write operations. +When the pipe is written using the descriptor +.IR fildes [1] +up to PIPE_MAX bytes of data are buffered +before the writing process is suspended. +A read using the descriptor +.IR fildes [0] +will pick up the data. +.PP +PIPE_MAX equals 7168 under Minix, but note that most systems use 4096. +.PP +It is assumed that after the +pipe has been set up, +two (or more) +cooperating processes +(created by subsequent +.B fork +calls) +will pass data through the +pipe with +.B read +and +.B write +calls. +.PP +The shell has a syntax +to set up a linear array of processes +connected by pipes. +.PP +Read calls on an empty +pipe (no buffered data) with only one end +(all write file descriptors closed) +returns an end-of-file. +.PP +The signal SIGPIPE is generated if a write on a pipe with only one end +is attempted. +.SH "RETURN VALUE +The function value zero is returned if the +pipe was created; \-1 if an error occurred. +.SH ERRORS +The \fBpipe\fP call will fail if: +.TP 15 +[EMFILE] +Too many descriptors are active. +.TP 15 +[ENFILE] +The system file table is full. +.TP 15 +[ENOSPC] +The pipe file system (usually the root file system) has no free inodes. +.TP 15 +[EFAULT] +The \fIfildes\fP buffer is in an invalid area of the process's address +space. +.SH "SEE ALSO" +.BR sh (1), +.BR read (2), +.BR write (2), +.BR fork (2). +.SH NOTES +Writes may return ENOSPC errors if no pipe data can be buffered, because +the pipe file system is full. +.SH BUGS +Should more than PIPE_MAX bytes be necessary in any +pipe among a loop of processes, deadlock will occur. diff --git a/man/man2/ptrace.2 b/man/man2/ptrace.2 new file mode 100644 index 000000000..d14f67605 --- /dev/null +++ b/man/man2/ptrace.2 @@ -0,0 +1,231 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)ptrace.2 6.4 (Berkeley) 5/23/86 +.\" +.TH PTRACE 2 "May 23, 1986" +.UC 4 +.SH NAME +ptrace \- process trace +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +int ptrace(int \fIrequest\fP, pid_t \fIpid\fP, long \fIaddr\fP, long \fIdata\fP) +.ft R +.fi +.SH DESCRIPTION +.ft B +Note: This manual page has no relation to Minix. Someone who knows ptrace() +has to check, or rewrite, this page. (kjb) +.ft R +.PP +.B Ptrace +provides a means by which a parent process +may control the execution of a child process, +and examine and change its core image. +Its primary use is for the implementation of breakpoint debugging. +There are four arguments whose interpretation +depends on a +.I request +argument. +Generally, +.I pid +is the process ID of the traced process, +which must be a child (no more distant descendant) +of the tracing process. +A process being traced +behaves normally until it encounters some signal +whether internally generated +like \*(lqillegal instruction\*(rq or externally +generated like \*(lqinterrupt\*(rq. +See +.BR sigaction (2) +for the list. +Then the traced process enters a stopped state +and its parent is notified via +.BR wait (2). +When the child is in the stopped state, +its core image can be examined and modified +using +.BR ptrace . +If desired, another +.B ptrace +request can then cause the child either to terminate +or to continue, possibly ignoring the signal. +.PP +The value of the +.I request +argument determines the precise +action of the call: +.TP 4 +PT_TRACE_ME +This request is the only one used by the child process; +it declares that the process is to be traced by its parent. +All the other arguments are ignored. +Peculiar results will ensue +if the parent does not expect to trace the child. +.TP 4 +PT_READ_I, PT_READ_D +The +word in the child process's address space +at +.I addr +is returned. +If I and D space are separated (e.g. historically +on a pdp-11), request PT_READ_I indicates I space, +PT_READ_D D space. +.I Addr +must be even on some machines. +The child must be stopped. +The input +.I data +is ignored. +.TP 4 +PT_READ_U +The word +of the system's per-process data area corresponding to +.I addr +is returned. +.I Addr +must be even on some machines and less than 512. +This space contains the registers and other information about +the process; +its layout corresponds to the +.I user +structure in the system. +.TP 4 +PT_WRITE_I, PT_WRITE_D +The +given +.I data +is written at the word in the process's address space corresponding to +.I addr, +which must be even on some machines. +No useful value is returned. +If I and D space are separated, request PT_WRITE_I indicates I space, +PT_WRITE_D D space. +Attempts to write in pure procedure +fail if another process is executing the same file. +.TP 4 +PT_WRITE_U +The process's system data is written, +as it is read with request PT_READ_U. +Only a few locations can be written in this way: +the general registers, +the floating point status and registers, +and certain bits of the processor status word. +.TP 4 +PT_CONTINUE +The +.I data +argument is taken as a signal number +and the child's execution continues +at location +.I addr +as if it had incurred that signal. +Normally the signal number will be +either 0 to indicate that the signal that caused the stop +should be ignored, +or that value fetched out of the +process's image indicating which signal caused +the stop. +If +.I addr +is (int *)1 then execution continues from where it stopped. +.TP 4 +PT_KILL +The traced process terminates. +.TP 4 +PT_STEP +Execution continues as in request PT_CONTINUE; +however, as soon as possible after execution of at least one instruction, +execution stops again. +The signal number from the stop is +SIGTRAP. +(On the VAX-11 the T-bit is used and just one instruction +is executed.) +This is part of the mechanism for implementing breakpoints. +.PP +As indicated, +these calls +(except for request PT_TRACE_ME) +can be used only when the subject process has stopped. +The +.B wait +call is used to determine +when a process stops; +in such a case the \*(lqtermination\*(rq status +returned by +.B wait +has the value 0177 to indicate stoppage rather +than genuine termination. +.PP +To forestall possible fraud, +.B ptrace +inhibits the set-user-id and set-group-id facilities +on subsequent +.BR execve (2) +calls. +If a traced process calls +.BR execve , +it will stop before executing the first instruction of the new image +showing signal SIGTRAP. +.PP +On a VAX-11, \*(lqword\*(rq also means a 32-bit integer, +but the \*(lqeven\*(rq +restriction does not apply. +.SH "RETURN VALUE +A 0 value is returned if the call succeeds. If the call fails +then a \-1 is returned and the global variable \fIerrno\fP is +set to indicate the error. +.SH "ERRORS +.TP 15 +[EIO] +The request code is invalid. +.TP 15 +[ESRCH] +The specified process does not exist. +.TP 15 +[EIO] +The given signal number is invalid. +.TP 15 +[EIO] +The specified address is out of bounds. +.TP 15 +[EPERM] +The specified process cannot be traced. +.SH "SEE ALSO" +.BR wait (2), +.BR sigaction (2), +.BR mdb (1). +.SH BUGS +.B Ptrace +is unique and arcane; it should be replaced with a special file that +can be opened and read and written. The control functions could then +be implemented with +.BR ioctl (2) +calls on this file. This would be simpler to understand and have much +higher performance. +.PP +The request PT_TRACE_ME call should be able to specify +signals that are to be treated normally and not cause a stop. +In this way, for example, +programs with simulated floating point (which +use \*(lqillegal instruction\*(rq signals at a very high rate) +could be efficiently debugged. +.PP +The error indication, \-1, is a legitimate function value; +.BR errno , +(see +.BR intro (2)), +can be used to disambiguate. +.PP +It should be possible to stop a process on occurrence of a system +call; +in this way a completely controlled environment could +be provided. diff --git a/man/man2/read.2 b/man/man2/read.2 new file mode 100644 index 000000000..4326ac06a --- /dev/null +++ b/man/man2/read.2 @@ -0,0 +1,83 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)read.2 6.6 (Berkeley) 5/23/86 +.\" +.TH READ 2 "May 23, 1986" +.UC 4 +.SH NAME +read \- read input +.SH SYNOPSIS +.nf +.ft B +#include +#include + +ssize_t read(int \fId\fP, void *\fIbuf\fP, size_t \fInbytes\fP) +.fi +.SH DESCRIPTION +.B Read +attempts to read +.I nbytes +of data from the object referenced by the descriptor +.I d +into the buffer pointed to by +.IR buf . +.PP +On objects capable of seeking, the +.B read +starts at a position +given by the pointer associated with +.IR d +(see +.BR lseek (2)). +Upon return from +.BR read , +the pointer is incremented by the number of bytes actually read. +.PP +Objects that are not capable of seeking always read from the current +position. The value of the pointer associated with such an +object is undefined. +.PP +Upon successful completion, +.B read +return the number of bytes actually read and placed in the buffer. +The system guarantees to read the number of bytes requested if +the descriptor references a normal file that has that many bytes left +before the end-of-file, but in no other case. +.PP +If the returned value is 0, then +end-of-file has been reached. +.SH "RETURN VALUE +If successful, the +number of bytes actually read is returned. +Otherwise, a \-1 is returned and the global variable +.B errno +is set to indicate the error. +.SH "ERRORS +.B Read +will fail if one or more of the following are true: +.TP 15 +[EBADF] +\fID\fP is not a valid descriptor open for reading. +.TP 15 +[EFAULT] +\fIBuf\fP points outside the allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading from the file system. +.TP 15 +[EINTR] +A read from a slow device was interrupted before +any data arrived by the delivery of a signal. +.TP 15 +[EAGAIN] +The file was marked for non-blocking I/O, +and no data were ready to be read. +.SH "SEE ALSO" +.BR dup (2), +.BR fcntl (2), +.BR open (2), +.BR pipe (2), +.BR write (2). diff --git a/man/man2/reboot.2 b/man/man2/reboot.2 new file mode 100644 index 000000000..b6b1a3573 --- /dev/null +++ b/man/man2/reboot.2 @@ -0,0 +1,62 @@ +.TH REBOOT 2 +.SH NAME +reboot \- close down the system or reboot +.SH SYNTAX +.ft B +.nf +#define _MINIX_SOURCE 1 + +#include + +int reboot(int \fIhow\fP, ...) +.fi +.ft P +.SH DESCRIPTION +.B Reboot() +is used to close down the system. It allows several ways of shutting +down depending on +.IR how : +.PP +.TP 5 +.BI "reboot(RBT_HALT)" +Halt the system and return to the monitor prompt. +.TP +.BI "reboot(RBT_REBOOT)" +Reboot the system by letting the monitor execute the "boot" command. +.TP +.BI "reboot(RBT_PANIC)" +Cause a system panic. This is not normally done from user mode, but by +servers using the +.B sys_abort() +kernel call. +.TP +.BI "reboot(RBT_MONITOR" ", code, length" ")" +Halt the system and let the monitor execute the given code of the given +length. +.RI ( code +is of type +.B "char *" +and +.I length +of type +.BR size_t .) +.TP +.BI "reboot(RBT_RESET)" +Reboot the system with a hardware reset. +.PP +.B Reboot() +may only be executed by the super-user. +.SH DIAGNOSTICS +If the call succeeds, it never returns. If something went wrong, +the return value is -1 and an error is indicated by +.BR errno . +.SH SEE ALSO +.BR shutdown (8), +.BR reboot (8), +.BR halt (8), +.BR sync (2). +.SH NOTES +Minix can not return to the monitor if running in real mode. This means +that most of the reboot functions will change to a system reset. +.SH AUTHOR +Edvard Tuinder (v892231@si.hhs.NL) diff --git a/man/man2/rename.2 b/man/man2/rename.2 new file mode 100644 index 000000000..1f675acfd --- /dev/null +++ b/man/man2/rename.2 @@ -0,0 +1,135 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rename.2 6.4 (Berkeley) 5/22/86 +.\" +.TH RENAME 2 "May 22, 1986" +.UC 5 +.SH NAME +rename \- change the name of a file +.SH SYNOPSIS +.ft B +.nf +#include + +int rename(const char *\fIfrom\fP, const char *\fIto\fP) +.fi +.ft R +.SH DESCRIPTION +.B Rename +causes the link named +.I from +to be renamed as +.IR to . +If +.I to +exists, then it is first removed. +Both +.I from +and +.I to +must be of the same type (that is, both directories or both +non-directories), and must reside on the same file system. +.PP +.B Rename +guarantees that an instance of +.I to +will always exist, even if the system should crash in +the middle of the operation. +.PP +If the final component of +.I from +is a symbolic link, +the symbolic link is renamed, +not the file or directory to which it points. +.SH "RETURN VALUE" +A 0 value is returned if the operation succeeds, otherwise +.B rename +returns \-1 and the global variable +.B errno +indicates the reason for the failure. +.SH "ERRORS +.B Rename +will fail and neither of the argument files will be +affected if any of the following are true: +.TP 15 +[ENAMETOOLONG] +A path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +A component of the \fIfrom\fP path does not exist, +or a path prefix of \fIto\fP does not exist. +.TP 15 +[EACCES] +A component of either path prefix denies search permission. +.TP 15 +[EACCES] +The requested link requires writing in a directory with a mode +that denies write permission. +.TP 15 +[EPERM] +The directory containing \fIfrom\fP is marked sticky, +and neither the containing directory nor \fIfrom\fP +are owned by the effective user ID. +.TP 15 +[EPERM] +The \fIto\fP file exists, +the directory containing \fIto\fP is marked sticky, +and neither the containing directory nor \fIto\fP +are owned by the effective user ID. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating either pathname. +(Minix-vmd) +.TP 15 +[ENOTDIR] +A component of either path prefix is not a directory. +.TP 15 +[ENOTDIR] +.I From +is a directory, but \fIto\fP is not a directory. +.TP 15 +[EISDIR] +.I To +is a directory, but \fIfrom\fP is not a directory. +.TP 15 +[EXDEV] +The link named by \fIto\fP and the file named by \fIfrom\fP +are on different logical devices (file systems). +.TP 15 +[ENOSPC] +The directory in which the entry for the new name is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.ig +.TP 15 +[EDQUOT] +The directory in which the entry for the new name +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.. +.TP 15 +[EIO] +An I/O error occurred while making or updating a directory entry. +.TP 15 +[EROFS] +The requested link requires writing in a directory on a read-only file +system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.TP 15 +[EINVAL] +.I From +is a parent directory of +.IR to , +or an attempt is made to rename ``.'' or ``..''. +.TP 15 +[ENOTEMPTY] +.I To +is a directory and is not empty. +.SH "SEE ALSO" +.BR open (2) diff --git a/man/man2/rmdir.2 b/man/man2/rmdir.2 new file mode 100644 index 000000000..5ed045443 --- /dev/null +++ b/man/man2/rmdir.2 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rmdir.2 6.3 (Berkeley) 8/26/85 +.\" +.TH RMDIR 2 "August 26, 1985" +.UC 5 +.SH NAME +rmdir \- remove a directory file +.SH SYNOPSIS +.nf +.ft B +#include + +int rmdir(const char *\fIpath\fP) +.fi +.ft R +.SH DESCRIPTION +.B Rmdir +removes a directory file +whose name is given by +.I path. +The directory must not have any entries other +than \*(lq.\*(rq and \*(lq..\*(rq. +.SH "RETURN VALUE +A 0 is returned if the remove succeeds; otherwise a \-1 is +returned and an error code is stored in the global location \fIerrno\fP\|. +.SH ERRORS +The named file is removed unless one or more of the +following are true: +.TP 15 +[ENOTDIR] +A component of the path is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named directory does not exist. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[ENOTEMPTY] +The named directory contains files other than ``.'' and ``..'' in it. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EACCES] +Write permission is denied on the directory containing the link +to be removed. +.TP 15 +[EPERM] +The directory containing the directory to be removed is marked sticky, +and neither the containing directory nor the directory to be removed +are owned by the effective user ID. +.TP 15 +[EBUSY] +The directory to be removed is the mount point +for a mounted file system. +.TP 15 +[EIO] +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.TP 15 +[EROFS] +The directory entry to be removed resides on a read-only file system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.SH "SEE ALSO" +.BR mkdir (2), +.BR unlink (2). diff --git a/man/man2/setsid.2 b/man/man2/setsid.2 new file mode 100644 index 000000000..f0fae84e5 --- /dev/null +++ b/man/man2/setsid.2 @@ -0,0 +1,40 @@ +.TH SETSID 2 +.SH NAME +setsid, getpgrp \- create process group, get process group id +.SH SYNOPSIS +.ft B +.nf +#include +#include + +pid_t setsid(void) +pid_t getpgrp(void) +.fi +.ft P +.SH DESCRIPTION +.B Setsid() +creates a new session if the calling process is not already a session +leader. The calling process becomes the session leader of a new process +group and the process group ID of this new process group will be equal to +the process ID of the new session leader. The process group ID is inherited +on a +.BR fork (2). +.PP +.B Getpgrp() +returns the process group ID of the calling process. +.SH "SEE ALSO" +.BR kill (2), +.BR termios (3), +.BR tty (4). +.SH DIAGNOSTICS +.B Setsid() +returns the new process group ID on success, or \-1 with +.B errno +set to +.B EPERM +if the process is already a session leader. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: setsid.2,v 1.2 1996/04/11 06:06:36 philip Exp $ diff --git a/man/man2/setuid.2 b/man/man2/setuid.2 new file mode 100644 index 000000000..a36dc4d48 --- /dev/null +++ b/man/man2/setuid.2 @@ -0,0 +1,48 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)setreuid.2 6.1 (Berkeley) 5/9/85 +.\" +.TH SETUID 2 "May 9, 1985" +.UC 4 +.SH NAME +setuid, setgid \- set user or group ID's +.SH SYNOPSIS +.nf +.ft B +#include + +int setuid(uid_t \fIuid\fP) +int setgid(gid_t \fIgid\fP) +.ft R +.fi +.SH DESCRIPTION +.B Setuid +sets the real and effective user ID's of the +current process to +.IR uid . +Unprivileged users may only change both user ID's +to the real user ID; only the super-user may +make other changes. +.B Setgid +does the same for the real and effective group ID's. +.PP +Minix-vmd +allows an unprivileged user to change ID's to the original real or effective +ID as they were at the time the process was executed. +.B Setgid +may also set the group ID's to any of the additional group ID's. +If one of the +remembered user ID's was 0 then any user or group ID may be chosen. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. Otherwise, +a value of \-1 is returned and \fBerrno\fP is set to indicate the error. +.SH "ERRORS +.TP 15 +[EPERM] +The current process is not the super-user and a change +other than one of the allowed changes was attempted. +.SH "SEE ALSO" +.BR getuid (2), +.BR getgid (2). diff --git a/man/man2/sigaction.2 b/man/man2/sigaction.2 new file mode 100644 index 000000000..fce981b95 --- /dev/null +++ b/man/man2/sigaction.2 @@ -0,0 +1,244 @@ +.TH SIGACTION 2 +.SH NAME +sigaction, signal \- manage signal state and handlers +.SH SYNOPSIS +.ft B +#include + +.in +5 +.ti -5 +int sigaction(int \fIsig\fP, const struct sigaction *\fIact\fP, struct sigaction *\fIoact\fP) +.in -5 +.br +void (*signal(int \fIsig\fP, void (*\fIhandler\fP)(int)))(int); +.ft P +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +.B Sigaction() +is used to examine, set, or modify the attributes of a signal. The argument +.I sig +is the signal in question. The +.I act +argument points to a structure containing the new attributes of the signal, +the structure pointed to by +.I oact +will receive the old attributes that were in effect before the call. +.PP +The +.I act +and +.I oact +arguments may be +.B NULL +to indicate that either no new attributes are to be set, or that the old +attributes are not of interest. +.PP +The structure containing the signal attributes is defined in and +looks like this: +.PP +.RS +.nf +.ft B +.ta +4n +12n +struct sigaction { + void (*sa_handler)(int sig); + sigset_t sa_mask; + int sa_flags; +}; +.ft R +.fi +.RE +.PP +The +.B sa_handler +field contains the address of a signal handler, a function that is called +when the process is signalled, or one of these special constants: +.PP +.TP 12 +.B SIG_DFL +Default signal handling is to be performed. This usually means that the +process is killed, but some signals may be ignored by default. +.TP +.B SIG_IGN +Ignore the signal. +.PP +The +.B sa_mask +field indicates a set of signals that must be blocked when the signal is +being handled. Whether the signal +.I sig +itself is blocked when being handled is not controlled by this mask. The +mask is of a "signal set" type that is to be manipulated by the +.BR sigset (3) +functions. +.PP +How the signal is handled precisely is specified by bits in +.BR sa_flags . +If none of the flags is set then the handler is called when the signal +arrives. The signal is blocked during the call to the handler, and +unblocked when the handler returns. A system call that is interrupted +returns +.B \-1 +with +.B errno +set to +.BR EINTR . +The following bit flags can be set to modify this behaviour: +.PP +.TP 15 +.B SA_RESETHAND +Reset the signal handler to +.B SIG_DFL +when the signal is caught. +.TP +.B SA_NODEFER +Do not block the signal on entry to the handler. +.TP +.B SA_COMPAT +Handle the signal in a way that is compatible with the the old +.B signal() +call. +.PP +The old +.B signal() +signal system call sets a signal handler for a given signal and returns the +old signal handler. No signals are blocked, the flags are +.BR "SA_RESETHAND | SA_NODEFER | SA_COMPAT" . +New code should not use +.BR signal() . +Note that +.B signal() +and all of the +.B SA_* +flags are Minix extensions. +.PP +Signal handlers are reset to +.B SIG_DFL +on an +.BR execve (2). +Signals that are ignored stay ignored. +.SS Signals +Minix knows about the following signals: +.PP +.nf +.ta +11n +7n +8n +signal num notes description +.SP +SIGHUP 1 k Hangup +SIGINT 2 k Interrupt (usually DEL or CTRL\-C) +SIGQUIT 3 kc Quit (usually CTRL\-\e) +SIGILL 4 kc Illegal instruction +SIGTRAP 5 xkc Trace trap +SIGABRT 6 kc Abort program +SIGFPE 8 k Floating point exception +SIGKILL 9 k Kill +SIGUSR1 10 k User defined signal #1 +SIGSEGV 11 kc Segmentation fault +SIGUSR2 12 k User defined signal #2 +SIGPIPE 13 k Write to a pipe with no reader +SIGALRM 14 k Alarm clock +SIGTERM 15 k Terminate (default for kill(1)) +SIGCHLD 17 pvi Child process terminated +SIGCONT 18 p Continue if stopped +SIGSTOP 19 ps Stop signal +SIGTSTP 20 ps Interactive stop signal +SIGTTIN 21 ps Background read +SIGTTOU 22 ps Background write +SIGWINCH 23 xvi Window size change +.ft R +.fi +.PP +The letters in the notes column indicate: +.PP +.TP 5 +.B k +The process is killed if the signal is not caught. +.TP +.B c +The signal causes a core dump. +.TP +.B i +The signal is ignored if not caught. +.TP +.B v +Only Minix-vmd implements this signal. +.TP +.B x +Minix extension, not defined by \s-2POSIX\s+2. +.TP +.B p +These signals are not implemented, but \s-2POSIX\s+2 requires that they are +defined. +.TP +.B s +The process should be stopped, but is killed instead. +.PP +The +.B SIGKILL +signal cannot be caught or ignored. The +.B SIGILL +and +.B SIGTRAP +signals cannot be automatically reset. The system silently enforces these +restrictions. This may or may not be reflected by the attributes of these +signals and the signal masks. +.SS Types +\s-2POSIX\s+2 prescribes that has the following definition: +.PP +.RS +.B "typedef int (*sighandler_t)(int)" +.RE +.PP +With this type the following declarations can be made: +.PP +.RS +.ft B +.nf +sighandler_t sa_handler; +sighandler_t signal(int \fIsig\fP, sighandler_t \fIhandler\fP); +.fi +.ft R +.RE +.PP +This may help you to understand the earlier declarations better. The +.B sighandler_t +type is also very useful in old style C code that is compiled by a compiler +for standard C. +.SH "SEE ALSO" +.BR kill (1), +.BR kill (2), +.BR pause (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigpending (2), +.BR sigset (3). +.SH DIAGNOSTICS +.B Sigaction() +returns +.B 0 +on success or +.B \-1 +on error. +.B Signal() +returns the old handler on success or +.B SIG_ERR +on error. The error code may be: +.PP +.TP 10 +.B EINVAL +Bad signal number. +.TP +.B EFAULT +Bad +.I act +or +.I oact +addresses. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: sigaction.2,v 1.2 1996/04/11 06:00:28 philip Exp $ diff --git a/man/man2/sigpending.2 b/man/man2/sigpending.2 new file mode 100644 index 000000000..e3341160f --- /dev/null +++ b/man/man2/sigpending.2 @@ -0,0 +1,33 @@ +.TH SIGPENDING 2 +.SH NAME +sigpending \- report pending signals +.SH SYNOPSIS +.ft B +#include + +int sigpending(sigset_t *\fIset\fP) +.ft P +.SH DESCRIPTION +.B Sigpending() +returns the set of signals that are waiting to be delivered. They are +currently blocked by the signal mask. +.SH "SEE ALSO" +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigset (3). +.SH DIAGNOSTICS +Returns +.B 0 +on success and +.B \-1 +on error. The only possible error code is +.B EFAULT +for a bad +.I set +address. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: sigpending.2,v 1.2 1996/04/11 06:01:22 philip Exp $ diff --git a/man/man2/sigprocmask.2 b/man/man2/sigprocmask.2 new file mode 100644 index 000000000..ac610f082 --- /dev/null +++ b/man/man2/sigprocmask.2 @@ -0,0 +1,75 @@ +.TH SIGPROCMASK 2 +.SH NAME +sigprocmask \- manipulate the signal mask +.SH SYNOPSIS +.ft B +#include + +int sigprocmask(int \fIhow\fP, const sigset_t *\fIset\fP, sigset_t *\fIoset\fP) +.ft P +.SH DESCRIPTION +.B Sigprocmask() +examines or manipulates the signal mask. This mask is the set of signals +that are currently blocked. The +.I how +argument determines the action that must be performed. In all cases the +signal set referenced by +.IR oset , +if not +.BR NULL , +will be used to receive the old signal mask. The +.I set +argument, if not +.BR NULL , +will be used to set or modify the current signal mask. +.PP +.I How +can be one of: +.PP +.TP 15 +.B SIG_BLOCK +Add the signals referenced by +.I set +to the mask. +.TP +.B SIG_UNBLOCK +Remove the signals referenced by +.I set +from the mask. +.TP +.B SIG_SETMASK +Set the signal mask to the set referenced by +.IR set . +.PP +The value of +.I how +is ignored if +.I set +is +.BR NULL . +.SH "SEE ALSO" +.BR sigaction (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR sigset (3). +.SH DIAGNOSTICS +Returns +.B 0 +on success and +.B \-1 +on error. The error code is +.B EFAULT +for a bad +.I set +or +.I oset +address, or +.B EINVAL +for a bad +.I how +argument. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: sigprocmask.2,v 1.2 1996/04/11 06:02:09 philip Exp $ diff --git a/man/man2/sigsuspend.2 b/man/man2/sigsuspend.2 new file mode 100644 index 000000000..c770c0555 --- /dev/null +++ b/man/man2/sigsuspend.2 @@ -0,0 +1,39 @@ +.TH SIGSUSPEND 2 +.SH NAME +sigsuspend \- suspend until signalled +.SH SYNOPSIS +.ft B +#include + +int sigsuspend(const sigset_t *\fIset\fP) +.ft P +.SH DESCRIPTION +.B Sigsuspend() +installs the signal mask referenced by +.I set +and suspends the process until signalled. The signal is handled, the signal +mask is restored to the value it had before the +.B sigsuspend() +call and call returns. +.SH "SEE ALSO" +.BR pause (2), +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigset (3). +.SH DIAGNOSTICS +.B Sigsuspend() +never returns normally, so it always returns +.BR \-1 . +The error code is either +.B EINTR +indicating that a signal has arrived, or +.B EFAULT +for a bad +.I set +address. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: sigsuspend.2,v 1.2 1996/04/11 06:02:41 philip Exp $ diff --git a/man/man2/stat.2 b/man/man2/stat.2 new file mode 100644 index 000000000..beca49cb1 --- /dev/null +++ b/man/man2/stat.2 @@ -0,0 +1,181 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)stat.2 6.5 (Berkeley) 5/12/86 +.\" +.TH STAT 2 "May 12, 1986" +.UC 4 +.SH NAME +stat, lstat, fstat \- get file status +.SH SYNOPSIS +.nf +.ft B +#include +#include + +.ta +54n +int stat(const char *\fIpath\fP, struct stat *\fIbuf\fP) +int lstat(const char *\fIpath\fP, struct stat *\fIbuf\fP) (Minix-vmd) +int fstat(int \fIfd\fP, struct stat *\fIbuf\fP) +.fi +.ft R +.SH DESCRIPTION +.B Stat +obtains information about the file +.IR path . +Read, write or execute +permission of the named file is not required, but all directories +listed in the path name leading to the file must be reachable. +.PP +.B Lstat +is like \fBstat\fP except in the case where the named file is a symbolic link, +in which case +.B lstat +returns information about the link, +while +.B stat +returns information about the file the link references. +(Minix-vmd) +.PP +.B Fstat +obtains the same information about an open file +referenced by the argument descriptor, such as would +be obtained by an \fBopen\fP call. Pipe descriptors +look like named pipes with a link count of zero. The +st_size field of pipes or named pipes shows the amount of +bytes currently buffered in the pipe. +.PP +.I Buf +is a pointer to a +.B stat +structure into which information is placed concerning the file. +The contents of the structure pointed to by +.I buf +is as follows: +.PP +.if t .RS +.nf +.ta +0.4i +0.8i +1i +struct stat { + dev_t st_dev; /* device inode resides on */ + ino_t st_ino; /* this inode's number */ + mode_t st_mode; /* file mode, protection bits, etc. */ + nlink_t st_nlink; /* number or hard links to the file */ + uid_t st_uid; /* user-id of the file's owner */ + gid_t st_gid; /* group-id of the file's owner */ + dev_t st_rdev; /* the device type, for inode that is device */ + off_t st_size; /* total size of file */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last data modification */ + time_t st_ctime; /* time of last file status change */ +}; +.fi +.if t .RE +.DT +.PP +.TP 12 +st_atime +Time when file data was last read or modified. Changed by the following system +calls: +.BR mknod (2), +.BR utime (2), +.BR read (2), +and +.BR write (2). +For reasons of efficiency, +st_atime is not set when a directory +is searched, although this would be more logical. +.TP 12 +st_mtime +Time when data was last modified. +It is not set by changes of owner, group, link count, or mode. +Changed by the following system calls: +.BR mknod (2), +.BR utime (2), +.BR write (2). +.TP 12 +st_ctime +Time when file status was last changed. +It is set both both by writing and changing the i-node. +Changed by the following system calls: +.BR chmod (2) +.BR chown (2), +.BR link (2), +.BR mknod (2), +.BR rename (2), +.BR unlink (2), +.BR utime (2), +.BR write (2). +.PP +The file type information in \fBst_mode\fP has bits: +.PP +.nf +.in +5n +.ta 1.6i 2.5i 3i +#define S_IFMT 0170000 /* type of file */ +#define\ \ \ \ S_IFIFO 0010000 /* named pipe */ +#define\ \ \ \ S_IFCHR 0020000 /* character special */ +#define\ \ \ \ S_IFDIR 0040000 /* directory */ +#define\ \ \ \ S_IFBLK 0060000 /* block special */ +#define\ \ \ \ S_IFREG 0100000 /* regular */ +#define\ \ \ \ S_IFLNK 0120000 /* symbolic link (Minix-vmd) */ +.fi +.in -5n +.PP +The mode bits 0007777 encode set-uid/gid bits and +permission bits (see +.BR chmod (2)). +.SH "RETURN VALUE +Upon successful completion a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +.B Stat +and +.B lstat +will fail if one or more of the following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EFAULT] +.I Buf +or +.I name +points to an invalid address. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.PP +.B Fstat +will fail if one or both of the following are true: +.TP 15 +[EBADF] +.I Fildes +is not a valid open file descriptor. +.TP 15 +[EFAULT] +.I Buf +points to an invalid address. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.SH "SEE ALSO" +.BR chmod (2), +.BR chown (2), +.BR utime (2). diff --git a/man/man2/svrctl.2 b/man/man2/svrctl.2 new file mode 100644 index 000000000..00af640dc --- /dev/null +++ b/man/man2/svrctl.2 @@ -0,0 +1,59 @@ +.\" svrctl.2 +.\" +.\" Created: July, 1994 by Philip Homburg +.TH svrctl 2 +.SH NAME +svrctl \- special server control functions +.SH SYNOPSIS +.nf +.ft B +#include + +int svrctl(u32_t \fIrequest\fP, void *\fIdata\fP); +.ft R +.fi +.SH DESCRIPTION +.B Svrctl +allows root to control the kernel in various ways, or implements some very +Minix specific system calls that don't deserve their own system call number. +.PP +This system call makes it easy to add new ways of setting and getting kernel +parameters, but at the same time, backwards compatibility is not guaranteed. +Read the include file to see what the struct's mentioned below +look like. Most calls are root-only, unless specified otherwise. +.PP +The only way to know how to properly use these calls is to study the +associated kernel or server code, or the programs that already use these +calls. +.PP +Current requests are: +.TP 5 +.B MMSIGNON +Inform MM that the current process wants to become a server. +.TP +.B MMSWAPON +Instruct MM to mount a file or device as swapspace. +.TP +.B MMSWAPOFF +Tell MM to stop using swapspace. +.TP +.B FSSIGNON +Register a new device with FS. +.ig +.TP +.B FSDEVMAP +Translate a device number to a task number, minor device pair using a +\fBstruct fsdevmap\fP +.. +.TP +.B SYSSIGNON +Inform the kernel that the process want to become a server. +The processes task number is filled-in in a \fBstruct systaskinfo\fP. +.TP +.B SYSGETENV +Request the value of one or all boot parameters. Can be used by non-root. +.SH "RETURN VALUES" +.B Svrctl +returns 0 upon success and -1 upon failure. +.SH AUTHOR +Philip Homburg diff --git a/man/man2/sync.2 b/man/man2/sync.2 new file mode 100644 index 000000000..c769d69b5 --- /dev/null +++ b/man/man2/sync.2 @@ -0,0 +1,27 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)sync.2 6.2 (Berkeley) 6/30/85 +.\" +.TH SYNC 2 "June 30, 1985" +.UC 4 +.SH NAME +sync \- update super-block +.SH SYNOPSIS +.nf +.ft B +#include + +int sync(void) +.ft R +.fi +.SH DESCRIPTION +.B Sync +causes all information in the file system +buffers that should be on disk to be written out. +This includes modified super blocks, +modified i-nodes, and delayed block I/O. +.SH "SEE ALSO" +.BR reboot (2), +.BR sync (8). diff --git a/man/man2/time.2 b/man/man2/time.2 new file mode 100644 index 000000000..dc9d72785 --- /dev/null +++ b/man/man2/time.2 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)gettimeofday.2 6.7 (Berkeley) 5/14/86 +.\" +.TH TIME 2 "May 14, 1986" +.UC 4 +.SH NAME +time, stime \- get/set date and time +.SH SYNOPSIS +.nf +.ft B +#include +#include + +time_t time(time_t *\fItp\fP) +int stime(time_t *\fItp\fP) +.fi +.SH DESCRIPTION +The system's notion of the current Greenwich time +is obtained with the +.B time +call, and set with the +.B stime +call. +The time is expressed +in seconds since midnight (0 hour), January 1, 1970. +The time is both returned by +.B time +and stored in the variable pointed to by +.I tp +unless +.I tp +is the null pointer. +.PP +.B Stime +obtains the time to set from the variable pointed to by +.IR tp . +.PP +Only the super-user may set the time of day. +.SH RETURN +A 0 return value from +.B stime +indicates that the call succeeded. +.B Time +returns the current time on success. +A \-1 return value indicates an error occurred, and in this +case an error code is stored into the global variable \fBerrno\fP. +.SH "ERRORS +The following error codes may be set in \fBerrno\fP: +.TP 15 +[EFAULT] +The +.I tp +address referenced invalid memory. +.TP 15 +[EPERM] +A user other than the super-user attempted to set the time. +.SH "SEE ALSO" +.BR date (1), +.BR ctime (3). diff --git a/man/man2/times.2 b/man/man2/times.2 new file mode 100644 index 000000000..da9fc9856 --- /dev/null +++ b/man/man2/times.2 @@ -0,0 +1,68 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)times.3c 6.1 (Berkeley) 5/9/85 +.\" +.TH TIMES 2 "May 9, 1985" +.UC 4 +.SH NAME +times \- get process times +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +int times(struct tms *\fIbuffer\fP) +.fi +.SH DESCRIPTION +.B Times +returns time-accounting information +for the current process +and for the terminated child processes +of the current process. +All times are in 1/CLOCKS_PER_SEC seconds. +.PP +This is the structure returned by +.BR times : +.PP +.RS +.nf +.ta +0.4i +0.8i +1.2i +struct tms { + clock_t tms_utime; /* user time for this process */ + clock_t tms_stime; /* system time for this process */ + clock_t tms_cutime; /* children's user time */ + clock_t tms_cstime; /* children's system time */ +}; +.fi +.RE +.PP +The user time is the number of clock ticks used by a process on +its own computations. The system time is the number of clock ticks +spent inside the kernel on behalf of a process. This does not +include time spent waiting for I/O to happen, only actual CPU +instruction times. +.PP +The children times are the sum +of the children's process times and +their children's times. +.SH RETURN +.B Times +returns 0 on success, otherwise \-1 with the error code stored into the +global variable +.BR errno . +.SH ERRORS +The following error code may be set in +.BR errno : +.TP 15 +[EFAULT] +The address specified by the +.I buffer +parameter is not in a valid part of the process address space. +.SH "SEE ALSO" +.BR time (1), +.BR wait (2), +.BR time (2). diff --git a/man/man2/umask.2 b/man/man2/umask.2 new file mode 100644 index 000000000..499c73ea4 --- /dev/null +++ b/man/man2/umask.2 @@ -0,0 +1,38 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)umask.2 6.1 (Berkeley) 5/9/85 +.\" +.TH UMASK 2 "May 9, 1985" +.UC 4 +.SH NAME +umask \- set file creation mode mask +.SH SYNOPSIS +.nf +.ft B +#include +#include + +mode_t umask(mode_t \fImask\fP) +.ft R +.fi +.SH DESCRIPTION +.B Umask +sets the process's file mode creation mask to \fImask\fP +and returns the previous value of the mask. The low-order +9 bits of \fImask\fP are used whenever a file is created, +clearing corresponding bits in the file mode +(see +.BR chmod (2)). +This clearing allows each user to restrict the default access +to his files. +.PP +The value is initially 022 (write access for owner only). +The mask is inherited by child processes. +.SH "RETURN VALUE +The previous value of the file mode mask is returned by the call. +.SH SEE ALSO +.BR chmod (2), +.BR mknod (2), +.BR open (2). diff --git a/man/man2/uname.2 b/man/man2/uname.2 new file mode 100644 index 000000000..dab0d8cf4 --- /dev/null +++ b/man/man2/uname.2 @@ -0,0 +1,35 @@ +.TH UNAME 2 +.SH NAME +uname \- get system info +.SH SYNOPSIS +.ft B +.nf +#include + +int uname(struct utsname *name) +.fi +.ft P +.SH DESCRIPTION +.B Uname() +fills a struct utsname with system information. This structure is described +in as follows: +.PP +.nf +.ta +4n +6n +25n +struct utsname { + char sysname[15+1]; /* System name */ + char nodename[255+1]; /* Node/Network name */ + char release[11+1]; /* O.S. release */ + char version[7+1]; /* O.S. version */ + char machine[11+1]; /* Machine hardware */ + char arch[11+1]; /* Architecture */ +}; +.fi +.PP +The strings are always null terminated, and may be of a different length then +shown here. The first five are required by \s-2POSIX\s+2, the last is +Minix specific. +.SH "SEE ALSO" +.BR uname (1). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man2/unlink.2 b/man/man2/unlink.2 new file mode 100644 index 000000000..0f6b940a9 --- /dev/null +++ b/man/man2/unlink.2 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)unlink.2 6.2 (Berkeley) 5/22/85 +.\" +.TH UNLINK 2 "May 22, 1985" +.UC 4 +.SH NAME +unlink \- remove directory entry +.SH SYNOPSIS +.nf +.ft B +#include + +int unlink(const char *path) +.fi +.ft R +.SH DESCRIPTION +.B Unlink +removes the entry for the file +.I path +from its directory. +If this entry was the last link to the file, +and no process has the file open, then +all resources associated with the file are reclaimed. +If, however, the file was open in any process, the actual +resource reclamation is delayed until it is closed, +even though the directory entry has disappeared. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +The \fIunlink\fP succeeds unless: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EACCES] +Write permission is denied on the directory containing the link +to be removed. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EPERM] +The named file is a directory. +.TP 15 +[EPERM] +The directory containing the file is marked sticky, +and neither the containing directory nor the file to be removed +are owned by the effective user ID. +(Minix-vmd) +.TP 15 +[EBUSY] +The entry to be unlinked is the mount point for a +mounted file system. +.TP 15 +[EIO] +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.TP 15 +[EROFS] +The named file resides on a read-only file system. +.TP 15 +[EFAULT] +.I Path +points outside the process's allocated address space. +.SH "SEE ALSO" +.BR close (2), +.BR link (2), +.BR rmdir (2). diff --git a/man/man2/utime.2 b/man/man2/utime.2 new file mode 100644 index 000000000..81352258e --- /dev/null +++ b/man/man2/utime.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)utimes.2 6.4 (Berkeley) 8/26/85 +.\" +.TH UTIME 2 "August 26, 1985" +.UC 4 +.SH NAME +utime \- set file times +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int utime(const char *\fIfile\fP, struct utimbuf *\fItimes\fP) +.fi +.SH DESCRIPTION +The +.B utime +call +uses the +\*(lqaccessed\*(rq and \*(lqupdated\*(rq times +from the utimbuf structure pointed to by +.I times +to set the corresponding recorded times for +.I file. +.PP +Struct utimbuf is defined in as follows: +.PP +.RS +.nf +.ta +0.4i +0.8i +1.0i +struct utimbuf { + time_t actime; /* access time */ + time_t modtime; /* modification time */ +}; +.fi +.RE +.PP +The caller must be the owner of the file or the super-user. +The \*(lqinode-changed\*(rq time of the file is set to the current time. +.SH "RETURN VALUE +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.B errno +is set to indicate the error. +.SH "ERRORS +.B Utime +will fail if one or more of the following are true: +.TP 15 +[ENOTDIR] +A component of the path prefix is not a directory. +.TP 15 +[EINVAL] +The pathname contains a character with the high-order bit set. +.TP 15 +[ENAMETOOLONG] +The path name exceeds PATH_MAX characters. +.TP 15 +[ENOENT] +The named file does not exist. +.TP 15 +[ELOOP] +Too many symbolic links were encountered in translating the pathname. +(Minix-vmd) +.TP 15 +[EPERM] +The process is not super-user and not the owner of the file. +.TP 15 +[EACCES] +Search permission is denied for a component of the path prefix. +.TP 15 +[EROFS] +The file system containing the file is mounted read-only. +.TP 15 +[EFAULT] +.I File +or \fItimes\fP points outside the process's allocated address space. +.TP 15 +[EIO] +An I/O error occurred while reading or writing the affected inode. +.SH SEE ALSO +.BR stat (2). diff --git a/man/man2/wait.2 b/man/man2/wait.2 new file mode 100644 index 000000000..b8d5f6f59 --- /dev/null +++ b/man/man2/wait.2 @@ -0,0 +1,162 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)wait.2 6.2 (Berkeley) 6/30/85 +.\" +.TH WAIT 2 "June 30, 1985" +.UC 4 +.SH NAME +wait, waitpid \- wait for process to terminate +.SH SYNOPSIS +.ft B +.nf +#include +#include + +pid_t wait(int *\fIstatus\fP) +pid_t waitpid(pid_t \fIpid\fP, int *\fIstatus\fP, int \fIoptions\fP) +.fi +.SH DESCRIPTION +.B Wait +causes its caller to delay until a signal is received or +one of its child +processes terminates. +If any child has died since the last +.BR wait , +return is immediate, returning the process id and +exit status of one of the terminated +children. +If there are no children, return is immediate with +the value \-1 returned. +.PP +On return from a successful +.B wait +call, +.I status +is nonzero, and the high byte of +.I status +contains the low byte of the argument to +.B exit +supplied by the child process; +the low byte of +.I status +contains the termination status of the process. +A more precise definition of the +.I status +word is given in +.RI < sys/wait.h >. +.B Wait +can be called with a null pointer argument to indicate that no status need +be returned. +.PP +.B Waitpid +provides an alternate interface for programs +that must not block when collecting the status +of child processes, or that wish to wait for +one particular child. The pid parameter is +the process ID of the child to wait for, \-1 +for any child. The +.I status +parameter is defined as above. The +.I options +parameter is used to indicate the call should not block if +there are no processes that wish to report status (WNOHANG), +and/or that children of the current process that are stopped +due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should also have +their status reported (WUNTRACED). (Job control is not implemented for +Minix, but these symbols and signals are.) +.PP +When the WNOHANG option is specified and no processes +wish to report status, +.B waitpid +either returns 0 under some implementations, or \-1 with +.B errno +set to +.B EAGAIN +under others. +(Under Minix it returns 0.) +The WNOHANG and WUNTRACED options may be combined by +.IR or 'ing +the two values. +.SH NOTES +The call +.BI "wait(&" status ")" +is equivalent to +.BI "waitpid(\-1, &" status ", 0)\fR." +.PP +See +.BR sigaction (2) +for a list of termination statuses (signals); +0 status indicates normal termination. +A special status (0177) is returned for a stopped process +that has not terminated and can be restarted; +see +.BR ptrace (2). +If the 0200 bit of the termination status +is set, +a core image of the process was produced +by the system. +.PP +If the parent process terminates without +waiting on its children, +the initialization process +(process ID = 1) +inherits the children. +.PP +.I +defines a number of macros that operate on a status word: +.TP 5 +.BI "WIFEXITED(" status ")" +True if normal exit. +.TP 5 +.BI "WEXITSTATUS(" status ")" +Exit status if the process returned by a normal exit, zero otherwise. +.TP 5 +.BI "WTERMSIG(" status ")" +Signal number if the process died by a signal, zero otherwise. +.TP 5 +.BI "WIFSIGNALED(" status ")" +True if the process died by a signal. +.TP 5 +.BI "WIFSTOPPED(" status ")" +True if the process is stopped. (Never true under Minix.) +.TP 5 +.BI "WSTOPSIG(" status ")" +Signal number of the signal that stopped the process. +.SH "RETURN VALUE +If \fBwait\fP returns due to a stopped +or terminated child process, the process ID of the child +is returned to the calling process. Otherwise, a value of \-1 +is returned and \fBerrno\fP is set to indicate the error. +.PP +.B Waitpid +returns \-1 if there are no children not previously waited for or if +the process that it wants to wait for doesn't exist. +.PP +.B Waitpid +returns 0 if WNOHANG is specified and there are no stopped or exited +children. (Under other implementations it may return \-1 instead. Portable +code should test for both possibilities.) +.SH ERRORS +.B Wait +will fail and return immediately if one or more of the following +are true: +.TP 15 +[ECHILD] +The calling process has no existing unwaited-for +child processes. +.TP 15 +[EFAULT] +The \fIstatus\fP argument points to an illegal address. +.TP 15 +[EAGAIN] +.B Waitpid +is called with the WNOHANG option and no child has exited yet. (Not under +Minix, it'll return 0 in this case and leave +.B errno +alone.) +.SH "SEE ALSO" +.BR execve (2), +.BR exit (2), +.BR sigaction (2). diff --git a/man/man2/write.2 b/man/man2/write.2 new file mode 100644 index 000000000..d3ede226a --- /dev/null +++ b/man/man2/write.2 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)write.2 6.5 (Berkeley) 5/14/86 +.\" +.TH WRITE 2 "May 14, 1986" +.UC 4 +.SH NAME +write \- write output +.SH SYNOPSIS +.nf +.ft B +#include +#include + +ssize_t write(int \fId\fP, const void *\fIbuf\fP, size_t \fInbytes\fP) +.fi +.SH DESCRIPTION +.B Write +attempts to write +.I nbytes +of data to the object referenced by the descriptor +.I d +from the buffer pointed to by +.IR buf . +.PP +On objects capable of seeking, the \fBwrite\fP starts at a position +given by the pointer associated with +.IR d , +see +.BR lseek (2). +Upon return from +.BR write , +the pointer is incremented by the number of bytes actually written. +.PP +Objects that are not capable of seeking always write from the current +position. The value of the pointer associated with such an object +is undefined. +.PP +When using non-blocking I/O on objects such as TCP/IP channels that are +subject to flow control, +.B write +may write fewer bytes than requested; +the return value must be noted, +and the remainder of the operation should be retried when possible. +.SH "RETURN VALUE +Upon successful completion the number of bytes actually written +is returned. Otherwise a \-1 is returned and the global variable +.B errno +is set to indicate the error. +.SH ERRORS +.B Write +will fail and the file pointer will remain unchanged if one or more +of the following are true: +.TP 15 +[EBADF] +\fID\fP is not a valid descriptor open for writing. +.TP 15 +[EPIPE] +An attempt is made to write to a pipe that is not open +for reading by any process. +.TP 15 +[EPIPE] +An attempt is made to write to a TCP channel +that is not connected to a peer socket. +.TP 15 +[EFBIG] +An attempt was made to write a file that exceeds the process's +file size limit or the maximum file size. +.TP 15 +[EFAULT] +Part of the data to be written to the file +points outside the process's allocated address space. +.TP 15 +[ENOSPC] +There is no free space remaining on the file system +containing the file. +.ig +.TP 15 +[EDQUOT] +The user's quota of disk blocks on the file system +containing the file has been exhausted. +.. +.TP 15 +[EIO] +An I/O error occurred while reading from or writing to the file system. +.TP 15 +[EAGAIN] +The file was marked for non-blocking I/O, +and no data could be written immediately. +.SH "SEE ALSO" +.BR fcntl (2), +.BR lseek (2), +.BR open (2), +.BR pipe (2), +.BR read (2). diff --git a/man/man3/abort.3 b/man/man3/abort.3 new file mode 100644 index 000000000..ddce54a12 --- /dev/null +++ b/man/man3/abort.3 @@ -0,0 +1,27 @@ +.\" @(#)abort.3 6.3 (Berkeley) 5/27/86 +.\" +.TH ABORT 3 "May 27, 1986" +.AT 3 +.SH NAME +abort \- generate a fault +.SH SYNOPSIS +.nf +.ft B +#include + +void abort(void) +.ft R +.fi +.SH DESCRIPTION +.B Abort +executes an instruction which is illegal in user mode. +This causes a signal that normally terminates +the process with a core dump, which may be used for debugging. +.SH SEE ALSO +.BR sigaction (2), +.BR exit (2). +.SH DIAGNOSTICS +Usually ``abort \- core dumped'' from the shell. +.SH BUGS +The abort() function does not flush standard I/O buffers. Use +.BR fflush (3). diff --git a/man/man3/abs.3 b/man/man3/abs.3 new file mode 100644 index 000000000..3b5bc348c --- /dev/null +++ b/man/man3/abs.3 @@ -0,0 +1,24 @@ +.\" @(#)abs.3 6.1 (Berkeley) 5/15/85 +.\" +.TH ABS 3 "May 15, 1985" +.AT 3 +.SH NAME +abs \- integer absolute value +.SH SYNOPSIS +.nf +.ft B +#include + +int abs(int \fIi\fP) +.ft R +.fi +.SH DESCRIPTION +.B Abs +returns the absolute value of its integer operand. +.SH SEE ALSO +.BR floor (3). +.SH BUGS +Applying the \fIabs\fP function to the most negative integer generates a +result which is the most negative integer. That is, abs(0x80000000) +returns 0x80000000 as a result on a machine with 32-bit ints. Using the +result in unsigned computations is sound however. diff --git a/man/man3/assert.3 b/man/man3/assert.3 new file mode 100644 index 000000000..6b6166022 --- /dev/null +++ b/man/man3/assert.3 @@ -0,0 +1,42 @@ +.\" @(#)assert.3 6.2 (Berkeley) 5/12/86 +.\" +.TH ASSERT 3 "May 12, 1986" +.AT 3 +.SH NAME +assert \- program verification +.SH SYNOPSIS +.nf +.ft B +#include + +void assert(int \fIexpression\fP) +.fi +.SH DESCRIPTION +.B Assert +is a macro that indicates +.I expression +is expected to be true at this point in the program. +It causes an +.BR abort (3) +with a diagnostic comment on the standard output when +.I expression +is false (0). +Compiling with the +.BR cc (1) +option +.SM +.B \-DNDEBUG +effectively deletes +.B assert +from the program. +.SH DIAGNOSTICS +`Assertion "\fIexpression\fR" failed: file +.I f +line +.IR n .' +.I F +is the source file and +.I n +the source line number of the +.B assert +statement. diff --git a/man/man3/atof.3 b/man/man3/atof.3 new file mode 100644 index 000000000..6673497b5 --- /dev/null +++ b/man/man3/atof.3 @@ -0,0 +1,39 @@ +.\" @(#)atof.3 6.1 (Berkeley) 5/15/85 +.\" +.TH ATOF 3 "May 15, 1985" +.AT 3 +.SH NAME +atof, atoi, atol \- convert ASCII to numbers +.SH SYNOPSIS +.nf +.ft B +#include + +double atof(const char *\fInptr\fP) +int atoi(const char *\fInptr\fP) +long atol(const char *\fInptr\fP) +.ft R +.fi +.SH DESCRIPTION +These functions convert a string pointed to by +.I nptr +to floating, integer, and long integer representation respectively. +The first unrecognized character ends the string. +.PP +.B Atof +recognizes an optional string of spaces, then an optional sign, then +a string of digits optionally containing a decimal +point, then an optional `e' or `E' followed by an optionally signed integer. +.PP +.B Atoi +and +.B atol +recognize an optional string of spaces, then an optional sign, then a +string of +digits. +.SH SEE ALSO +.BR strtol (3), +.BR strtod (3), +.BR scanf (3). +.SH BUGS +There are no provisions for overflow. diff --git a/man/man3/bstring.3 b/man/man3/bstring.3 new file mode 100644 index 000000000..256865f32 --- /dev/null +++ b/man/man3/bstring.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)bstring.3 6.1 (Berkeley) 5/15/85 +.\" +.TH BSTRING 3 "May 15, 1985" +.UC 5 +.SH NAME +bstring, bcopy, bcmp, bzero, ffs \- bit and byte string operations +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +void bcopy(const void *\fIsrc\fP, void *\fIdst\fP, size_t \fIlength\fP) +int bcmp(const void *\fIb1\fP, const void *\fIb2\fP, size_t \fIlength\fP) +void bzero(void *\fIdst\fP, size_t \fIlength\fP) +int ffs(int \fIi\fP) +.ft R +.fi +.SH DESCRIPTION +The functions +.BR bcopy , +.BR bcmp , +and +.B bzero +operate on variable length strings of bytes. +They do not check for null bytes as the routines in +.BR string (3) +do. +.PP +.B Bcopy +copies +.I length +bytes from string +.I src +to the string +.IR dst . +.PP +.B Bcmp +compares byte string +.I b1 +against byte string +.IR b2 , +returning zero if they are identical, +non-zero otherwise. Both strings are +assumed to be +.I length +bytes long. +.PP +.B Bzero +places +.I length +0 bytes in the string +.IR b1 . +.PP +.B Ffs +find the first bit set in the argument passed it and +returns the index of that bit. Bits are numbered +starting at 1. A return value of 0 indicates the +value passed is zero. +.SH BUGS +The +.BR bcopy , +.BR bcmp , +and +.BR bzero +functions are obsolete; new code should use +.BR memmove , +.BR memcmp , +and +.BR memset +respectively. +.PP +The +.B bcopy +routine takes parameters backwards from +.BR memcpy , +.BR memmove , +and +.BR strcpy . diff --git a/man/man3/configfile.3 b/man/man3/configfile.3 new file mode 100644 index 000000000..87338983e --- /dev/null +++ b/man/man3/configfile.3 @@ -0,0 +1,194 @@ +.TH CONFIGFILE 3 +.SH NAME +configfile, config_read, config_delete, config_renewed, config_length, config_issub, config_isatom, config_isstring \- generic configuration file functions +.SH SYNOPSIS +.ft B +.nf +#include + +config_t *config_read(const char *\fIfile\fP, int \fIflags\fP, config_t *\fIcfg\fP) +void config_delete(config_t *\fIcfg\fP) +int config_renewed(config_t *\fIcfg\fP) +size_t config_length(config_t *\fIcfg\fP) +int config_issub(config_t *\fIcfg\fP) +int config_isatom(config_t *\fIcfg\fP) +int config_isstring(config_t *\fIcfg\fP) +.fi +.ft P +.SH DESCRIPTION +The +.B configfile +routines operate on a generic configuration file that follows the syntax +described in +.BR configfile (5). +.PP +The interface presented by the functions above uses the following type and +definitions from : +.PP +.if n .in +2 +.if t .RS +.nf +.ta +\w'type'u +\w'const charmm'u +\w'word[];mm'u +typedef const struct config { + config_t *next; /* Next configuration file thing. */ + config_t *list; /* For a { sublist }. */ + const char *file; /* File and line where this is found. */ + unsigned line; + int flags; /* Special flags. */ + char word[]; /* Payload. */ +} config_t; + +.ta +\w'#definem'u +\w'CFG_SUBLISTm'u +\w'0x0000mm'u +#define CFG_CLONG 0x0001 /* strtol(word, &end, 0) is valid. */ +#define CFG_OLONG 0x0002 /* strtol(word, &end, 010). */ +#define CFG_DLONG 0x0004 /* strtol(word, &end, 10). */ +#define CFG_XLONG 0x0008 /* strtol(word, &end, 0x10). */ +#define CFG_CULONG 0x0010 /* strtoul(word, &end, 0). */ +#define CFG_OULONG 0x0020 /* strtoul(word, &end, 010). */ +#define CFG_DULONG 0x0040 /* strtoul(word, &end, 10). */ +#define CFG_XULONG 0x0080 /* strtoul(word, &end, 0x10). */ +#define CFG_STRING 0x0100 /* The word is enclosed in quotes. */ +#define CFG_SUBLIST 0x0200 /* This is a sublist, so no word. */ +#define CFG_ESCAPED 0x0400 /* Escapes are still marked with \e. */ +.fi +.if n .in -2 +.if t .RE +.PP +In memory a configuration file is represented as a list of +.B config_t +cells linked together with the +.B next +field ending with a null pointer. A sublist between braces is attached to a +cell at the +.B list +field. +Words and strings are put in the +.B word +field, a null terminated string. The +.B flags +field records the type and features of a cell. The +.B CFG_*LONG +flags are set if a word is a number according to one of the +.B strtol +or +.B strtoul +calls. Purely a number, no quotes or trailing garbage. The +.B CFG_STRING +flag is set if the object was enclosed in double quotes. Lastly +.B CFG_SUBLIST +tells if the cell is only a pointer to a sublist in braces. +.PP +Characters in a word or string may have been formed with the +.B \e +escape character. They have been parsed and expanded, but the \e is still +present if +.B CFG_ESCAPED +is set. The +.B word +array may be changed, as long as it doesn't grow longer, so one may remove +the \es like this: +.PP +.RS +.ta +4n +4n +.nf +if (cfg->flags & CFG_ESCAPED) { + char *p, *q; + p= q= cfg->word; + for (;;) { + if ((*q = *p) == '\e\e') *q = *++p; + if (*q == 0) break; + p++; + q++; + } +} +.fi +.RE +.PP +The low level syntax of a config file is checked when it is read. If an +error is encountered a message is printed and the program exits with exit +code 1. What the data means is not checked, that +should be done by the program using the data. Only the atom +.B include +at the beginning of a list is special. It should be followed by a string. +The string is seen as the name of a file, that is opened, read, and inserted +in place of the +.BR include . +Unless the name of the file starts with a +.BR / , +it is sought relative to the directory the current file is found in. +Nonexistent files are treated as being empty. +.PP +The +.B file +and +.B line +fields in each cell tell where the cell was read. +.SS Functions +A configuration file is read with +.BR config_read . +The first argument is the file to read. The second is either +.B 0 +or +.B CFG_ESCAPED +to tell whether \e escapes should be fully expanded without leaving a trace, +or if they should still be marked with a \e so that the caller knows where +the excapes are. +The third argument, +.IR cfg , +should be a null pointer on the first call. If you want to reread a config +file that may have changed then +.I cfg +should be what you previously read. +.PP +With +.B config_delete +one can free up the memory that has been acquired with +.BR malloc (3) +to hold the contents of the configuration file. +.PP +To determine if the contents of configuration file has changed when reread +one uses +.BR config_renewed +after +.BR config_read . +It returns a "changed" flag that is set when the configuration file changed +and then clears that flag. It returns true on the very first call. For the +function to work you need to feed the old data back into +.BR config_read , +not delete and reread. +.PP +The length of a series of config structures is told by +.BR config_length . +It follows the +.B next +fields, so a sublist between braces counts as one extra. +.PP +The +.BR config_issub , +.BR config_isatom +and +.BR config_isstring +functions are just pretty macros to test if a cell references a sublist, is +a word/string, or is just a string. +.B CFG_SUBLIST +and +.B CFG_STRING +tell the same story. +.SH FILES +.TP \w'*/etc/*.confmmmm'u +.B */etc/*.conf +Several files in several +.B etc +directories. +.SH "SEE ALSO" +.BR configfile (5). +.SH NOTES +The syntax of a config file puts some constraints on what you find in memory. +The top level list consists entirely of sublist cells. These point to lists +that start with at least an atom, followed by a mix of atoms and sublist cells. +These sublists in turn point to a list of only sublist cells (recurse now.) +.PP +The struct config shown above is not exactly proper C to aid +readability, read itself to see why. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man3/crypt.3 b/man/man3/crypt.3 new file mode 100644 index 000000000..0d9bee8a3 --- /dev/null +++ b/man/man3/crypt.3 @@ -0,0 +1,71 @@ +.TH CRYPT 3 +.SH NAME +crypt \- one-way password encryption function +.SH SYNOPSIS +.ft B +.nf +#define _MINIX_SOURCE 1 +#include + +char *crypt(const char *\fIkey\fP, const char *\fIsalt\fP) +.fi +.ft P +.SH DESCRIPTION +The first use of +.B crypt() +is to encrypt a password. Its second use is to authenticate a shadow +password. In both cases +.B crypt() +calls +.BR pwdauth (8) +to do the real work. +.PP +.B Crypt() +encrypts a password if called with a user typed key, and a salt +whose first two characters are in the set [./0-9A-Za-z]. The result is a +character string in the [./0-9A-Za-z] alphabet of which the first two +characters are equal to the salt, and the rest is the result of encrypting +the key and the salt. +.PP +If +.B crypt() +is called with a salt that has the form +.BI "##" user +then the key is encrypted and compared to the encrypted password of +.I user +in the shadow password file. If they are equal then +.B crypt() +returns the +.BI "##" user +argument, if not then some other string is returned. This trick assures +that the normal way to authenticate a password still works: +.PP +.RS +.nf +if (strcmp(pw->pw_passwd, crypt(key, pw->pw_passwd))) ... +.fi +.RE +.PP +If +.I key +is a null string, and the shadow password is a null string or the salt is a +null string then the result equals +.IR salt . +(This is because the caller can't tell if a password field is empty in the +shadow password file.) +.PP +The key and salt are limited to 1024 bytes total including the null bytes. +.SH FILES +.TP 25 +/usr/lib/pwdauth +The password authentication program +.SH "SEE ALSO" +.BR getpass (3), +.BR getpwent (3), +.BR passwd (5), +.BR pwdauth (8). +.SH NOTES +The result of an encryption is returned in a static array that is +overwritten by each call. The return value should not be modified. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 000000000..25005d93c --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,116 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)ctime.3 6.8 (Berkeley) 4/2/87 +.\" +.TH CTIME 3 "April 2, 1987" +.UC 4 +.SH NAME +ctime, localtime, gmtime, asctime, tzset \- convert date and time to ASCII +.SH SYNOPSIS +.nf +.ft B +#include +#include + +void tzset(void) +char *ctime(const time_t *\fIclock\fP) +char *asctime(const struct tm *\fItm\fP) +struct tm *localtime(const time_t *\fIclock\fP) +struct tm *gmtime(const time_t *\fIclock\fP) +.fi +.SH DESCRIPTION +\fBTzset\fP uses the value of the environment variable \fBTZ\fP to +set up the time conversion information used by \fBlocaltime\fP. +.PP +If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP +file (as defined in \fI\fP) is used by \fBlocaltime\fP. If +this file fails for any reason, the GMT offset as provided by the +kernel is used. In this case, DST is ignored, resulting in the time +being incorrect by some amount if DST is currently in effect. If +this fails for any reason, GMT is used. +.PP +If \fBTZ\fP appears in the environment but its value is a null string, +Greenwich Mean Time is used; if \fBTZ\fP appears and begins with a +slash, it is used as the absolute pathname of the \fBtzfile\fP(5)-format +file from which to read the time conversion information; if \fBTZ\fP +appears and begins with a character other than a slash, it's used as +a pathname relative to the system time conversion information directory, +defined as \fBTZDIR\fP in the include file \fBtzfile.h\fP. If this file +fails for any reason, the GMT offset as provided by the kernel is +used, as described above. If this fails for any reason, GMT is used. +See +.BR TZ (5) +for a proper description of the +.B TZ +variable. +.PP +\fBCtime\fP converts a time value, pointed to by \fIclock\fP, +such as returned by \fBtime\fP(2) into ASCII and returns a pointer +to a 26-character string in the following form. All the fields +have constant width. +.PP +.RS +.nf +Sun Sep 16 01:03:52 1973\en\e0 +.fi +.RE +.PP +.B Localtime +and +.B gmtime +return pointers to structures containing +the broken-down time. +.B Localtime +corrects for the time zone and possible daylight savings time; +.B gmtime +converts directly to GMT, which is the time UNIX uses. +.B Asctime +converts a broken-down time to ASCII and returns a pointer +to a 26-character string. +.PP +The structure declaration from the include file is: +.PP +.RS +.nf +.nr .0 .8i+\w'int tm_isdst'u +.ta .5i \n(.0u \n(.0u+\w'/* 0-000'u+1n +struct tm { + int tm_sec; /* 0-59 seconds */ + int tm_min; /* 0-59 minutes */ + int tm_hour; /* 0-23 hour */ + int tm_mday; /* 1-31 day of month */ + int tm_mon; /* 0-11 month */ + int tm_year; /* 0- year \- 1900 */ + int tm_wday; /* 0-6 day of week (Sunday = 0) */ + int tm_yday; /* 0-365 day of year */ + int tm_isdst; /* flag: daylight savings time in effect */ + long tm_gmtoff; /* offset from GMT in seconds */ + char **tm_zone; /* abbreviation of timezone name */ +}; +.fi +.RE +.PP +\fBTm_isdst\fP is non-zero if a time zone adjustment such as Daylight +Savings time is in effect. +.PP +\fBTm_gmtoff\fP is the offset (in seconds) of the time represented +from GMT, with positive values indicating East of Greenwich. +.SH FILES +.ta \w'/usr/lib/zoneinfo\0\0'u +/usr/lib/zoneinfo time zone information directory +.br +/etc/localtime local time zone file +.SH SEE ALSO +.BR time (2), +.BR getenv (3), +.BR tzfile (5), +.BR TZ (5), +.BR environ (7), +.BR zic (8). +.SH NOTE +The return values point to static data whose content is overwritten by +each call. The \fBtm_zone\fP field of a returned \fBstruct tm\fP +points to a static array of characters, which will also be overwritten +at the next call (and by calls to \fBtzset\fP). diff --git a/man/man3/ctype.3 b/man/man3/ctype.3 new file mode 100644 index 000000000..00d7536d7 --- /dev/null +++ b/man/man3/ctype.3 @@ -0,0 +1,95 @@ +.\" @(#)ctype.3 6.4 (Berkeley) 5/12/86 +.\" +.TH CTYPE 3 "May 12, 1986" +.AT 3 +.SH NAME +ctype, isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toupper, tolower, toascii \- character classification macros +.SH SYNOPSIS +.nf +.ft B +#include + +int isalpha(int \fIc\fP) +\&... +.fi +.SH DESCRIPTION +These macros classify characters +by table lookup. +Each is a predicate returning nonzero for true, +zero for false. +.B Isascii +and +.B toascii +are defined on all integer values; the rest +are defined only on the range of +.B "unsigned char" +and on the special value +EOF (see +.BR stdio (3)). +.TP 15n +.B isalpha +.I c +is a letter +.TP +.B isupper +.I c +is an upper case letter +.TP +.B islower +.I c +is a lower case letter +.TP +.B isdigit +.I c +is a digit +.TP +.B isxdigit +.I c +is a hex digit +.TP +.B isalnum +.I c +is an alphanumeric character +.TP +.B isspace +.I c +is a space, tab, carriage return, newline, vertical tab, or formfeed +.TP +.B ispunct +.I c +is a punctuation character (neither control nor alphanumeric) +.TP +.B isprint +.I c +is a printing character, code 040(8) (space) through 0176 (tilde) +.TP +.B isgraph +.I c +is a printing character, similar to +.B isprint +except false for space. +.TP +.B iscntrl +.I c +is a delete character (0177) or ordinary control character +(less than 040). +.TP +.B isascii +.I c +is an ASCII character, code less than 0200 +.TP +.B tolower +.I c +is converted to lower case. Return value is undefined if not +.BR isupper (\fIc\fR). +.TP +.B toupper +.I c +is converted to upper case. Return value is undefined if not +.BR islower (\fIc\fR). +.TP +.B toascii +.I c +is converted to be a valid ascii character. +.SH "SEE ALSO" +.BR ascii (7) diff --git a/man/man3/curses.3 b/man/man3/curses.3 new file mode 100644 index 000000000..e9eaa3e94 --- /dev/null +++ b/man/man3/curses.3 @@ -0,0 +1,248 @@ +.TH CURSES 3 +.SH NAME +curses \- screen/window management library +.SH SYNOPSIS +cc demo.c -lcurses +.SH DESCRIPTION +Curses is a library of screen and window management routines. It is modeled +after the UNIX curses and ncurses libraries. Normally, programs written for +curses should be easily ported to UNIX, and vice versa. +.PP +To use the routines, the function initscr() must first be called. +This creates two 'windows' for the user: stdscr and curscr. Stdscr is the +default +window for the user to make changes on, and curscr reflects the current +contents of the physical display screen. The user writes or edits the stdscr +window to his liking, then calls the refresh() function to make curscr +and the physical screen look like stdscr. When the user program terminates, +it should call the endwin() function to restore things to normal. +.PP +There are all sorts of window manipulation routines available to the +programmer: auxiliary windows may be created, edited, moved and deleted. The +terminal may be set in many different modes, output text may be attributed +with blink, blank, bold and reverse attributes. Screen colors may also be +set, foreground and background. There are window-specific +printf- and scanf-like routines, routines for scrolling, box-drawing, +window overlaying, clearing routines etc. +.PP +For more and detailed information, see the library source codes. All curses +functions are preceded by a complete description. +.SH FUNCTIONS +Below is a list over the available functions, together with a brief +description of what they do. In general, functions whose names start with 'w' +differ from the one without 'w' (like wmove vs. move) signify that +a specific window is used. Without a 'w', sdtscr is implied. The functions +that start with 'mv' before the 'genereic' function name signify that a +cursor motion should be made before the actual work. 'mv' and 'w' combine +as expected. +.PP +Most routines that return an int will return the manifest constant ERR if +there is a failure during execution. Routines that return a char actually +return an int, so that ERR does not conflict with the character code 0xff. +All characters from 0 to 0xff are allowed for usage with curses. +.PP +Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful +positive value if the operation is successful. +.PP +The curses package uses some predefined types, variables and manifest +constants that are also available to the programmer. There are also a few +globally accessible variables that should not be touched by the application +program. Those untouchable variables have names starting with an +underscore (_) to avoid conflicts. The user-accessible types, variables +and constants are (there are a number of other constants defining character +attribute names and function key names - consult for details): +.sp +.nf +.ta 3i +(manifest constants) +.RS +TRUE boolean true +FALSE boolean false +ERR unsuccessfull operation +OK successfull operation +.RE +.sp +(types) +.RS +WINDOW a window structure type +bool boolean flag type +.RE +.sp +(variables) +.RS +WINDOW curscr physical display image +WINDOW stdscr default user drawing board +int LINES terminal height +int COLS terminal width +int NONL \\n causes CR and LF when TRUE +.RE +.sp +.fi +The following is an alphabetical list of the curses functions, together +with their types, parameters and a short comment for each (win is a window, +ch, vc, hc are characters, buf is a character buffer, attrs is an +attribute bit map, bf is a boolean flag. Note that `characters' in this +context usually can have 16 bits): +.nf +.sp +int waddch(win,ch) put char in stdscr +int addch(ch) +int mvaddch(y,x,ch) +int mvwaddch(win,y,x,ch) + +int waddstr(win,str) put string in stdscr +int addstr(str) +int mvaddstr(y,x,str) +int mvwaddstr(win,y,x,str) + +void wattroff(win,attrs) clear attribute(s) in window +void attroff(attrs) + +void wattron(win,attrs) add attribute(s) in window +void attron(attrs) + +void wattrset(win,attrs) set window char attributes +void attrset(attrs) + +int baudrate() dummy for compatibility + +void beep() ring the bell or visible bell if no bell available + +void flash() flash terminal screen or rings bell if no visible bell available + +void wbox(win,miny,minx,maxy,maxx,vc,hc) box in a window, with given characters +void box(win,vc,hc) + +void cbreak() set terminal cbreak mode + +void wclear(win) clear stdscr +void clear() + +void clearok(win,bf) marks window for screen clear + +int wclrtobot(win) clear from cursor to end of line and all lines down this line +int clrtobot() +int mvclrtoeol(y,x) +int mvwclrtobot(win,y,x) + +int wclrtoeol(win) clear from cursor to end of line +int clrtoeol() +int mvclrtoeol(y,x) +int mvwclrtoeol(win,y,x) + +int wdelch(win) delete a char in a window +int delch() +int mvdelch(y,x) +int mvwdelch(win,y,x) + +int wdeleteln(win) delete a line in a window +int deleteln() +int mvdeleteln(y,x) +int mvwdeleteln(win,y,x) + +void delwin(win) delete a window or a subwindow +void doupdate() update physical screen +void echo() set terminal echo mode +int endwin() cleanup and curses finitialization + +void werase(win) erase a window +void erase() + +int erasechar() return char delete character +int fixterm() dummy for compatibility +void flushinp() kill pending keyboard input + +int wgetch(win) get char via a window +int getch() +int mvgetch(y,x) +int mvwgetch(win,y,x) + +int wgetstr(win,str) get string via window to a buffer +int getstr(str) +int mvgetstr(y,x,str) +int mvwgetstr(win,y,x,str) + +void getyx(win,y,x) get a window's cursor position + +int gettmode() dummy for compatibility +void idlok(win,bf) dummy for compatibility +WINDOW *initscr() curses initialization (ret stdscr or NULL) + +int winch(win) get char at window cursor +int inch() +int mvinch(y,x) +int mvwinch(win,y,x) + +int winsch(win,ch) insert character in a window +int insch(ch) +int mvinsch(y,x,ch) +int mvwinsch(win,y,x,ch) + +int winsertln(win) insert new line in a window +int insertln() +int mvinsertln(y,x) +int mvwinsertln(win,y,x) + +void keypad(win,bf) marks a window for keypad usage +int killchar() return line delete character +char *longname() returns terminal description string +void leaveok(win,bf) marks window for cursor 'update leave' +void meta(win,bf) marks window for meta +int move(y,x) move cursor in stdscr +int mvcur(oldy,oldx,y,x) move terminal cursor to + +int mvprintw(y,x,fmt,args) move & print string in stdscr + +int mvscanw(y,x,fmt,args) move & get values via stdscr +int mvwin(win,y,x) move window on physical screen +int mvwprintw(win,x,y,fmt,args) move & print string in a window +int mvwscanw(win,y,x,fmt,args) move & get values via a window +WINDOW *newwin(lines,cols,begy,begx) create a new window +void nl() set terminal cr-crlf mapping mode +void nocbreak() unset terminal cbreak mod +void nodelay(win,bf) marks window for no input wait +void noecho() unset terminal echo mode +void nonl() unset terminal cr-crlf mapping mode +void noraw() unset raw terminal mode +void overlay(win1,win2) overlay one window on another +void overwrite(win1,win2) overwrite one window on another +int printw(fmt,args) print string in stdscr +void raw() set raw terminal mode +void refrbrk(bf) set screen update break mode +void refresh() refresh stdscr +int resetterm() dummy for compatibility +int resetty() restore terminal I/O modes +int saveoldterm() dummy for compatibility +int saveterm() dummy for compatibility +int savetty() save terminal I/O modes +int scanw(fmt,args) get values via stdscr +void scroll(win) scroll scrolling region of a window +void scrollok(win,bf) marks a window to allow scroll +void setcolors(A_COLOR(for,back)) sets the forground and background + colors of stdscr +void set_curs(visibility) 0 for invisible, 1 for visible, 2 for good + visible +int setsrcreg(miny,maxy) define stdscr's scroll region +int setterm() dummy for compatibility +int setupterm(term,fd,errret) set up terminal +void standend() start normal chars in stdscr +void standout() start standout chars in stdscr +WINDOW *subwin(win,lines,cols,begy,begx) + create a sub-window in window win +int tabsize(ts) set/get tabsize of stdscr +void touchwin(win) mark a window as totally modified +char *unctrl(ch) char-to-string converter +int wmove(win,y,x) move cursor in a window +void wnoutrefresh(win) create internal screen image +int wprintw(win,fmt,args) print string in a window +void wrefresh(win) refresh window +int wscanw(win,fmt,args) get values via a window +void wsetcolors(win,A_COLOR(for,back)) sets the forground and + background colors of the specified window +int wsetsrcreg(win,miny,maxy) define a window's scrolling region +void wstandend(win) start normal chars in window +void wstandout(win) start standout chars in window +int wtabsize(win,ts) set/get tabsize of a window +.SH BUGS +Function keys are not available under the MINIX version. +.\" $PchId: curses.3,v 1.3 1996/02/22 21:26:28 philip Exp $ diff --git a/man/man3/directory.3 b/man/man3/directory.3 new file mode 100644 index 000000000..a05c6cfbb --- /dev/null +++ b/man/man3/directory.3 @@ -0,0 +1,89 @@ +.TH DIRECTORY 3 +.SH NAME +directory, opendir, readdir, rewinddir, closedir, telldir, seekdir \- directory routines +.SH SYNOPSIS +.nf +.ft B +#include +#include + +DIR *opendir(const char *\fIdirname\fP) +struct dirent *readdir(DIR *\fIdirp\fP) +void rewinddir(DIR *\fIdirp\fP) +int closedir(DIR *\fIdirp\fP) + +#define _MINIX 1 +#include +#include + +long telldir(DIR *\fIdirp\fP) +int seekdir(DIR *\fIdirp\fP, long \fIpos\fP) +.SH DESCRIPTION +These routines form a system independent interface to access directories. +.PP +.B Opendir() +opens the directory +.I dirname +and returns a pointer to this open directory stream. +.PP +.B Readdir() +reads one entry from the directory as a pointer to a structure containing +the field +.BR d_name , +a character array containing the null-terminated name of the entry. +.PP +.B Rewinddir() +allows the directory to be read again from the beginning. +.PP +.B Closedir() +closes the directory and releases administrative data. +.PP +The Minix specific functions +.B telldir() +and +.B seekdir() +allow one to get the current position in the directory file and to return +there later. +.B Seekdir() +may only be called with a position returned by +.B telldir() +or 0 (rewind). These functions should not be used in portable programs. +.SH "SEE ALSO" +.BR dir (5). +.SH DIAGNOSTICS +.B Opendir() +returns a null pointer if +.I dirname +can't be opened, or if it can't allocate enough memory for the +.B DIR +structure. +.PP +.B Readdir() +returns null if there are no more directory entries or on error. +.PP +.B Closedir() +and +.B seekdir() +returns 0 on success, -1 on error. +.PP +.B Telldir() +returns -1 on error. +.PP +All of them set +.B errno +appropriately. +.B Readdir() +will only set +.B errno +on error, not on end-of-dir, so you should set +.B errno +to zero beforehand, and check its value if +.B readdir() +returns null. +.SH NOTES +The return value of +.B readdir() +needs to be copied before the next operation on the same directory if it is +to be saved. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man3/editline.3 b/man/man3/editline.3 new file mode 100644 index 000000000..ff298f6f5 --- /dev/null +++ b/man/man3/editline.3 @@ -0,0 +1,169 @@ +.\" $Revision$ +.TH EDITLINE 3 +.SH NAME +editline \- command-line editing library with history +.SH SYNOPSIS +.ft B +char *readline(char *\fIprompt\fP) +.ft P +.SH DESCRIPTION +.I Editline +is a library that provides an line-editing interface with text recall. +It is intended to be compatible with the +.I readline +library provided by the Free Software Foundation, but much smaller. +The bulk of this manual page describes the user interface. +.PP +The +.I readline +routine returns a line of text with the trailing newline removed. +The data is returned in a buffer allocated with +.IR malloc (3), +so the space should be released with +.IR free (3) +when the calling program is done with it. +Before accepting input from the user, the specified +.I prompt +is displayed on the terminal. +.PP +Each line returned is copied to the internal history list, unless it happens +to be equal to the previous line. +.SS "User Interface" +A program that uses this library provides a simple emacs-like editing +interface to its users. +A line may be edited before it is sent to the calling program by typing either +control characters or escape sequences. +A control character, shown as a caret followed by a letter, is typed by +holding down the ``control'' key while the letter is typed. +For example, ``^A'' is a control-A. +An escape sequence is entered by typing the ``escape'' key followed by one or +more characters. +The escape key is abbreviated as ``ESC.'' +Note that unlike control keys, case matters in escape sequences; ``ESC\ F'' +is not the same as ``ESC\ f''. +.PP +An editing command may be typed anywhere on the line, not just at the +beginning. +In addition, a return may also be typed anywhere on the line, not just at +the end. +.PP +Most editing commands may be given a repeat count, +.IR n , +where +.I n +is a number. +To enter a repeat count, type the escape key, the number, and then +the command to execute. +For example, ``ESC\ 4\ ^f'' moves forward four characters. +If a command may be given a repeat count then the text ``[n]'' is given at the +end of its description. +.PP +The following control characters are accepted: +.RS +.nf +.ta \w'ESC DEL 'u +^A Move to the beginning of the line +^B Move left (backwards) [n] +^D Delete character [n] +^E Move to end of line +^F Move right (forwards) [n] +^G Ring the bell +^H Delete character before cursor (backspace key) [n] +^I Complete filename (tab key); see below +^J Done with line (return key) +^K Kill to end of line (or column [n]) +^L Redisplay line +^M Done with line (alternate return key) +^N Get next line from history [n] +^P Get previous line from history [n] +^R Search backward (forward if [n]) through history for text; +\& must start line if text begins with an uparrow +^T Transpose characters +^V Insert next character, even if it is an edit command +^W Wipe to the mark +^X^X Exchange current location and mark +^Y Yank back last killed text +^[ Start an escape sequence (escape key) +^]c Move forward to next character ``c'' +^? Delete character before cursor (delete key) [n] +.fi +.RE +.PP +The following escape sequences are provided. +.RS +.nf +.ta \w'ESC DEL 'u +ESC\ ^H Delete previous word (backspace key) [n] +ESC\ DEL Delete previous word (delete key) [n] +ESC\ SP Set the mark (space key); see ^X^X and ^Y above +ESC\ \. Get the last (or [n]'th) word from previous line +ESC\ \? Show possible completions; see below +ESC\ < Move to start of history +ESC\ > Move to end of history +ESC\ b Move backward a word [n] +ESC\ d Delete word under cursor [n] +ESC\ f Move forward a word [n] +ESC\ l Make word lowercase [n] +ESC\ m Toggle if 8bit chars display normally or with ``M\-'' prefix +ESC\ u Make word uppercase [n] +ESC\ y Yank back last killed text +ESC\ v Show library version +ESC\ w Make area up to mark yankable +ESC\ nn Set repeat count to the number nn +ESC\ C Read from environment variable ``_C_'', where C is +\& an uppercase letter +.fi +.RE +.PP +The +.I editline +library has a small macro facility. +If you type the escape key followed by an uppercase letter, +.IR C , +then the contents of the environment variable +.I _C_ +are read in as if you had typed them at the keyboard. +For example, if the variable +.I _L_ +contains the following: +.RS +^A^Kecho '^V^[[H^V^[[2J'^M +.RE +Then typing ``ESC L'' will move to the beginning of the line, kill the +entire line, enter the echo command needed to clear the terminal (if your +terminal is like a VT-100), and send the line back to the shell. +.PP +The +.I editline +library also does filename completion. +Suppose the root directory has the following files in it: +.RS +.nf +.ta \w'core 'u +bin vmunix +core vmunix.old +.fi +.RE +If you type ``rm\ /v'' and then the tab key. +.I Editline +will then finish off as much of the name as possible by adding ``munix''. +Because the name is not unique, it will then beep. +If you type the escape key and a question mark, it will display the +two choices. +If you then type a period and a tab, the library will finish off the filename +for you: +.RS +.nf +.RI "rm /v[TAB]" munix .TAB old +.fi +.RE +The tab key is shown by ``[TAB]'' and the automatically-entered text +is shown in italics. +.SH "BUGS AND LIMITATIONS" +Doesn't know how to handle multiple lines. +.SH AUTHORS +Simmule R. Turner +and Rich $alz . +Original manual page by DaviD W. Sanderson . + +.\" $PchId: editline.3,v 1.3 1996/02/22 21:18:51 philip Exp $ diff --git a/man/man3/end.3 b/man/man3/end.3 new file mode 100644 index 000000000..0f0ee7ff7 --- /dev/null +++ b/man/man3/end.3 @@ -0,0 +1,42 @@ +.\" @(#)end.3 6.2 (Berkeley) 5/12/86 +.\" +.TH END 3 "May 12, 1986" +.AT 3 +.SH NAME +end, etext, edata \- last locations in program +.SH SYNOPSIS +.nf +.ft B +extern int etext; +extern int edata; +extern int end, _end; +.ft R +.fi +.SH DESCRIPTION +These names refer neither to routines nor to locations with interesting +contents. The address of +.B etext +is the first address above the program text, +.B edata +above the initialized data region, and +.B end +above the uninitialized data region. +.B _end +is the same as +.BR end , +but in the implementers name space, i.e. for use in libraries. +.PP +When execution begins, the program break coincides with +.BR end , +but it is reset by the routines +.BR brk (2), +.BR malloc (3), +standard input/output +.RB ( stdio (3)), +etc. +The current value of the program break is reliably returned by `sbrk(0)', +see +.BR brk (2). +.SH "SEE ALSO" +.BR brk (2), +.BR malloc (3). diff --git a/man/man3/execl.3 b/man/man3/execl.3 new file mode 100644 index 000000000..fa7be8cea --- /dev/null +++ b/man/man3/execl.3 @@ -0,0 +1,196 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)execl.3 6.2 (Berkeley) 4/25/86 +.\" +.TH EXECL 3 "April 25, 1986" +.UC 5 +.SH NAME +execl, execv, execle, execlp, execvp, exec, environ \- execute a file +.SH SYNOPSIS +.ft B +#include + +.in +.5i +.ti -.5i +int execl(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL) +.ti -.5i +int execv(const char *\fIname\fP, char *const \fIargv\fP[]) +.ti -.5i +int execle(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL, char *const \fIenvp\fP[]) +.ti -.5i +int execlp(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL) +.ti -.5i +int execvp(const char *\fIname\fP, char *const \fIargv\fP[]) +.in -.5i + +extern char *const *environ; +.fi +.SH DESCRIPTION +These routines provide various interfaces to the +.B execve +system call. Refer to +.BR execve (2) +for a description of their properties; only +brief descriptions are provided here. +.PP +.B Exec +in all its forms +overlays the calling process with the named file, then +transfers to the +entry point of the core image of the file. +There can be no return from a successful exec; the calling +core image is lost. +.PP +The +.I name +argument +is a pointer to the name of the file +to be executed. +The pointers +.IR arg [ 0 ], +.IR arg [ 1 "] ..." +address null-terminated strings. +Conventionally +.IR arg [ 0 ] +is the name of the +file. +.PP +Two interfaces are available. +.B execl +is useful when a known file with known arguments is +being called; +the arguments to +.B execl +are the character strings +constituting the file and the arguments; +the first argument is conventionally +the same as the file name (or its last component). +A null pointer argument must end the argument list. +(Note that the +.B execl* +functions are variable argument functions. This means that the type +of the arguments beyond +.I arg0 +is not checked. So the null pointer requires an explicit cast to type +.B "(char *)" +if not of that type already.) +.PP +The +.B execv +version is useful when the number of arguments is unknown +in advance; +the arguments to +.B execv +are the name of the file to be +executed and a vector of strings containing +the arguments. +The last argument string must be followed +by a null pointer. +.PP +When a C program is executed, +it is called as follows: +.PP +.RS +.ft B +.nf +int main(int \fIargc\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); + +exit(main(\fIargc\fP, \fIargv\fP, \fIenvp\fP)); +.fi +.ft R +.RE +.PP +where +.I argc +is the argument count +and +.I argv +is an array of character pointers +to the arguments themselves. +As indicated, +.I argc +is conventionally at least one +and the first member of the array points to a +string containing the name of the file. +.PP +.I Argv +is directly usable in another +.B execv +because +.IR argv [ argc ] +is 0. +.PP +.I Envp +is a pointer to an array of strings that constitute +the +.I environment +of the process. +Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. +The array of pointers is terminated by a null pointer. +The shell +.BR sh (1) +passes an environment entry for each global shell variable +defined when the program is called. +See +.BR environ (7) +for some conventionally +used names. +The C run-time start-off routine places a copy of +.I envp +in the global cell +.BR environ , +which is used +by +.B execv +and +.B execl +to pass the environment to any subprograms executed by the +current program. +.PP +.B Execlp +and +.B execvp +are called with the same arguments as +.B execl +and +.BR execv , +but duplicate the shell's actions in searching for an executable +file in a list of directories. +The directory list is obtained from the environment variable +.BR PATH . +Under standard Minix, if a file is found that is executable, but does +not have the proper executable header then it is assumed to be +a shell script. +.B Execlp +and +.B execvp +execute +.B /bin/sh +to interpret the script. +Under Minix-vmd this does not happen, a script must begin with +.B #! +and the full path name of the interpreter if it is to be an +executable script. +.SH "SEE ALSO" +.BR execve (2), +.BR fork (2), +.BR environ (7), +.BR sh (1). +.SH DIAGNOSTICS +If the file cannot be found, +if it is not executable, +if it does not start with a valid magic number (see +.BR a.out (5)), +if maximum memory is exceeded, +or if the arguments require too much space, +a return +constitutes the diagnostic; +the return value is \-1 and +.B errno +is set as for +.BR execve . +Even for the super-user, +at least one of the execute-permission bits must be set for +a file to be executed. diff --git a/man/man3/exit.3 b/man/man3/exit.3 new file mode 100644 index 000000000..a0ddf807b --- /dev/null +++ b/man/man3/exit.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)exit.3 6.2 (Berkeley) 5/12/86 +.\" +.TH EXIT 3 "May 12, 1986" +.UC 5 +.SH NAME +exit, atexit \- terminate a process after flushing any pending output +.SH SYNOPSIS +.nf +.ft B +#include + +void exit(int \fIstatus\fP) +int atexit(void (*\fIfunc\fP)(void)) +.ft R +.fi +.SH DESCRIPTION +.B Exit +first calls all functions registered by +.BR atexit , +flushes all data buffered by the Standard I/O library, and finally +terminates the process. +.B Exit +never returns. +.PP +.B Atexit +registers the function +.I func +into a table of functions to be called on exit. +.SH "SEE ALSO" +.BR exit (2). +.SH DIAGNOSTICS +.B Atexit +returns 0 on success, \-1 if +.B malloc +cannot allocate more memory for the list of registered functions. diff --git a/man/man3/fclose.3 b/man/man3/fclose.3 new file mode 100644 index 000000000..a8986d4c8 --- /dev/null +++ b/man/man3/fclose.3 @@ -0,0 +1,45 @@ +.\" @(#)fclose.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH FCLOSE 3 "May 15, 1985" +.AT 3 +.SH NAME +fclose, fflush \- close or flush a stream +.SH SYNOPSIS +.nf +.ft B +#include + +int fclose(FILE *\fIstream\fP) +int fflush(FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Fclose +causes any buffers for the named +.I stream +to be emptied, and the file to be closed. +Buffers allocated by the standard input/output system +are freed. +.PP +.B Fclose +is performed automatically upon +calling +.BR exit (3). +.PP +.B Fflush +causes any buffered data for the named output +.I stream +to be written to that file. +The stream remains open. +.SH "SEE ALSO" +.BR close (2), +.BR fopen (3), +.BR setbuf (3). +.SH DIAGNOSTICS +These routines return +.SM +.B EOF +if +.I stream +is not associated with an output file, or +if buffered data cannot be transferred to that file. diff --git a/man/man3/ferror.3 b/man/man3/ferror.3 new file mode 100644 index 000000000..ebafdd6da --- /dev/null +++ b/man/man3/ferror.3 @@ -0,0 +1,58 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)ferror.3s 6.3 (Berkeley) 5/14/86 +.\" +.TH FERROR 3 "May 14, 1986" +.UC 4 +.SH NAME +ferror, feof, clearerr, fileno \- stream status inquiries +.SH SYNOPSIS +.nf +.ft B +#include + +int feof(FILE *\fIstream\fP) +int ferror(FILE *\fIstream\fP) +int clearerr(FILE *\fIstream\fP) +int fileno(FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Feof +returns non-zero when end of file is read on the named input +.IR stream , +otherwise zero. +Unless cleared by +.BR clearerr , +the end-of-file indication lasts until +the stream is closed. +.PP +.B Ferror +returns non-zero when an error has occurred reading or writing +the named +.IR stream , +otherwise zero. +Unless cleared by +.BR clearerr , +the error indication lasts until +the stream is closed. +.PP +.B Clearerr +resets the error and end-of-file indicators on the named +.IR stream . +.PP +.B Fileno +returns the integer file descriptor +associated with the +.IR stream , +see +.BR open (2). +.PP +Currently all of these functions +are implemented as macros; +they cannot be redeclared. +.SH "SEE ALSO" +.BR fopen (3), +.BR open (2). diff --git a/man/man3/fopen.3 b/man/man3/fopen.3 new file mode 100644 index 000000000..4ae3f8002 --- /dev/null +++ b/man/man3/fopen.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)fopen.3s 6.3 (Berkeley) 5/27/86 +.\" +.TH FOPEN 3 "May 27, 1986" +.UC 4 +.SH NAME +fopen, freopen, fdopen \- open a stream +.SH SYNOPSIS +.nf +.ft B +#include + +FILE *fopen(const char *\fIfilename\fP, const char *\fItype\fP) +FILE *freopen(const char *\fIfilename\fP, const char *\fItype\fP, FILE *\fIstream\fP) +FILE *fdopen(int \fIfildes\fP, const char *\fItype\fP) +.ft R +.fi +.SH DESCRIPTION +.B Fopen +opens the file named by +.I filename +and associates a stream with it. +.B Fopen +returns a pointer to be used to identify the stream in subsequent operations. +.PP +.I Type +is a character string having one of the following values: +.TP 5 +"r" +open for reading +.ns +.TP 5 +"w" +create for writing +.ns +.TP 5 +"a" +append: open for writing at end of file, or create for writing +.PP +In addition, each +.I type +may be followed by a "+" to have the file opened for reading and writing. +"r+" positions the stream at the beginning of the file, "w+" creates +or truncates it, and "a+" positions it at the end. Both reads and writes +may be used on read/write streams, with the limitation that an +.BR fseek , +.BR rewind , +or reading an end-of-file must be used between a read and a write or vice-versa. +.PP +.B Freopen +substitutes the named file in place of the open +.IR stream . +It returns the original value of +.IR stream . +The original stream is closed. +.PP +.B Freopen +is typically used to attach the preopened constant names, +.B stdin, stdout, stderr, +to specified files. +.PP +.B Fdopen +associates a stream with a file descriptor obtained from +.BR open , +.BR dup , +.BR creat , +or +.BR pipe (2). +The +.I type +of the stream must agree with the mode of the open file. +.SH "SEE ALSO" +.BR open (2), +.BR fclose (3). +.SH DIAGNOSTICS +.B Fopen +and +.B freopen +return the pointer +.SM +.B NULL +if +.I filename +cannot be accessed, +if too many files are already open, +or if other resources needed cannot be allocated. +.SH BUGS +.B Fdopen +is not portable to systems other than UNIX. +.PP +The read/write +.I types +do not exist on all systems. Those systems without +read/write modes will probably treat the +.I type +as if the "+" was not present. These are unreliable in any event. diff --git a/man/man3/fread.3 b/man/man3/fread.3 new file mode 100644 index 000000000..535975c46 --- /dev/null +++ b/man/man3/fread.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)fread.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH FREAD 3 "May 15, 1985" +.UC 4 +.SH NAME +fread, fwrite \- buffered binary input/output +.SH SYNOPSIS +.nf +.ft B +#include +#include + +size_t fread(void *\fIptr\fP, size_t \fIitemsize\fP, size_t \fInitems\fP, FILE *\fIstream\fP) +size_t fwrite(void *\fIptr\fP, size_t \fIitemsize\fP, size_t \fInitems\fP, FILE *\fIstream\fP) +.SH DESCRIPTION +.B Fread +reads, into a block beginning at +.IR ptr , +.I nitems +of data of the type of +.I *ptr +from the named input +.IR stream . +It returns the number of items actually read. +.PP +If +.I stream +is +.B stdin +and the standard output is line buffered, then any partial output line +will be flushed before any call to +.BR read (2) +to satisfy the +.BR fread . +.PP +.B Fwrite +appends at most +.I nitems +of data of the type of +.I *ptr +beginning at +.I ptr +to the named output +.IR stream . +It returns the number of items actually written. +.SH "SEE ALSO" +.BR read (2), +.BR write (2), +.BR fopen (3), +.BR getc (3), +.BR putc (3), +.BR gets (3), +.BR puts (3), +.BR printf (3), +.BR scanf (3). +.SH DIAGNOSTICS +.B Fread +and +.B fwrite +return +0 +upon end of file or error. diff --git a/man/man3/fseek.3 b/man/man3/fseek.3 new file mode 100644 index 000000000..fe863bdac --- /dev/null +++ b/man/man3/fseek.3 @@ -0,0 +1,53 @@ +.\" @(#)fseek.3s 6.3 (Berkeley) 2/24/86 +.\" +.TH FSEEK 3 "February 24, 1986" +.AT 3 +.SH NAME +fseek, ftell, rewind \- reposition a stream +.SH SYNOPSIS +.nf +.ft B +#include + +int fseek(FILE *\fIstream\fP, long \fIoffset\fP, int \fIptrname\fP) +long ftell(FILE *\fIstream\fP) +void rewind(FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Fseek +sets the position of the next input or output +operation on the +.IR stream . +The new position is at the signed distance +.I offset +bytes +from the beginning, the current position, or the end of the file, +according as +.I ptrname +has the value 0, 1, or 2. +.PP +.B Fseek +undoes any effects of +.BR ungetc (3). +.PP +.B Ftell +returns the current value of the offset relative to the beginning +of the file associated with the named +.IR stream . +It is measured in bytes on UNIX; +on some other systems it is a magic cookie, +and the only foolproof way to obtain an +.I offset +for +.BR fseek . +.PP +.BR Rewind "(\fIstream\fR)" +is equivalent to +.BR fseek "(\fIstream\fR, 0L, 0)." +.SH "SEE ALSO" +.BR lseek (2), +.BR fopen (3). +.SH DIAGNOSTICS +.B Fseek +returns \-1 for improper seeks, otherwise zero. diff --git a/man/man3/g_h_b_n.3 b/man/man3/g_h_b_n.3 new file mode 100644 index 000000000..9f716e33c --- /dev/null +++ b/man/man3/g_h_b_n.3 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted provided +.\" that: (1) source distributions retain this entire copyright notice and +.\" comment, and (2) distributions including binaries display the following +.\" acknowledgement: ``This product includes software developed by the +.\" University of California, Berkeley and its contributors'' in the +.\" documentation or other materials provided with the distribution and in +.\" all advertising materials mentioning features or use of this software. +.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90 +.\" +.TH GETHOSTBYNAME 3 "June 23, 1990" +.UC 5 +.SH NAME +g_h_b_n, gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry +.SH SYNOPSIS +.B "#include +.PP +.B "extern int h_errno; +.PP +.B "struct hostent *gethostbyname(name) +.br +.B "char *name; +.PP +.B "struct hostent *gethostbyaddr(addr, len, type) +.br +.B "char *addr; int len, type; +.PP +.B "struct hostent *gethostent() +.PP +.B "sethostent(stayopen) +.br +.B "int stayopen; +.PP +.B "endhostent() +.PP +.B "herror(string) +.br +.B "char *string; +.PP +.SH DESCRIPTION +.I Gethostbyname +and +.I gethostbyaddr +each return a pointer to an object with the +following structure describing an internet host +referenced by name or by address, respectively. +This structure contains the information obtained from the name server. +.PP +.nf +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.ft R +.ad +.fi +.PP +The members of this structure are: +.TP \w'h_addr_list'u+2n +h_name +Official name of the host. +.TP \w'h_addr_list'u+2n +h_aliases +A zero terminated array of alternate names for the host. +.TP \w'h_addr_list'u+2n +h_addrtype +The type of address being returned; currently always AF_INET. +.TP \w'h_addr_list'u+2n +h_length +The length, in bytes, of the address. +.TP \w'h_addr_list'u+2n +h_addr_list +A zero terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.TP \w'h_addr_list'u+2n +h_addr +The first address in h_addr_list; this is for backward compatiblity. +.PP +When using the nameserver, +.I gethostbyname +will search for the named host in the current domain and its parents +unless the name ends in a dot. +If the name contains no dot, and if the environment variable ``HOSTALAIASES'' +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.IR hostname (7) +for the domain search procedure and the alias file format. +.PP +.I Sethostent +may be used to request the use of a connected TCP socket for queries. +If the +.I stayopen +flag is non-zero, +this sets the option to send all queries to the name server using TCP +and to retain the connection after each call to +.I gethostbyname +or +.IR gethostbyaddr . +Otherwise, queries are performed using UDP datagrams. +.PP +.I Endhostent +closes the TCP connection. +.SH DIAGNOSTICS +.PP +Error return status from +.I gethostbyname +and +.I gethostbyaddr +is indicated by return of a null pointer. +The external integer +.IR h_errno +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The routine +.I herror +can be used to print an error message describing the failure. +If its argument +.I string +is non-NULL, it is printed, followed by a colon and a space. +The error message is printed with a trailing newline. +.PP +.IR h_errno +can have the following values: +.RS +.IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n +No such host is known. +.IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n +This is usually a temporary error +and means that the local server did not receive +a response from an authoritative server. +A retry at some later time may succeed. +.IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n +Some unexpected server failure was encountered. +This is a non-recoverable error. +.IP NO_DATA \w'HOST_NOT_FOUND'u+2n +The requested name is valid but does not have an IP address; +this is not a temporary error. +This means that the name is known to the name server but there is no address +associated with this name. +Another type of request to the name server using this domain name +will result in an answer; +for example, a mail-forwarder may be registered for this domain. +.RE +.SH "SEE ALSO" +resolver(3), hostname(7), nonamed(8), named(8) +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. Only the Internet +address format is currently understood. diff --git a/man/man3/getc.3 b/man/man3/getc.3 new file mode 100644 index 000000000..4c9afdc3c --- /dev/null +++ b/man/man3/getc.3 @@ -0,0 +1,79 @@ +.\" @(#)getc.3s 6.2 (Berkeley) 5/14/86 +.\" +.TH GETC 3 "May 14, 1986" +.AT 3 +.SH NAME +getc, getchar, fgetc, getw \- get character or word from stream +.SH SYNOPSIS +.nf +.ft B +#include + +int getc(FILE *\fIstream\fP) +int getchar(void) +int fgetc(FILE *\fIstream\fP) +int getw(FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Getc +returns the next character from the named input +.IR stream . +.PP +.BR Getchar () +is identical to +.BR getc ( stdin ). +.PP +.B Fgetc +behaves like +.BR getc , +but is a genuine function, not a macro; +it may be used to save object text. +.PP +.B Getw +returns the next +.B int +from the named input +.IR stream . +It returns the constant +.SM +.B EOF +upon end of file or error, but since that is a good +integer value, +.B feof +and +.BR ferror (3) +should be used to check the success of +.BR getw . +.B Getw +assumes no special alignment in the file. +.SH "SEE ALSO" +.BR clearerr (3), +.BR fopen (3), +.BR putc (3), +.BR gets (3), +.BR scanf (3), +.BR fread (3), +.BR ungetc (3). +.SH DIAGNOSTICS +These functions return the integer constant +.SM +.B EOF +at end of file, upon read error, +or if an attempt is made to read a file not opened by +.BR fopen . +The end-of-file condition is remembered, +even on a terminal, +and all subsequent attempts to read will return +.B EOF +until the condition is cleared with +.BR clearerr (3). +.SH BUGS +Because it is implemented as a macro, +.B getc +treats a +.I stream +argument with side effects incorrectly. +In particular, +`getc(*f++);' +doesn't work sensibly. diff --git a/man/man3/getcwd.3 b/man/man3/getcwd.3 new file mode 100644 index 000000000..08d66fe71 --- /dev/null +++ b/man/man3/getcwd.3 @@ -0,0 +1,36 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getwd.3 6.2 (Berkeley) 5/12/86 +.\" +.TH GETCWD 3 "May 12, 1986" +.UC 5 +.SH NAME +getcwd \- get current working directory pathname +.SH SYNOPSIS +.nf +.ft B +#include + +char *getcwd(char *\fIpathname\fP, size_t \fIlen\fP) +.fi +.SH DESCRIPTION +.B Getcwd +copies the absolute pathname of the current working directory to +.I pathname +and returns a pointer to the result. +.I Pathname +is a character array of length +.IR len . +.SH DIAGNOSTICS +.B Getcwd +returns a null pointer and sets +.B errno +if an error occurs. The error will reflect the system call errors that +may occur if the path to the current directory is searched upwards to +the root directory. The error +.B ERANGE +is returned if the result does not fit within +.I len +bytes. diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 new file mode 100644 index 000000000..78c282d2d --- /dev/null +++ b/man/man3/getenv.3 @@ -0,0 +1,29 @@ +.\" @(#)getenv.3 6.1 (Berkeley) 5/15/85 +.\" +.TH GETENV 3 "May 15, 1985" +.AT 3 +.SH NAME +getenv \- value for environment name +.SH SYNOPSIS +.nf +.ft B +#include + +char *getenv(const char *\fIname\fP) +.ft R +.fi +.SH DESCRIPTION +.B Getenv +searches the environment list +(see +.BR environ (7)) +for a string of the form +.IB name = value +and returns a pointer to the string +.I value +if such a string is present, otherwise +.B getenv +returns the null pointer. +.SH SEE ALSO +.BR environ (7), +.BR execve (2). diff --git a/man/man3/getgrent.3 b/man/man3/getgrent.3 new file mode 100644 index 000000000..f1aba2619 --- /dev/null +++ b/man/man3/getgrent.3 @@ -0,0 +1,136 @@ +.TH GETGRENT 3 +.SH NAME +getgrent, getgrnam, getgrgid, setgrent, endgrent, setgrfile \- group file routines +.SH SYNOPSIS +.ft B +.nf +#include + +struct group *getgrent(void) +struct group *getgrnam(const char *\fIname\fP) +struct group *getgrgid(gid_t \fIgid\fP) +int setgrent(void) +void endgrent(void) +void setgrfile(const char *\fIfile\fP) +.fi +.ft P +.SH DESCRIPTION +These functions are used to obtain information from the group file. They +return this information in a +.B struct group +as defined by : +.PP +.nf +.ta +4n +6n +15n +struct group { + char *gr_name; /* login name */ + char *gr_passwd; /* encrypted password */ + gid_t gr_gid; /* numeric group id */ + char **gr_mem; /* null-terminated list of group members */ +}; +.fi +.PP +.B Getgrent() +reads the group file entry by entry. +.B Getgrnam() +scans the entire group file for the group with the given +.IR name . +.B Getgrgid() +looks for the first group with the given +.IR gid . +The +.B setgrent() +and +.B endgrent() +functions are used to open and later close the group file. With +.B setgrfile() +one can specify the file to read other than the normal group file. This +only sets the name, the next +.B setgrent() +call will open the file. Do not touch the file name while it is active. +Use +.B setgrfile(NULL) +to revert back to the normal group file. +.PP +The usual way to scan the group file is (error checking omitted): +.PP +.RS +.nf +.DT +setgrent(); +while ((gr = getgrent()) != NULL) + if (appropriate_test(gr)) break; +endgrent(); +.fi +.RE +.PP +The +.B gr +variable contains the entry that is wanted if non-NULL. The +.B getgrnam() +and +.B getgrgid() +functions are implemented as in this example, with error checking of course. +.PP +.B Getgrent() +calls +.B setgrent() +if this has not yet been done. +.B Setgrent() +first calls +.B endgrent() +if the group file is still open. (Other implementations may simply +rewind the file.) +.SH FILES +.TP 15 +.B /etc/group +The group file database. +.SH "SEE ALSO" +.BR getgroups (2), +.BR initgroups (3), +.BR getpwent (3), +.BR passwd (5). +.SH DIAGNOSTICS +.B Setgrent() +has the same return value and error codes as the +.BR open (2) +call it uses to open the group file. The +.BI get xxx () +functions return NULL on end of file, entry not found, or error. You can +set +.B errno +to zero before the call and check it after. +.SH NOTES +All +.BI get xxx () +routines return a pointer to static storage that is overwritten in each call. +.PP +Only +.B getgrnam() +and +.B getgrgid() +are defined by \s-2POSIX\s+2. The +.B _MINIX_SOURCE +macro must be defined before including to make the other functions +visible. The +.B gr_passwd +field is also not defined by \s-2POSIX\s+2, but is always visible. +Portable code cannot reliably detect errors by setting +.B errno +to zero. Under Minix it is better to make a +.B getgrent() +scan if you need to look up several group-id's or names, but portable code +had better use several +.B getgrgid() +or +.B getgrnam() +calls. The +.B getgrent() +is usually available on other systems, but may be very expensive. See +.BR initgroups (3) +if you are after supplementary group id's. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: getgrent.3,v 1.2 1996/04/11 06:35:01 philip Exp $ diff --git a/man/man3/getlogin.3 b/man/man3/getlogin.3 new file mode 100644 index 000000000..cff579064 --- /dev/null +++ b/man/man3/getlogin.3 @@ -0,0 +1,45 @@ +.\" @(#)getlogin.3 6.2 (Berkeley) 5/9/86 +.\" +.TH GETLOGIN 3 "May 9, 1986" +.AT 3 +.SH NAME +getlogin \- get login name +.SH SYNOPSIS +.nf +.ft B +#include + +char *getlogin(void) +.fi +.SH DESCRIPTION +.B Getlogin +returns a pointer to the login name as found in +.BR /etc/utmp . +It may be used in conjunction with +.B getpwnam +to locate the correct password file entry when the same user ID +is shared by several login names. +.PP +If +.B getlogin +is called within a process that is not attached to a +terminal, or if there is no entry in +.B /etc/utmp +for the process's terminal, +.B getlogin +returns a null pointer. +A reasonable procedure for determining the login name is to first call +.B getlogin +and if it fails, to call +.BR getpwuid ( getuid ()). +.SH FILES +/etc/utmp +.SH "SEE ALSO" +.BR getpwent (3), +.BR utmp (5), +.BR ttyslot (3) +.SH DIAGNOSTICS +Returns a null pointer if the name cannot be found. +.SH BUGS +The return values point to static data +whose content is overwritten by each call. diff --git a/man/man3/getopt.3 b/man/man3/getopt.3 new file mode 100644 index 000000000..befeacb25 --- /dev/null +++ b/man/man3/getopt.3 @@ -0,0 +1,150 @@ +.\" Copyright (c) 1985 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getopt.3 6.4 (Berkeley) 5/27/86 +.\" +.TH GETOPT 3 "May 27, 1986" +.UC 6 +.SH NAME +getopt \- get option letter from argv +.SH SYNOPSIS +.ft B +int getopt(argc, argv, optstring) +.br +int argc; +.br +char **argv; +.br +char *optstring; +.sp +extern char *optarg; +.br +extern int optind; +.ft +.SH DESCRIPTION +.I Getopt +returns the next option letter in +.I argv +that matches a letter in +.IR optstring . +.I Optstring +is a string of recognized option letters; +if a letter is followed by a colon, the option is expected to have +an argument that may or may not be separated from it by white space. +.I Optarg +is set to point to the start of the option argument on return from +.IR getopt . +.PP +.I Getopt +places in +.I optind +the +.I argv +index of the next argument to be processed. +Because +.I optind +is external, it is normally initialized to zero automatically +before the first call to +.IR getopt . +.PP +When all options have been processed (i.e., up to the first +non-option argument), +.I getopt +returns +.BR EOF . +The special option +.B \-\- +may be used to delimit the end of the options; +.B EOF +will be returned, and +.B \-\- +will be skipped. +.SH DIAGNOSTICS +.I Getopt +prints an error message on +.I stderr +and returns a question mark +.RB ( ? ) +when it encounters an option letter not included in +.IR optstring . +.SH EXAMPLE +The following code fragment shows how one might process the arguments +for a command that can take the mutually exclusive options +.B a +and +.BR b , +and the options +.B f +and +.BR o , +both of which require arguments: +.PP +.RS +.nf +main(argc, argv) +int argc; +char **argv; +{ + int c; + extern int optind; + extern char *optarg; + \&. + \&. + \&. + while ((c = getopt(argc, argv, "abf:o:")) != EOF) + switch (c) { + case `a': + if (bflg) + errflg++; + else + aflg++; + break; + case `b': + if (aflg) + errflg++; + else + bproc(); + break; + case `f': + ifile = optarg; + break; + case `o': + ofile = optarg; + break; + case `?': + default: + errflg++; + break; + } + if (errflg) { + fprintf(stderr, "Usage: ..."); + exit(2); + } + for (; optind < argc; optind++) { + \&. + \&. + \&. + } + \&. + \&. + \&. +} +.RE +.SH HISTORY +Written by Henry Spencer, working from a Bell Labs manual page. +Modified by Keith Bostic to behave more like the System V version. +.SH BUGS +It is not obvious how +`\-' +standing alone should be treated; this version treats it as +a non-option argument, which is not always right. +.PP +Option arguments are allowed to begin with `\-'; +this is reasonable but reduces the amount of error checking possible. +.PP +.I Getopt +is quite flexible but the obvious price must be paid: there is much +it could do that it doesn't, like +checking mutually exclusive options, checking type of +option arguments, etc. diff --git a/man/man3/getpass.3 b/man/man3/getpass.3 new file mode 100644 index 000000000..8d357d2f8 --- /dev/null +++ b/man/man3/getpass.3 @@ -0,0 +1,28 @@ +.\" @(#)getpass.3 6.1 (Berkeley) 5/15/85 +.\" +.TH GETPASS 3 "May 15, 1985" +.AT 3 +.SH NAME +getpass \- read a password +.SH SYNOPSIS +.nf +.ft B +#include + +char *getpass(const char *\fIprompt\fP) +.fi +.SH DESCRIPTION +.B Getpass +reads a password from the file +.BR /dev/tty , +or if that cannot be opened, from the standard input, +after prompting with the null-terminated string +.I prompt +and disabling echoing. +A pointer is returned to a null-terminated string +of at most 32 characters, excluding the null. +.SH "SEE ALSO" +.BR crypt (3). +.SH BUGS +The return value points to static data +whose content is overwritten by each call. diff --git a/man/man3/getpwent.3 b/man/man3/getpwent.3 new file mode 100644 index 000000000..6a217ac43 --- /dev/null +++ b/man/man3/getpwent.3 @@ -0,0 +1,139 @@ +.TH GETPWENT 3 +.SH NAME +getpwent, getpwnam, getpwuid, setpwent, endpwent, setpwfile \- password file routines +.SH SYNOPSIS +.ft B +.nf +#include + +struct passwd *getpwent(void) +struct passwd *getpwnam(const char *\fIname\fP) +struct passwd *getpwuid(uid_t \fIuid\fP) +int setpwent(void) +void endpwent(void) +void setpwfile(const char *\fIfile\fP) +.fi +.ft P +.SH DESCRIPTION +These functions are used to obtain information from the password file. They +return this information in a +.B struct passwd +as defined by : +.PP +.nf +.ta +4n +6n +15n +struct passwd { + char *pw_name; /* login name */ + char *pw_passwd; /* encrypted password */ + uid_t pw_uid; /* numeric user id */ + gid_t pw_gid; /* numeric group id */ + char *pw_gecos; /* user full name and other info */ + char *pw_dir; /* user's home directory */ + char *pw_shell; /* name of the user's shell */ +}; +.fi +.PP +.B Getpwent() +reads the password file entry by entry. +.B Getpwnam() +scans the entire password file for the user with the given +.IR name . +.B Getpwuid() +looks for the first user with the given +.IR uid . +The +.B setpwent() +and +.B endpwent() +functions are used to open and later close the password file. With +.B setpwfile() +one can specify the file to read other than the normal password file. This +only sets the name, the next +.B setpwent() +call will open the file. Do not touch the file name while it is active. +Use +.B setpwfile(NULL) +to revert back to the normal password file. +.PP +The usual way to scan the password file is (error checking omitted): +.PP +.RS +.nf +.DT +setpwent(); +while ((pw = getpwent()) != NULL) + if (appropriate_test(pw)) break; +endpwent(); +.fi +.RE +.PP +The +.B pw +variable contains the entry that is wanted if non-NULL. The +.B getpwnam() +and +.B getpwuid() +functions are implemented as in this example, with error checking of course. +.PP +.B Getpwent() +calls +.B setpwent() +if this has not yet been done. +.B Setpwent() +first calls +.B endpwent() +if the password file is still open. (Other implementations may simply +rewind the file.) +.SH FILES +.TP 15 +.B /etc/passwd +The password file database. +.SH "SEE ALSO" +.BR cuserid (3), +.BR getlogin (3), +.BR getgrent (3), +.BR passwd (5). +.SH DIAGNOSTICS +.B Setpwent() +has the same return value and error codes as the +.BR open (2) +call it uses to open the password file. The +.BI get xxx () +functions return NULL on end of file, entry not found, or error. You can +set +.B errno +to zero before the call and check it after. +.SH NOTES +All +.BI get xxx () +routines return a pointer to static storage that is overwritten in each call. +.PP +Only +.B getpwnam() +and +.B getpwuid() +are defined by \s-2POSIX\s+2. The +.B _MINIX_SOURCE +macro must be defined before including to make the other functions +visible. The +.B pw_passwd +and +.B pw_gecos +fields are also not defined by \s-2POSIX\s+2, but are always visible. +Portable code cannot reliably detect errors by setting +.B errno +to zero. Under Minix it is better to make a +.B getpwent() +scan if you need to look up several user-id's or names, but portable code +had better use several +.B getpwuid() +or +.B getpwnam() +calls. The +.B getpwent() +is usually available on other systems, but may be very expensive. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: getpwent.3,v 1.2 1996/04/11 06:37:43 philip Exp $ diff --git a/man/man3/gets.3 b/man/man3/gets.3 new file mode 100644 index 000000000..a0eda05fb --- /dev/null +++ b/man/man3/gets.3 @@ -0,0 +1,68 @@ +.\" @(#)gets.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH GETS 3 "May 15, 1985" +.AT 3 +.SH NAME +gets, fgets \- get a string from a stream +.SH SYNOPSIS +.nf +.ft B +#include + +char *gets(char *\fIs\fP) +char *fgets(char *\fIs\fP, int \fIn\fP, FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Gets +reads a string into +.I s +from the standard input stream +.BR stdin . +The string is terminated by a newline +character, which is replaced in +.I s +by a null character. +.B Gets +returns its argument. +.PP +.B Fgets +reads +.IR n \-1 +characters, or up through a newline +character, whichever comes first, +from the +.I stream +into the string +.IR s . +The last character read into +.I s +is followed by a null character. +.B Fgets +returns its first argument. +.SH "SEE ALSO" +.BR puts (3), +.BR getc (3), +.BR scanf (3), +.BR fread (3), +.BR ferror (3). +.SH DIAGNOSTICS +.B Gets +and +.B fgets +return the constant pointer +.SM +.B NULL +upon end of file or error. +.SH BUGS +.B Gets +deletes a newline, +.B fgets +keeps it, +all in the name of backward compatibility. +.PP +.B Gets +is not present in the Minix-vmd C library for reasons that should be obvious. +Use +.B fgets +instead. diff --git a/man/man3/getservent.3 b/man/man3/getservent.3 new file mode 100644 index 000000000..d3d760b38 --- /dev/null +++ b/man/man3/getservent.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getservent.3n 6.3 (Berkeley) 5/19/86 +.\" +.TH GETSERVENT 3 "May 19, 1986" +.UC 5 +.SH NAME +getservent, getservbyport, getservbyname, setservent, endservent \- get service entry +.SH SYNOPSIS +.nf +.ft B +#include +.PP +.ft B +struct servent *getservent() +.PP +.ft B +struct servent *getservbyname(name, proto) +char *name, *proto; +.PP +.ft B +struct servent *getservbyport(port, proto) +int port; char *proto; +.PP +.ft B +setservent(stayopen) +int stayopen +.PP +.ft B +endservent() +.fi +.SH DESCRIPTION +.IR Getservent , +.IR getservbyname , +and +.I getservbyport +each return a pointer to an object with the +following structure +containing the broken-out +fields of a line in the network services data base, +.IR /etc/services . +.RS +.PP +.nf +struct servent { + char *s_name; /* official name of service */ + char **s_aliases; /* alias list */ + int s_port; /* port service resides at */ + char *s_proto; /* protocol to use */ +}; +.ft R +.ad +.fi +.RE +.PP +The members of this structure are: +.TP \w's_aliases'u+2n +s_name +The official name of the service. +.TP \w's_aliases'u+2n +s_aliases +A zero terminated list of alternate names for the service. +.TP \w's_aliases'u+2n +s_port +The port number at which the service resides. +Port numbers are returned in network byte order. +.TP \w's_aliases'u+2n +s_proto +The name of the protocol to use when contacting the +service. +.PP +.I Getservent +reads the next line of the file, opening the file if necessary. +.PP +.I Setservent +opens and rewinds the file. If the +.I stayopen +flag is non-zero, +the net data base will not be closed after each call to +.I getservbyname +or +.IR getservbyport . +.PP +.I Endservent +closes the file. +.PP +.I Getservbyname +and +.I getservbyport +sequentially search from the beginning +of the file until a matching +protocol name or +port number is found, +or until EOF is encountered. +If a protocol name is also supplied (non-NULL), +searches must also match the protocol. +.SH FILES +/etc/services +.SH "SEE ALSO" +getprotoent(3), services(5) +.SH DIAGNOSTICS +Null pointer +(0) returned on EOF or error. +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. Expecting port +numbers to fit in a 32 bit +quantity is probably naive. diff --git a/man/man3/getttyent.3 b/man/man3/getttyent.3 new file mode 100644 index 000000000..6b507ff70 --- /dev/null +++ b/man/man3/getttyent.3 @@ -0,0 +1,107 @@ +.TH GETTTYENT 3 +.SH NAME +getttyent, getttynam, setttyent, endttyent \- interface to /etc/ttytab +.SH SYNOPSIS +.ft B +.nf +#include + +struct ttyent *getttyent(void) +struct ttyent *getttynam(const char *\fIname\fP) +int setttyent(void) +void endttyent(void) +.fi +.ft P +.SH DESCRIPTION +The +.B getttyent +functions provide an interface to the /etc/ttytab. (See +.BR ttytab (5)). +.PP +To read one of these files one calls +.B getttyent() +several times to read the entries in the table until NULL is returned for +end-of-file. +.PP +.B Getttyname() +searches the +.B ttytab +file for the given terminal device. It is equivalent to a call to +.BR setttyent(), +several calls to +.B getttyent() +to locate the entry, and a final +.B endttyent() +to close the file. +.PP +.B Setttyent() +opens or rewinds the ttytab database, and +.B endttyent() closes it. +.B Getttyent() +opens the database if not already open, but does not close it. +.PP +The struct ttyent is defined by as follows: +.sp +.nf +.ta +4n +6n +15n +struct ttyent { + char *ty_name; /* Name of the terminal device. */ + char *ty_type; /* Terminal type name (termcap(3)). */ + char **ty_getty; /* Program to run, normally getty. */ + char **ty_init; /* Initialization command, normally stty. */ +}; +.fi +.PP +A valid entry has at least two strings, so both +.B ty_name +and +.B ty_type +are filled in. The optional +.B ty_getty +and +.B ty_init +may be NULL (field omitted), point to a pointer that is NULL (null lenght +field, i.e. ""), or an array of strings terminated by a NULL (field +present). For now no useful distinction can be made between a omitted field +and an empty field, so treat both cases as an omission. +.SH FILES +.TP 15 +.B /etc/ttytab +The terminal device database +.SH "SEE ALSO" +.BR ttyname (3), +.BR ttyslot (3), +.BR ttytab (5), +.BR init (8). +.SH DIAGNOSTICS +.B Setttyent() +has the same return value and error codes as the +.BR open (2) +call it uses to open the ttytab file. The +.BI get xxx () +functions return NULL on end of file, entry not found, or error. You can +set +.B errno +to zero before the call and check it after. +.SH NOTES +.B Getttyent() +and +.B getttynam() +return a pointer to static storage that is overwritten in each call. +.PP +The Minix +.B struct ttyent +has only the +.B ty_name +and +.B ty_type +fields in common with the BSD implementation. This does not seem to be a +problem, because most third party software that need to know about terminals +only look at the +.B ty_name +field. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: getttyent.3,v 1.2 1996/04/11 06:57:26 philip Exp $ diff --git a/man/man3/hton.3 b/man/man3/hton.3 new file mode 100644 index 000000000..2b02fa8ef --- /dev/null +++ b/man/man3/hton.3 @@ -0,0 +1,60 @@ +.TH HTON 3 +.SH NAME +hton, htons, htonl, ntohs, ntohl \- host to network byte order conversion +.SH SYNOPSIS +.ft B +.nf +#define _MINIX_SOURCE 1 +#include +#include + +#include + +u16_t htons(u16_t \fIhost_word\fP) +u32_t htonl(u32_t \fIhost_dword\fP) +u16_t ntohs(u16_t \fInetwork_word\fP) +u32_t ntohl(u32_t \fInetwork_dword\fP) +u16_t HTONS(u16_t \fIhost_word\fP) +u32_t HTONL(u32_t \fIhost_dword\fP) +u16_t NTOHS(u16_t \fInetwork_word\fP) +u32_t NTOHL(u32_t \fInetwork_dword\fP) +.fi +.ft R +.SH DESCRIPTION +These macros convert 16-bit and 32-bit quantities to and from the network +byte order used by the TCP/IP protocols. +The function of the macros is encoded in their name. +.B H +means host byte order, +.B n +means network byte order, +.B s +means a 16-bit quantity and +.B l +means a 32-bit quantity. +Thus +.B htons +converts a 16-bit quantity from host byte order to network byte order. +The difference between the lower case and upper case variants is that +the lower case variants evaluate the argument at most once and the +upper case variants can be used for constant folding. +That is, +.PP +.RS +htonl(f(x)) +.RE +.PP +will call f(x) at most once and +.PP +.RS +HTONS(0x10) +.RE +.PP +will be equivalent to 0x10 on a big-endian machine and 0x1000 on a +little-endian machine. +.SH "SEE ALSO" +.BR ip (4). +.SH AUTHOR +Philip Homburg (philip@cs.vu.nl) +.\" +.\" $PchId: hton.3,v 1.3 1996/02/22 21:10:01 philip Exp $ diff --git a/man/man3/int64.3 b/man/man3/int64.3 new file mode 100644 index 000000000..f76cde688 --- /dev/null +++ b/man/man3/int64.3 @@ -0,0 +1,193 @@ +.TH INT64 3 +.SH NAME +int64, add64, add64u, add64ul, sub64, sub64u, sub64ul, diff64, cvu64, cvul64, cv64u, cv64ul, div64u, rem64u, mul64u, cmp64, cmp64u, cmp64ul, ex64lo, ex64hi, make64 \- 64 bit disk offset computations +.SH SYNOPSIS +.ft B +.nf +#include + +u64_t add64(u64_t \fIi\fP, u64_t \fIj\fP) +u64_t add64u(u64_t \fIi\fP, unsigned \fIj\fP) +u64_t add64ul(u64_t \fIi\fP, unsigned long \fIj\fP) +u64_t sub64(u64_t \fIi\fP, u64_t \fIj\fP) +u64_t sub64u(u64_t \fIi\fP, unsigned \fIj\fP) +u64_t sub64ul(u64_t \fIi\fP, unsigned long \fIj\fP) +unsigned diff64(u64_t \fIi\fP, u64_t \fIj\fP) +u64_t cvu64(unsigned \fIi\fP) +u64_t cvul64(unsigned long \fIi\fP) +unsigned cv64u(u64_t \fIi\fP) +unsigned long cv64ul(u64_t \fIi\fP) +unsigned long div64u(u64_t \fIi\fP, unsigned \fIj\fP) +unsigned rem64u(u64_t \fIi\fP, unsigned \fIj\fP) +u64_t mul64u(unsigned long \fIi\fP, unsigned \fIj\fP) +int cmp64(u64_t \fIi\fP, u64_t \fIj\fP) +int cmp64u(u64_t \fIi\fP, unsigned \fIj\fP) +int cmp64ul(u64_t \fIi\fP, unsigned long \fIj\fP) +unsigned long ex64lo(u64_t \fIi\fP) +unsigned long ex64hi(u64_t \fIi\fP) +u64_t make64(unsigned long \fIlo\fP, unsigned long \fIhi\fP) +.fi +.ft P +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The +.B int64 +family of functions allow Minix to handle disks of up to 4 terabytes using +32 bit sector numbers and 64 bit byte offsets on a machine where the C type +.B long +is 32 bits. The include file defines a 64 bit data +type, +.BR u64_t , +and a number of functions to operate on them. Note that these functions are +geared towards common disk offset and block computations, and do not provide +a full set of 64 bit operations. They are: +.PP +.TP +.B "u64_t add64(u64_t \fIi\fP, u64_t \fIj\fP)" +Add the 64 bit numbers +.I i +and +.I j +forming a 64 bit result. +.TP +.B "u64_t add64u(u64_t \fIi\fP, unsigned \fIj\fP)" +Add an unsigned +.I j +to a 64 bit number +.I i +forming a 64 bit result. +.TP +.B "u64_t add64ul(u64_t \fIi\fP, unsigned long \fIj\fP)" +Add an unsigned long +.I j +to a 64 bit number +.I i +forming a 64 bit result. +.TP +.B "u64_t sub64(u64_t \fIi\fP, u64_t \fIj\fP)" +Subtract the 64 bit number +.I j +from the 64 bit number +.I i +forming a 64 bit result. +.TP +.B "u64_t sub64u(u64_t \fIi\fP, unsigned \fIj\fP)" +Subtract the unsigned +.I j +from the 64 bit number +.I i +forming a 64 bit result. +.TP +.B "u64_t sub64ul(u64_t \fIi\fP, unsigned long \fIj\fP)" +Subtract the unsigned long +.I j +from the 64 bit number +.I i +forming a 64 bit result. +.TP +.B "unsigned diff64(u64_t \fIi\fP, u64_t \fIj\fP)" +Subtract the 64 bit number +.I j +from the 64 bit number +.I i +forming an unsigned. Overflow is not checked. +.TP +.B "u64_t cvu64(unsigned \fIi\fP)" +Convert an unsigned to a 64 bit number. +.TP +.B "u64_t cvul64(unsigned long \fIi\fP)" +Convert an unsigned long to a 64 bit number. +.TP +.B "unsigned cv64u(u64_t \fIi\fP)" +Convert a 64 bit number to an unsigned if it fits, otherwise return +.BR UINT_MAX . +.TP +.B "unsigned long cv64ul(u64_t \fIi\fP)" +Convert a 64 bit number to an unsigned long if it fits, otherwise return +.BR ULONG_MAX . +.TP +.B "unsigned long div64u(u64_t \fIi\fP, unsigned \fIj\fP)" +Divide the 64 bit number +.I i +by the unsigned +.I j +giving an unsigned long. Overflow is not checked. (Typical "byte offset to +block number" conversion.) +.TP +.B "unsigned rem64u(u64_t \fIi\fP, unsigned \fIj\fP)" +Compute the remainder of the division of the 64 bit number +.I i +by the unsigned +.I j +as an unsigned. (Typical "byte offset within a block" computation.) +.TP +.B "u64_t mul64u(unsigned long \fIi\fP, unsigned \fIj\fP)" +Multiply the unsigned long +.I i +by the unsigned +.I j +giving a 64 bit number. (Typical "block number to byte offset" conversion.) +.TP +.B "int cmp64(u64_t \fIi\fP, u64_t \fIj\fP)" +Compare two 64 bit numbers. +Returns +.B -1 +if +.I i +< +.IR j , +.B 0 +if +.I i +== +.IR j , +and +.B 1 +if +.I i +> +.IR j . +.TP +.B "int cmp64u(u64_t \fIi\fP, unsigned \fIj\fP)" +Likewise compare a 64 bit number with an unsigned. +.TP +.B "int cmp64ul(u64_t \fIi\fP, unsigned long \fIj\fP)" +Likewise compare a 64 bit number with an unsigned long. +.TP +.B "unsigned long ex64lo(u64_t \fIi\fP)" +Extract the low 32 bits of a 64 bit number. +.TP +.B "unsigned long ex64hi(u64_t \fIi\fP)" +Extract the high 32 bits of a 64 bit number. +.TP +.B "u64_t make64(unsigned long \fIlo\fP, unsigned long \fIhi\fP)" +Combine the low and high parts of a 64 bit number to a 64 bit number. (The +last three functions are used to pass 64 bit numbers in messages within the +kernel. They should not be used for anything else.) +.SH "SEE ALSO" +.BR fcntl (2), +.BR controller (4). +.SH NOTES +With the usual disk block size of 512 bytes the maximum disk size is 512 +\(** 4 gigabytes = 2 terabytes. +.PP +Standard Minix only uses 64 bit computations within the disk drivers, so +individual partitions are still limited to 4 gigabytes. Minix-vmd has 64 +bit computations also in the file system code. +.PP +Special care must be taken when accessing disk devices. For Minix one may +have to temporarily change the start of the partition to go beyond 4 G. +Minix-vmd can go beyond 4 G, but the +.B lseek +system call is still limited to a 32 bit offset. One needs to use +.PP +.RS +.BI "fcntl(" fd ", F_SEEK, u64_t " offset ")" +.RE +.PP +to seek to a 64 bit position. +.SH AUTHOR +Kees J. Bot diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 000000000..efbe0e417 --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)malloc.3 6.3 (Berkeley) 5/14/86 +.\" +.TH MALLOC 3 "May 14, 1986" +.UC 4 +.SH NAME +malloc, free, realloc, calloc, alloca \- memory allocator +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +void *malloc(size_t \fIsize\fP) +void free(void *\fIptr\fP) +void *realloc(void *\fIptr\fP, size_t \fIsize\fP) +void *calloc(size_t \fInelem\fP, size_t \fIelsize\fP) +void *alloca(size_t \fIsize\fP) +.ft R +.fi +.SH DESCRIPTION +.B Malloc +and +.B free +provide a general-purpose memory allocation package. +.B Malloc +returns a pointer to a block of at least +.I size +bytes beginning on a word boundary. +.PP +The argument to +.B free +is a pointer to a block previously allocated by +.BR malloc ; +this space is made available for further allocation, +but its contents are left undisturbed. +A call with a null +.I ptr +is legal and does nothing. +.PP +Needless to say, grave disorder will result if the space assigned by +.B malloc +is overrun or if some random number is handed to +.BR free . +.PP +.B Malloc +maintains multiple lists of free blocks according to size, +allocating space from the appropriate list. +It calls +.B sbrk +(see +.BR brk (2)) +to get more memory from the system when there is no +suitable space already free. +.PP +.B Realloc +changes the size of the block pointed to by +.I ptr +to +.I size +bytes and returns a pointer to the (possibly moved) block. +The contents will be unchanged up to the lesser of the new and old sizes. +A call with a null +.I ptr +is legal and has the same result as +.BI malloc( size )\fR. +.PP +.B Calloc +allocates space for an array of +.I nelem +elements of size +.I elsize. +The space is initialized to zeros. +.PP +.B Alloca +allocates +.I size +bytes of space in the stack frame of the caller. +This temporary space is automatically freed on +return. +.PP +Each of the allocation routines returns a pointer +to space suitably aligned (after possible pointer coercion) +for storage of any type of object. +.SH SEE ALSO +.BR brk (2). +.SH DIAGNOSTICS +.BR Malloc , +.BR realloc +and +.B calloc +return a null pointer if there is no available memory or if the arena +has been detectably corrupted by storing outside the bounds of a block. +.SH NOTES +Other implementations of +.BR malloc , +.BR realloc +or +.BR calloc +may return a null pointer if the size of the requested block is zero. This +implementation will always return a zero length block at a unique address, +but you should keep in mind that a null return is possible if the program +is run to another system and that this should not be mistakenly seen as +an error. +.SH BUGS +When +.B realloc +returns a null pointer, the block pointed to by +.I ptr +may be destroyed. +.PP +.B Alloca +is machine dependent; its use is discouraged. diff --git a/man/man3/oneC_sum.3 b/man/man3/oneC_sum.3 new file mode 100644 index 000000000..1f7fa2216 --- /dev/null +++ b/man/man3/oneC_sum.3 @@ -0,0 +1,45 @@ +.TH ONEC_SUM 3 +.SH NAME +oneC_sum \- One's complement internet checksum +.SH SYNOPSIS +.ft B +.nf +#define _MINIX_SOURCE 1 +#include +#include + +#include + +u16_t oneC_sum(u16_t \fIprev\fP, void *\fIdata\fP, size_t \fIsize\fP) +.fi +.ft R +.SH DESCRIPTION +.B OneC_sum +is used to calculate the one's complement checksum needed for IP network +packets. +A good document about the Internet Checksum is RFC-1071 (Computing the +Internet checksum). +.PP +.B OneC_sum +expects three parameters: +.TP 10 +.I prev +The checksum of previous blocks of data that are to be included in the +checksum. +The value of prev in first call to oneC_sum should be 0. +.TP +.I data +A pointer to the block of data. +The data is interpreted as a series of 16 bit numbers in network byte order, but +an odd number of bytes is also allowed. +.TP +.I size +The size of the data in bytes. +.SH "SEE ALSO" +.BR ip (4). +.br +.B RFC-1071 +.SH AUTHOR +Philip Homburg (philip@cs.vu.nl) +.\" +.\" $PchId: oneC_sum.3,v 1.3 1996/02/22 21:05:31 philip Exp $ diff --git a/man/man3/popen.3 b/man/man3/popen.3 new file mode 100644 index 000000000..fe9f58f15 --- /dev/null +++ b/man/man3/popen.3 @@ -0,0 +1,51 @@ +.\" @(#)popen.3 6.1 (Berkeley) 5/15/85 +.\" +.TH POPEN 3 "May 15, 1985" +.AT 3 +.SH NAME +popen, pclose \- initiate I/O to/from a process +.SH SYNOPSIS +.nf +.ft B +#include + +FILE *popen(const char *command, const char *type) +int pclose(FILE *stream) +.SH DESCRIPTION +The arguments to +.B popen +are pointers to null-terminated strings containing respectively a +shell command line and an I/O mode, either "r" for reading or "w" for +writing. It creates a pipe between the calling process and +the command to be executed. The value returned is a stream pointer that +can be used (as appropriate) to write to the standard input +of the command or read from its standard output. +.PP +A stream opened by +.B popen +should be closed by +.BR pclose , +which waits for the associated process to terminate +and returns the exit status of the command. +.PP +Because open files are shared, a type "r" command may be used as an input +filter, and a type "w" as an output filter. +.SH "SEE ALSO" +.BR pipe (2), +.BR fopen (3), +.BR fclose (3), +.BR system (3), +.BR wait (2), +.BR sh (1). +.SH DIAGNOSTICS +.B Popen +returns a null pointer if files or processes cannot be created, or the shell +cannot be accessed. +.SH BUGS +Buffered reading before opening an input filter +may leave the standard input of that filter mispositioned. +Similar problems with an output filter may be +forestalled by careful buffer flushing, for instance, with +.BR fflush , +see +.BR fclose (3). diff --git a/man/man3/printf.3 b/man/man3/printf.3 new file mode 100644 index 000000000..4c7d6d3b6 --- /dev/null +++ b/man/man3/printf.3 @@ -0,0 +1,264 @@ +.\" @(#)printf.3s 6.3 (Berkeley) 6/5/86 +.\" +.TH PRINTF 3 "June 5, 1986" +.AT 3 +.SH NAME +printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +int printf(const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP); +int fprintf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP); +int sprintf(char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP); +int snprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP); +int vprintf(const char *\fIformat\fP, va_list \fIargs\fP); +int vfprintf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP); +int vsprintf(char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP); +int vsnprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP, va_list \fIargs\fP); +.ft R +.fi +.SH DESCRIPTION +.B Printf +places output on the standard output stream +.BR stdout . +.B Fprintf +places output on the named output +.IR stream . +.B Sprintf +places `output' in the string +.IR s , +followed by the character `\e0'. +.B Snprintf +(Minix-vmd only) +is like +.B sprintf +except that no more than +.IR n \-1 +characters are written to +.I s +followed by a `\e0'. +.PP +The +.B v*printf +functions can be used to make functions like the first four by using the +.BR stdarg (3) +method to process the argument. +.PP +Each of these functions converts, formats, and prints its arguments after +the first under control of the first argument. +The first argument is a character string which contains two types of objects: +plain characters, which are simply copied to the output stream, +and conversion specifications, each of which causes conversion and printing +of the next successive +.IR arg . +.PP +Each conversion specification is introduced by the character +.BR % . +The remainder of the conversion specification includes +in the following order +.TP +\(bu +Zero or more of following flags: +.RS +.TP +\(bu +a `#' character +specifying that the value should be converted to an ``alternate form''. +For +.BR c , +.BR d , +.BR s , +and +.BR u +conversions, this option has no effect. For +.B o +conversions, the precision of the number is increased to force the first +character of the output string to a zero. For +.BR x ( X ) +conversion, a non-zero result has the string +.BR 0x ( 0X ) +prepended to it. For +.BR e , +.BR E , +.BR f , +.BR g , +and +.BR G +conversions, the result will always contain a decimal point, even if no +digits follow the point (normally, a decimal point only appears in the +results of those conversions if a digit follows the decimal point). For +.B g +and +.B G +conversions, trailing zeros are not removed from the result as they +would otherwise be. +.TP +\(bu +a minus sign `\-' which specifies +.I "left adjustment" +of the converted value in the indicated field; +.TP +\(bu +a `+' character specifying that there should always be +a sign placed before the number when using signed conversions. +.TP +\(bu +a space specifying that a blank should be left before a positive number +during a signed conversion. A `+' overrides a space if both are used. +.RE +.TP +\(bu +an optional digit string specifying a +.I "field width;" +if the converted value has fewer characters than the field width +it will be blank-padded on the left (or right, +if the left-adjustment indicator has been given) to make up the field width; +if the field width begins with a zero, +zero-padding will be done instead of blank-padding; +.TP +\(bu +an optional period +.RB ` . ' +which serves to separate the field width from the next digit string; +.TP +\(bu +an optional digit string specifying a +.I precision +which specifies the number of digits to appear after the +decimal point, for e- and f-conversion, or the maximum number of characters +to be printed from a string; +.TP +\(bu +the character +.B l +specifying that a following +.BR d , +.BR o , +.BR x , +or +.B u +corresponds to a long integer +.IR arg . +.TP +\(bu +a character which indicates the type of +conversion to be applied. +.PP +A field width or precision may be `*' instead of a digit string. +In this case an integer +.I arg +supplies +the field width or precision. +.PP +The conversion characters +and their meanings are +.TP +.B dox +The integer +.I arg +is converted to decimal, octal, or +hexadecimal notation respectively. +.TP +.B X +Like +.BR x , +but use upper case instead of lower case. +.TP +.B f +The float or double +.I arg +is converted to decimal notation +in the style `[\fB\-\fR]ddd.ddd' +where the number of d's after the decimal point +is equal to the precision specification +for the argument. +If the precision +is missing, +6 digits are given; +if the precision is explicitly 0, no digits and +no decimal point are printed. +.TP +.B e +The float or double +.I arg +is converted in the style +`[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' +where there is one digit before the decimal point and +the number after is equal to the +precision specification for the argument; +when the precision is missing, +6 digits are produced. +.TP +.B g +The float or double +.I arg +is printed in style +.BR d , +in style +.BR f , +or in +style +.BR e , +whichever gives full precision in minimum space. +.TP +.B c +The character +.I arg +is printed. +.TP +.B s +.I Arg +is taken to be a string (character pointer) +and characters from the string are printed until +a null character or until +the number of characters indicated by the precision +specification is reached; +however if the precision is 0 or missing +all characters up to a null are printed. +.TP +.B u +The unsigned integer +.I arg +is converted to decimal +and printed. +.TP +.B % +Print a `%'; no argument is converted. +.PP +In no case does a non-existent or small field width +cause truncation of a field; +padding takes place only if the specified field +width exceeds the actual width. +Characters generated by +.B printf +are printed by +.BR putc (3). +.PP +.B Examples +.br +To print a date and time in the form `Sunday, July 3, 10:02', +where +.I weekday +and +.I month +are pointers to null-terminated strings: +.PP +.RS +printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); +.RE +.PP +To print +.if n pi +.if t \(*p +to 5 decimals: +.IP +printf("pi = %.5f", 4*atan(1.0)); +.SH "SEE ALSO" +.BR putc (3), +.BR scanf (3), +.BR ecvt (3), +.BR stdarg (3). diff --git a/man/man3/putc.3 b/man/man3/putc.3 new file mode 100644 index 000000000..fd728e7cc --- /dev/null +++ b/man/man3/putc.3 @@ -0,0 +1,70 @@ +.\" @(#)putc.3s 6.2 (Berkeley) 11/6/85 +.\" +.TH PUTC 3 "November 6, 1985" +.AT 3 +.SH NAME +putc, putchar, fputc, putw \- put character or word on a stream +.SH SYNOPSIS +.nf +.ft B +#include + +int putc(int \fIc\fP, FILE *\fIstream\fP) +int putchar(int \fIc\fP) +int fputc(int \fIc\fP, FILE *\fIstream\fP) +int putw(int \fIw\fP, FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Putc +appends the character +.I c +to the named output +.IR stream . +It returns the character written. +.PP +.BI Putchar( c ) +is defined as +.BI putc( c ", stdout)\fR." +.PP +.B Fputc +behaves like +.BR putc , +but is a genuine function rather than a macro. +.PP +.B Putw +appends word (that is, +.BR int ) +.I w +to the output +.IR stream . +It returns the word written. +.B Putw +neither assumes nor causes special alignment in the file. +.SH "SEE ALSO" +.BR fopen (3), +.BR fclose (3), +.BR getc (3), +.BR puts (3), +.BR printf (3), +.BR fread (3). +.SH DIAGNOSTICS +These functions return the constant +.SM +.B EOF +upon error. Since this is a good integer, +.BR ferror (3) +should be used to detect +.B putw +errors. +.SH BUGS +Because it is implemented as a macro, +.B putc +treats a +.I stream +argument with side effects improperly. In particular +`putc(c,\ *f++);' +doesn't work sensibly. +.PP +Errors can occur long after the call to +.BR putc . diff --git a/man/man3/puts.3 b/man/man3/puts.3 new file mode 100644 index 000000000..bdaa106fd --- /dev/null +++ b/man/man3/puts.3 @@ -0,0 +1,43 @@ +.\" @(#)puts.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH PUTS 3 "May 15, 1985" +.AT 3 +.SH NAME +puts, fputs \- put a string on a stream +.SH SYNOPSIS +.nf +.ft B +#include + +int puts(char *\fIs\fP) +int fputs(char *\fIs\fP, FILE *\fIstream\fP) +.ft P +.fi +.SH DESCRIPTION +.B Puts +copies the null-terminated string +.I s +to the standard output stream +.B stdout +and appends a +newline character. +.PP +.B Fputs +copies the null-terminated string +.I s +to the named output +.IR stream . +.PP +Neither routine copies the terminal null character. +.SH "SEE ALSO" +.BR fopen (3), +.BR gets (3), +.BR putc (3), +.BR printf (3), +.BR ferror (3), +.BR fread (3). +.SH BUGS +.B Puts +appends a newline, +.B fputs +does not, all in the name of backward compatibility. diff --git a/man/man3/qsort.3 b/man/man3/qsort.3 new file mode 100644 index 000000000..8dcfbd558 --- /dev/null +++ b/man/man3/qsort.3 @@ -0,0 +1,36 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)qsort.3 6.1 (Berkeley) 5/15/85 +.\" +.TH QSORT 3 "May 15, 1985" +.UC 4 +.SH NAME +qsort \- quicker sort +.SH SYNOPSIS +.nf +.ft B +#include +#include + +.fi +.in +.5i +.ti -.5i +void qsort(void *\fIbase\fP, size_t \fInel\fP, size_t \fIwidth\fP, int (*\fIcompar\fP)(const void *, const void *)) +.in -.5i +.ft R +.SH DESCRIPTION +.B Qsort +is an implementation of the quicker-sort algorithm. +The first argument is a pointer to the base of the data; +the second is the number of elements; +the third is the width of an element in bytes; +the last is the name of the comparison routine +to be called with two arguments which are pointers +to the elements being compared. +The routine must return an integer less than, equal to, or greater than 0 +according as the first argument is to be considered +less than, equal to, or greater than the second. +.SH "SEE ALSO" +.BR sort (1). diff --git a/man/man3/rand.3 b/man/man3/rand.3 new file mode 100644 index 000000000..052e10fe3 --- /dev/null +++ b/man/man3/rand.3 @@ -0,0 +1,33 @@ +.\" @(#)rand.3c 6.2 (Berkeley) 9/29/85 +.\" +.TH RAND 3 "September 29, 1985" +.AT 3 +.SH NAME +rand, srand \- random number generator +.SH SYNOPSIS +.nf +.ft B +#include + +void srand(unsigned \fIseed\fP) +unsigned rand(void) +.ft R +.fi +.SH DESCRIPTION +.B Rand +uses a multiplicative congruential +random number generator with period +.if t 2\u\s732\s0\d +.if n 2**32 +to return successive pseudo-random +numbers in the range from 0 to +.BR RAND_MAX . +.PP +The generator is reinitialized by calling +.B srand +with 1 as argument. +It can be set to a random starting point by calling +.B srand +with whatever you like as argument. +.SH "SEE ALSO" +.BR random (3). diff --git a/man/man3/random.3 b/man/man3/random.3 new file mode 100644 index 000000000..7b4516d73 --- /dev/null +++ b/man/man3/random.3 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)random.3 6.2 (Berkeley) 9/29/85 +.\" +.TH RANDOM 3 "September 29, 1985" +.UC 5 +.SH NAME +random, srandom, initstate, setstate \- better random number generator; routines for changing generators +.SH SYNOPSIS +.nf +.ft B +#include + +long random(void) +void srandom(unsigned \fIseed\fP) +char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, int \fIn\fP) +char *setstate(char *\fIstate\fP) +.ft R +.fi +.SH DESCRIPTION +.PP +.B Random +uses a non-linear additive feedback random number generator employing a +default table of size 31 long integers to return successive pseudo-random +numbers in the range from 0 to +.if t 2\u\s731\s10\d\(mi1. +.if n (2**31)\(mi1. +The period of this random number generator is very large, approximately +.if t 16\(mu(2\u\s731\s10\d\(mi1). +.if n 16*((2**31)\(mi1). +.PP +.B Random/srandom +have (almost) the same calling sequence and initialization properties as +.B rand/srand. +The difference is that +.BR rand (3) +produces a much less random sequence \(em in fact, the low dozen bits +generated by rand go through a cyclic pattern. All the bits generated by +.B random +are usable. For example, ``random()&01'' will produce a random binary +value. +.PP +Unlike +.BR srand , +.B srandom +does not return the old seed; the reason for this is that the amount of +state information used is much more than a single word. (Two other +routines are provided to deal with restarting/changing random +number generators). Like +.BR rand (3), +however, +.B random +will by default produce a sequence of numbers that can be duplicated +by calling +.B srandom +with +.B 1 +as the seed. +.PP +The +.B initstate +routine allows a state array, passed in as an argument, to be initialized +for future use. The size of the state array (in bytes) is used by +.B initstate +to decide how sophisticated a random number generator it should use -- the +more state, the better the random numbers will be. +(Current "optimal" values for the amount of state information are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. Using less than 8 bytes will cause an error). +The seed for the initialization (which specifies a starting point for +the random number sequence, and provides for restarting at the same +point) is also an argument. +.B Initstate +returns a pointer to the previous state information array. +.PP +Once a state has been initialized, the +.B setstate +routine provides for rapid switching between states. +.B Setstate +returns a pointer to the previous state array; its +argument state array is used for further random number generation +until the next call to +.B initstate +or +.BR setstate . +.PP +Once a state array has been initialized, it may be restarted at a +different point either by calling +.B initstate +(with the desired seed, the state array, and its size) or by calling +both +.B setstate +(with the state array) and +.B srandom +(with the desired seed). +The advantage of calling both +.B setstate +and +.B srandom +is that the size of the state array does not have to be remembered after +it is initialized. +.PP +With 256 bytes of state information, the period of the random number +generator is greater than +.if t 2\u\s769\s10\d, +.if n 2**69 +which should be sufficient for most purposes. +.SH AUTHOR +Earl T. Cohen +.SH DIAGNOSTICS +.PP +If +.B initstate +is called with less than 8 bytes of state information, or if +.B setstate +detects that the state information has been garbled, error +messages are printed on the standard error output. +.SH "SEE ALSO" +.BR rand (3). +.SH NOTES +.B initstate +and +.B setstate +are not declared in +.IR , +programmers must provide their own declarations. +.SH BUGS +About 2/3 the speed of +.BR rand (3). diff --git a/man/man3/rcmd.3 b/man/man3/rcmd.3 new file mode 100644 index 000000000..efc8cb076 --- /dev/null +++ b/man/man3/rcmd.3 @@ -0,0 +1,141 @@ +.\" Copyright (c) 1983 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)rcmd.3 6.7 (Berkeley) 5/14/86 +.\" +.TH RCMD 3 "May 14, 1986" +.UC 5 +.SH NAME +rcmd, rresvport, ruserok \- routines for returning a stream to a remote command +.SH SYNOPSIS +.nf +.B "#include " +.B "#include " +.PP +.B "rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p);" +.B char **ahost; +.B int inport; +.B "char *locuser, *remuser, *cmd;" +.B int *fd2p; +.PP +.B s = rresvport(port); +.B int *port; +.PP +.B "ruserok(rhost, superuser, ruser, luser);" +.B char *rhost; +.B int superuser; +.B char *ruser, *luser; +.fi +.SH DESCRIPTION +.I Rcmd +is a routine used by the super-user to execute a command on +a remote machine using an authentication scheme based +on reserved port numbers. +.I Rresvport +is a routine which returns a descriptor to a socket +with an address in the privileged port space. +.I Ruserok +is a routine used by servers +to authenticate clients requesting service with +.IR rcmd . +All three functions are present in the same file and are used +by the +.IR rshd (8) +server (among others). +.PP +.I Rcmd +looks up the host +.I *ahost +using +.IR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise +.I *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.IR inport . +.PP +If the connection succeeds, +a socket in the Internet domain of type SOCK_STREAM +is returned to the caller, and given to the remote +command as +.B stdin +and +.BR stdout . +If +.I fd2p +is non-zero, then an auxiliary channel to a control +process will be set up, and a descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +If +.I fd2p +is 0, then the +.B stderr +(unit 2 of the remote +command) will be made the same as the +.B stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.PP +The protocol is described in detail in +.IR rshd (8). +.PP +The +.I rresvport +routine is used to obtain a socket with a privileged +address bound to it. This socket is suitable for use +by +.I rcmd +and several other routines. Privileged Internet ports are those +in the range 0 to 1023. Only the super-user +is allowed to bind an address of this sort to a socket. +.PP +.I Ruserok +takes a remote host's name, as returned by a +.IR gethostbyaddr (3) +routine, two user names and a flag indicating whether +the local user's name is that of the super-user. It then +checks the files +.I /etc/hosts.equiv +and, possibly, +.I .rhosts +in the current working directory (normally the local +user's home directory) to see if the request for +service is allowed. A 0 is returned if the machine +name is listed in the ``hosts.equiv'' file, or the +host and remote user name are found in the ``.rhosts'' +file; otherwise +.I ruserok +returns \-1. If the +.I superuser +flag is 1, the checking of the ``host.equiv'' file is +bypassed. +If the local domain (as obtained from \fIgethostname\fP\|(3)) +is the same as the remote domain, only the machine name need be specified. +.SH SEE ALSO +rlogin(1), +rsh(1), +intro(2), +rexec(3), +rexecd(8), +rlogind(8), +rshd(8) +.SH DIAGNOSTICS +.I Rcmd +returns a valid socket descriptor on success. +It returns -1 on error and prints a diagnostic message on the standard error. +.PP +.I Rresvport +returns a valid, bound socket descriptor on success. +It returns -1 on error with the global value +.I errno +set according to the reason for failure. +The error code EAGAIN is overloaded to mean ``All network ports in use.'' diff --git a/man/man3/regex.3 b/man/man3/regex.3 new file mode 100644 index 000000000..fbe2eca20 --- /dev/null +++ b/man/man3/regex.3 @@ -0,0 +1,541 @@ +.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Henry Spencer. +.\" +.\" 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. +.\" +.\" @(#)regex.3 8.4 (Berkeley) 3/20/94 +.\" +.TH REGEX 3 "March 20, 1994" +.de ZR +.\" one other place knows this name: the SEE ALSO section +.BR re_format (7) \\$1 +.. +.SH NAME +regex, regcomp, regexec, regerror, regfree \- regular-expression library +.SH SYNOPSIS +.ft B +.\".na +#include +.br +#include +.sp +.in +.5i +.ti -.5i +int regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP, int \fIcflags\fP); +.ti -.5i +int regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP, +size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP); +.ti -.5i +size_t regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP, +char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP); +.ti -.5i +void regfree(regex_t *\fIpreg\fP); +.in -.5i +.ft R +.SH DESCRIPTION +These routines implement POSIX 1003.2 regular expressions (``RE''s); +see +.ZR . +.B Regcomp +compiles an RE written as a string into an internal form, +.B regexec +matches that internal form against a string and reports results, +.B regerror +transforms error codes from either into human-readable messages, +and +.B regfree +frees any dynamically-allocated storage used by the internal form +of an RE. +.PP +The header +.I +declares two structure types, +.B regex_t +and +.BR regmatch_t , +the former for compiled internal forms and the latter for match reporting. +It also declares the four functions, +a type +.BR regoff_t , +and a number of constants with names starting with ``REG_''. +.PP +.B Regcomp +compiles the regular expression contained in the +.I pattern +string, +subject to the flags in +.IR cflags , +and places the results in the +.B regex_t +structure pointed to by +.IR preg . +.I Cflags +is the bitwise OR of zero or more of the following flags: +.IP REG_EXTENDED \w'REG_EXTENDED'u+2n +Compile modern (``extended'') REs, +rather than the obsolete (``basic'') REs that +are the default. +.IP REG_BASIC +This is a synonym for 0, +provided as a counterpart to REG_EXTENDED to improve readability. +.IP REG_NOSPEC +Compile with recognition of all special characters turned off. +All characters are thus considered ordinary, +so the ``RE'' is a literal string. +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +REG_EXTENDED and REG_NOSPEC may not be used +in the same call to +.IR regcomp . +.IP REG_ICASE +Compile for matching that ignores upper/lower case distinctions. +See +.ZR . +.IP REG_NOSUB +Compile for matching that need only report success or failure, +not what was matched. +.IP REG_NEWLINE +Compile for newline-sensitive matching. +By default, newline is a completely ordinary character with no special +meaning in either REs or strings. +With this flag, +`[^' bracket expressions and `.' never match newline, +a `^' anchor matches the null string after any newline in the string +in addition to its normal function, +and the `$' anchor matches the null string before any newline in the +string in addition to its normal function. +.IP REG_PEND +The regular expression ends, +not at the first NUL, +but just before the character pointed to by the +.B re_endp +member of the structure pointed to by +.IR preg . +The +.B re_endp +member is of type +.BR "const\ char\ *" . +This flag permits inclusion of NULs in the RE; +they are considered ordinary characters. +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +.PP +When successful, +.B regcomp +returns 0 and fills in the structure pointed to by +.IR preg . +One member of that structure +(other than +.BR re_endp ) +is publicized: +.BR re_nsub , +of type +.BR size_t , +contains the number of parenthesized subexpressions within the RE +(except that the value of this member is undefined if the +REG_NOSUB flag was used). +If +.B regcomp +fails, it returns a non-zero error code; +see DIAGNOSTICS. +.PP +.B Regexec +matches the compiled RE pointed to by +.I preg +against the +.IR string , +subject to the flags in +.IR eflags , +and reports results using +.IR nmatch , +.IR pmatch , +and the returned value. +The RE must have been compiled by a previous invocation of +.BR regcomp . +The compiled form is not altered during execution of +.BR regexec , +so a single compiled RE can be used simultaneously by multiple threads. +.PP +By default, +the NUL-terminated string pointed to by +.I string +is considered to be the text of an entire line, minus any terminating +newline. +The +.I eflags +argument is the bitwise OR of zero or more of the following flags: +.IP REG_NOTBOL \w'REG_STARTEND'u+2n +The first character of +the string +is not the beginning of a line, so the `^' anchor should not match before it. +This does not affect the behavior of newlines under REG_NEWLINE. +.IP REG_NOTEOL +The NUL terminating +the string +does not end a line, so the `$' anchor should not match before it. +This does not affect the behavior of newlines under REG_NEWLINE. +.IP REG_STARTEND +The string is considered to start at +\fIstring\fR\ + \fIpmatch\fR[0].\fBrm_so\fR +and to have a terminating NUL located at +\fIstring\fR\ + \fIpmatch\fR[0].\fBrm_eo\fR +(there need not actually be a NUL at that location), +regardless of the value of +.IR nmatch . +See below for the definition of +.IR pmatch +and +.IR nmatch . +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +Note that a non-zero \fBrm_so\fR does not imply REG_NOTBOL; +REG_STARTEND affects only the location of the string, +not how it is matched. +.PP +See +.ZR +for a discussion of what is matched in situations where an RE or a +portion thereof could match any of several substrings of +.IR string . +.PP +Normally, +.B regexec +returns 0 for success and the non-zero code REG_NOMATCH for failure. +Other non-zero error codes may be returned in exceptional situations; +see DIAGNOSTICS. +.PP +If REG_NOSUB was specified in the compilation of the RE, +or if +.I nmatch +is 0, +.B regexec +ignores the +.I pmatch +argument (but see below for the case where REG_STARTEND is specified). +Otherwise, +.I pmatch +points to an array of +.I nmatch +structures of type +.BR regmatch_t . +Such a structure has at least the members +.B rm_so +and +.BR rm_eo , +both of type +.B regoff_t +(a signed arithmetic type at least as large as an +.B off_t +and a +.BR ssize_t ), +containing respectively the offset of the first character of a substring +and the offset of the first character after the end of the substring. +Offsets are measured from the beginning of the +.I string +argument given to +.BR regexec . +An empty substring is denoted by equal offsets, +both indicating the character following the empty substring. +.PP +The 0th member of the +.I pmatch +array is filled in to indicate what substring of +.I string +was matched by the entire RE. +Remaining members report what substring was matched by parenthesized +subexpressions within the RE; +member +.I i +reports subexpression +.IR i , +with subexpressions counted (starting at 1) by the order of their opening +parentheses in the RE, left to right. +Unused entries in the array\(emcorresponding either to subexpressions that +did not participate in the match at all, or to subexpressions that do not +exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fBre_nsub\fR)\(emhave both +.B rm_so +and +.B rm_eo +set to \-1. +If a subexpression participated in the match several times, +the reported substring is the last one it matched. +(Note, as an example in particular, that when the RE `(b*)+' matches `bbb', +the parenthesized subexpression matches each of the three `b's and then +an infinite number of empty strings following the last `b', +so the reported substring is one of the empties.) +.PP +If REG_STARTEND is specified, +.I pmatch +must point to at least one +.B regmatch_t +(even if +.I nmatch +is 0 or REG_NOSUB was specified), +to hold the input offsets for REG_STARTEND. +Use for output is still entirely controlled by +.IR nmatch ; +if +.I nmatch +is 0 or REG_NOSUB was specified, +the value of +.IR pmatch [0] +will not be changed by a successful +.BR regexec . +.PP +.B Regerror +maps a non-zero +.I errcode +from either +.B regcomp +or +.B regexec +to a human-readable, printable message. +If +.I preg +is non-NULL, +the error code should have arisen from use of +the +.B regex_t +pointed to by +.IR preg , +and if the error code came from +.BR regcomp , +it should have been the result from the most recent +.B regcomp +using that +.BR regex_t . +.RI ( Regerror +may be able to supply a more detailed message using information +from the +.BR regex_t .) +.B Regerror +places the NUL-terminated message into the buffer pointed to by +.IR errbuf , +limiting the length (including the NUL) to at most +.I errbuf_size +bytes. +If the whole message won't fit, +as much of it as will fit before the terminating NUL is supplied. +In any case, +the returned value is the size of buffer needed to hold the whole +message (including terminating NUL). +If +.I errbuf_size +is 0, +.I errbuf +is ignored but the return value is still correct. +.PP +If the +.I errcode +given to +.B regerror +is first ORed with REG_ITOA, +the ``message'' that results is the printable name of the error code, +e.g. ``REG_NOMATCH'', +rather than an explanation thereof. +If +.I errcode +is REG_ATOI, +then +.I preg +shall be non-NULL and the +.B re_endp +member of the structure it points to +must point to the printable name of an error code; +in this case, the result in +.I errbuf +is the decimal digits of +the numeric value of the error code +(0 if the name is not recognized). +REG_ITOA and REG_ATOI are intended primarily as debugging facilities; +they are extensions, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +Be warned also that they are considered experimental and changes are possible. +.PP +.B Regfree +frees any dynamically-allocated storage associated with the compiled RE +pointed to by +.IR preg . +The remaining +.B regex_t +is no longer a valid compiled RE +and the effect of supplying it to +.B regexec +or +.B regerror +is undefined. +.PP +None of these functions references global variables except for tables +of constants; +all are safe for use from multiple threads if the arguments are safe. +.SH IMPLEMENTATION CHOICES +There are a number of decisions that 1003.2 leaves up to the implementor, +either by explicitly saying ``undefined'' or by virtue of them being +forbidden by the RE grammar. +This implementation treats them as follows. +.PP +See +.ZR +for a discussion of the definition of case-independent matching. +.PP +There is no particular limit on the length of REs, +except insofar as memory is limited. +Memory usage is approximately linear in RE size, and largely insensitive +to RE complexity, except for bounded repetitions. +See BUGS for one short RE using them +that will run almost any system out of memory. +.PP +A backslashed character other than one specifically given a magic meaning +by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs) +is taken as an ordinary character. +.PP +Any unmatched [ is a REG_EBRACK error. +.PP +Equivalence classes cannot begin or end bracket-expression ranges. +The endpoint of one range cannot begin another. +.PP +RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255. +.PP +A repetition operator (?, *, +, or bounds) cannot follow another +repetition operator. +A repetition operator cannot begin an expression or subexpression +or follow `^' or `|'. +.PP +`|' cannot appear first or last in a (sub)expression or after another `|', +i.e. an operand of `|' cannot be an empty subexpression. +An empty parenthesized subexpression, `()', is legal and matches an +empty (sub)string. +An empty string is not a legal RE. +.PP +A `{' followed by a digit is considered the beginning of bounds for a +bounded repetition, which must then follow the syntax for bounds. +A `{' \fInot\fR followed by a digit is considered an ordinary character. +.PP +`^' and `$' beginning and ending subexpressions in obsolete (``basic'') +REs are anchors, not ordinary characters. +.SH SEE ALSO +.BR grep (1), +.BR re_format (7). +.PP +POSIX 1003.2, sections 2.8 (Regular Expression Notation) +and +B.5 (C Binding for Regular Expression Matching). +.SH DIAGNOSTICS +Non-zero error codes from +.B regcomp +and +.B regexec +include the following: +.PP +.nf +.ta \w'REG_ECOLLATE'u+3n +REG_NOMATCH regexec() failed to match +REG_BADPAT invalid regular expression +REG_ECOLLATE invalid collating element +REG_ECTYPE invalid character class +REG_EESCAPE \e applied to unescapable character +REG_ESUBREG invalid backreference number +REG_EBRACK brackets [ ] not balanced +REG_EPAREN parentheses ( ) not balanced +REG_EBRACE braces { } not balanced +REG_BADBR invalid repetition count(s) in { } +REG_ERANGE invalid character range in [ ] +REG_ESPACE ran out of memory +REG_BADRPT ?, *, or + operand invalid +REG_EMPTY empty (sub)expression +REG_ASSERT ``can't happen''\(emyou found a bug +REG_INVARG invalid argument, e.g. negative-length string +.fi +.SH HISTORY +Originally written by Henry Spencer. +Altered for inclusion in the 4.4BSD distribution. +.SH BUGS +This is an alpha release with known defects. +Please report problems. +.PP +There is one known functionality bug. +The implementation of internationalization is incomplete: +the locale is always assumed to be the default one of 1003.2, +and only the collating elements etc. of that locale are available. +.PP +The back-reference code is subtle and doubts linger about its correctness +in complex cases. +.PP +.B Regexec +performance is poor. +This will improve with later releases. +.I Nmatch +exceeding 0 is expensive; +.I nmatch +exceeding 1 is worse. +.B Regexec +is largely insensitive to RE complexity \fIexcept\fR that back +references are massively expensive. +RE length does matter; in particular, there is a strong speed bonus +for keeping RE length under about 30 characters, +with most special characters counting roughly double. +.PP +.B Regcomp +implements bounded repetitions by macro expansion, +which is costly in time and space if counts are large +or bounded repetitions are nested. +An RE like, say, +`((((a{1,100}){1,100}){1,100}){1,100}){1,100}' +will (eventually) run almost any existing machine out of swap space. +.PP +There are suspected problems with response to obscure error conditions. +Notably, +certain kinds of internal overflow, +produced only by truly enormous REs or by multiply nested bounded repetitions, +are probably not handled well. +.PP +Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is +a special character only in the presence of a previous unmatched `('. +This can't be fixed until the spec is fixed. +.PP +The standard's definition of back references is vague. +For example, does +`a\e(\e(b\e)*\e2\e)*d' match `abbbd'? +Until the standard is clarified, +behavior in such cases should not be relied on. +.PP +The implementation of word-boundary matching is a bit of a kludge, +and bugs may lurk in combinations of word-boundary matching and anchoring. diff --git a/man/man3/resolver.3 b/man/man3/resolver.3 new file mode 100644 index 000000000..b9ddef1a9 --- /dev/null +++ b/man/man3/resolver.3 @@ -0,0 +1,280 @@ +.\" Copyright (c) 1985 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted provided +.\" that: (1) source distributions retain this entire copyright notice and +.\" comment, and (2) distributions including binaries display the following +.\" acknowledgement: ``This product includes software developed by the +.\" University of California, Berkeley and its contributors'' in the +.\" documentation or other materials provided with the distribution and in +.\" all advertising materials mentioning features or use of this software. +.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" @(#)resolver.3 6.5 (Berkeley) 6/23/90 +.\" +.TH RESOLVER 3 "June 23, 1990" +.UC 4 +.SH NAME +resolver, res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand \- resolver routines +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B "res_query(dname, class, type, answer, anslen)" +.br +.B char *dname; +.br +.B int class, type; +.br +.B u_char *answer; +.br +.B int anslen; +.PP +.B "res_search(dname, class, type, answer, anslen)" +.br +.B char *dname; +.br +.B int class, type; +.br +.B u_char *answer; +.br +.B int anslen; +.PP +.B "res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)" +.br +.B int op; +.br +.B char *dname; +.br +.B int class, type; +.br +.B char *data; +.br +.B int datalen; +.br +.B struct rrec *newrr; +.br +.B char *buf; +.br +.B int buflen; +.PP +.B res_send(msg, msglen, answer, anslen) +.br +.B char *msg; +.br +.B int msglen; +.br +.B char *answer; +.br +.B int anslen; +.PP +.B res_init() +.PP +.B dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr) +.br +.B char *exp_dn, *comp_dn; +.br +.B int length; +.br +.B char **dnptrs, **lastdnptr; +.PP +.B dn_expand(msg, eomorig, comp_dn, exp_dn, length) +.br +.B char *msg, *eomorig, *comp_dn, exp_dn; +.br +.B int length; +.SH DESCRIPTION +These routines are used for making, sending and interpreting +query and reply messages with Internet domain name servers. +.PP +Global configuration and state information that is used by the +resolver routines is kept in the structure +.IR _res . +Most of the values have reasonable defaults and can be ignored. +Options +stored in +.I _res.options +are defined in +.I resolv.h +and are as follows. +Options are stored as a simple bit mask containing the bitwise ``or'' +of the options enabled. +.IP RES_INIT +True if the initial name server address and default domain name are +initialized (i.e., +.I res_init +has been called). +.IP RES_DEBUG +Print debugging messages. +.IP RES_AAONLY +Accept authoritative answers only. +With this option, +.I res_send +should continue until it finds an authoritative answer or finds an error. +Currently this is not implemented. +.IP RES_USEVC +Use TCP connections for queries instead of UDP datagrams. +.IP RES_STAYOPEN +Used with RES_USEVC to keep the TCP connection open between +queries. +This is useful only in programs that regularly do many queries. +UDP should be the normal mode used. +.IP RES_IGNTC +Unused currently (ignore truncation errors, i.e., don't retry with TCP). +.IP RES_RECURSE +Set the recursion-desired bit in queries. +This is the default. +(\c +.I res_send +does not do iterative queries and expects the name server +to handle recursion.) +.IP RES_DEFNAMES +If set, +.I res_search +will append the default domain name to single-component names +(those that do not contain a dot). +This option is enabled by default. +.IP RES_DNSRCH +If this option is set, +.I res_search +will search for host names in the current domain and in parent domains; see +.IR hostname (7). +This is used by the standard host lookup routine +.IR gethostbyname (3). +This option is enabled by default. +.PP +The +.I res_init +routine +reads the configuration file (if any; see +.IR resolver (5)) +to get the default domain name, +search list and +the Internet address of the local name server(s). +If no server is configured, the host running +the resolver is tried. +The current domain name is defined by the hostname +if not specified in the configuration file; +it can be overridden by the environment variable LOCALDOMAIN. +Initialization normally occurs on the first call +to one of the following routines. +.PP +The +.I res_query +function provides an interface to the server query mechanism. +It constructs a query, sends it to the local server, +awaits a response, and makes preliminary checks on the reply. +The query requests information of the specified +.I type +and +.I class +for the specified fully-qualified domain name +.I dname . +The reply message is left in the +.I answer +buffer with length +.I anslen +supplied by the caller. +.PP +The +.I res_search +routine makes a query and awaits a response like +.IR res_query , +but in addition, it implements the default and search rules +controlled by the RES_DEFNAMES and RES_DNSRCH options. +It returns the first successful reply. +.PP +The remaining routines are lower-level routines used by +.IR res_query . +The +.I res_mkquery +function +constructs a standard query message and places it in +.IR buf . +It returns the size of the query, or \-1 if the query is +larger than +.IR buflen . +The query type +.I op +is usually QUERY, but can be any of the query types defined in +.IR . +The domain name for the query is given by +.IR dname . +.I Newrr +is currently unused but is intended for making update messages. +.PP +The +.I res_send +routine +sends a pre-formatted query and returns an answer. +It will call +.I res_init +if RES_INIT is not set, send the query to the local name server, and +handle timeouts and retries. +The length of the reply message is returned, or +\-1 if there were errors. +.PP +The +.I dn_comp +function +compresses the domain name +.I exp_dn +and stores it in +.IR comp_dn . +The size of the compressed name is returned or \-1 if there were errors. +The size of the array pointed to by +.I comp_dn +is given by +.IR length . +The compression uses +an array of pointers +.I dnptrs +to previously-compressed names in the current message. +The first pointer points to +to the beginning of the message and the list ends with NULL. +The limit to the array is specified by +.IR lastdnptr . +A side effect of +.I dn_comp +is to update the list of pointers for +labels inserted into the message +as the name is compressed. +If +.I dnptr +is NULL, names are not compressed. +If +.I lastdnptr +is NULL, the list of labels is not updated. +.PP +The +.I dn_expand +entry +expands the compressed domain name +.I comp_dn +to a full domain name +The compressed name is contained in a query or reply message; +.I msg +is a pointer to the beginning of the message. +The uncompressed name is placed in the buffer indicated by +.I exp_dn +which is of size +.IR length . +The size of compressed name is returned or \-1 if there was an error. +.SH FILES +/etc/resolv.conf see resolver(5) +.SH "SEE ALSO" +gethostbyname(3), named(8), resolver(5), hostname(7), +.br +RFC1032, RFC1033, RFC1034, RFC1035, RFC974, +.br +SMM:11 Name Server Operations Guide for BIND diff --git a/man/man3/scanf.3 b/man/man3/scanf.3 new file mode 100644 index 000000000..7743d2ef1 --- /dev/null +++ b/man/man3/scanf.3 @@ -0,0 +1,251 @@ +.\" @(#)scanf.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH SCANF 3 "May 15, 1985" +.AT 3 +.SH NAME +scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf \- formatted input conversion +.SH SYNOPSIS +.nf +.ft B +#include +#include + +int scanf(const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP) +int fscanf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP) +int sscanf(const char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP) +int vscanf(const char *\fIformat\fP, va_list \fIargs\fP) +int vfscanf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP) +int vsscanf(const char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP) +.SH DESCRIPTION +.B Scanf +reads from the standard input stream +.BR stdin . +.B Fscanf +reads from the named input +.IR stream . +.B Sscanf +reads from the character string +.IR s . +Each function reads characters, interprets +them according to a format, and stores the results in its arguments. +Each expects as arguments +a control string +.IR format , +described below, +and a set of +.I pointer +arguments +indicating where the converted input should be stored. +.PP +The +.B v*scanf +functions can be used to make functions like the first three by using the +.BR stdarg (3) +method to process the argument pointers. +.PP +The +control string +usually contains +conversion specifications, which are used to direct interpretation +of input sequences. +The control string may contain: +.TP 4 +1. +Blanks, tabs or newlines, +which match optional white space in the input. +.TP 4 +2. +An ordinary character (not %) which must match +the next character of the input stream. +.TP 4 +3. +Conversion specifications, consisting of the +character +.BR % , +an optional assignment suppressing character +.BR * , +an optional numerical maximum field width, and a conversion +character. +.PP +A conversion specification directs the conversion of the +next input field; the result +is placed in the variable pointed to by the corresponding argument, +unless assignment suppression was +indicated by +.BR * . +An input field is defined as a string of non-space characters; +it extends to the next inappropriate character or until the field +width, if specified, is exhausted. +.PP +The conversion character indicates the interpretation of the +input field; the corresponding pointer argument must +usually be of a restricted type. +The following conversion characters are legal: +.TP 4 +.B % +a single `%' is expected +in the input at this point; +no assignment is done. +.TP 4 +.B d +a decimal integer is expected; +the corresponding argument should be an integer pointer. +.TP 4 +.B o +an octal integer is expected; +the corresponding argument should be a integer pointer. +.TP 4 +.B x +a hexadecimal integer is expected; +the corresponding argument should be an integer pointer. +.ti -0.2i +.TP 4 +.B s +a character string is expected; +the corresponding argument should be a character pointer +pointing to an array of characters large enough to accept the +string and a terminating `\e0', which will be added. +The input field is terminated by a space character +or a newline. +.TP 4 +.B c +a character is expected; the +corresponding argument should be a character pointer. +The normal skip over space characters is suppressed +in this case; +to read the next non-space character, try +`%1s'. +If a field width is given, the corresponding argument +should refer to a character array, and the +indicated number of characters is read. +.TP 4 +.B efg +a floating point number is expected; +the next field is converted accordingly and stored through the +corresponding argument, which should be a pointer to a +.BR float . +The input format for +floating point numbers is +an optionally signed +string of digits +possibly containing a decimal point, followed by an optional +exponent field consisting of an E or e followed by an optionally signed integer. +.TP 4 +.B [ +indicates a string not to be delimited by space characters. +The left bracket is followed by a set of characters and a right +bracket; the characters between the brackets define a set +of characters making up the string. +If the first character +is not circumflex (\|^\|), the input field +is all characters until the first character not in the set between +the brackets; if the first character +after the left bracket is ^, the input field is all characters +until the first character which is in the remaining set of characters +between the brackets. +The corresponding argument must point to a character array. +.PP +The conversion characters +.BR d , +.B o +and +.B x +may be capitalized or preceded by +.B l +to indicate that a pointer to +.B long +rather than to +.B int +is in the argument list. +Similarly, the conversion characters +.BR e , +.B f +or +.B g +may be capitalized or +preceded by +.B l +to indicate a pointer to +.B double +rather than to +.BR float . +The conversion characters +.BR d , +.B o +and +.B x +may be preceded by +.B h +to indicate a pointer to +.B short +rather than to +.BR int . +.PP +The +.B scanf +functions return the number of successfully matched and assigned input +items. +This can be used to decide how many input items were found. +The constant +.SM +.B EOF +is returned upon end of input; note that this is different +from 0, which means that no conversion was done; +if conversion was intended, it was frustrated by an +inappropriate character in the input. +.PP +For example, the call +.IP "\&" 10 +int i; float x; char name[50]; +.br +scanf("%d%f%s", &i, &x, name); +.PP +with the input line +.IP +25 54.32E\(mi1 thompson +.PP +will assign to +.B i +the value +25, +.B x +the value 5.432, and +.B name +will contain `\fBthompson\e0\fP' . +Or, +.IP +int i; float x; char name[50]; +.br +scanf("%2d%f%*d%[1234567890]", &i, &x, name); +.PP +with input +.IP +56789 0123 56a72 +.PP +will assign 56 to +.BR i , +789.0 to +.BR x , +skip `0123', +and place the string `56\e0' in +.BR name . +The next call to +.B getchar +will return `a'. +.SH "SEE ALSO" +.BR atof (3), +.BR getc (3), +.BR printf (3), +.BR stdarg (3). +.SH DIAGNOSTICS +The +.B scanf +functions return +.SM +.B EOF +on end of input, +and a short count for missing or illegal data items. +.SH BUGS +The success of literal matches and suppressed +assignments is not directly +determinable. diff --git a/man/man3/servxcheck.3 b/man/man3/servxcheck.3 new file mode 100644 index 000000000..97d25e107 --- /dev/null +++ b/man/man3/servxcheck.3 @@ -0,0 +1,120 @@ +.TH SERVXCHECK 3 +.SH NAME +servxcheck \- Internet service access check +.SH SYNOPSIS +.ft B +.nf +#define _MINIX_SOURCE 1 +#include + +int servxcheck(ipaddr_t \fIpeer\fP, const char *\fIservice\fP, + void (*\fIlogf\fP)(int \fIpass\fP, const char *\fIname\fP)); +char *servxfile(const char *\fIfile\fP); +.fi +.ft R +.SH DESCRIPTION +.B Servxcheck() +is used by programs like +.B inetd +to perform an access check on the host connected to the other end of the TCP +channel that has IP address +.IR peer . +.PP +.B Servxcheck() +translates the IP address to the +associated host name if necessary, and checks if the host is granted access +as guided by the file +.BR /etc/serv.access . +(See +.BR serv.access (5).) +The service name used to search the access file is passed by the caller as +.IR service . +These names should be the same as the service names in +.BR /etc/services . +.PP +The caller should use the NWIOGTCPCONF ioctl() call to find out what the +IP address of the remote end is. It is wise to bypass the +.B servxcheck() +call if the remote end happens to be the local machine (remaddr == locaddr), +so that local connections aren't impeded by slow checks. +.B Servxcheck() +will itself allow connections from 127.0.0.1/8 immediately, so you +don't have to check for that. Example of use: +.PP +.RS +.nf +.ta +4n +4n +4n +if (ioctl(fd, NWIOGTCPCONF, &tcpconf) < 0 + || tcpconf.nwtc_remaddr == tcpconf.nwtc_locaddr + || servxcheck(tcpconf.nwtc_remaddr, service_name, NULL) +) { + serve(); +} +.fi +.RE +.PP +An attempt to connect to a service is logged if the access is denied. You +can use the special checkword "\fBlog\fP" to also log if access is granted. +Logging will be done with +.B syslog() +at the +.B warning +level. +A syntax error in the access file may be logged under the +.B err +level. +The caller must use +.B openlog() +to set the appropriate logging facility. One may do one's own logging by +supplying a +.I logf +function that will be called by +.B servxcheck +with a first argument that is true if access is granted, false if +denied, and a second argument that is the name of the remote host whose +access has been checked. +.PP +The default is to fail the check unless the access file says otherwise. +Strange errors make the check succeed. (We do not want +remote access to fail because of some system error.) Note that this +function is not meant to check access to the system, that's what +passwords and such are for, but only to limit access to those who are +allowed to use the services the system offers. +.PP +Connections from a machine to itself are accepted immediately. No further +checks, no logging. +.PP +.B Servxfile() +may be used to specify a file other than the default +.BR /etc/serv.access . +This is useful for programs started from +.B inetd +that want to handle the access check themselves, using a private access file. +The return value of +.B servxfile() +is the pathname of the old access file. Only a pointer to the new path is +saved, the caller must keep the string it points to intact. +.SH FILES +.TP 25n +.B /etc/serv.access +Default access check file. +.SH "SEE ALSO" +.BR syslog (3), +.BR serv.access (5), +.BR services (5), +.BR inetd (8). +.SH DIAGNOSTICS +.B Servxcheck() +returns 0 if the access is denied, 1 if granted. +.PP +Typical syslog message: +.PP +.RS +Jan 10 20:27:20 flotsam inetd[174]: service 'shell' granted to jetsam.cs.vu.nl +.RE +.SH BUGS +IP and DNS based access checks will stop most crackers, but not the really +determined ones. Luckily Minix is sufficiently strange to thwart the well +known cracking schemes. But don't ever allow yourself to feel secure. +.SH AUTHOR +Kees J. Bot diff --git a/man/man3/setbuf.3 b/man/man3/setbuf.3 new file mode 100644 index 000000000..91d01b010 --- /dev/null +++ b/man/man3/setbuf.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)setbuf.3s 6.2 (Berkeley) 5/12/86 +.\" +.TH SETBUF 3 "May 12, 1986" +.UC 4 +.SH NAME +setbuf, setvbuf \- assign buffering to a stream +.SH SYNOPSIS +.nf +.ft B +#include + +int setbuf(FILE *\fIstream\fP, char *\fIbuf\fP) +int setvbuf(FILE *\fIstream\fP, char *\fIbuf\fP, int \fItype\fP, size_t \fIsize\fP) +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, +and line buffered. +When an output stream is unbuffered, information appears on the +destination file or terminal as soon as written; +when it is block buffered many characters are saved up and written as a block; +when it is line buffered characters are saved up until a newline is +encountered or input is read from stdin. +.B Fflush +(see +.BR fclose (3)) +may be used to force the block out early. +Normally all files are block buffered. +A buffer is obtained from +.BR malloc (3) +upon the first +.B getc +or +.BR putc (3) +on the file. +If the standard stream +.B stdout +refers to a terminal it is line buffered. +The standard stream +.B stderr +is always unbuffered. +.PP +.B Setbuf +is used after a stream has been opened but before it is read or written. +The character array +.I buf +is used instead of an automatically allocated buffer. If +.I buf +is the constant pointer +.SM +.BR NULL , +input/output will be completely unbuffered. +A manifest constant +.SM +.B BUFSIZ +tells how big an array is needed: +.IP +.B char +buf[BUFSIZ]; +.PP +.BR Setvbuf , +an alternate form of +.BR setbuf , +is used after a stream has been opened but before it is read or written. +It has three uses, depending on the value of the +.IR type +argument: +.TP 5 +.B "setvbuf(\fIstream\fP, \fIbuf\fP, _IOFBF, \fIsize\fP)" +Causes input/output to be fully buffered using the character array +.I buf +whose size is determined by the +.I size +argument. +If +.I buf +is the constant pointer +.SM +.BR NULL , +then an automatically allocated buffer will be used. +.TP 5 +.B "setvbuf(\fIstream\fP, \fIbuf\fP, _IOLBF, \fIsize\fP)" +Like above, except that output will be line buffered, i.e. the buffer will +be flushed when a newline is written, the buffer is full, or input is +requested. +.TP 5 +.B "setvbuf(\fIstream\fP, \fIbuf\fP, _IONBF, \fIsize\fP)" +Causes input/output to be completely unbuffered. +.I Buf +and +.I size +are ignored. +.PP +A file can be changed between unbuffered, line buffered, or block buffered +by using +.B freopen +(see +.BR fopen (3)) +followed by the appropriate +.B setvbuf +call. +.SH "SEE ALSO" +.BR fopen (3), +.BR getc (3), +.BR putc (3), +.BR malloc (3), +.BR fclose (3), +.BR puts (3), +.BR printf (3), +.BR fread (3). diff --git a/man/man3/sigset.3 b/man/man3/sigset.3 new file mode 100644 index 000000000..f832f7119 --- /dev/null +++ b/man/man3/sigset.3 @@ -0,0 +1,85 @@ +.TH SIGSET 3 +.SH NAME +sigset, sigaddset, sigdelset, sigemptyset, sigfillset, sigismember \- manipulate signal sets +.SH SYNOPSIS +.ft B +#include + +.nf +int sigaddset(sigset_t *\fIset\fP, int \fIsig\fP) +int sigdelset(sigset_t *\fIset\fP, int \fIsig\fP) +int sigemptyset(sigset_t *\fIset\fP) +int sigfillset(sigset_t *\fIset\fP) +int sigismember(const sigset_t *\fIset\fP, int \fIsig\fP) +.fi +.ft P +.SH DESCRIPTION +The system calls that handle signals, such as +.BR sigaction (2) +and +.BR sigprocmask (2) +use sets of signals to keep a process from being interrupted by those +signals while executing a signal handler or a critical code segment. These +signal sets are manipulated by the following functions: +.TP 5 +.B "int sigaddset(sigset_t *\fIset\fP, int \fIsig\fP)" +Add signal +.I sig +to the signal set referenced by +.IR set . +.TP +.B "int sigdelset(sigset_t *\fIset\fP, int \fIsig\fP)" +Remove signal +.I sig +from the signal set referenced by +.IR set . +.TP +.B "int sigemptyset(sigset_t *\fIset\fP)" +Initialize the signal set referenced by +.I set +to an empty set. +.TP +.B "int sigfillset(sigset_t *\fIset\fP)" +Initialize the signal set referenced by +.I set +to an full set, i.e. all signals are in the set. +.TP +.B "int sigismember(const sigset_t *\fIset\fP, int \fIsig\fP)" +Return +.B 1 +if the signal +.I sig +is present in the set referenced by +.IR set , +.B 0 +otherwise. +.SH "SEE ALSO" +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2). +.SH DIAGNOSTICS +All functions except +.B sigismember +return +.B 0 +on success. +.B Sigismember +returns +.B 0 +or +.B 1 +on success. They return +.B \-1 +with error code +.B EINVAL +for an invalid signal number. (They do not use +.B EFAULT +for a bad +.I set +address, but will simply cause a segmentation violation.) +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: sigset.3,v 1.2 1996/04/11 06:39:09 philip Exp $ diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 new file mode 100644 index 000000000..7757f2cf8 --- /dev/null +++ b/man/man3/sleep.3 @@ -0,0 +1,31 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)sleep.3 6.2 (Berkeley) 5/12/86 +.\" +.TH SLEEP 3 "May 12, 1986" +.UC 4 +.SH NAME +sleep \- suspend execution for interval +.SH SYNOPSIS +.nf +.ft B +#include + +unsigned int sleep(unsigned int \fIseconds\fP) +.fi +.SH DESCRIPTION +The current process is suspended from execution for the number +of seconds specified by the argument. +.PP +The routine is implemented by setting an alarm timer +and pausing until it occurs. +The previous state of this timer is saved and restored. +If the sleep time exceeds the time to the expiration of the +previous timer, +the process sleeps only until the signal would have occurred, and the +signal is sent 1 second later. +.SH "SEE ALSO" +.BR alarm (2), +.BR pause (2). diff --git a/man/man3/stdarg.3 b/man/man3/stdarg.3 new file mode 100644 index 000000000..7ad0835c3 --- /dev/null +++ b/man/man3/stdarg.3 @@ -0,0 +1,123 @@ +.\" @(#)varargs.3 6.3 (Berkeley) 5/15/86 +.\" +.TH STDARG 3 "May 15, 1986" +.AT 3 +.SH NAME +stdarg \- variable argument list +.SH SYNOPSIS +.nf +.ft B +#include + +void va_start(va_list \fIap\fP, \fIargtypeN\fP \fIparmN\fP) +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP) +void va_end(va_list \fIap\fP) +.ft R +.fi +.SH DESCRIPTION +This set of macros provides a means of writing portable procedures that +accept variable argument lists. +Routines having variable argument lists (such as +.BR printf (3)) +that do not use +.B stdarg +are inherently nonportable, since different +machines use different argument passing conventions. +.PP +A function that accepts a variable argument list is declared with "..." at +the end of its parameter list. It must have at least one normal argument +before the "...". For example: +.PP +.RS +.nf +int printf(const char *format, ...) { /* code */ } +int fprintf(FILE *stream, const char *format, ...) { /* code */ } +.fi +.RE +.PP +.B va_list +is a type which is used for the variable +.I ap +within the body of a variable argument function which is used to traverse +the list. +.PP +.B va_start\c +.RI ( ap , +.IR parmN ) +is called to initialize +.I ap +to the beginning of the list. The last true parameter of the function, +.IR parmN , +must be supplied to allow +.B va_start +to compute the address of the first variable parameter. +.PP +.B va_arg\c +.RI ( ap , +.IR type ) +will return the next argument in the list pointed to by +.IR ap . +.I Type +is the type to which the expected argument will be converted +when passed as an argument. +.PP +Different types can be mixed, but it is up +to the routine to know what type of argument is +expected, since it cannot be determined at runtime. +.PP +.B va_end\c +.RI ( ap ) +must be used to finish up. +.PP +Multiple traversals, each bracketed by +.B va_start +\&... +.B va_end, +are possible. +.SH EXAMPLE +.nf +.ta +4n +4n +4n +4n + \fB#include\fP +.sp 0.4 + execl(\fBconst char\fP *path, \fB...\fP) + { + \fBva_list\fP ap; + \fBchar\fP *args[100]; + \fBint\fP argno = 0; + + \fBva_start\fP(ap, path); + \fBwhile\fP ((args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *)) != NULL) {} + \fBva_end\fP(ap); + \fBreturn\fP execv(path, args); + } +.DT +.fi +.SH NOTES +It is up to the calling routine to determine how many arguments +there are, since it is not possible to determine this from the +stack frame. For example, +.B execl +passes a null pointer to signal the end of the list. +.B Printf +can tell how many arguments are supposed to be there by the format. +.PP +The macros +.B va_start +and +.B va_end +may be arbitrarily complex; +for example, +.B va_start +might contain an opening brace, +which is closed by a matching brace in +.BR va_end . +Thus, they should only be used where they could +be placed within a single complex statement. +.SH BUGS +It is impossible to properly show the macros as C declarations as is +done in the synopsis. They can never be coded as C functions, because +all three macros use their arguments by address, and the +.I type +field is certainly impossible. +Just look at them as being part of the C language, like +.BR sizeof . diff --git a/man/man3/stdio.3 b/man/man3/stdio.3 new file mode 100644 index 000000000..78f66e7fa --- /dev/null +++ b/man/man3/stdio.3 @@ -0,0 +1,199 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)stdio.3s 6.2 (Berkeley) 5/13/86 +.\" +.TH STDIO 3 "May 13, 1986" +.UC 4 +.SH NAME +stdio \- standard buffered input/output package +.SH SYNOPSIS +.nf +.ft B +#include + +FILE *stdin; +FILE *stdout; +FILE *stderr; +.ft R +.fi +.SH DESCRIPTION +The functions in the standard I/O library constitute a user-level buffering +scheme. The in-line macros +.B getc +and +.BR putc (3) +handle characters quickly. The higher level routines +.BR gets , +.BR fgets , +.BR scanf , +.BR fscanf , +.BR fread , +.BR puts , +.BR fputs , +.BR printf , +.BR fprintf , +.BR fwrite +all use +.B getc +and +.BR putc ; +they can be freely intermixed. +.PP +A file with associated buffering is called a +.IR stream , +and is declared to be a pointer to a defined type +.SM +.BR FILE . +.BR Fopen (3) +creates certain descriptive data for a stream +and returns a pointer to designate the stream in all further transactions. +There are three normally open streams with constant pointers declared in +the include file and associated with the standard open files: +.TP 10n +.B stdin +standard input file +.br +.ns +.TP +.B stdout +standard output file +.br +.ns +.TP +.B stderr +standard error file +.PP +A constant `pointer' +.SM +.B NULL +(0) +designates no stream at all. +.PP +An integer constant +.SM +.B EOF +(\-1) is returned upon end of file or error by integer functions that +deal with streams. +.PP +Any routine that uses the standard input/output package +must include the header file +.RI < stdio.h > +of pertinent macro definitions. +The functions and constants mentioned in the standard I/O manual pages +are declared in the include file and need no further declaration. +The constants, and the following `functions' are +implemented as macros; redeclaration of these names is perilous: +.BR clearerr , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR feof , +.BR ferror , +.BR fileno . +.SH "SEE ALSO" +.BR open (2), +.BR close (2), +.BR read (2), +.BR write (2), +.BR fclose (3), +.BR ferror (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getc (3), +.BR gets (3), +.BR printf (3), +.BR putc (3), +.BR puts (3), +.BR scanf (3), +.BR setbuf (3), +.BR ungetc (3). +.SH DIAGNOSTICS +The value +.SM +.B EOF +is returned uniformly to indicate that a +.SM +.B FILE +pointer has not been initialized with +.BR fopen , +input (output) has been attempted on an output (input) stream, or a +.SM +.B FILE +pointer designates corrupt or otherwise unintelligible +.SM +.B FILE +data. +.PP +For purposes of efficiency, this implementation of the standard library +has been changed to line buffer output to a terminal by default and attempts +to do this transparently by flushing the output whenever a +.BR read (2) +from the standard input is necessary. This is almost always transparent, +but may cause confusion or malfunctioning of programs which use +standard i/o routines but use +.BR read (2) +themselves to read from the standard input. +.PP +In cases where a large amount of computation is done after printing +part of a line on an output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output +will appear. +.SH BUGS +The standard buffered functions do not interact well with certain other +library and system functions, especially \fBfork\fP and \fBabort\fP. +.SH "LIST OF FUNCTIONS" +.sp 2 +.nf +.ta \w'setlinebuf'u+2n +\w'setbuf(3)'u+10n +\fBName\fP \fBAppears on Page\fP \fBDescription\fP +.ta \w'setlinebuf'u+4n +\w'setbuf(3)'u+4n +.sp 5p +clearerr ferror(3) stream status inquiries +fclose fclose(3) close or flush a stream +fdopen fopen(3) open a stream +feof ferror(3) stream status inquiries +ferror ferror(3) stream status inquiries +fflush fclose(3) close or flush a stream +fgetc getc(3) get character or word from stream +fgets gets(3) get a string from a stream +fileno ferror(3) stream status inquiries +fopen fopen(3) open a stream +fprintf printf(3) formatted output conversion +fputc putc(3) put character or word on a stream +fputs puts(3) put a string on a stream +fread fread(3) buffered binary input/output +freopen fopen(3) open a stream +fscanf scanf(3) formatted input conversion +fseek fseek(3) reposition a stream +ftell fseek(3) reposition a stream +fwrite fread(3) buffered binary input/output +getc getc(3) get character or word from stream +getchar getc(3) get character or word from stream +gets gets(3) get a string from a stream +getw getc(3) get character or word from stream +printf printf(3) formatted output conversion +putc putc(3) put character or word on a stream +putchar putc(3) put character or word on a stream +puts puts(3) put a string on a stream +putw putc(3) put character or word on a stream +rewind fseek(3) reposition a stream +scanf scanf(3) formatted input conversion +setbuf setbuf(3) assign buffering to a stream +setvbuf setbuf(3) assign buffering to a stream +snprintf printf(3) formatted output conversion +sprintf printf(3) formatted output conversion +sscanf scanf(3) formatted input conversion +ungetc ungetc(3) push character back into input stream +vfprintf printf(3) formatted output conversion +vfscanf scanf(3) formatted input conversion +vprintf printf(3) formatted output conversion +vscanf scanf(3) formatted input conversion +vsnprintf printf(3) formatted output conversion +vsprintf printf(3) formatted output conversion +vsscanf scanf(3) formatted input conversion +.fi diff --git a/man/man3/string.3 b/man/man3/string.3 new file mode 100644 index 000000000..d1c044eca --- /dev/null +++ b/man/man3/string.3 @@ -0,0 +1,149 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)string.3 6.1 (Berkeley) 5/15/85 +.\" +.TH STRING 3 "May 15, 1985" +.UC 4 +.SH NAME +string, strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr, strerror, memcmp, memcpy, memmove, memchr, memset, index, rindex \- string operations +.SH SYNOPSIS +.nf +.ft B +#include + +char *strcat(char *\fIs1\fP, const char *\fIs2\fP) +char *strncat(char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP) +int strcmp(const char *\fIs1\fP, const char *\fIs2\fP) +int strncmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP) +char *strcpy(char *\fIs1\fP, const char *\fIs2\fP) +char *strncpy(char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP) +size_t strlen(const char *\fIs\fP) +char *strchr(const char *\fIs\fP, int \fIc\fP) +char *strrchr(const char *\fIs\fP, int \fIc\fP) +char *strerror(int \fIerrnum\fP) +int memcmp(const void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP) +void *memcpy(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP) +void *memmove(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP) +void *memchr(const void *\fIs\fP, int \fIc\fP, size_t \fIn\fP) +void *memset(void *\fIs\fP, int \fIc\fP, size_t \fIn\fP) +char *index(const char *\fIs\fP, int \fIc\fP) +char *rindex(const char *\fIs\fP, int \fIc\fP) +.ft R +.fi +.SH DESCRIPTION +These functions operate on null-terminated strings. +They do not check for overflow of any receiving string. +.PP +.B Strcat +appends a copy of string +.I s2 +to the end of string +.IR s1 . +.B Strncat +copies at most +.I n +characters. Both return a pointer to the null-terminated result. +.PP +.B Strcmp +compares its arguments and returns an integer +greater than, equal to, or less than 0, according as +.I s1 +is lexicographically greater than, equal to, or less than +.IR s2 . +.B Strncmp +makes the same comparison but looks at at most +.I n +characters. +.PP +.B Strcpy +copies string +.I s2 +to +.IR s1 , +stopping after the null character has been moved. +.B Strncpy +copies exactly +.I n +characters, truncating or null-padding +.I s2; +the target may not be null-terminated if the length of +.I s2 +is +.I n +or more. Both return +.IR s1 . +.PP +.B Strlen +returns the number of non-null characters in +.IR s . +.PP +.B Strchr +.RB ( strrchr ) +returns a pointer to the first (last) occurrence of character +.I c +in string +.I s, +or null if +.I c +does not occur in the string. +.PP +.B Strerror +returns the error string for the system call error +.IR errnum . +See +.BR intro (2). +.PP +.B Memcmp +is like +.B strcmp +except that the strings are memory blocks of length +.IR n . +Null characters are treated as ordinary characters. +.PP +.B Memcpy +copies +.I n +bytes from the location pointed to by +.I s2 +to +.IR s1 . +.B Memmove +is like memcpy, except that it can handle overlap between the two strings. +Both functions return +.IR s1 . +.PP +.B Memchr +returns a pointer to the first occurrence of character +.I c +in string +.I s, +or null if +.I c +does not occur in the string. +.PP +.B Memset +sets +.I n +bytes to +.I c +starting at location +.IR s . +It returns +.IR s . +.PP +.B Index +and +.B rindex +are obsolete versions of +.B strchr +and +.BR strrchr . +New code should avoid using them. +.SH NOTES +Characters are compared as +.BR "unsigned char" , +whether +.B char +itself is signed or not. diff --git a/man/man3/system.3 b/man/man3/system.3 new file mode 100644 index 000000000..760eb5105 --- /dev/null +++ b/man/man3/system.3 @@ -0,0 +1,30 @@ +.\" @(#)system.3 6.1 (Berkeley) 5/15/85 +.\" +.TH SYSTEM 3 "May 15, 1985" +.AT 3 +.SH NAME +system \- issue a shell command +.SH SYNOPSIS +.nf +.ft B +#include + +int system(const char *\fIstring\fP) +.fi +.SH DESCRIPTION +.B System +causes the +.I string +to be given to +.BR sh (1) +as input as if the string had been typed as a command +at a terminal. +The current process waits until the shell has +completed, then returns the exit status of the shell. +.SH "SEE ALSO" +.BR sh (1), +.BR popen (3), +.BR execve (2), +.BR wait (2). +.SH DIAGNOSTICS +Exit status 127 indicates the shell couldn't be executed. diff --git a/man/man3/termcap.3 b/man/man3/termcap.3 new file mode 100644 index 000000000..d80710681 --- /dev/null +++ b/man/man3/termcap.3 @@ -0,0 +1,167 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)termcap.3x 6.1 (Berkeley) 5/15/85 +.\" +.TH TERMCAP 3 "May 15, 1985" +.UC 4 +.SH NAME +termcap, tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs \- terminal independent operation routines +.SH SYNOPSIS +.nf +.ft B +#include + +int tgetent(char *\fIbp\fP, char *\fIname\fP) +int tgetflag(char *\fIid\fP) +int tgetnum(char *\fIid\fP) +char *tgetstr(char *\fIid\fP, char **\fIarea\fP) +char *tgoto(char *\fIcm\fP, int \fIdestcol\fP, int \fIdestline\fP) +int tputs(char *\fIcp\fP, int \fIaffcnt\fP, void (*\fIoutc\fP)(int)) +.ft R +.fi +.SH DESCRIPTION +These functions extract and use capabilities from the terminal capability data +base +.BR termcap (5). +These are low level routines; +see +.BR curses (3) +for a higher level package. +.PP +.B Tgetent +extracts the entry for terminal +.I name +into the buffer at +.IR bp . +.I Bp +should be a character buffer of size +1024 and must be retained through all subsequent calls +to +.BR tgetnum , +.BR tgetflag , +and +.BR tgetstr . +.B Tgetent +returns \-1 if it cannot find a termcap +file, 0 if the terminal name given does not have an entry, +and 1 if all goes well. +.PP +.B Tgetent +uses the following recipe to find the termcap file and entry +.IR name : +.PP +.in +5n +if $TERMCAP is itself a termcap entry for +.I name +.br +then +.in +5n +use $TERMCAP +.in -5n +elif $TERMCAP names a file +.br +then +.in +5n +use entry +.I name +found in that file +.in -5n +elif this is Minix-vmd +.br +then +.in +5n +if $TERMPATH is defined +.br +then +.in +5n +search the termcap files named in $TERMPATH for the first occurance of a +.I name +entry and use that entry +.in -5n +else +.in +5n +the path +.B $HOME/.termcap:/etc/termcap:/usr/etc/termcap" +is searched for entry +.I name +.in -5n +fi +.in -5n +fi +.in -5n +.RE +.PP +.B Tgetnum +gets the numeric value of capability +.IR id , +returning \-1 if is not given for the terminal. +.B Tgetflag +returns 1 if the specified capability is present in +the terminal's entry, 0 if it is not. +.B Tgetstr +returns the string value of the capability +.IR id , +places it in the buffer at +.IR area , +and advances the +.I area +pointer. +It decodes the abbreviations for this field described in +.BR termcap (5), +except for cursor addressing and padding information. +.B Tgetstr +returns NULL if the capability was not found. +.PP +.B Tgoto +returns a cursor addressing string decoded from +.I cm +to go to column +.I destcol +in line +.IR destline . +It uses the external variables +.B UP +(from the \fBup\fR capability) +and +.B BC +(if \fBbc\fR is given rather than \fBbs\fR) +if necessary to avoid placing \fB\en\fR, \fB^D\fR or \fB^@\fR in +the returned string. +(Programs which call tgoto should be sure to turn off the XTABS bit(s), +since +.B tgoto +may now output a tab. +Note that programs using termcap should in general turn off XTABS +anyway since some terminals use CTRL-I for other functions, +such as nondestructive space.) +If a \fB%\fR sequence is given which is not understood, then +.B tgoto +returns \*(lqOOPS\*(rq. +.PP +.B Tputs +decodes the leading padding information of the string +.IR cp ; +.I affcnt +gives the number of lines affected by the operation, or 1 if this is +not applicable, +.I outc +is a routine which is called with each character in turn. +The external variable +.B ospeed +should contain the output speed of the terminal as encoded by +.BR stty (3). +The external variable +.B PC +should contain a pad character to be used (from the \fBpc\fR capability) +if a null (\fB^@\fR) is inappropriate. +.SH SEE ALSO +.BR curses (3), +.BR termcap (5). +.SH AUTHOR +William Joy +.SH NOTES +The Minix implementation does not support any of the external variables, +only the functions calls. The Minix-vmd termcap does support it all, +although noone in his right mind meddles with those variables. diff --git a/man/man3/termios.3 b/man/man3/termios.3 new file mode 100644 index 000000000..411e22cb5 --- /dev/null +++ b/man/man3/termios.3 @@ -0,0 +1,155 @@ +.TH TERMIOS 3 +.SH NAME +termios, tcgetattr, tcsetattr, cfgetispeed, cfgetospeed, cfsetispeed, cfsetospeed, tcsendbreak, tcdrain, tcflush, tcflow \- change terminal attributes +.SH SYNOPSIS +.ft B +.nf +#include + +int tcgetattr(int \fIfd\fP, struct termios *\fItp\fP) +int tcsetattr(int \fIfd\fP, int \fIaction\fP, const struct termios *\fItp\fP) + +speed_t cfgetispeed(const struct termios *\fItp\fP) +speed_t cfgetospeed(const struct termios *\fItp\fP) +int cfsetispeed(struct termios *\fItp\fP, speed_t \fIspeed\fP) +int cfsetospeed(struct termios *\fItp\fP, speed_t \fIspeed\fP) + +int tcsendbreak(int \fIfd\fP, int \fIduration\fP) +int tcdrain(int \fIfd\fP) +int tcflush(int \fIfd\fP, int \fIqueue_selector\fP) +int tcflow(int \fIfd\fP, int \fIaction\fP) +.fi +.ft P +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +These are the user functions that modify the tty attributes mentioned in +.BR tty (4). +In the following, +.I fd +refers to an open terminal device file, +.I tp +is the address of a +.BR "struct termios" , +and +.I speed +and values of type +.B speed_t +are equal to one of the +.BR B0 , +.BR B50 , +etc. baud rate symbols. All functions, symbols, and types are declared in +.BR . +.PP +The effects of the tty functions are: +.TP +.B tcgetattr(\fIfd\fP, \fItp\fP) +Get the current settings of the tty attributes. +.TP +.B tcsetattr(\fIfd\fP, TCSANOW, \fItp\fP) +Set the terminal attributes. The change occurs immediately. +.TP +.B tcsetattr(\fIfd\fP, TCSADRAIN, \fItp\fP) +Set the terminal attributes. The change occurs once all the output waiting +in the output queues has been transmitted. This should be used when options +affecting output are changed. +.TP +.B tcsetattr(\fIfd\fP, TCSAFLUSH, \fItp\fP) +Set the terminal attributes. But first wait until all the output waiting +in the output queues has been transmitted. All input waiting in the input +queues is then discarded and the change is made. This should be used when +switching from canonical to non-canonical mode or vice-versa. (Oddly +enough, this is seldom what you want, because it discards typeahead. An +editing shell does the Right Thing if it uses +.B TCSANOW +instead. \s-2POSIX\s+2 may not guarantee good results, but in practice most +systems make the canonical input available in raw mode.) +.TP +.B cfgetispeed(\fItp\fP) +Return the input baud rate encoded in the termios structure. +.TP +.B cfgetospeed(\fItp\fP) +Return the output baud rate encoded in the termios structure. +.TP +.B cfsetispeed(\fItp\fP, \fIspeed\fP) +Encode the new input baud rate into the termios structure. +.TP +.B cfsetospeed(\fItp\fP, \fIspeed\fP) +Encode the new output baud rate into the termios structure. +.TP +.B tcsendbreak(\fIfd\fP, \fIduration\fP) +Emit a break condition on a serial line for a time indicated by +.IR duration . +(Always 0.4 seconds under Minix, +.I duration +is ignored.) +.TP +.B tcdrain(\fIfd\fP) +Wait until all output waiting in the output queues has been transmitted. +.TP +.B tcflush(\fIfd\fP, TCIFLUSH) +Flush the input queue. (I.e. discard it.) +.TP +.B tcflush(\fIfd\fP, TCOFLUSH) +Flush the output queue. +.TP +.B tcflush(\fIfd\fP, TCIOFLUSH) +Flush the input and output queues. +.TP +.B tcflow(\fIfd\fP, TCOOFF) +Suspend output. (Like the effect of +.BR STOP .) +.TP +.B tcflow(\fIfd\fP, TCOON) +Restart output. (Like the effect of +.BR START .) +.TP +.B tcflow(\fIfd\fP, TCIOFF) +Transmit a +.B STOP +character intended to make the remote device stop transmitting data. +.TP +.B tcflow(\fIfd\fP, TCION) +Transmit a +.B START +character to restart the remote device. +.SH "SEE ALSO" +.BR stty (1), +.BR tty (4). +.SH DIAGNOSTICS +All functions return 0 unless otherwise specified, and \-1 on error with +.B errno +set to indicate the type of error. The most notable errors are +.B ENOTTY +if +.I fd +does not refer to a terminal device, and +.B EINTR +if one of the functions waiting for output to drain is interrupted. +.SH NOTES +It may be interesting to know that the functions operating on the tty are +directly translated into the following Minix +.B ioctl +requests: +.BR TCGETS , +.BR TCSETS +(now), +.BR TCSETSW +(drain), +.BR TCSETSF , +(flush), +.BR TCSBRK , +.BR TCDRAIN , +.BR TCFLSH , +and +.BR TCFLOW . +You should only use this knowledge when trying to understand the tty driver +code, of course. +.SH BUGS +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: termios.3,v 1.2 1996/04/11 06:41:24 philip Exp $ diff --git a/man/man3/ttyname.3 b/man/man3/ttyname.3 new file mode 100644 index 000000000..59ce81d87 --- /dev/null +++ b/man/man3/ttyname.3 @@ -0,0 +1,28 @@ +.TH TTYNAME 3 +.SH NAME +ttyname \- file descriptor to terminal device name +.SH SYNOPSIS +.nf +.ft B +#define _POSIX_SOURCE 1 +#include + +char *ttyname(int \fIfd\fP) +.ft P +.fi +.SH DESCRIPTION +.B Ttyname +searches through the +.B /dev +directory for the terminal device file that is associated with file +descriptor +.IR fd . +It returns the full path name of the terminal file if found, NULL is +returned otherwise. +.SH "SEE ALSO" +.BR ttyslot (3). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) + +.\" +.\" $PchId: ttyname.3,v 1.2 1996/04/11 06:42:17 philip Exp $ diff --git a/man/man3/ttyslot.3 b/man/man3/ttyslot.3 new file mode 100644 index 000000000..30748b088 --- /dev/null +++ b/man/man3/ttyslot.3 @@ -0,0 +1,56 @@ +.TH TTYSLOT 3 +.SH NAME +ttyslot, fttyslot \- utmp slot number +.SH SYNOPSIS +.nf +.ft B +#define _MINIX_SOURCE 1 +#include + +int ttyslot(void) +int fttyslot(int \fIfd\fP) +.fi +.ft P +.SH DESCRIPTION +.B Ttyslot() +returns the index of the login terminal in the +.B utmp +file. It tries +.B fttyslot() +on file descriptors +.BR 0, +.BR 1, +and +.BR 2 +to find the index. +.PP +.B Fttyslot() +returns the utmp index of the terminal associated with file descriptor +.IR fd . +First it tries to map +.I fd +to a terminal name with +.BR ttyname (3), +then it searches the +.BR ttytab (5) +database with the +.BR getttyent (3) +function for this terminal. This means that the utmp slot number is the +same as the ttytab entry number counting from 1. The value 0 is returned if +no slot number can be found for a file descriptor. +.SH "SEE ALSO" +.BR ttyname (3), +.BR getttyent (3), +.BR utmp (5), +.BR ttytab (5), +.BR init (8). +.SH NOTES +Since 0 is used as an error return this means that the first entry in the +utmp file is not used. +.PP +.B Ttyslot() +is often found in a UNIX implementation, +.B fttyslot() +is Minix specific. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man3/ungetc.3 b/man/man3/ungetc.3 new file mode 100644 index 000000000..503ec7a93 --- /dev/null +++ b/man/man3/ungetc.3 @@ -0,0 +1,41 @@ +.\" @(#)ungetc.3s 6.1 (Berkeley) 5/15/85 +.\" +.TH UNGETC 3 "May 15, 1985" +.AT 3 +.SH NAME +ungetc \- push character back into input stream +.SH SYNOPSIS +.nf +.ft B +#include + +int ungetc(int \fIc\fP, FILE *\fIstream\fP) +.ft R +.fi +.SH DESCRIPTION +.B Ungetc +pushes the character +.I c +back on an input stream. That character will be returned by the next +.B getc +call on that stream. +.B Ungetc +returns +.IR c . +.PP +One character of pushback is guaranteed provided +something has been read from the stream and the stream is actually buffered. +Attempts to push EOF are rejected. +.PP +.BR Fseek (3) +erases all memory of pushed back characters. +.SH "SEE ALSO" +.BR getc (3), +.BR setbuf (3), +.BR fseek (3). +.SH DIAGNOSTICS +.B Ungetc +returns +.SM +.B EOF +if it can't push a character back. diff --git a/man/man4/console.4 b/man/man4/console.4 new file mode 100644 index 000000000..89479d995 --- /dev/null +++ b/man/man4/console.4 @@ -0,0 +1,268 @@ +.TH CONSOLE 4 +.SH NAME +console, keyboard, log \- system console +.SH DESCRIPTION +The TTY device driver manages two devices related to the main user +interface, the system screen and the keyboard. These two together are +named "the Console". +.SS "The Screen" +The screen of a PC can be managed by a Monochrome Display Adapter, a +Hercules card, a Color Graphics Adapter, an Enhanced Graphics Adapter, +or a Video Graphics Array. To the console driver these devices are +seen as a block of video memory into which characters can be written to +be displayed, an I/O register that sets the video memory origin to the +character that is to be displayed on the top-left position of the +screen, and an I/O register that sets the position of the hardware +cursor. Each character within video memory is a two-byte word. The low +byte is the character code, and the high byte is the "attribute byte", +a set of bits that controls the way the character is displayed, +character and background colours for a colour card, or +intensity/underline/reverse video for monochrome. +.PP +These are the characteristics of the adapters in text mode: +.PP +.RS +.nf +.ta +15n +15n +Adapter Usable memory Mono/Colour +.ta +1n +15n +15n + MDA 4K M + Hercules 4K M + CGA 16K C + EGA 32K M or C + VGA 32K M or C +.fi +.RE +.PP +MDA and Hercules are the same to the console driver, because the graphics +mode of the Hercules is of no use to Minix. EGA and VGA are also mostly +seen as the same in text mode. An EGA adapter is either a monochrome or a +colour device depending on the screen attached to it. A VGA adapter can run +in either monochrome or colour (grayscale) mode depending on how the Boot +Monitor has initialized it. +.PP +The driver uses the video origin to avoid copying the screen contents when +scrolling up or down. Instead the origin is simply moved one line. This is +named "hardware scrolling", as opposed to copying memory: "software +scrolling". +.PP +The video origin is also used to implement several virtual consoles inside +the video memory of the adapter. Each virtual console gets a segment of +video memory. The driver chooses which console to display by moving the +video origin. Note that an MDA or Hercules adapter can only support one +console. CGA can support up to four 80x25 consoles, and EGA and VGA can +have eight. It is best to configure one less console to leave some video +memory free so that hardware scrolling has some space to work in. +.PP +Character codes are used as indices into a display font that is stored in the +adapter. The default font is the IBM character set, which is an ASCII +character set in the low 128 codes, and a number of mathematical, greek, +silly graphics, and accented characters in the upper 128 codes. This font +is fixed in the MDA, Hercules and CGA adapters, but can be replaced by a +user selected font for the EGA and VGA adapters. +.PP +A number of control characters and escape sequences are implemented by the +driver. The result is upward compatible with the ANSI standard terminal. +The +.BR termcap (5) +type is +.BR minix . +Normal characters written to the console are displayed at the cursor +position and the cursor is advanced one column to the right. If an entire +line is filled then the cursor wraps to the first column of the next line +when the next character must be displayed. The screen is scrolled up if +needed to start a new line. Some characters have special effects when sent +to the console. Some even have arguments in the form of comma separated +decimal numbers. These numbers default to the lowest possible value when +omitted. The top-left character is at position (1, 1). The following +control characters and escape sequences are implemented by the console: +.PP +.ta +10n +20n +Sequence Name Function +.in +31n +.ti -30n +^@ Null Ignored (padding character) +.ti -30n +^G Bell Produce a short tone from the speaker +.ti -30n +^H Backspace Move the cursor back one column, wrapping from the +left edge up one line to the right edge +.ti -30n +^I Horizontal Tab Move to the next tab stop, with each tab stop at +columns 1, 9, 25, etc. Wrap to the next line if necessary. +.ti -30n +^J Line Feed Move one line down, scrolling the screen up if +necessary +.ti -30n +^K Vertical Tab Same as LF +.ti -30n +^L Form Feed Same as LF +.ti -30n +^M Carriage Return Move to column 1 +.ti -30n +^[ Escape Start of an escape sequence +.ti -30n +^[M Reverse Index Move one line up, scrolling the screen down if +necessary +.ti -30n +^[[\fIn\fPA Cursor Up Move the cursor up \fIn\fP lines +.ti -30n +^[[\fIn\fPB Cursor Down Move the cursor down \fIn\fP lines +.ti -30n +^[[\fIn\fPC Cursor Forward Move the cursor right \fIn\fP columns +.ti -30n +^[[\fIn\fPD Cursor Backward Move the cursor left \fIn\fP columns +.ti -30n +^[[\fIm\fP;\fIn\fPH Cursor Position Move the cursor to line \fIm\fP, +column \fIn\fP +.ti -30n +^[[\fIs\fPJ Erase in Display Clear characters as follows: +.br +\fIs\fP = 0: From cursor to end of screen +.br +\fIs\fP = 1: From start of screen to cursor +.br +\fIs\fP = 2: Entire screen +.ti -30n +^[[\fIs\fPK Erase in Line Clear characters as follows: +.br +\fIs\fP = 0: From cursor to end of line +.br +\fIs\fP = 1: From start of line to cursor +.br +\fIs\fP = 2: Entire line +.ti -30n +^[[\fIn\fPL Insert Lines Insert \fIn\fP blank lines +.ti -30n +^[[\fIn\fPM Delete Lines Delete \fIn\fP lines +.ti -30n +^[[\fIn\fP@ Insert Characters Insert \fIn\fP blank characters +.ti -30n +^[[\fIn\fPP Delete Characters Delete \fIn\fP characters +.ti -30n +^[[\fIn\fPm Character Attribute Set character attribute as follows: +.br +\fIn\fP = 0: Normal (default) attribute +.br +\fIn\fP = 1: Bold (high intensity fg colour) +.br +\fIn\fP = 4: Underline (mono) / Cyan (colour) +.br +\fIn\fP = 5: Blinking +.br +\fIn\fP = 7: Reverse Video +.br +\fIn\fP = 30: Black foreground colour +.br +\fIn\fP = 31: Red +.br +\fIn\fP = 32: Green +.br +\fIn\fP = 33: Brown +.br +\fIn\fP = 34: Blue +.br +\fIn\fP = 35: Magenta +.br +\fIn\fP = 36: Cyan +.br +\fIn\fP = 37: Light Gray +.br +\fIn\fP = 39: Default fg colour (lt gray) +.br +\fIn\fP = 40\-47: Same for background colour +.br +\fIn\fP = 49: Default bg colour (black) +.br +Note: The "bold" versions of black, brown and lt gray become dark gray, +yellow and white. +.in -31n +.PP +The console device implements the following ioctl to copy a font into +font memory on EGA and VGA adapters: +.PP +.RS +.BI "ioctl(" fd ", TIOCSFON, u8_t " font "[256][32]);" +.RE +.PP +Font memory consists of 256 character definitions of 32 lines per character +and 8 pixels per line. The first line is the topmost line of the character. +The leftmost pixel is lit if the most significant bit of a line is set, etc. +How many lines are used depends on the current video mode. The 80x25 video +mode used by Minix has an 8x16 character cell, 80x28 has 8x14 characters, +and 132x43 or 132x50 has 8x8 characters. The boot variable +.B console +is used by both the Boot Monitor and the console driver to set the video +mode, software scrolling on/off, and VGA screen blank timeout. See +.BR boot (8). +.SS "The Keyboard" +The keyboard produces key codes for each key that is pressed. These keys +are transformed into character codes or sequences according to the current +keyboard translation table. The format of this table is described in +.BR keymap (5). +The character codes can be read from the console device unless they map to +special hotkeys. The hotkeys are as follows: +.PP +.ta +17n +Name Key Function +.in +18n +.ti -17n +CTRL\-ALT\-DEL Send an abort signal to process 1 (init). Init then +halts the system +.ti -17n +CTRL\-ALT\-KP-. Likewise for keypad period +.ti -17n +F1 Process table dump +.ti -17n +F2 Show memory map +.ti -17n +F3 Toggle software/hardware scrolling +.ti -17n +F5 Show network statistics +.ti -17n +CTRL\-F7 Send a quit signal to all processes connected to the console +.ti -17n +CTRL\-F8 Send an interrupt signal +.ti -17n +CTRL\-F9 Send a kill signal. If CTRL\-F8 or CTRL\-F7 don't get 'em, +then this surely will. These keys are for disaster recovery. You would +normally use DEL and CTRL\-\e to send interrupt and quit signals. +.\" .ig VC +.ti -17n +ALT\-F1 Select virtual console 0 (/dev/console) +.ti -17n +ALT\-F2 Select virtual console 1 (/dev/ttyc1) +.ti -17n +ALT\-F(\fIn\fP+1) Select virtual console \fIn\fP +(/dev/ttyc\fIn\fP) +.ti -17n +ALT\-Left Select previous virtual console +.ti -17n +ALT\-Right Select next virtual console +.\" .. +.in -18n +.PP +.\"XXX +The keyboard map is set with the +.B KIOCSMAP +ioctl whose precise details are currently hidden in the +.B loadkeys +utility. +.SS "Log device" +The +.B log +device can be used by processes to print debug messages onto the console. +The console is a terminal type device, so it is taken from processes when a +session leader exits. This does not happen with the log device. +.SH "SEE ALSO" +.BR tty (4), +.BR loadkeys (1), +.BR keymap (5), +.BR boot (8). +.SH NOTES +Output processing turns Line Feeds into CR LF sequences. Don't let this +surprise you. Either turn off output processing or use one of the synonyms +for LF. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) +.\" minor editing of man page by asw 07.08.96 diff --git a/man/man4/controller.4 b/man/man4/controller.4 new file mode 100644 index 000000000..36ad7b8a7 --- /dev/null +++ b/man/man4/controller.4 @@ -0,0 +1,387 @@ +.TH CONTROLLER 4 +.SH NAME +controller, disk, tape, at, bios, esdi, aha1540, ncr810, dosfile, fatfile \- controllers, disks and tapes +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The +.BI c n * +family of devices refer to drivers that control disks, disk like devices, +and tapes. Minix contains a number of drivers for several different +controllers. These controllers can have disks, cdroms and tapes attached to +them. Boot Monitor variables specify which drivers are activated using +the variables +.BR c0 , +.BR c1 , +etc. The names of the devices in +.BR /dev +that correspond with the driver for controller 0 are all named beginning +with +.BR c0 . +.PP +For each controller, the minor device numbers are organized as follows: +.PP +.RS +.nf +.ta +\w'122-127nnmm'u +\w'd0p0s0nnmm'u +\w'disk 0, part 0, subpart 0nnmm'u +.ft B +minor device what? obsolete +.ft P +0 d0 disk 0 hd0 +1 d0p0 disk 0, partition 0 hd1 +2 d0p1 disk 0, partition 1 hd2 +3 d0p2 disk 0, partition 2 hd3 +4 d0p3 disk 0, partition 3 hd4 +5 d1 disk 1 hd5 +6 d1p0 disk 1, partition 0 hd6 +7 d1p1 disk 1, partition 1 hd7 +8 d1p2 disk 1, partition 2 hd8 +9 d1p3 disk 1, partition 3 hd9 +\&... ... +39 d7p3 disk 7, partition 3 hd39 +.SP +64 t0n tape 0, non-rewinding +65 t0 tape 0, rewind on close +66 t1n tape 1, non-rewinding +67 t1 tape 1, rewind on close +\&... ... +78 t7n tape 7, non-rewinding +79 t7 tape 7, rewind on close +.SP +120 r0 raw access device 0 +121 r1 raw access device 1 +\&... ... +127 r7 raw access device 7 +.SP +128 d0p0s0 disk 0, part 0, subpart 0 hd1a +129 d0p0s1 disk 0, part 0, subpart 1 hd1b +130 d0p0s2 disk 0, part 0, subpart 2 hd1c +131 d0p0s3 disk 0, part 0, subpart 3 hd1d +132 d0p1s0 disk 0, part 1, subpart 0 hd2a +\&... ... +144 d1p0s0 disk 1, part 0, subpart 0 hd6a +\&... ... +255 d7p3s3 disk 7, part 3, subpart 3 hd39d +.fi +.RE +.PP +The device names in +.B /dev +also name the controller, of course, so the usual place for the Minix +root device, the first subpartition of the second partition of disk 0 on +controller 0 is +.BR /dev/c0d0p1s0 . +Note that everything is numbered from 0! The first controller is controller +0, the first disk is disk 0, etc. So the second partition is +.BR p1 . +.PP +The fourth column in the table above shows the disk devices names that were +used by previous versions of Minix for what is now controller 0. These +devices are no longer present in +.BR /dev . +.SS Disks +Most disks are arrays of 512 byte sectors. The disk devices are normally +block devices, which means they are block buffered by the Minix file system +cache using 1024 byte blocks. The FS cache allows I/O at any byte offset, +and takes care of cutting and pasting incomplete blocks together. If one +creates a character device for a disk device, then I/O must be in multiples +of the disk block size. +.PP +For each disk there is a device that covers the entire disk, these are named +.BR c0d0 , +.BR c0d1 , +etc, up to +.B c0d7 +for controller 0. If a partition table is placed in the first sector of the +disk, then the disk is subdivided into regions named partitions. Up to four +partitions may be defined, named +.BR c0d0p0 +to +.BR c0d0p3 +for disk 0 on controller 0. To make things interesting you can also place a +partition table in the first sector of a Minix partition, which divides the +partition into up to four subpartitions. Normally Minix is installed into a +single partition, with the root, swap and /usr file systems in subpartitions. +.PP +If a partition is an extended partition then it contains a linked list of +partition tables each of which may specify a logical partition. Up to four +of these logical partitions are presented by the driver as subpartitions of +the extended partition. +.PP +A sector containing a partition table starts with 446 bytes of boot code, +followed by four partition table entries of 16 bytes each, and ends with +the magic number 0xAA55 (little endian, so first 0x55 then 0xAA.) Partition +table information is defined in : +.PP +.nf +.ta +2n +29n +37n +/* Description of entry in the partition table. */ + +struct part_entry { + unsigned char bootind; /* boot indicator 0/ACTIVE_FLAG */ + unsigned char start_head; /* head value for first sector */ + unsigned char start_sec; /* sector value + high 2 cyl bits */ + unsigned char start_cyl; /* low 8 cylinder bits */ + unsigned char sysind; /* system indicator */ + unsigned char last_head; /* h/s/c for the last sector */ + unsigned char last_sec; + unsigned char last_cyl; + unsigned long lowsec; /* logical first sector */ + unsigned long size; /* size of partition in sectors */ +}; + +.ta +24n +7n +37n +#define ACTIVE_FLAG 0x80 /* value for active in bootind field */ +#define NR_PARTITIONS 4 /* number of entries in table */ +#define PART_TABLE_OFF 0x1BE /* offset of table in boot sector */ + +/* Partition types (sysind). */ +#define NO_PART 0x00 /* unused entry */ +#define MINIX_PART 0x81 /* Minix partition type */ +.fi +.PP +The cylinder numbers are encoded in a very strange way, bits 8 and 9 are +in the high two bits of the sector number. The sector numbers count from 1, +not 0! More useful are the lowsec and size fields however, they simply give +the location of the partition as an absolute sector offset and length within +the drive. +.PP +The partition table entry defined above is specific to IBM type disks. The +device drivers use another partition entry structure to pass information on +a partition. This is what looks like: +.sp +.nf +.ta +2n +25n +struct partition { + u64_t base; /* byte offset to the partition start */ + u64_t size; /* number of bytes in the partition */ + unsigned cylinders; /* disk geometry for partitioning */ + unsigned heads; + unsigned sectors; +}; +.fi +.PP +The base and size fields are the byte offset and length of a partition. +The geometry of the disk is also given for the benefit of +partition table editors. This information can be obtained from an open disk +device with the call: +.sp +.RS +.ft B +ioctl(\fIfd\fP, DIOCGETP, &\fIentry\fP); +.ft R +.RE +.sp +One can change the placement of the device to the lowsec and size fields of +.I entry +by using the +.B DIOCSETP +call instead. Only the base and size fields are used for +.BR DIOCSETP . +.PP +The partition tables when read from disk by the driver are checked and +truncated to fit within the primary partition or drive. The first sector +is normally left free for the partition table. +.PP +The partition tables are read when the in-use count (opens and mounts) +changes from 0 to 1. So an idle disk is automatically repartitioned on the +next access. This means that DIOCSETP only has effect if the disk is in +use. +.SS "Disk-like devices" +Devices like a CD-ROM are treated as read-only disks, and can be accessed +using disk devices. A CD-ROM usually has a block size of 2048 bytes, but +the driver knows this, and allows one to read at any byte offset by reading +what isn't needed into a scratch buffer. +.SS Tapes +There are two kinds of tape devices: Non-rewinding, and rewind-on-close. +The non-rewinding devices treat the tape as a series of files. The +rewind-on-close devices look at the tape as a single file, and when you close +such a device the tape is told to rewind. +See +.BR mt (1), +and +.BR mtio (4) +for a description of the commands that may be sent to the tape, either from +the command prompt or from a program. +.PP +There are two kinds of tape drives: Fixed and variable block size tape +drives. Examples of the first kind are cartridge +tapes, with a fixed 512 bytes block size. An Exabyte tape drive has a +variable block size, with a minimum of 1 byte and a maximum of 245760 bytes +(see the documentation of such devices.) +The maximum is truncated to 32767 bytes for Minix-86 and 61440 bytes for +Minix-vmd, because the driver can't move more bytes in a single request. +.PP +A read or write to a fixed block size tape must be a precise multiple of the +block size, any other count gives results in an I/O error. A read from a +variable block sized tape must be large enough to accept the block that is +read, otherwise an I/O error will be returned. A write can be any size +above the minimum, creating a block of that size. If the write count is +larger than the maximum block size then more blocks are written until the +count becomes zero. The last block must be larger than the minimum of +course. (This minimum is often as small as 1 byte, as for the Exabyte.) +.PP +The +.B mt blksize +command may be used to select a fixed block size for a variable block sized +tape. This will speed up I/O considerably for small block sizes. (Some +systems can only use fixed mode and will write an Exabyte tape with 1024 +byte blocks, which read very slow in variable mode.) +.PP +A tape is a sequence of blocks and filemarks. A tape may be opened and +blocks may be read from it upto a filemark, after that all further reads +return 0. After the tape is closed and reopened one can read the blocks +following the filemark if using a non-rewinding device. This makes the tape +look like a sequence of files. +.PP +If a tape has been written to or opened in write-only mode, then a filemark +is written if the tape is closed or if a space command is issued. No extra +filemark is written if the drive is instructed to write filemarks. +.SS "Raw Access Devices" +Under Minix-vmd one can use the raw access devices to program a SCSI +device entirely from user mode. The disk and tape devices probe for devices +when opened, start disks and load tapes, but the raw access devices do +nothing at all. Given an open file descriptor to any SCSI character device +(not just the raw access devices) one can use the following ioctl: +.PP +.RS +ioctl(fd, SCIOCCMD, &scsicmd) +.RE +.PP +The structure whose address is passed as the third argument is defined +in as follows: +.PP +.RS +.nf +struct scsicmd { + void *cmd; + size_t cmdlen; + void *buf; + size_t buflen; + void *sense; + size_t senselen; + int dir; +}; +.fi +.RE +.PP +.B Cmd +and +.B cmdlen +hold the address and length of an object holding a Group 0 or Group 1 +SCSI command. The next two fields describe a buffer of at most 8 kilobytes +used in the data in or out phase. +.B Dir +is 0 if data is to be read from the device, 1 if data is written to the +device. If the ioctl succeeds then 0 is returned, otherwise -1 with +.B errno +set to +.B EIO +and the request sense info returned in the buffer described by the sense and +senselen fields. If the sense key is zero on error then a host adapter +error occurred, this means that the device is most likely turned off or not +present. +.SH DRIVERS +By setting the Boot variables +.BR c0 +to +.BR c3 +under Minix, or +.BR c0 +to +.BR c4 +under Minix-vmd one attaches a set of disk and tape devices to a driver. +See +.BR boot (8) +for a list of boot variables that configure each of these drivers. +The following drivers are available: +.SS at +The standard IBM/AT disk driver that also supports IDE disks. This is the +default driver for controller 0 on AT class machines. (Most PCs are in that +class.) +.SS bios +A disk driver that uses BIOS calls to do disk I/O. This is the default +driver on anything but an AT. (Old XTs and PS/2s.) On an XT this is the +best driver you can use, but on any other machine this driver may be +somewhat slow, because the system has to switch out of protected mode to +make a BIOS call. On a fast enough machine with a high enough setting of +DMA_SECTORS (see +.BR config (8)) +it works well enough. +.SS esdi +A hard disk driver for use on some PS/2 models. +.SS "xt \fR(Minix only)" +A hard disk driver for IBM/XT type hard disks. Useful for old 286 based +machines that have such a disk. On XTs you are better off with the +.B bios +driver. +.SS aha1540 +A SCSI driver for the Adaptec 1540 host adapter family, which includes the +1540, 1540A, 1540B, 1540C, 1540CF, 1640, and 1740. Also supported is the +compatible BusLogic 545. +.SS ncr810 +This will eventually become a Symbios 810 SCSI driver. (Formerly owned by +NCR.) KJB has read the docs on this card three times, but has still done +nothing, the lazy bum. +.SS dosfile +The "DOS file as disk" driver that is used when Minix is running +under DOS. It treats a large DOS file as a Minix disk. Only primary +partitions are supported, there are no subpartitions. This is the default +driver when Minix is started under DOS. +.SS fatfile +Uses a large file on a FAT file system as a disk. It needs one of the other +disk drivers to do the actual I/O. This driver only knows how to interpret +a FAT file system to find the file to use. With a fast native disk driver +this driver is much faster than the +.B dosfile +driver. +.SH FILES +.TP 25 +/dev/c*d* +Disks devices. +.TP +/dev/c*d*p* +Partitions. +.TP +/dev/c*d*p*s* +Subpartitions. +.TP +/dev/c*t*n, /dev/c*t* +Tapes. +.TP +/dev/c*r* +Raw access devices. +.SH "SEE ALSO" +.BR dd (1), +.BR mt (1), +.BR eject (1), +.BR ioctl (2), +.BR int64 (3), +.BR mtio (4), +.BR boot (8), +.BR config (8), +.BR monitor (8), +.BR part (8), +.BR repartition (8). +.SH BUGS +The subpartitioning is incompatible with the MS-DOS method of extended +partitions. The latter does not map well to the sparse minor device number +space. +.PP +The primary partition table is sorted by lowsec like MS-DOS does, subpartition +tables are not. Just think about what happens when you delete a partition in +the MS-DOS scheme. +.PP +Don't move a partition that is mounted or kept open by some process. The +file system may write cached blocks to the new location. +.PP +The BIOS driver is not slow at all on a buffered disk. +.PP +Some IDE disks send an interrupt when they spin down under hardware power +management. The driver acknowledges the interrupt as it is supposed to do by +reading the status register. The disk then spins up again... You have to +disable the spin down in the computer setup to fix the problem. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man4/dev.4 b/man/man4/dev.4 new file mode 100644 index 000000000..9bdffbf00 --- /dev/null +++ b/man/man4/dev.4 @@ -0,0 +1,261 @@ +.TH DEV 4 +.SH NAME +dev \- device files in /dev +.SH DESCRIPTION +Device files are the eyes and ears of the system. Through the device files +one has access to the disks, terminals and other parts of the machine. +Single bytes or disk blocks may be transferred to or from a device with +ordinary +.BR read (2) +or +.BR write (2) +calls, byte positions set with +.BR lseek (2), +or more complicated control functions performed with +.BR ioctl(2). +.PP +Device files as found in +.B /dev +have several attributes that must be considered. Here are two examples as +.B "ls \-l" +shows them: +.PP +.RS +.nf +.if t .ft C +brw-rw-rw- 1 root operator 2, 1 Jun 10 1995 fd1 +crw--w---- 1 kjb tty 4, 0 May 11 09:41 console +.if t .ft P +.fi +.RE +.PP +Most attributes are the same as for a regular file and have the same +function. The file type and the major and minor device numbers are special +to devices. +.PP +Character devices are marked with a +.B c +as a file type letter. Any I/O on a character device is sent down to the +device driver without any interpretation. This means that a process doing +the I/O must know the characteristics of the device and deal with them +appropriately. +.PP +Block devices provoke the file system server into buffering the data on +those devices. Data read or written by processes is passed through the file +system block cache. Unaligned bytes read or written are extracted or +reassembled by the file server from or to whole blocks in the cache. The +file server transfers data to or from the device driver as blocks to +positions at block size boundaries. These blocks are Minix blocks of 1024 +bytes, disk devices usually have a 512 byte block size. Only block devices +can be mounted as part of the file system tree if they contain a Minix file +system. +.PP +The major device number (2 for +.B fd1 +and 4 for +.BR console ) +are used by FS to find the device driver that manages a device. The minor +device number (1 for +.B fd1 +and 0 for +.BR console ) +is passed to the driver to select a device among a number of related devices +that are all managed by that driver. The device drivers are usually kernel +tasks under Minix, small processes that are contained within the address +space of the kernel. The following tasks and associated devices exist: +.SS "Memory (major 1)" +The +.BR ram , +.BR mem , +.BR kmem , +and +.BR null +devices are managed by the memory task. +The +.B ram +device is a block device for a chunk of memory that is the RAM disk. Any +byte read from or written to the +.B ram +device is copied from or to that memory chunk. +The +.B mem +device is a character device for the entire address space of the system, but +.B kmem +only for the kernel data area. These two devices allow programs like +.BR ps (1) +to hunt around the system looking for interesting bits. +The +.B null +device is a data sink. It happily swallows any bytes written to it, and +returns nothing on a read. +.SS "Floppy disk (major 2)" +The +.BR fd0 , +.BR fd0p0 , +.BR fd0p1 , +.BR fd0p2 , +and +.BR fd0p3 +block devices are the first floppy disk and the four partitions that may +exist on a that floppy disk. Likewise are +.BR fd1 +and +.BR fd1p[0\-3] +the device and partitions for the second floppy disk. The floppy disk +devices are described in detail in +.BR fd (4). +Partitioning in general is explained in +.BR controller (4). +.SS "Controller 0 (major 3)" +The first hard disk on controller 0 can be accessed by block device +.BR c0d0 . +This device addresses the entire hard disk from the first to the last +sector. A hard disk is normally partitioned in up to four primary +partitions, +.BR c0d0p0 , +.BR c0d0p1 , +.BR c0d0p2 , +and +.BR c0d0p3 . +Each of these devices accesses a range of sectors on the +.B c0d0 +device. It is customary to give each operating system on a disk a primary +partition. So the Windows C: "drive" can be on +.BR c0d0p0 , +and Minix can be on +.BR c0d0p1 . +Minix wants to have several partitions on its own, so +.B c0d0p1 +can be further subdivided into the subpartitions +.BR c0d0p1s0 , +.BR c0d0p1s1 , +.BR c0d0p1s2 , +and +.BR c0d0p1s3 . +.B /dev +contains devices for the first and second hard disk +.RB ( c0d0 +and +.BR c0d1 ), +their primary partitions +.RB ( c0d[01]p[0\-3] ) +and subpartitions thereof +.RB ( c0d[01]p[0\-3]s[0\-3] ). +More detail can be found in +.BR controller (4). +.SS "Terminals (minor 4)" +The TTY driver manages the system console device, aptly named +.BR console , +the serial lines, +.BR tty00 +and +.BR tty01 , +and the pseudo ttys. +Through the console device one can display characters on a screen attached +to a monochrome, Hercules, color, or VGA adapter. The +.BR ttyc1 , +.BR ttyc2 , +etc. devices are the so-called "virtual consoles" that share the one +console display. One can select which virtual console is to be visible on +the screen and take input from the keyboard. +To allow remote login the devices with minor numbers of 128 or higher offer +virtual terminals. These pseudo ttys come in tty, pty pairs that form a +pipe between processes running under the tty, and a controlling process +attached to the pty side. +See also +.BR console (4), +and +.BR tty (4). +.SS "Anonymous TTY (major 5)" +This is just one device named +.BR tty +that is a synonym for the controlling tty of a process. This device is not +managed by any device driver, but is handled by FS itself. A process can +get access to the terminal it is running under by using +.BR /dev/tty . +.SS "Line printer (major 6)" +The +.B lp +device sends any bytes written to it to the printer. +.SS "TCP/IP (major 7)" +The TCP/IP task is not a kernel task, but a server like MM and FS. It sits +between FS and the DP8390 task that manages the ethernet boards. Together +they implement the TCP/IP protocol. See also +.BR ip (4). +.SS "Controller 1 (major 8)" +Like controller 0 (major 3), but managing a second controller with devices +.BR /dev/c1* . +.SS "Controller 2 (major 10)" +Like controller 0. +.SS "Controller 3 (major 12)" +Like controller 0. +.SS "Audio (major 13)" +The +.B audio +device can be used to produce or record air vibrations using a Soundblaster +16 type audio card. See +.BR audio (4). +.SS "Mixer (major 14)" +The +.B mixer +device is used to control the audio driver. +.SH FILES +.TP 10 +.B /dev/* +All Minix devices +.SH "SEE ALSO" +.BR read (2), +.BR write (2), +.BR lseek (2), +.BR ioctl (2), +.BR console (4), +.BR fd (4), +.BR controller (4), +.BR ip (4), +.BR tty (4), +.BR MAKEDEV (8). +.SH DIAGNOSTICS +There are five prominent errors that processes accessing device files may +provoke: +.IP "ENODEV \- No such device" 5 +There is no driver managing the device class this device belongs to. Either +the driver is configured out, or it is not loaded (inet). +.IP "ENXIO \- No such device or address" +This device is not available. Either the driver does not support it at all, +or the hardware isn't available, i.e. accessing the second disk on a system +with only one disk. +.IP "EACCES \- Permission denied" +This error may cause a lot of head scratching if +.B ls \-l +shows a device file to be writable. The media you are trying to access is +simply physically write protected! +.IP "EINVAL \- Invalid argument" +Devices may not like reads or writes that are not block multiples, or very +big transfers, etc. The device manual page should list the limits. +.IP "EIO \- I/O error" +This may be a real I/O error, i.e. a read or write on the device failing due +to a media error. But it may also be the result of an operation that a +device can't do, or an empty tape drive, etc. +.SH NOTES +Some devices are not present by default. The +.BR MAKEDEV +script knows how to make them. +.SS "MS-DOS/Windows equivalents" +The names of MS-DOS/Windows devices probably map to Minix devices as follows: +.PP +.RS +.nf +.ta +\w'COM1mmm'u +\w'c0d1, c0d2, c0d3mmm'u +A: fd0 +B: fd1 +C: c0d0p0 (usually the first partition) +D: c0d1p0, c0d2p0 (if it's another disk) +D: c0d0p1s0 (if it's an extended partition) +D: c0d1, c0d2, c0d3 (if it's a CD-ROM) +CON console +COM1 tty00 (UNIX counts from 0) +LPT1 lp +.fi +.RE +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man4/fd.4 b/man/man4/fd.4 new file mode 100644 index 000000000..bec3231e5 --- /dev/null +++ b/man/man4/fd.4 @@ -0,0 +1,88 @@ +.TH FD 4 +.SH NAME +fd \- floppy disk +.SH DESCRIPTION +The +.B fd* +devices refer to the Floppy disk driver using the NEC PD765 floppy disk +controller. These diskettes are arrays of 512 byte sectors, although Minix +always works with two sectors at a time due to its 1024 byte block size. You +can read or write any number of bytes however, Minix takes care of cutting +and pasting incomplete blocks together. +.PP +The driver is normally configured for two floppy disk devices +.B fd0 +and +.BR fd1 . +It can handle two more, but it is unlikely that the average PC can. +.PP +On the first access to an +.B fd +device (by +.BR open (2) +or +.BR mount (2)), +the driver will execute a series of read tests to determine the floppy type. +This works ok for all floppy types except the true 360k type, because it +is indistinguishable from the 720k type. This only means that the size of +the floppy is not estimated right. +.PP +Bits 2\-6 of the minor device number may be set to the floppy disk type +to make it known to the driver what type of diskette it is reading or +writing. The non-auto devices should be used for formatting, or when one wants to +be absolutely sure that the device is accessed right. These devices exist for +drive 0: +.sp +.nf +.ta +4n +7n +9n +8n + type device minor media +.ta +5n +7n +9n +7n + 0 fd0 0 autodetect + 1 pc0 4 360k, 5.25" + 2 at0 8 1.2M, 5.25" + 3 qd0 12 360k in a 720k, 5.25" drive + 4 ps0 16 720k, 3.5" + 5 pat0 20 360k in a 1.2M, 5.25" drive + 6 qh0 24 720k in a 1.2M, 5.25" drive + 7 PS0 28 1.44M, 3.5" +.fi +.DT +.PP +Type 4 may also be used for the rarely seen 720k, 5.25" floppies (type 2 made +them obsolete fast.) Note that these "types" only describe the floppies from +a software point of view, type 1 and 4 drives use the same parameters. +.PP +If the format bit (bit 7) is set, then the driver interprets write commands +as track formatting requests. This is used by the +.BR format (1) +command. +.PP +If the type bits are set to 28, 29, 30, or 31, then the driver uses a +partition table found in sector 0 to partition the floppy. The partitions +of +.B fd0 +may be accessed as +.B fd0p0 +through +.BR fd0p3 . +See +.BR controller (4) +for a description of the partition table, and associated ioctl commands. +.SH FILES +/dev/fd[0\-3], /dev/pc[0\-3], /dev/at[0\-3], /dev/qd[0\-3], /dev/ps[0\-3], +/dev/pat[0\-3], /dev/qh[0\-3], /dev/PS[0\-3], /dev/fd[0\-3]p[0\-3] +.SH "SEE ALSO" +.BR format (1), +.BR controller (4), +.BR part (8). +.SH BUGS +The driver does not know the size of a 360k diskette in a 360k 5.25" +drive, because it uses the 720k parameters for it. So it will happily try +to read past the end making all kinds of interesting noises. It's a good +thing these drives are practically obsolete. +.PP +The partition table is only read when the drive motor is off and only for +an auto or partition device. The driver assumes that a floppy in a drive +with a running motor can't have been replaced all of a sudden. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man4/ip.4 b/man/man4/ip.4 new file mode 100644 index 000000000..9b1efea98 --- /dev/null +++ b/man/man4/ip.4 @@ -0,0 +1,1466 @@ +.\" +.\" Copyright 1994 Vrije Universiteit, The Netherlands. +.\" For full copyright and restrictions on use see the file COPYRIGHT in the +.\" top level of the Amoeba distribution. +.\" +.ig + Software: Philip Homburg, 1991 + Document: Philip Homburg, Sept 3, 1991 + Modified: Greg Sharp and Philip Homburg, March 1992 + - merged with udp(L) and made a little more complete. + Greg Sharp, April 1992 + - updated keywords for auto index generation + Modified: Kees J. Bot, June 1994 + - changed to man(7) format for Minix. +.. +.TH IP 4 +.SH NAME +ip, eth, psip, udp, tcp \- Internet Protocol server devices and definitions +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The +.BR ip* , +.BR eth* , +.BR psip* , +.BR tcp* , +and +.B udp* +devices give access to the Internet Protocol (IP) services in Minix. +There can be up to 16 different networks, with 4 network devices each +(a network has either an +.B eth* +or a +.B psip* +device, not both.) +The +.B * +in the device names is a decimal number, so one may see names from +.B ip0 +to +.BR ip15 . +A program scanning all networks must try all 16, and not stop if one in +between is missing. One network is the default network. Its devices are +linked to names without numbers. +.PP +The +.B eth* +and +.B psip* +devices give direct access to the network packets at the lowest level. +The +.BR ip* , +.BR tcp* , +and +.B udp* +devices give access to IP, TCP, or UDP services. +.PP +Most programs that use TCP/IP use code like the following to access the +proper devices: +.PP +.RS +.nf +if ((tcp_device= getenv("TCP_DEVICE")) == NULL) + tcp_device= "/dev/tcp"; +.fi +.RE +.PP +The low level networking programs such as +.BR ifconfig (8) +also have options to select the device they are working with. The +convention is: +.PP +.RS +.BI ETH_DEVICE= device +.br +.BI -E " device" +.RS +Device to use as raw ethernet device instead of the default /dev/eth. +.RE +.SP +.BI PSIP_DEVICE= device +.br +.BI -P " device" +.RS +Pseudo IP device to use instead of +.BR /dev/psip . +.RE +.SP +.BI IP_DEVICE= device +.br +.BI -I " device" +.RS +IP device to use instead of +.BR /dev/ip . +.RE +.SP +.BI TCP_DEVICE= device +.br +.BI -T " device" +.RS +TCP device to use instead of +.BR /dev/tcp . +.RE +.SP +.BI UDP_DEVICE= device +.br +.BI -U " device" +.RS +UDP device to use instead of +.BR /dev/udp . +.RE +.RE +.SS Programming +Access to the IP services is provided using filedescriptors to open IP +devices. These open IP channels can be configured with +.BR ioctl (2) +calls, and data can be transferred by calls to +.BR read (2), +and +.BR write (2). +.SS "Types (general)" +.IP +.br +Defines +.BR u8_t , +.BR u16_t , +.B u32_t +and +.B i32_t +(and +.BR U8_t , +.BR U16_t , +.B U32_t +and +.B I32_t +for use in prototypes). +.SS "Types (eth)" +.IP +.br +Defines struct ether_addr (\fBether_addr_t\fP) and +.B ether_type_t +and +.B Ether_type_t +for use in prototypes. +.IP +.br +Defines struct nwio_ethopt (\fBnwio_ethopt_t\fP) and +struct nwio_ethstat (\fBnwio_ethstat_t\fP) +.IP +.br +Defines struct eth_hdr (\fBeth_hdr_t\fP) +.SS "Types (psip)" +.IP +.br +[[[No description available yet.]]] +.IP +.br +[[[No description available yet.]]] +.SS "Types (ip)" +.IP +.br +Defines +.BR ipaddr_t , +.BR ipproto_t +and struct ip_hdropt (\fBip_hdropt_t\fP). +.IP +.br +Defines struct nwio_ipconf (\fBnwio_ipconf_t\fP) and +struct nwio_ipopt (\fBnwio_ipopt_t\fP) +.IP +.br +Defines struct ip_hdr (\fBip_hdr_t\fP) +.IP +.br +Defines struct nwio_route (\fBnwio_route_t\fP) +.SS "Types (tcp)" +.IP +.br +Defines +.B tcpport_t +and +.B Tcpport_t +for use in prototypes. +.IP +.br +Defines struct nwio_tcpconf (\fBnwio_tcpconf_t\fP), +struct nwio_tcpcl (\fBnwio_tcpcl_t\fP), +struct nwio_tcpatt (\fBnwio_tcpatt_t\fP) and +struct nwio_tcpopt (\fBnwio_tcpopt_t\fP). +.IP +.br +Defines struct tcp_hdr (\fBtcp_hdr_t\fP) and struct tcp_hdropt +(\fBtcp_hdropt_t\fP). +.SS "Types (udp)" +.IP +.br +Defines +.B udpport_t +and +.B Udpport_t +for use in prototypes. +.IP +.br +Defines struct nwio_udpopt (\fBnwio_udpopt_t\fP). +.IP +.br +Defines struct udp_hdr (\fBudp_hdr_t\fP) and struct udp_io_hdr +(\fBudp_io_hdr_t\fP). +.SS "Byte Order Conversion" +All 16-bit and 32-bit quantities in IP headers must be in network byte +order. The macros described in +.BR hton (3) +can be used to convert these values to and from the byte order used by +the host machine. +.SS "The Internet Checksum" +The +.B oneC_sum +function (see +.BR oneC_sum (3)) +is used to calculate the one's complement checksum needed for IP network +packets. +.SS "General Functions" +.PP +.ft B +\fIfd\fP = open(\fItcpip_device\fP, O_RDWR) +.ft R +.PP +This is how one normally obtains a filedescriptor for a new TCP/IP channel. +.I tcpip_device +names one of the TCP/IP devices. The channel may be used both to send or to +receive data. +.PP +.ft B +\fIn\fP = read(\fIfd\fP, \fIbuf\fP, \fIsize\fP) +.ft R +.PP +Receives one packet (low level devices) or a number of bytes (TCP stream). +Returns the the number of bytes placed into +.IR buf , +or returns -1 with an error code placed into +.BR errno . +.PP +.ft B +\fIn\fP = write(\fIfd\fP, \fIbuf\fP, \fIsize\fP) +.ft R +.PP +Sends one packet (low level devices) or a number of bytes (TCP stream). +Returns +.I size +or -1 with the error code placed into +.BR errno . +The TCP/IP +.B read +and +.B write +functions behave like reads and writes on pipes when it comes to signals. +.SS "ETH Functions" +.PP +.ft B +ioctl(\fIfd\fP, NWIOGETHSTAT, &struct nwio_ethstat) +.ft R +.PP +The +.B NWIOGETHSTAT +ioctl +returns the Ethernet address and some statistics of the Ethernet server of +the channel +.IR fd . +The result is returned in the nwio_ethstat structure. +The \fBstruct nwio_ethstat\fP is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_ethstat +{ + ether_addr_t nwes_addr; + eth_stat_t nwes_stat; +} nwio_ethstat_t; +.SP +typedef struct eth_stat +{ + unsigned long ets_recvErr, /* # receive errors */ + ets_sendErr, /* # send error */ + ets_OVW, /* # buffer overwrite warnings, + (packets arrive faster than + can be processed) */ + ets_CRCerr, /* # crc errors of read */ + ets_frameAll, /* # frames not aligned (# bits + not a multiple of 8) */ + ets_missedP, /* # packets missed due to too + slow packet processing */ + ets_packetR, /* # packets received */ + ets_packetT, /* # packets transmitted */ + ets_transDef, /* # transmission deferred (there + was a transmission of an + other station in progress */ + ets_collision, /* # collisions */ + ets_transAb, /* # transmissions aborted due + to excessive collisions */ + ets_carrSense, /* # carrier sense lost */ + ets_fifoUnder, /* # fifo underruns (processor + is too busy) */ + ets_fifoOver, /* # fifo overruns (processor is + too busy) */ + ets_CDheartbeat, /* # times unable to transmit + collision signal */ + ets_OWC; /* # times out of window + collision */ +} eth_stat_t; +.if t .ft R +.fi +.RE +.PP +.ft B +ioctl(\fIfd\fP, NWIOSETHOPT, &struct nwio_ethopt) +.ft R +.PP +Before an Ethernet channel can be used to send or receive +Ethernet packets, it has to be configured using the +.B NWIOSETHOPT +ioctl. +The structure +.B nwio_ethopt +is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_ethopt +{ + u32_t nweo_flags; + ether_addr_t nweo_multi, nweo_rem; + ether_type_t nweo_type; +} nwio_ethopt_t; +.SP +#define NWEO_NOFLAGS 0x0000L +#define NWEO_ACC_MASK 0x0003L +# define NWEO_EXCL 0x00000001L +# define NWEO_SHARED 0x00000002L +# define NWEO_COPY 0x00000003L +#define NWEO_LOC_MASK 0x0010L +# define NWEO_EN_LOC 0x00000010L +# define NWEO_DI_LOC 0x00100000L +#define NWEO_BROAD_MASK 0x0020L +# define NWEO_EN_BROAD 0x00000020L +# define NWEO_DI_BROAD 0x00200000L +#define NWEO_MULTI_MASK 0x0040L +# define NWEO_EN_MULTI 0x00000040L +# define NWEO_DI_MULTI 0x00400000L +#define NWEO_PROMISC_MASK 0x0080L +# define NWEO_EN_PROMISC 0x00000080L +# define NWEO_DI_PROMISC 0x00800000L +#define NWEO_REM_MASK 0x0100L +# define NWEO_REMSPEC 0x00000100L +# define NWEO_REMANY 0x01000000L +#define NWEO_TYPE_MASK 0x0200L +# define NWEO_TYPESPEC 0x00000200L +# define NWEO_TYPEANY 0x02000000L +#define NWEO_RW_MASK 0x1000L +# define NWEO_RWDATONLY 0x00001000L +# define NWEO_RWDATALL 0x10000000L +.if t .ft R +.fi +.RE +.PP +The configuration is divided in a number of section (covered by the xx_MASK +macros). +Options can be set in the +.B nweo_flags +field. +The first section (\fBNWEO_ACC_MASK\fP) controls the access to a certain +Ethernet packet type. +If +.B NWEO_EXCL +is selected then this is the only channel that can send or +receive Ethernet packets of the selected type. +If +.B NWEO_SHARED +is selected then multiple channels (which all have to +select +.BR NWEO_SHARED ) +can use the same Ethernet type, they all can send +packets but incoming packets will be delivered to at most one of them. +If +.B NWEO_COPY +is selected then multiple channels have access to the same +Ethernet type and all receive a copy of an incoming packet. +.LP +The +.B NWEO_LOC_MASK +flags control the delivery of packets with a destination +address equal to the Ethernet address of the machine. +If +.B NWEO_EN_LOC +is selected then these packets will be delivered and with +.B NWEO_DI_LOC +they will be discarded. +.PP +.BR NWEO_BROAD_MASK , +.BR NWEO_MULTI_MASK , +and +.B NWEO_PROMISC_MASK +do the same to broadcast packets, +multicast packets and promiscuous mode packets as +.B NWEO_LOC_MASK +does for local packets. +Except that the precise multicast address is taken from the \fBnweo_multi\fP +field. +.LP +The +.B NWEO_REM_MASK +flags control whether communication is restricted to +single destination or not. +.B NWEO_REMSPEC +restricts sending and receiving of packets to the single +remote computer specified in the \fBnweo_rem\fP field. +.B NWEO_REMANY +allows sending to and receiving from any remote computer. +.PP +.B NWEO_TYPESPEC +restricts sending and receiving of packets to the type +specified in \fBnweo_type\fP. +The type has to be in network byte order (using +.BR hton (3)). +.B NWEO_TYPEANY +allows any type. +.PP +If the Ethernet header is completely specified by the +.B nweo_flags +i.e., all of +.BR NWEO_EN_LOC , +.BR NWEO_DI_BROAD , +.BR NWEO_DI_MULTI , +.BR NWEO_DI_PROMISC , +.BR NWEO_REMSPEC +and +.B NWEO_TYPESPEC +are +specified, then +.B NWEO_RWDATONLY +can be used to send and receive only the data part of an Ethernet packet. +If +.B NWEO_RWDATALL +is specified then both Ethernet header and data are used. +.SS "PSIP Functions" +.PP +[[[No description available yet.]]] +.SS "IP Functions" +.PP +.ft B +ioctl(\fIfd\fP, NWIOGIPCONF, &struct nwio_ipconf) +.ft R +.PP +The +.B NWIOGIPCONF +ioctl reports the Internet Address and the netmask. +For the \fInwio_ipconf\fP structure see the \fBNWIOSIPCONF\fP ioctl below. +.PP +.ft B +ioctl(\fIfd\fP, NWIOGIPOROUTE, &struct nwio_route) +.ft R +.PP +The +.B NWIOGIPOROUTE +ioctl can be used to query an IP server about its routing table. +[[[NWIODIPOROUTE, NWIOGIPIROUTE, NWIODIPIROUTE?]]] +The structure \fBnwio_route\fP is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_route +{ + u32_t nwr_ent_no; + u32_t nwr_ent_count; + ipaddr_t nwr_dest; + ipaddr_t nwr_netmask; + ipaddr_t nwr_gateway; + u32_t nwr_dist; + u32_t nwr_flags; + u32_t nwr_pref; +} nwio_route_t; +.SP +#define NWRF_EMPTY 0 +#define NWRF_INUSE 1 +#define NWRF_FIXED 2 +.if t .ft R +.fi +.RE +.PP +The requested entry is taken from \fBnwr_ent_no\fP. +Entries are counted from 0, so the value 0 can be used for an initial query. +The size of the routing table is returned in \fBnwr_ent_count\fP. +The \fBnwr_flags\fP indicates if the entry is in use (\fBNWRF_INUSE\fP) and +if the entry was inserted manually (using \fBNWIOSIPOROUTE\fP) or generated +by the IP server itself. +The route is described by +.BR nwr_dest , +.BR nwr_netmask , +.BR nwr_gateway , +.BR nwr_dist , +and +.BR nwr_pref . +\fBNwr_dest\fP and \fBnwr_netmask\fP select the destination addresses. +A value of 0.0.0.0 (0x0) in both \fBnwr_dest\fP and \fBnwr_netmask\fP means +every host. +A value of 255.255.255.255 (0xffffffff) in \fBnwr_netmask\fP means a single +host. +Other values of \fBnwr_netmask\fP are netmasks for the network specified +by \fBnwr_dest\fP. +\fBNwr_gateway\fP is gateway that should be used. +\fBNwr_dist\fP is a minimal distance. +Packets with a time to live smaller than \fBnwr_dist\fP will not reach the +destination. +If two routes have equal netmask and distance fields but different +gateways then the gateway with highest value in \fBnwr_pref\fP is used. +.PP +.ft B +ioctl(\fIfd\fP, NWIOSIPCONF, &struct nwio_ipconf) +.ft R +.PP +The +.B NWIOSIPCONF +ioctl can be used to inform the IP server about its Internet Address +and/or its netmask. +Normally an IP server will discover its Internet Address using the RARP +protocol. +.B NWIOSIPCONF +can be used in the case that the RARP failed, or the netmask has to be changed. +Note that higher level protocols (TCP and UDP) assume that the Internet Address +of an IP device does not change, therefore TCP and UDP stop functioning if +the Internet Address is changed. +.PP +The structure \fBnwio_ipconf\fP is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_ipconf +{ + u32_t nwic_flags; + ipaddr_t nwic_ipaddr; + ipaddr_t nwic_netmask; +} nwio_ipconf_t; +.SP +#define NWIC_NOFLAGS 0x0 +#define NWIC_FLAGS 0x3 +# define NWIC_IPADDR_SET 0x1 +# define NWIC_NETMASK_SET 0x2 +.if t .ft R +.fi +.RE +.PP +The function of \fBnwio_ipconf\fP depends on the value of \fBnwic_flags\fP. +If +.B NWIC_IPADDR_SET +is set then the Internet Address will be set to +\fBnwic_ipaddr\fP. +If +.B NWIC_NETMASK_SET +is set then the Internet Address will be set to +\fBnwic_netmask\fP. +.PP +.ft B +ioctl(\fIfd\fP, NWIOSIPOPT, &struct nwio_ipopt) +.ft R +.PP +Before an IP channel can be used, it has to be configured using the +.B NWIOSIPOPT +ioctl. +The structure \fBnwio_ipopt\fP is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_ipopt +{ + u32_t nwio_flags; + ipaddr_t nwio_rem; + ip_hdropt_t nwio_hdropt; + u8_t nwio_tos; + u8_t nwio_ttl; + u8_t nwio_df; + ipproto_t nwio_proto; +} nwio_ipopt_t; +.SP +#define NWIO_NOFLAGS 0x0000L +#define NWIO_ACC_MASK 0x0003L +# define NWIO_EXCL 0x00000001L +# define NWIO_SHARED 0x00000002L +# define NWIO_COPY 0x00000003L +#define NWIO_LOC_MASK 0x0010L +# define NWIO_EN_LOC 0x00000010L +# define NWIO_DI_LOC 0x00100000L +#define NWIO_BROAD_MASK 0x0020L +# define NWIO_EN_BROAD 0x00000020L +# define NWIO_DI_BROAD 0x00200000L +#define NWIO_REM_MASK 0x0100L +# define NWIO_REMSPEC 0x00000100L +# define NWIO_REMANY 0x01000000L +#define NWIO_PROTO_MASK 0x0200L +# define NWIO_PROTOSPEC 0x00000200L +# define NWIO_PROTOANY 0x02000000L +#define NWIO_HDR_O_MASK 0x0400L +# define NWIO_HDR_O_SPEC 0x00000400L +# define NWIO_HDR_O_ANY 0x04000000L +#define NWIO_RW_MASK 0x1000L +# define NWIO_RWDATONLY 0x00001000L +# define NWIO_RWDATALL 0x10000000L +.if t .ft R +.fi +.RE +.PP +The options are divided in several categories: +.BR NWIO_ACC_MASK , +.BR NWIO_LOC_MASK , +.BR NWIO_BROAD_MASK , +.BR NWIO_REM_MASK , +.BR NWIO_PROTO_MASK , +.B NWIO_HDR_O_MASK +and +.BR NWIO_RW_MASK . +A channel is configured when one option of each category is set. +.PP +The options covered by +.B NWIO_ACC_MASK +control the number of channels that +can use one IP protocol. +If +.B NWIO_EXCL +is specified then only that channel can use a certain IP protocol. +If +.B NWIO_SHARED +then multiple channels that all have to specify +.B NWIO_SHARED +can use the same IP protocol, but incoming packets will +be delivered to a most one channel. +.B NWIO_COPY +does not impose any restrictions. +Every channel gets a copy of an incoming packet. +.PP +.B NWIO_LOC_MASK +and +.B NWIO_BROAD_MASK +control the delivery of packets. +If +.B NWIO_EN_LOC +is specified then packets that are explicitly send to +the IP server are delivered. +If +.B NWIO_EN_BROAD +is specified then broadcast packets are delivered. +Either one or both of them can be disabled with +.B NWIO_DI_LOC +and +.BR NWIO_DI_BROAD . +.PP +.B NWIO_REMSPEC +can be used to restrict communication to one remote host. +This host is taken from the \fBnwio_rem\fP field. +If any remote host is to be allowed then +.B NWIO_REMANY +can be used. +.PP +.B NWIO_PROTOSPEC +restricts communication to one IP protocol, specified +in \fBnwio_proto\fP. +.B NWIO_PROTOANY +allows any protocol to be sent or received. +.PP +.B NWIO_HDR_O_SPEC +specifies all IP header options in advance. +The values are taken from +.BR nwio_hdropt , +.BR nwio_tos , +.BR nwio_ttl , +and +.BR nwio_df . +\fBNwio_hdropt\fP specifies the IP options that should be present in an +outgoing packet. +\fBIp_hdropt_t\fP is defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct ip_hdropt +{ + u8_t iho_opt_siz; + u8_t iho_data[IP_MAX_HDR_SIZE-IP_MIN_HDR_SIZE]; +} ip_hdropt_t; +.if t .ft R +.fi +.RE +.PP +The bytes of size \fBiho_opt_siz\fP in \fBiho_data\fP are appended to the IP +header. +\fBNwio_tos\fP specifies the value of the ``type of service'' bits, +\fBnwio_ttl\fP gives the value of the ``time to live'' field and \fBnwio_df\fP +specifies whether fragmentation is disallowed or not. +.B NWIO_HDR_O_ANY +specifies that the header options should be specified at +each write request. +.PP +.B NWIO_RWDATONLY +specifies that the header should be omitted from a +write request. +This option can only be used when all header fields are specified in previous +options: +.BR NWIO_EN_LOC , +.BR NWIO_DI_BROAD , +.BR NWIO_REMSPEC , +.B NWIO_PROTOSPEC +and +.BR NWIO_HDR_O_SPEC . +A read operation will also only return the data part, so the IP options will +be lost. +.PP +.ft B +ioctl(\fIfd\fP, NWIOSIPOROUTE, &struct nwio_route) +.ft R +.PP +The +.B NWIOSIPOROUTE +ioctl adds a route to the routing table. +See \fBNWIOGIPOROUTE\fP above for a description of the \fBnwio_route\fP +structure. +The fields \fBnwr_ent_no\fP and \fBnwr_ent_count\fP are ignored. +.SS "TCP Functions" +.PP +.ft B +ioctl(\fIfd\fP, NWIOTCPCONN, &struct nwio_tcpcl) +.ft R +.PP +The +.B NWIOTCPCONN +ioctl tries to setup a connection with a remote TCP/IP server. +The channel must be fully configured (see +.BR NWIOSTCPCONF ) +and values for the local port, the remote port and the remote address have be +specified using +.B NWTC_LP_SET +or +.BR NWTC_LP_SEL , +.B NWTC_SET_RA +and +.BR NWTC_SET_RP . +The struct nwio_tcpcl is defined in as: +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_tcpcl +{ + long nwtcl_flags; + long nwtcl_ttl; +} nwio_tcpcl_t; +.if t .ft R +.fi +.RE +.PP +Set the +.B nwtcl_flags +field to zero before the connect or listen call. [[[Further explanation of +nwio_tcpcl?]]] +.PP +.ft B +ioctl(\fIfd\fP, NWIOGTCPCONF, &struct nwio_tcpconf) +.ft R +.PP +This call reports the current configuration of a TCP channel. +The +.B nwtc_flags +field shows the status of the +.BR access , +.BR locport , +.B remaddr +and +.B remport +fields. +.B Nwtc_locaddr +contains the Internet address of the TCP/IP server. +.B Remaddr +contains the Internet address of the remote TCP/IP server when set with +.B NWTC_SET_RA +or after a successful connect or listen (see +.B NWIOTCPCONN +or +.BR NWIOTCPLISTEN ). +.B Nwio_locport +contains the local TCP/IP port set with +.B NWTC_LP_SET +or the selected port set with +.BR NWTC_LP_SEL . +.B Nwtc_remport +contains the TCP port of the remote TCP/IP server as set with +.B NWIO_SET_RP +or after a successful connect or listen. +.PP +A value of 0 (zero) is reported for +.BR nwtc_remaddr , +.B nwtc_locport +or +.B nwtc_remport +when no value is set either explicitly or implicitly. +.PP +.ft B +ioctl(\fIfd\fP, NWIOTCPLISTEN, &struct nwio_tcpcl) +.ft R +.PP +The +.B NWIOTCPLISTEN +ioctl waits until a remote TCP/IP server tries to connect to this channel. +The channel has to be configured (see +.BR NWIOSTCPCONF ). +An additional restriction is that the local port +must be set (with +.BR NWTC_LP_SET ) +or selected (with +.BR NWTC_LP_SEL ). +When a remote address is set only connections for that host are accepted, and +when a remote port is set only connections from that port are accepted. +After a successful listen +.B NWIOGTCPCONF +can be used to find out what the address and port of the other side are. +.PP +.ft B +ioctl(\fIfd\fP, NWIOSTCPCONF, &struct nwio_tcpconf) +.ft R +.PP +Before a TCP channel can be used it must configured using the +.B NWIOSTCPCONF +ioctl. +The parameters to +.B NWIOSTCPCONF +are the channel file descriptor and a +.B struct nwio_tcpconf +as defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_tcpconf +{ + u32_t nwtc_flags; + ipaddr_t nwtc_locaddr; + ipaddr_t nwtc_remaddr; + tcpport_t nwtc_locport; + tcpport_t nwtc_remport; +} nwio_tcpconf_t; +.SP +#define NWTC_NOFLAGS 0x0000L +#define NWTC_ACC_MASK 0x0003L +# define NWTC_EXCL 0x00000001L +# define NWTC_SHARED 0x00000002L +# define NWTC_COPY 0x00000003L +#define NWTC_LOCPORT_MASK 0x0030L +# define NWTC_LP_UNSET 0x00000010L +# define NWTC_LP_SET 0x00000020L +# define NWTC_LP_SEL 0x00000030L +#define NWTC_REMADDR_MASK 0x0100L +# define NWTC_SET_RA 0x00000100L +# define NWTC_UNSET_RA 0x01000000L +#define NWTC_REMPORT_MASK 0x0200L +# define NWTC_SET_RP 0x00000200L +# define NWTC_UNSET_RP 0x02000000L +.if t .ft R +.fi +.RE +.PP +A tcp channel is considered configured when one flag in each category has +been selected. +Thus one of +.BR NWTC_EXCL , +.B NWTC_SHARED +or +.BR NWTC_COPY , +one of +.BR NWTC_LP_UNSET , +.B NWTC_LP_SET +or +.BR NWTC_LP_SEL , +one of +.B NWTC_SET_RA +or +.BR NWTC_UNSET_RA , +and one of +.B NWTC_SET_RP +or +.BR NWTC_UNSET_RP . +.PP +The acc flags control the access to a certain TCP port. +.B NWTC_EXCL +means exclusive access. +An attempt to configure a channel will be denied if the same port is specified +as that of a channel that requested exclusive access. +.B NWTC_SHARED +indicates that several channels use the same port but cooperate. +If the shared mode is specified for one channel than all other channel that +use the same port should also be configured with the +.B NWTC_SHARED +flag. +.B NWTC_COPY +is specified when the programmer does not care about other channels. +This is the default. +.PP +The locport flags control which TCP port is used for communication. +.B NWTC_LP_UNSET +indicates the absence of a local port. +This is the default. +.B NWTC_LP_SET +means that the +.B nwtc_locport +field contains the local port to be used by TCP. +This value must be in network byte order (see +.BR hton (3).) +.B NWTC_LP_SEL +requests the TCP server to pick a port. +This port will be in the range from 32768 to 65535 and will be unique. +.LP +The +.B remaddr +flags specify which hosts are acceptable for connections. +.B NWTC_SET_RA +indicates that only connection to the host specified in +.B nwtc_remaddr +are acceptable. +.B Nwtc_remaddr +should be in network byte order (see +.BR hton (3).) +.B NWTC_UNSET_RA +allows every host on the other side of a connection. +This is the default. +.PP +The +.B remport +flags specify which remote ports are acceptable for connections. +.B NWTC_SET_RP +indicates that only the port specified in +.B nwtc_remport +is acceptable. +.B NWTC_UNSET_RP +allows every port on the other side of a connection. +This is the default. +.PP +.ft B +ioctl(\fIfd\fP, NWIOTCPSHUTDOWN) +.ft R +.PP +The +.B NWIOTCPSHUTDOWN +tells the TCP/IP server that no more data will be sent over the channel +specified by +.IR fd . +This command can be issued when the channel is connected to a remote TCP/IP +server. +The TCP/IP server will tell the remote TCP/IP server and the client of the +remote TCP/IP server will receive an end-of-file indication. +.PP +.ft B +ioctl(\fIfd\fP, NWIOGTCPOPT, &struct nwio_tcpopt) +.br +ioctl(\fIfd\fP, NWIOSTCPOPT, &struct nwio_tcpopt) +.ft R +.PP +The behaviour of a TCP channel may be changed by setting a number of +options. The TCP options can be obtained with the +.B NWIOGTCPOPT +ioctl and set with the +.B NWIOSTCPOPT +ioctl. The options are passed in a +.B struct nwio_tcpopt +as defined in : +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_tcpopt +{ + u32_t nwto_flags; +} nwio_tcpopt_t; +.SP +#define NWTO_NOFLAG 0x0000L +#define NWTO_SND_URG_MASK 0x0001L +# define NWTO_SND_URG 0x00000001L +# define NWTO_SND_NOTURG 0x00010000L +#define NWTO_RCV_URG_MASK 0x0002L +# define NWTO_RCV_URG 0x00000002L +# define NWTO_RCV_NOTURG 0x00020000L +#define NWTO_BSD_URG_MASK 0x0004L +# define NWTO_BSD_URG 0x00000004L +#define NWTO_DEL_RST_MASK 0x0008L +# define NWTO_DEL_RST 0x00000008L +.if t .ft R +.fi +.RE +.PP +The +.B NWTO_SND_URG +option causes bytes written to the channel to be send out as urgent data. +On receiving an +.B EURG +error the +.B NWTO_RCV_URG +option must be set to switch over to reading urgent data. When all urgent +data has been read an +.B ENOURG +error will follow, +indicating that the option must be cleared with +.BR NWTO_RCV_NOTURG . +Alas the BSD implementation of urgent data disagrees with the RFC's, so to +be BSD compatible one must set the +.B NWTO_BSD_URG +option beforehand on a channel that is to send or receive urgent data. +Given that the BSD implementation is the regarded as the TCP/IP standard one +should always use the BSD style. The +.B NWTO_DEL_RST +option delays a failure response on a connect to the same port as the +current open connection. Without this option a connect would fail if +a server is not yet listening. With this option a connect will linger +on until the server starts listening. This option is useful for a server +that opens a connection, tells the remote end the local port number and +then listens (FTP), or for a program that forks off servers for incoming +connections (TELNET). A new connection may come in before a new listen +can be started, so it is nice if the new connect doesn't fail. Use this +option only when it is clearly needed. +.SS "UDP Functions" +.PP +.ft B +ioctl(\fIfd\fP, NWIOGUDPOPT, &struct nwio_udpopt) +.ft R +.PP +The +.B NWIOGUDPOPT +ioctl returns the current options that result from the default options +and the options set with +.BR NWIOSUDPOPT . +When +.B NWUO_LP_SEL +or +.B NWUO_LP_SET +is selected the local port is returned in +.BR nwuo_locport . +When +.B NWUO_RP_SET +is selected the remote port is returned in +.BR nwuo_remport . +The local address is always returned in +.BR nwuo_locaddr , +and when +.B NWUO_RA_SET +is selected the remote address is returned in +.BR nwuo_remaddr . +.PP +.ft B +ioctl(\fIfd\fP, NWIOSUDPOPT, &struct nwio_udpopt) +.ft R +.PP +A UDP channel must be configured using the +.B NWIOSUDPOPT +ioctl before any data can be read or written. +.B NWIOSUDPOPT +takes two parameters, a file descriptor to an open UDP device and +pointer to a +.B nwio_udpopt +structure that describes the requested configuration. +The +.B nwio_udpopt +structure is defined in as: +.PP +.RS +.nf +.if t .ft C +typedef struct nwio_udpopt +{ + unsigned long nwuo_flags; + udpport_t nwuo_locport; + udpport_t nwuo_remport; + ipaddr_t nwuo_locaddr; + ipaddr_t nwuo_remaddr; +} nwio_udpopt_t; +.SP +#define NWUO_NOFLAGS 0x0000L +#define NWUO_ACC_MASK 0x0003L +#define NWUO_EXCL 0x00000001L +#define NWUO_SHARED 0x00000002L +#define NWUO_COPY 0x00000003L +#define NWUO_LOCPORT_MASK 0x000CL +#define NWUO_LP_SEL 0x00000004L +#define NWUO_LP_SET 0x00000008L +#define NWUO_LP_ANY 0x0000000CL +#define NWUO_LOCADDR_MASK 0x0010L +#define NWUO_EN_LOC 0x00000010L +#define NWUO_DI_LOC 0x00100000L +#define NWUO_BROAD_MASK 0x0020L +#define NWUO_EN_BROAD 0x00000020L +#define NWUO_DI_BROAD 0x00200000L +#define NWUO_REMPORT_MASK 0x0100L +#define NWUO_RP_SET 0x00000100L +#define NWUO_RP_ANY 0x01000000L +#define NWUO_REMADDR_MASK 0x0200L +#define NWUO_RA_SET 0x00000200L +#define NWUO_RA_ANY 0x02000000L +#define NWUO_RW_MASK 0x1000L +#define NWUO_RWDATONLY 0x00001000L +#define NWUO_RWDATALL 0x10000000L +#define NWUO_IPOPT_MASK 0x2000L +#define NWUO_EN_IPOPT 0x00002000L +#define NWUO_DI_IPOPT 0x20000000L +.if t .ft R +.fi +.RE +.PP +A UDP channel is considered configured when one flag in each category has been +selected. +Thus one of +.BR NWUO_EXCL , +.B NWUO_SHARED +or +.BR NWUO_COPY , +one of +.BR NWUO_LP_SEL , +.B NWUO_LP_SET +or +.BR NWUO_LP_ANY , +one of +.B NWUO_EN_LOC +or +.BR NWUO_DI_LOC , +one of +.BR NWUO_EN_BROAD , +or +.BR NWUO_DI_BROAD , +one of +.BR NWUO_RP_SET , +or +.BR NWUO_RP_ANY , +one of +.BR NWUO_RA_SET , +or +.BR NWUO_RA_ANY , +one of +.BR NWUO_RWDATONLY , +or +.BR NWUO_RWDATALL , +and one of +.BR NWUO_EN_IPOPT , +or +.BR NWUO_DI_IPOPT . +The acc flags control the access to a certain UDP port. +.B NWUO_EXCL +means exclusive access: +no other channel can use this port. +.B NWUO_SHARED +means shared access: +only channels that specify shared access can use this port +and all packets that are received are handed to at most one channel. +.B NWUO_COPY +imposes no access restriction and all channels get a copy of every received +packet for that port. +.PP +The +.B locport +flags control the selection of the UDP port for this channel. +.B NWUO_LP_SEL +requests the server to pick a port. +This port will be in the range from 32768 to 65535 and it will be unique. +.B NWUO_LP_SET +sets the local port to the value of the +.B nwuo_locport +field. +.B NWUO_LP_ANY +does not select a port. +Reception of data is therefore not possible but it is +possible to send data. +.PP +The +.B locaddr +flags control the reception of packets. +.B NWUO_EN_LOC +enables the reception of packets with the local IP address as destination. +.B NWUO_DI_LOC +disables the reception of packet for the local IP address. +.PP +The +.B broad +flags control the reception of broadcast packets. +.B NWUO_EN_BROAD +enables the reception of broadcast packets and +.B NWUO_DI_BROAD +disables the reception of broadcast packets. +.PP +The +.B remport +flags let the client to specify one specific remote UDP port or +to allow any remote port. +.B NWUO_RP_SET +sets the remote UDP port to the value of +.BR nwuo_remport . +Only packets with a matching remote port will be delivered +and all packets will be sent to that port. +.B NWUO_RP_ANY +allows reception of packets form any port and when transmitting packets the +remote port has to be specified. +.PP +The +.B remaddr +flags control the remote IP address. +.B NWUO_RA_SET +sets the remote IP address the value of +.BR nwuo_remaddr . +Only packets from that address will be delivered and all packets will be sent +to that address. +.B NWUO_RA_ANY +allows reception of packets from any host and when transmitting packets the +remote host has to be specified. +.PP +The +.B rw +flags control the format of the data to be sent or received. +With +.B NWUO_RWDATONLY +only the data part of a UDP packet is sent to the server and only the data +part is received from the server. +The +.B NWUO_RWDATALL +mode presents the data part of a UDP packet with a header that contains +the source and destination IP address, source and destination UDP ports, +the IP options, etc. +The server expects such a header in front of the data to be transmitted. +.ig \" Some for Philip to explain properly: +The header is defined in and looks like this: +.PP +.RS +.nf +.if t .ft C +typedef struct udp_io_hdr +{ + ipaddr_t uih_src_addr; + ipaddr_t uih_dst_addr; + udpport_t uih_src_port; + udpport_t uih_dst_port; + u16_t uih_ip_opt_len; + u16_t uih_data_len; +} udp_io_hdr_t; +.if t .ft R +.fi +.RE +.PP +The first four fields are the source and destination IP addresses and +ports. +.B Uih_ip_opt_len +is ???. +.B Uih_data_len +should equal the length of the packet data (packet lenght minus the +header.) ??? +.. +.PP +The +.B ipopt +flags control the delivery and transmission of IP options. +When +.B NWUO_EN_IPOPT +is set IP, options will be delivered and sent. +When +.B NWUO_DI_IPOPT +is set IP option will be stripped from received packets and no IP options will +be sent. +.ig \" Minix doesn't have this stuff (yet? ever?) +.SS "UDP Library Functions" +.PP +The following routines provide an somewhat easier to use interface to UDP than +the routines described above (\fBtcpip_open\fP, \fBudp_ioc_setopt\fP, +\fBtcpip_read\fP and \fBtcpip_write\fP). +.LP +.sC +errstat +udp_connect(udp_cap, chan_cap, srcport, dstport, dstaddr, flags) +capability *udp_cap; +capability *chan_cap; +udpport_t srcport; +udpport_t dstport; +ipaddr_t dstaddr; +int flags; +.eC +.kW "\fIudp_connect\fP" +\fIUdp_connect\fP combines the functionality of \fItcpip_open\fP and +\fIudp_ioc_setopt\fP. +A pointer to a UDP server capability should be passed in \fIudp_cap\fP, and +the channel capability will be returned in the capability pointed to by +\fIchan_cap\fP. +If \fIsrcport\fP is 0 then an unused port will be selected, otherwise the local +port will be set to \fIsrcport\fP. +If \fIdstport\fP is non-zero then communication will be restricted to remote ports +that equal to \fIdstport\fP, otherwise any data can be sent to or received from +any remote port. +The same thing applies to \fIdstaddr\fP; if \fIdstaddr\fP is non-zero then +only \fIdstaddr\fP can be reached. +Currently no flags are defined so \fIflags\fP should be 0. +.sH +udp_reconnect +.LP +.sC +errstat +udp_reconnect(chan_cap, srcport, dstport, dstaddr, flags) +capability *chan_cap; +udpport_t srcport; +udpport_t dstport; +ipaddr_t dstaddr; +int flags; +.eC +.kW "\fIudp_reconnect\fP" +\fIUdp_reconnect\fP is the same as \fIudp_connect\fP except that an existing +channel capability is (re)used. +.sH +udp_read_msg +.LP +.sC +errstat +udp_read_msg(chan_cap, msg, msglen, actlen, flags) +capability *chan_cap; +char *msg; +int msglen; +int *actlen; +int flags; +.eC +.kW "\fIudp_read_msg\fP" +\fIUdp_read_msg\fP delivers a UDP packet. +The data part of the UDP packet is +prepended with an \fIudp_io_hdr\fP. +The actual length of the possibly truncated packet is returned in \fIactlen\fP. +No flags are defined so \fIflags\fP should be 0. +.sH +udp_write_msg +.LP +.sC +errstat +udp_write_msg(chan_cap, msg, msglen, flags) +capability *chan_cap; +char *msg; +int msglen; +int flags; +.eC +.kW "\fIudp_write_msg\fP" +A UDP packet can be sent with \fIudp_write_msg\fP. +\fIMsg\fP should point to a \fIudp_io_hdr\fP followed by the data part of the +UDP packet. +The \fIuih_dst_addr\fP and \fIuih_dst_port\fP fields of the \fIudp_io_hdr\fP +should be filled in if no values are specified in the \fIudp_connect\fP, +or \fIudp_reconnect\fP. +.sH +udp_close +.LP +.sC +errstat +udp_close(chan_cap, flags) +capability *chan_cap; +int flags; +.eC +.kW "\fIudp_close\fP" +\fIUdp_close\fP cleans up the administration kept by the UDP library but does +not destroy the capability. +The function should be used if the capability is passed to another process +and should continue to exist. +No flags are defined so \fIflags\fP should be 0. +.sH +udp_destroy +.LP +.sC +errstat +udp_destroy(chan_cap, flags) +capability *chan_cap; +int flags; +.eC +.kW "\fIudp_destroy\fP" +\fIUdp_destroy\fP not only cleans up the administration kept by the UDP library +but also destroys the channel capability. +.. +.SH FILES +.IP /dev/eth* \w'/dev/psip*mmm'u +Raw ethernet. The numbers in the device names are decimal, so one may see +names from +.B eth0 +to +.BR eth15 . + +.IP /dev/psip* +First and second Pseudo IP network. +.IP /dev/ip* +IP devices for two ethernets and two Pseudo IP networks. +.IP /dev/tcp* +TCP devices for same four networks. +.IP /dev/udp* +UDP devices. +.IP "/dev/eth, /dev/psip, /dev/ip, /dev/tcp, /dev/udp" +Devices for the default network, links to the devices above. +.B Eth +is only present if ethernet is the default, +.B psip +only for pseudo IP. +.SH "SEE ALSO" +.BR hton (3), +.BR oneC_sum (3), +.BR inet (8), +.BR boot (8). +.SH DIAGNOSTICS +Several errors may be returned by the TCP/IP server. The error code +is found in the +.B errno +variable if the +.BR read , +.BR write , +or +.B ioctl +call returns -1. The TCP/IP error codes defined in are: +.IP EPACKSIZE 5c +This indicates an attempt to read or write with a buffer that is too +large or too small. +.IP EOUTOFBUFS +The TCP/IP server has insufficient memory to execute the request. +.IP EBADIOCTL +This indicates an attempt to execute a command the particular server +does not understand. +For example, a +.B NWIOGTCPCONF +on an ETH channel. +.IP EBADMODE +The request is refused because the channel is not fully configured, in the +wrong state or the parameters are invalid. +.IP EBADDEST +This indicates an illegal destination address for a packet. +.IP EDSTNORCH +The destination is not reachable. +.IP EISCONN +The channel is already connected so a second request is refused. +.IP EADDRINUSE +This address is in use. +.IP ECONNREFUSED +The connection is refused by the other side. +.IP ECONNRESET +The connection is reset (non-gracefully terminated) by the other side. +.IP ETIMEDOUT +The connection is terminated due to an expired timer. +.IP EURG +Urgent data is present and the current receive mode does not allow urgent data +to be transferred. +.IP ENOURG +No urgent data is present and a request came for urgent data. +.IP ENOTCONN +The request requires a connected channel and the channel is not connected. +.IP ESHUTDOWN +The connection is shut down. +That is, a +.B NWIOTCPSHUTDOWN +has been executed so no more data can be transmitted. +.IP ENOCONN +The connection does not exist. +.IP EGENERIC +A generic error code for extremely weird cases. +.SH AUTHOR +Philip Homburg (philip@cs.vu.nl) + +.\" +.\" $PchId: ip.4,v 1.4 2001/01/08 19:58:14 philip Exp $ diff --git a/man/man4/lp.4 b/man/man4/lp.4 new file mode 100644 index 000000000..119dad34b --- /dev/null +++ b/man/man4/lp.4 @@ -0,0 +1,28 @@ +.TH LP 4 +.SH NAME +lp \- line printer +.SH DESCRIPTION +The +.B lp +device refers to the line printer attached to the parallel port. Any byte +written to this device is printed. Only one process may have the device +open. +.PP +The +.B write (2) +call may return with a smaller count then the number of bytes requested to +write. The next write call is then likely to fail with the error code +.B EAGAIN +if the printer is out of paper, or +.B EIO +if the printer is turned off. +.SH FILES +.TP 10 +/dev/lp +Parallel port device. +.SH "SEE ALSO" +.BR lp (1). +.SH BUGS +Only one parallel port is supported. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man4/mtio.4 b/man/man4/mtio.4 new file mode 100644 index 000000000..3076445ed --- /dev/null +++ b/man/man4/mtio.4 @@ -0,0 +1,98 @@ +.TH MTIO 4 +.SH NAME +mtio \- magnetic tape commands +.SH SYNOPSIS +.B "#include " +.br +.B "#include " +.br +.B "#include " +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The magnetic tape devices described in +.BR sd (4) +may be sent commands or queried for their status using the following ioctl +calls: +.PP +.RS +.BR ioctl ( \fIfd , +.BR MTIOCTOP , +.RB & "struct mtop" ) +.br +.BR ioctl ( \fIfd , +.BR MTIOCGET , +.RB & "struct mtget" ) +.RE +.PP +The struct mtop, struct mtget and associated definitions are defined in + as follows: +.PP +.nf + +/* Tape operations: ioctl(fd, MTIOCTOP, &struct mtop) */ + +.ta +4n +7n +15n +struct mtop { + short mt_op; /* Operation (MTWEOF, etc.) */ + int mt_count; /* Repeat count. */ +}; + +.ta +17n +5n +#define MTWEOF 0 /* Write End-Of-File Marker */ +#define MTFSF 1 /* Forward Space File mark */ +#define MTBSF 2 /* Backward Space File mark */ +#define MTFSR 3 /* Forward Space Record */ +#define MTBSR 4 /* Backward Space Record */ +#define MTREW 5 /* Rewind tape */ +#define MTOFFL 6 /* Rewind and take Offline */ +#define MTNOP 7 /* No-Operation, set status only */ +#define MTRETEN 8 /* Retension (completely wind and rewind) */ +#define MTERASE 9 /* Erase the tape and rewind */ +#define MTEOM 10 /* Position at End-Of-Media */ +#define MTMODE 11 /* Select tape density */ +#define MTBLKZ 12 /* Select tape block size */ + +/* Tape status: ioctl(fd, MTIOCGET, &struct mtget) */ + +.ta +4n +7n +15n +struct mtget { + short mt_type; /* Type of tape device. */ + + /* Device dependent "registers". */ + short mt_dsreg; /* Drive status register. */ + short mt_erreg; /* Error register. */ + + /* Misc info. */ + off_t mt_resid; /* Residual count. */ + off_t mt_fileno; /* Current File Number. */ + off_t mt_blkno; /* Current Block Number within file. */ + off_t mt_blksize; /* Current block size. */ +}; + +.fi +.PP +See +.BR mt (1) +for a detailed description on what each operation does. The mt_type field +is always zero, there is no use for it yet. Mt_dsreg is 0 (OK), 1 (Error), +or 2 (EOF encountered.) Mt_erreg holds the SCSI sense key of the last +operation. Mt_blksize is the current tape block size in bytes, zero if the +block size is variable. +.PP +Note that one can issue these commands on a file descriptor that is in use +to read or write data, something that +.B mt +can't do. So you can add eof markers in the middle of an output stream, +or get the status of a device before a rewind-on-close tape rewinds. +.PP +The driver will automatically add an end of file marker to a tape that is +written to if you execute a space command. If you write eof markers +yourself then the driver will not add one extra on close. +.SH "SEE ALSO" +.BR mt (1), +.BR sd (4). +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man4/tty.4 b/man/man4/tty.4 new file mode 100644 index 000000000..e47f7d4f1 --- /dev/null +++ b/man/man4/tty.4 @@ -0,0 +1,736 @@ +.TH TTY 4 +.SH NAME +tty, termios \- terminals +.SH DESCRIPTION +The +.B tty +driver family takes care of all user input and output. It governs the +keyboard, the console, the serial lines, and pseudo ttys. Input on any of +these devices undergoes "input processing", and output undergoes "output +processing" according to the standard termios terminal interface. +.SS "Input processing" +Each terminal device has an input queue. This queue is used to store +preprocessed input characters, and to perform the backspacing and erase +functions. Some special characters like a newline make the contents of the +queue available to a process reading from the terminal. Characters up to +and including the newline, or another so-called "line break", may be read by +a process. The process need not read all characters at once. An input line +may be read byte by byte if one wants to. A line break just makes +characters available for reading, thats all. +.PP +When data is made available depends on whether the tty is in canonical mode +or not. In canonical mode the terminal processes input line by line. A +line ends with a newline +.RB ( NL ), +end-of-file +.RB ( EOF ), +or end-of-line +.RB ( EOL ). +Characters that have not been delimited by such a line break may be erased +one by one with the +.B ERASE +character or all at once with the +.B KILL +character. Once a line break is typed the characters become available to a +reading process and can no longer be erased. Once read they are removed +from the input queue. Several lines may be gathered in the input queue if +no reader is present to read them, but a new reader will only receive one +line. Two line breaks are never returned in one read call. The input queue +has a maximum length of +.B MAX_CANON +characters. Any more characters are discarded. One must use +.B ERASE +or +.B KILL +to make the terminal functioning again if the input queue fills up. If +nonblocking I/O is set then \-1 is returned with +.B errno +set to +.B EAGAIN +if the reader would otherwise be blocked. +.PP +In non-canonical mode (raw mode for short) all characters are immediately +available to the reader in principle. One may however tune the terminal to +bursty input with the +.B MIN +and +.B TIME +parameters, see the raw I/O parameters section below. In raw mode no +characters are discarded if the input queue threatens to overflow if the +device supports flow control. +.SS "Output processing" +Characters written to a terminal device may undergo output processing, which +is usually just inserting a carriage returns before newlines. A writer +may return before all characters are output if the characters can be stored +in the output buffers. If not then the writer may be blocked until space is +available. If non-blocking I/O is set then only the count of the number of +bytes that can be processed immediately is returned. If no characters can +be written at all then \-1 is returned with +.B errno +set to +.BR EAGAIN . +.SS "Special characters" +Some characters have special functions in some of the terminal modes. These +characters are as follows, with the Minix defaults shown in parentheses: +.TP 5 +.BR INTR " (^?)" +Special input character that is recognized if +.B ISIG +is set. (For +.B ISIG +and other flags see the various modes sections below.) It causes a +.B SIGINT +signal to be sent to all processes in the terminal process group. (See the +section on session leaders below.) +.TP +.BR QUIT " (^\e)" +Special input character if +.B ISIG +is set. Causes a +.B SIGQUIT +signal to be sent to the terminal process group. +.TP +.BR ERASE " (^H)" +Special input character if +.B ICANON +is set. Erases the last character in the current line. +.TP +.BR KILL " (^U)" +Special input character if +.B ICANON +is set. Erases the entire line. +.TP +.BR EOF " (^D)" +Special input character if +.B ICANON +is set. It is a line break character that is not itself returned to a +reader. If EOF is typed with no input present then the read returns zero, +which normally causes the reader to assume that end-of-file is reached. +.TP +.BR CR " (^M)" +Special input character if +.B IGNCR +or +.B ICRNL +is set. It is a carriage return ('\er'). If +.B IGNCR +is set then +.B CR +is discarded. If +.B ICRNL +is set and +.B IGNCR +is not set then +.B CR +is changed into an +.B NL +and has the same function as +.BR NL. +.TP +.BR NL " (^J)" +Special input character if +.B ICANON +is set. It is both a newline ('\en') and a line break. +.br +Special output character if +.B OPOST +and +.B ONLCR +are set. A +.B CR NL +sequence is output instead of just +.BR NL . +(Minix specific, but almost mandatory on any UNIX-like system.) +.TP +.BR TAB " (^I)" +Special character on output if +.B OPOST +and +.B XTABS +are set. It is transformed into the number of spaces necessary to reach a +column position that is a multiple of eight. (Only needed for terminals +without hardware tabs.) +.TP +.BR EOL " (undefined)" +Special input character if +.B ICANON +is set. It is an additional line break. +.TP +.BR SUSP " (^Z)" +Special input character if job control is implemented and +.B ISIG +is set. It causes a +.B SIGTSTP +signal to be send to the terminal process group. (Minix does not have job +control.) +.TP +.BR STOP " (^S)" +Special input character if +.B IXON +is set. It suspends terminal output and is then discarded. +.TP +.BR START " (^Q)" +Special output character if +.B IXON +is set. It starts terminal output if suspended and is then discarded. If +.B IXANY +is also set then any other character also starts terminal output, but they +are not discarded. +.TP +.BR REPRINT " (^R)" +Special input character if +.B IEXTEN +and +.B ECHO +are set. Reprints the input queue from the last line break onwards. A +reprint also happens automatically if the echoed input has been messed up by +other output and +.B ERASE +is typed. +.TP +.BR LNEXT " (^V)" +Special input character if +.B IEXTEN +is set. It is the "literal next" character that causes the next character +to be input without any special processing. +.TP +.BR DISCARD " (^O)" +Special input character if +.B IEXTEN +is set. Causes output to be discarded until it is typed again. (Implemented +only under Minix-vmd.) +.PP +All of these characters except +.BR CR , +.B NL +and +.B TAB +may be changed or disabled under Minix. (Changes to +.B START +and +.B STOP +may be ignored under other termios implementations.) The +.B REPRINT +and +.B LNEXT +characters are Minix extensions that are commonly present in other +implementations. \s-2POSIX\s+2 is unclear on whether +.BR IEXTEN, +.BR IGNCR +and +.BR ICRNL +should be active in non-canonical mode, but under Minix they are. +.SS "Terminal attributes" +The attributes of a terminal, such as whether the mode should be canonical or +non-canonical, are controlled by routines that use the +.B termios +structure as defined in +.BR : +.PP +.RS +.nf +.ta +4n +10n +15n +struct termios { + tcflag_t c_iflag; /* input modes */ + tcflag_t c_oflag; /* output modes */ + tcflag_t c_cflag; /* control modes */ + tcflag_t c_lflag; /* local modes */ + speed_t c_ispeed; /* input speed */ + speed_t c_ospeed; /* output speed */ + cc_t c_cc[NCCS]; /* control characters */ +}; +.fi +.RE +.PP +The types +.BR tcflag , +.B speed_t +and +.B cc_t +are defined in +.B +as unsigned integral types. +.SS "Input Modes" +The +.B c_iflag +field contains the following single bit flags that control input processing: +.TP 5 +.B ICRNL +Map +.B CR +to +.B NL +on input. +.TP +.B IGNCR +Ignore +.B CR +on input. This flag overrides +.BR ICRNL . +.TP +.B INLCR +Map +.B NL +to +.B CR +on input. This is done after the +.B IGNCR +check. +.TP +.B IXON +Enable start/stop output control. +.TP +.B IXOFF +Enable start/stop input control. (Not implemented.) +.TP +.B IXANY +Allow any character to restart output. (Minix specific.) +.TP +.B ISTRIP +Strip characters to seven bits. +.TP +.B IGNPAR +Ignore characters with parity errors. (Not implemented.) +.TP +.B INPCK +Enable input parity checking. (Not implemented.) +.TP +.B PARMRK +Mark parity errors by preceding the faulty character with '\e377', '\e0'. +The character '\e377' is preceded by another '\e377' to avoid ambiguity. +(Not implemented.) +.TP +.B BRKINT +Send the signal +.B SIGINT +to the terminal process group when receiving a break condition. (Not +implemented.) +.TP +.B IGNBRK +Ignore break condition. If neither +.B BRKINT +or +.B IGNBRK +is set a break is input as a single '\e0', or if +.B PARMRK +is set as '\e377', '\e0', '\e0'. +(Breaks are always ignored.) +.SS "Output Modes" +The +.B c_oflag +field contains the following single bit flags that control output processing: +.TP +.B OPOST +Perform output processing. This flag is the "main switch" on output +processing. All other flags are Minix specific. +.TP +.B ONLCR +Transform an +.B NL +to a +.B CR NL +sequence on output. Note that a key labeled "RETURN" or "ENTER" usually +sends a +.BR CR . +In line oriented mode this is normally transformed into +.B NL +by +.BR ICRNL . +.B NL +is the normal UNIX line delimiter ('\en'). On output an +.B NL +is transformed into the +.B CR NL +sequence that is necessary to reach the first column of the next line. +(This is a common output processing function for UNIX-like systems, but not +always separately switchable by an +.B ONLCR +flag.) +.TP +.B XTABS +Transform a +.B TAB +into the number of spaces necessary to reach a column position that is a +multiple of eight. +.TP +.B ONOEOT +Discard +.B EOT +(^D) characters. (Minix-vmd only.) +.SS "Control Modes" +The +.B c_cflag +field contains the following single bit flags and bit field for basic +hardware control: +.TP +.B CLOCAL +Ignore modem status lines. +.TP +.B CREAD +Enable receiver. (The receiver is always enabled.) +.TP +.B CSIZE +Number of bits per byte. +.B CSIZE +masks off the values +.BR CS5 , +.BR CS6 , +.BR CS7 +and +.BR CS8 +that indicate that 5, 6, 7 or 8 bits are used. +.TP +.B CSTOPB +Send two stop bits instead of one. Two stop bits are normally used at 110 +baud or less. +.TP +.B PARENB +Enable parity generation. +.TP +.B PARODD +Generate odd parity if parity is generated, otherwise even parity. +.TP +.B HUPCL +Drop the modem control lines on the last close of the terminal line. (Not +implemented.) +.SS "Local Modes" +The +.B c_lflag +field contains the following single bit flags that control various functions: +.TP +.B ECHO +Enable echoing of input characters. Most input characters are echoed as +they are. Control characters are echoed as +.BI "^" X +where +.I X +is the letter used to say that the control character is +.BI CTRL\- X\fR. +The +.BR CR , +.BR NL +and +.BR TAB +characters are echoed with their normal effect unless they are escaped by +.BR LNEXT . +.TP +.B ECHOE +If +.B ICANON +and +.B ECHO +are set then echo +.B ERASE +and +.B KILL +as one or more backspace-space-backspace sequences to wipe out the last +character or the entire line, otherwise they are echoed as they are. +.TP +.B ECHOK +If +.B ICANON +and +.B ECHO +are set and +.B ECHOE +is not set then output an +.B NL +after the +.B KILL +character. (For hardcopy terminals it is best to unset +.B ECHOE +and to set +.BR ECHOK .) +.TP +.B ECHONL +Echo +.B NL +even if +.B ECHO +is not set, but +.B ICANON +is set. +.TP +.B ICANON +Canonical input. This enables line oriented input and erase and kill +processing. +.TP +.B IEXTEN +Enable implementation defined input extensions. +.TP +.B ISIG +Enable the signal characters +.BR INTR , +.BR QUIT +and +.BR SUSP . +.TP +.B NOFLSH +Disable the flushing of the input and output queues that is normally done if +a signal is sent. +.TP +.B TOSTOP +Send a +.B SIGTTOU +signal if job control is implemented and a background process tries to +write. (Minix has no job control.) +.SS "Input and output speed" +The input and output speed are encoded into the +.B c_ispeed +and +.B c_ospeed +fields. +.B +defines the symbols +.BR B0 , +.BR B50 , +.BR B75 , +.BR B110 , +.BR B134 , +.BR B150 , +.BR B200 , +.BR B300 , +.BR B600 , +.BR B1200 , +.BR B1800 , +.BR B2400 , +.BR B4800 , +.BR B9600 , +.BR B19200 , +.BR B38400 , +.BR B57600 +and +.BR B115200 +as values used to indicate the given baud rates. The zero baud rate, +.BR B0 , +if used for the input speed causes the input speed to be equal to the +output speed. Setting the output speed to zero hangs up the line. One +should use the functions +.BR cfgetispeed() , +.BR cfgetospeed() , +.BR cfsetispeed() +and +.BR cfsetospeed() +to get or set a speed, because the +.B c_ispeed +and +.B c_ospeed +fields may not be visible under other implementations. (The +.B c_ispeed +and +.B c_ospeed +fields and the +.B B57600 +and +.B B115200 +symbols are Minix specific.) +.SS "Special characters" +The +.B c_cc +array contains the special characters that can be modified. The array has +length +.B NCCS +and is subscripted by the symbols +.BR VEOF , +.BR VEOL , +.BR VERASE , +.BR VINTR , +.BR VKILL , +.BR VMIN , +.BR VQUIT , +.BR VTIME , +.BR VSUSP , +.BR VSTART , +.BR VSTOP , +.BR VREPRINT , +.BR VLNEXT +and +.BR VDISCARD . +All these symbols are defined in +.BR . +Some implementations may give the same values to the +.B VMIN +and +.B VTIME +subscripts and the +.B VEOF +and +.B VEOL +subscripts respectively, and may ignore changes to +.B START +and +.BR STOP . +(Under Minix all special characters have their own +.I c_cc +slot and can all be modified.) +.SS "Raw I/O Parameters" +The +.B MIN +and +.B TIME +parameters can be used to adjust a raw connection to bursty input. +.B MIN +represents a minimum number of bytes that must be received before a read +call returns. +.B TIME +is a timer of 0.1 second granularity that can be used to time out a read. +Setting either of these parameters to zero has special meaning, which leads +to the following four possibilities: +.TP 5 +.B "MIN > 0, TIME > 0" +.B TIME +is an inter-byte timer that is started (and restarted) when a byte is +received. A read succeeds when either the minimum number of characters +is received or the timer expires. Note that the timer starts +.B after +the first character, so the read returns at least one byte. +.TP +.B "MIN > 0, TIME = 0" +Now the timer is disabled, and a reader blocks indefinitely until at least +.B MIN +characters are received. +.TP +.B "MIN = 0, TIME > 0" +.B TIME +is now a read timer that is started when a read is executed. The read will +return if the read timer expires or if at least one byte is input. (Note +that a value of zero may be returned to the reader.) +.TP +.B "MIN = 0, TIME = 0" +The bytes currently available are returned. Zero is returned if no bytes +are available. +.SS "User Level Functions" +Termios attributes are set or examined, and special functions can be +performed by using the functions described in +.BR termios (3). +.SS "Session Leaders and Process Groups" +With the use of the +.B setsid() +function can a process become a session leader. A session leader forms a +process group with a process group id equal to the process id of the session +leader. If a session leader opens a terminal device file then this terminal +becomes the controlling tty of the session leader. Unless the terminal is +already the controlling tty of another process, or unless the +.B O_NOCTTY +flag is used to prevent the allocation of a controlling tty. The process +group of the session leader is now remembered as the terminal process group +for signals sent by the terminal driver. All the children and grandchildren +of the session leader inherit the controlling terminal and process group +until they themselves use +.BR setsid() . +.PP +The controlling tty becomes inaccessible to the children of the session +leader when the session leader exits, and a hangup signal is sent to all +the members of the process group. The input and output queues are flushed +on the last close of a terminal and all attributes are reset to the default +state. +.PP +A special device +.B /dev/tty +is a synonym for the controlling tty of a process. It allows a process to +reach the terminal even when standard input, output and error are +redirected. Opening this device can also be used as a test to see if a +process has a controlling tty or not. +.PP +For Minix a special write-only device +.B /dev/log +exists for processes that want to write messages to the system console. +Unlike the console this device is still accessible when a session leader +exits. +.PP +Minix-vmd also has a +.B /dev/log +device, but this device is read-write. All messages written to the log +device or to the console when X11 is active can be read from +.BR /dev/log . +The system tries to preserve the log buffer over a reboot so that panic +messages reappear in the log if the system happens to crash. +.SS "Pseudo Terminals" +Pseudo ttys allow a process such as a remote login daemon to set up a +terminal for a remote login session. The login session uses a device like +.B /dev/ttyp0 +for input and output, and the remote login daemon uses the device +.B /dev/ptyp0 +to supply input to or take output from the login session and transfer this +to or from the originating system. So the character flow may be: Local +user input sent to the remote system is written to +.B /dev/ptyp0 +by the remote login daemon, undergoes input processing and appears on +.B /dev/ttyp0 +as input to the login session. Output from the login session to +.B /dev/ttyp0 +undergoes output processing, is read from +.B /dev/ptyp0 +by the remote login daemon and is send over to the local system to be +displayed for the user. (So there are only four data streams to worry about +in a pseudo terminal.) +.PP +A pseudo terminal can be allocated by trying to open all the controlling +devices +.BI /dev/pty nn +one by one until it succeeds. Further opens will fail once a pty is open. +The process should now fork, the child should become session leader, open +the tty side of the pty and start a login session. +.PP +If the tty side is eventually closed down then reads from the pty side will +return zero and writes return \-1 with +.B errno +set to +.BR EIO . +If the pty side is closed first then a +.B SIGHUP +signal is sent to the session leader and further reads from the tty side +return zero and writes return \-1 with +.B errno +set to +.BR EIO . +(Special note: A line erase may cause up to three times the size of the +tty input queue to be sent to the pty reader as backspace overstrikes. Some +of this output may get lost if the pty reader cannot accept it all at once +in a single read call.) +.SS "Backwards compatibility" +The +.BR TIOCGETP , +.BR TIOCSETP , +.BR TIOCGETC +and +.BR TIOCSETC +ioctl functions that are used by the old +.B sgtty +terminal interface are still supported by the terminal driver by emulation. +Note that these old functions cannot control all termios attributes, so the +terminal must be in a relatively sane state to avoid problems. +.SH FILES +The list below shows all devices that Minix and Minix-vmd have. Not all of +these devices are configured in by default, as indicated by the numbers +(i/j/k, l/m/n) that tell the minimum, default and maximum possible number of +these devices for Minix (i/j/k) and Minix-vmd (l/m/n). +.TP 20 +.B /dev/console +System console. +.TP +.B /dev/ttyc[1-7] +Virtual consoles. (0/1/7, 0/1/7) +.TP +.BR /dev/log +Console log device. +.TP +.B /dev/tty0[0-3] +Serial lines. (0/2/2, 4/4/4) +.TP +.B /dev/tty[p-w][0-f] +Pseudo ttys. (0/0/64, 1/32/128) +.TP +.B /dev/pty[p-w][0-f] +Associated pseudo tty controllers. +.SH "SEE ALSO" +.BR stty (1), +.BR termios (3), +.BR setsid (2), +.BR read (2), +.BR write (2). +.SH BUGS +A fair number of flags are not implemented under Minix (yet). Luckily they +are very limited utility and only apply to RS-232, not to the user interface. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man5/TZ.5 b/man/man5/TZ.5 new file mode 100644 index 000000000..bf5456329 --- /dev/null +++ b/man/man5/TZ.5 @@ -0,0 +1,138 @@ +.TH TZ 5 +.SH NAME +TZ \- Time zone environment variable +.SH SYNOPSIS +\fBTZ=\fIzone\fR[\fB\-\fR]\fIoffset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIstart\fR[\fB/\fItime\fR]\fB,\fIend\fR[\fB/\fItime\fR]]] +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The +.B TZ +environment variable tells functions such as the +.BR ctime (3) +family and programs like +.B date +what the time zone and daylight saving rule is. The value of +.B TZ +has the \s-2POSIX\s+2 standardized form shown in the synopsis. This form +specifies the zone names, offsets from GMT, and daylight saving changeover +times for at least the current year. +.TP +.I zone +A three or more letter name for the time zone in normal (winter) time. +.TP +.BI [\-] offset +A signed time telling the offset of the time zone westwards from Greenwich. +The time has the form +.I hh[:mm[:ss]] +with a one of two digit hour, and optional two digit minutes and seconds. +.TP +.I dst +The name of the time zone when daylight saving is in effect. It may +be followed by an offset telling how big the clock correction is other than +the default of 1 hour. +.TP +\fIstart\fR/\fItime\fR,\fIend\fR/\fItime\fR +Specifies the start and end of the daylight saving period. The +.I start +and +.I end +fields indicate on what day the changeover occurs. They must be in one of +the following formats: +.SP +.ta +5 +.in +5 +.ti -5 +\fBJ\fIn\fR The Julian day +.I n +(1 <= +.I n +<= 365) ignoring leap days, i.e. there is no February 29. +.SP +.ti -5 +\fIn\fR The zero-based Julian day +(0 <= +.I n +<= 365). Leap days are not ignored. +.SP +.ti -5 +.BI M m . n . d +.br +This indicates month +.IR m , +the +.IR n -th +occurrence of day +.I d +(1 <= +.I m +<= 12, 1 <= +.I n +<= 5, 0 <= +.I d +<= 6, 0=Sunday). The 5-th occurrence means the last occurrence of that day +in a month. So +.B M4.1.0 +is the first Sunday in April, +.B M9.5.0 +is the last Sunday in September. +.in -5 +.SP +The +.I time +field indicates the time the changeover occurs on the given day. +.SH EXAMPLES +Greenwich Mean Time: +.PP +.RS +.B TZ=GMT0 +.RE +.PP +Central European Time, 1 hour east from Greenwich, daylight saving starts on +the last Sunday in March at 2 AM and ends on the last Sunday in October +at 3 AM: +.PP +.RS +.B TZ='CET\-1CEST,M3.5.0/2,M10.5.0/3' +.RE +.PP +British time, daylight saving starts and ends at the same moment as CET, +but in an earlier time zone: +.PP +.RS +.B TZ=GMT0BST,M3.5.0/1,M10.5.0/2 +.RE +.PP +The eastern european time zones also have the changeovers at the same +absolute time as British time and CET. +.PP +U.S. Eastern Standard Time, 5 hours west from Greenwich, daylight saving +starts on the first Sunday in April at 2 AM and ends on the last Sunday in +October at 2 AM: +.PP +.RS +.B TZ=EST5EDT,M4.1.0/2,M10.5.0/2 +.RE +.PP +It shouldn't surprise you that daylight saving in New Zealand is observed +in the months opposite from the previous examples. It starts on the first +Sunday in October at 2 AM and ends on the third Sunday in March at 3 AM: +.PP +.RS +.B TZ=NZST\-12NZDT,M10.1.0/2,M3.3.0/3 +.RE +.SH "SEE ALSO" +.BR readclock (8), +.BR date (1). +.SH BUGS +You may have noticed that many fields are optional. Do no omit them, +because the defaults are bogus. If you need daylight saving then fully +specify the changeovers. +.PP +West is negative, east is positive, ask any sailor. +.PP +Next year's time zone and daylight saving time are determined by politicians. +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man5/configfile.5 b/man/man5/configfile.5 new file mode 100644 index 000000000..e9e151fdc --- /dev/null +++ b/man/man5/configfile.5 @@ -0,0 +1,83 @@ +.TH CONFIGFILE 5 +.SH NAME +configfile \- generic configuration file format +.SH SYNOPSIS +.B */etc/*.conf +.SH DESCRIPTION +.de SP +.if t .sp 0.4 +.if n .sp +.. +The syntax of the generic configuration file format is as follows: +.PP +.RS +.nf +.ta +16n +configfile: empty +.ta +8n +8n + | configline configfile + ; + +.ta +16n +configline: wordlist '\fB;\fR' +.ta +8n +8n + | \fBinclude\fR string '\fB;\fR' + ; + +.ta +16n +wordlist: empty +.ta +8n +8n + | word wordlist + | string wordlist + | '\fB{\fR' configfile '\fB}\fR' wordlist + ; + +empty: ; +.fi +.RE +.PP +A word is a sequence of letters, numbers, and characters from the set +.BR "!#$%&*+-./<=>?[\e]^_|~" . +A backslash +.RB ( \e ) +may be followed by a character in the set +.B abefnrstv +to form a BEL, BS, ESC, FF, NL, CR, SP, TAB, or VT character. Followed by +up to three octal digits a character of that value is formed, and likewise +for an +.B x +followed by up to two hexadecimal digits. Any other character is left +as-is. A backslash followed by whitespace is completely removed from the +input. (This includes comments.) +.PP +A string is started by a single or double quote, a series of characters, and +ended by the same type of quote it started with. Any character or +escape with +.B \e +may be found in a string. Strings may not span lines. +.PP +Tokens are separated by whitespace, being the usual whitespace characters +and comments. A comment starts with the +.B # +character, and ends at a newline. +.PP +The special word +.B include +tells that the file mentioned in the following string must be read and +included at that point. The file is found relative to the directory the +current configuration file is found in, unless its name starts with a +.BR / . +A file that doesn't exist is seen as empty. +.PP +A generic configuration file can be read with the functions described in +.BR configfile (3). +.SH EXAMPLES +Have a look at +.BR /etc/dhcp.conf . +.SH "SEE ALSO" +.BR configfile (3). +.SH NOTES +Inspired by the configuration file of Paul Vixie's +.BR bind . +.SH AUTHOR +Kees J. Bot (kjb@cs.vu.nl) diff --git a/man/man5/crontab.5 b/man/man5/crontab.5 new file mode 100644 index 000000000..4bc987633 --- /dev/null +++ b/man/man5/crontab.5 @@ -0,0 +1,137 @@ +.TH CRONTAB 5 +.SH NAME +crontab \- table of jobs to be performed by cron +.SH SYNOPSIS +.nf +.ft B +/usr/lib/crontab +/usr/local/lib/crontab +/var/lib/crontab +/var/opt/\fIname\fP/lib/crontab\ \ \fR(Minix-vmd only)\fB +/usr/spool/crontabs/\fIuser\fP +.ft R +.fi +.SH DESCRIPTION +The +.BR cron (8) +daemon runs jobs at regular intervals. These jobs are listed in +.B crontab +files. The format of entries in a crontab file are five fields of numbers +specifying the minute (0\-59), hour (0\-23), day of the month (1\-31), month +(1\-12), and day of the week (0\-6 with 0 = Sunday) that a task must be +executed. The task to be executed follows as a shell command. +.PP +The time numbers can be given as a comma separated list of simple numbers, +ranges ("2\-5" is the same as "2,3,4,5"), and repeats ("2:5" means +"2,7,12,17,22" in the hour field). A repeat is cyclic affair, i.e. 2:5 +and 12:5 are the same thing. A single "*" can be used in a field to +indicate all valid numbers in that field, so it translates to "always". In +the minute field you can use "?" for the current minute that the crontab +file is loaded. It can be used in a repeat, i.e. "?:10" for every 10 +minutes. This keeps machines with identical crontabs from executing tasks +at exactly the same time, causing a burst of traffic if anything is done +over a network. +.PP +If a given time is valid in all five fields then a command is executed. +Here are a few examples that illustrate the possibilities: +.PP +.if t .RS +.if t .ft C +.nf +# min hour mday mon wday command + ? 3 * * * /usr/etc/daily # Daily system cleanup + 0 * * * * date # Print date on the hour + 30 4 * * 2\-6 /var/etc/backup # After workdays on 4:30 + 0 9 25 12 * \-u ast sing # Andy sings on Xmas morning + 0 0 13 * 5 echo Beware! # For the superstitious +.fi +.if t .ft P +.if t .RE +.PP +The command may optionally be prefixed by +.BI \-u " user" +to specify under which user the command should be run. Commands from +crontabs in the spool directory are always run under the id of the crontab's +owner, the +.B \-u +flag is ignored. +.PP +A command can be placed on the same line as the time fields, or on the next +line indented by one TAB character. (A TAB, not eight spaces.) More TAB +indented lines can be added for a multiline command. The tabs are removed +from the command when passed to the shell. If a command is put on the same +line as the time fields then percent characters are changed into newlines, +this is not done for a TAB indented command. The following three entries +give the same output: +.PP +.RS +.if t .ft C +.nf +.ta +8n +0 12 * * * echo 'Hello'; echo ' World!' +#1 +0 12 * * * echo 'Hello% World!' #2 +0 12 * * * #3 + cat <