From c60d02e58116f0bc849b3044b5c5d00847c2a049 Mon Sep 17 00:00:00 2001 From: Doc Manager Date: Tue, 21 Oct 1997 14:18:47 +0000 Subject: Create tag '2.2.5'. --- en/tutorials/Makefile | 11 - en/tutorials/Makefile.inc | 4 - en/tutorials/ddwg/Makefile | 6 - en/tutorials/ddwg/ddwg.sgml | 1142 ------------ en/tutorials/devel/Makefile | 7 - en/tutorials/devel/devel.docb | 1835 -------------------- en/tutorials/diskformat/Makefile | 7 - en/tutorials/diskformat/diskformat.docb | 418 ----- en/tutorials/disklessx/Makefile | 5 - en/tutorials/disklessx/disklessx.sgml | 266 --- en/tutorials/doc.ftr | 5 - en/tutorials/doc.hdr | 14 - en/tutorials/fonts/Makefile | 6 - en/tutorials/fonts/fonts.docb | 723 -------- en/tutorials/index.sgml | 49 - en/tutorials/mh/Makefile | 7 - en/tutorials/mh/mh.docb | 704 -------- en/tutorials/multios/Makefile | 7 - en/tutorials/multios/multios.docb | 680 -------- en/tutorials/newuser/Makefile | 7 - en/tutorials/newuser/newuser.docb | 943 ---------- en/tutorials/ppp/Makefile | 6 - en/tutorials/ppp/ppp.sgml | 1736 ------------------ en/tutorials/upgrade/Makefile | 6 - en/tutorials/upgrade/upgrade.docb | 758 -------- en_US.ISO8859-1/articles/fonts/Makefile | 6 - en_US.ISO8859-1/articles/fonts/article.sgml | 723 -------- en_US.ISO8859-1/articles/formatting-media/Makefile | 7 - .../articles/formatting-media/article.sgml | 418 ----- en_US.ISO8859-1/articles/mh/Makefile | 7 - en_US.ISO8859-1/articles/mh/article.sgml | 704 -------- en_US.ISO8859-1/articles/multi-os/Makefile | 7 - en_US.ISO8859-1/articles/multi-os/article.sgml | 680 -------- en_US.ISO8859-1/articles/new-users/Makefile | 7 - en_US.ISO8859-1/articles/new-users/article.sgml | 943 ---------- .../articles/programming-tools/Makefile | 7 - .../articles/programming-tools/article.sgml | 1835 -------------------- en_US.ISO_8859-1/articles/fonts/Makefile | 6 - en_US.ISO_8859-1/articles/fonts/article.sgml | 723 -------- .../articles/formatting-media/Makefile | 7 - .../articles/formatting-media/article.sgml | 418 ----- en_US.ISO_8859-1/articles/mh/Makefile | 7 - en_US.ISO_8859-1/articles/mh/article.sgml | 704 -------- en_US.ISO_8859-1/articles/multi-os/Makefile | 7 - en_US.ISO_8859-1/articles/multi-os/article.sgml | 680 -------- en_US.ISO_8859-1/articles/new-users/Makefile | 7 - en_US.ISO_8859-1/articles/new-users/article.sgml | 943 ---------- .../articles/programming-tools/Makefile | 7 - .../articles/programming-tools/article.sgml | 1835 -------------------- en_US.ISO_8859-1/tutorials/Makefile | 11 - en_US.ISO_8859-1/tutorials/Makefile.inc | 4 - en_US.ISO_8859-1/tutorials/ddwg/Makefile | 6 - en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml | 1142 ------------ en_US.ISO_8859-1/tutorials/disklessx/Makefile | 5 - en_US.ISO_8859-1/tutorials/doc.ftr | 5 - en_US.ISO_8859-1/tutorials/doc.hdr | 14 - en_US.ISO_8859-1/tutorials/index.sgml | 49 - en_US.ISO_8859-1/tutorials/ppp/Makefile | 6 - en_US.ISO_8859-1/tutorials/ppp/ppp.sgml | 1736 ------------------ ja_JP.eucJP/Makefile | 6 - ja_JP.eucJP/books/handbook/Makefile | 27 - ja_JP.eucJP/books/handbook/book.sgml | 195 --- 62 files changed, 23246 deletions(-) delete mode 100644 en/tutorials/Makefile delete mode 100644 en/tutorials/Makefile.inc delete mode 100644 en/tutorials/ddwg/Makefile delete mode 100644 en/tutorials/ddwg/ddwg.sgml delete mode 100644 en/tutorials/devel/Makefile delete mode 100644 en/tutorials/devel/devel.docb delete mode 100644 en/tutorials/diskformat/Makefile delete mode 100644 en/tutorials/diskformat/diskformat.docb delete mode 100644 en/tutorials/disklessx/Makefile delete mode 100644 en/tutorials/disklessx/disklessx.sgml delete mode 100644 en/tutorials/doc.ftr delete mode 100644 en/tutorials/doc.hdr delete mode 100644 en/tutorials/fonts/Makefile delete mode 100644 en/tutorials/fonts/fonts.docb delete mode 100644 en/tutorials/index.sgml delete mode 100644 en/tutorials/mh/Makefile delete mode 100644 en/tutorials/mh/mh.docb delete mode 100644 en/tutorials/multios/Makefile delete mode 100644 en/tutorials/multios/multios.docb delete mode 100644 en/tutorials/newuser/Makefile delete mode 100644 en/tutorials/newuser/newuser.docb delete mode 100644 en/tutorials/ppp/Makefile delete mode 100644 en/tutorials/ppp/ppp.sgml delete mode 100644 en/tutorials/upgrade/Makefile delete mode 100644 en/tutorials/upgrade/upgrade.docb delete mode 100644 en_US.ISO8859-1/articles/fonts/Makefile delete mode 100644 en_US.ISO8859-1/articles/fonts/article.sgml delete mode 100644 en_US.ISO8859-1/articles/formatting-media/Makefile delete mode 100644 en_US.ISO8859-1/articles/formatting-media/article.sgml delete mode 100644 en_US.ISO8859-1/articles/mh/Makefile delete mode 100644 en_US.ISO8859-1/articles/mh/article.sgml delete mode 100644 en_US.ISO8859-1/articles/multi-os/Makefile delete mode 100644 en_US.ISO8859-1/articles/multi-os/article.sgml delete mode 100644 en_US.ISO8859-1/articles/new-users/Makefile delete mode 100644 en_US.ISO8859-1/articles/new-users/article.sgml delete mode 100644 en_US.ISO8859-1/articles/programming-tools/Makefile delete mode 100644 en_US.ISO8859-1/articles/programming-tools/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/fonts/Makefile delete mode 100644 en_US.ISO_8859-1/articles/fonts/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/formatting-media/Makefile delete mode 100644 en_US.ISO_8859-1/articles/formatting-media/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/mh/Makefile delete mode 100644 en_US.ISO_8859-1/articles/mh/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/multi-os/Makefile delete mode 100644 en_US.ISO_8859-1/articles/multi-os/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/new-users/Makefile delete mode 100644 en_US.ISO_8859-1/articles/new-users/article.sgml delete mode 100644 en_US.ISO_8859-1/articles/programming-tools/Makefile delete mode 100644 en_US.ISO_8859-1/articles/programming-tools/article.sgml delete mode 100644 en_US.ISO_8859-1/tutorials/Makefile delete mode 100644 en_US.ISO_8859-1/tutorials/Makefile.inc delete mode 100644 en_US.ISO_8859-1/tutorials/ddwg/Makefile delete mode 100644 en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml delete mode 100644 en_US.ISO_8859-1/tutorials/disklessx/Makefile delete mode 100644 en_US.ISO_8859-1/tutorials/doc.ftr delete mode 100644 en_US.ISO_8859-1/tutorials/doc.hdr delete mode 100644 en_US.ISO_8859-1/tutorials/index.sgml delete mode 100644 en_US.ISO_8859-1/tutorials/ppp/Makefile delete mode 100644 en_US.ISO_8859-1/tutorials/ppp/ppp.sgml delete mode 100644 ja_JP.eucJP/Makefile delete mode 100644 ja_JP.eucJP/books/handbook/Makefile delete mode 100644 ja_JP.eucJP/books/handbook/book.sgml diff --git a/en/tutorials/Makefile b/en/tutorials/Makefile deleted file mode 100644 index 0434928bee..0000000000 --- a/en/tutorials/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -# $Id: Makefile,v 1.11 1997-09-13 04:24:09 jfieber Exp $ - -DOCS?= index.sgml -SUBDIR= devel diskformat disklessx fonts mh multios newuser upgrade -DOCSUBDIR= ddwg ppp - -.if defined $(NEW_BUILD) -SUBDIR= -.endif - -.include "../web.mk" diff --git a/en/tutorials/Makefile.inc b/en/tutorials/Makefile.inc deleted file mode 100644 index 7da7fe75c2..0000000000 --- a/en/tutorials/Makefile.inc +++ /dev/null @@ -1,4 +0,0 @@ -# $Id: Makefile.inc,v 1.4 1997-07-01 03:52:21 max Exp $ - -WEBBASE?= /data/tutorials -SGMLOPTS+= -hdr ${.CURDIR}/../doc.hdr -ftr ${.CURDIR}/../doc.ftr diff --git a/en/tutorials/ddwg/Makefile b/en/tutorials/ddwg/Makefile deleted file mode 100644 index f28e8dcab7..0000000000 --- a/en/tutorials/ddwg/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:11 max Exp $ - -DOC= ddwg -SRCS= ddwg.sgml - -.include diff --git a/en/tutorials/ddwg/ddwg.sgml b/en/tutorials/ddwg/ddwg.sgml deleted file mode 100644 index 9cb25739aa..0000000000 --- a/en/tutorials/ddwg/ddwg.sgml +++ /dev/null @@ -1,1142 +0,0 @@ - - - - -
- -FreeBSD Device Driver Writer's Guide -<author>Eric L. Hernes, <tt/erich@rrnet.com/ -<date>Wednesday, May 29, 1996 - -<abstract> - -This document describes how to add a device driver to FreeBSD. It is -<it/not/ intended to be a tutorial on UNIX device drivers in general. -It is intended for device driver authors, familiar with the UNIX -device driver model, to work on FreeBSD. - -</abstract> - -<toc> - -<sect> Overview - -<p> <it> -The FreeBSD kernel is very well documented, unfortunately it's all -in `C'. -</it> - -<sect> Types of drivers. - -<sect1> Character - -<sect2> Data Structures -<p> <tt/struct cdevsw/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> -d_open() takes several arguments, the formal list looks something like: -<code> -int -d_open(dev_t dev, int flag, int mode, struct proc *p) -</code> -d_open() is called on <em/every/ open of the device. -<p> - -The <tt/dev/ argument contains the major and minor number of the -device opened. These are available through the macros <tt/major()/ and -<tt/minor()/ -<p> - -The <tt/flag/ and <tt/mode/ arguments are as described in the -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?open(2)" name="open(2)"> -manual page. It is recommended that you check these for access modes -in <sys/fcntl.h> and do what is required. For example if <tt/flag/ -is (O_NONBLOCK | O_EXLOCK) the open should fail if either it would -block, or exclusive access cannot be granted. -<p> - -The <tt/p/ argument contains all the information about the current -process. - -<sect3> d_close() -<p> -d_close() takes the same argument list as d_open(): -<code> -int -d_close(dev_t dev , int flag , int mode , struct proc *p) -</code> - -d_close() is only called on the last close of your device (per minor -device). For example in the following code fragment, d_open() is called -3 times, but d_close() is called only once. -<code> - ... - fd1=open("/dev/mydev", O_RDONLY); - fd2=open("/dev/mydev", O_RDONLY); - fd3=open("/dev/mydev", O_RDONLY); - ... - <useful stuff with fd1, fd2, fd3 here> - ... - close(fd1); - close(fd2); - close(fd3); - ... -</code> - -The arguments are similar to those described above for -d_open(). - -<sect3> d_read() and d_write() -<p> -d_read() and d_write take the following argument lists: -<code> -int -d_read(dev_t dev, struct uio *uio, int flat) -int -d_write(dev_t dev, struct uio *uio, int flat) -</code> - -The d_read() and d_write() entry points are called when -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?read(2)" name="read(2)"> and -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?write(2)" name="write(2)"> -are called on your device from user-space. The transfer -of data can be handled through the kernel support routine uiomove(). - -<sect3> d_ioctl() -<p> -It's argument list is as follows: -<code> -int -d_ioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p) -</code> - -d_ioctl() is a catch-all for operations which don't make sense in -a read/write paradigm. Probably the most famous of all ioctl's is on -tty devices, through -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?stty(1)" name="stty(1)">. -The ioctl entry point is called from -ioctl() in sys/kern/sys_generic.c<p> - -There are four different types of ioctl's which can be implemented. -<sys/ioccom.h> contains convenience macros for defining these ioctls. - -<tt/_IO(g,n)/ for control type operations. &nl; - -<tt/_IOR(g,n,t)/ for operations that read data from a device. &nl; - -<tt/_IOW(g,n,t)/ for operations that write data to a device. &nl; - -<tt/_IOWR(g,n,t)/ for operations that write to a device, and then -read data back. &nl; - -Here <tt/g/ refers to a <em/group/. This is an 8-bit value, typically -indicative of the device; for example, 't' is used in tty ioctls. -<tt/n/ refers to the number of the ioctl within the group. On SCO, this -number alone denotes the ioctl. <tt/t/ is the data type which will -get passed to the driver; this gets handed to a sizeof() operator in -the kernel. The ioctl() system call will either copyin() or copyout() -or both for your driver, then hand you a pointer to the data structure -in the <tt/arg/ argument of the d_ioctl call. Currently the data size -is limited to one page (4k on the i386). - -<sect3> d_stop() -<sect3> d_reset() -<sect3> d_devtotty() -<sect3> d_select() -<sect3> d_mmap() -<sect3> d_strategy() -<p> -d_strategy()'s argument list is as follows: -<code> -void -d_strategy(struct buf *bp) -</code> - -<p> d_strategy() is used for devices which use some form of scatter-gather -io. It is most common in a block device. This is significantly different -than the System V model, where only the block driver performs scatter-gather -io. Under BSD, character devices are sometimes requested to perform -scatter-gather io via the readv() and writev() system calls. - -<sect2> Header Files - -<sect1> Block -<sect2> Data Structures -<p> <tt/struct bdevsw/ Structure -<p> <tt/struct buf/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> Described in the Character device section. - -<sect3> d_close() -<p> Described in the Character device section. - -<sect3> d_strategy() -<p> Described in the Character device section. - -<sect3> d_ioctl() -<p> Described in the Character device section. - -<sect3> d_dump() - -<sect3> d_psize() - -<sect2> Header Files - -<sect1> Network -<sect2> Data Structures -<p> <tt/struct ifnet/ Structure - -<sect2> Entry Points -<sect3> if_init() -<sect3> if_output() -<sect3> if_start() -<sect3> if_done() -<sect3> if_ioctl() -<sect3> if_watchdog() - -<sect2> Header Files - -<sect1> Line Discipline -<sect2> Data Structures - -<p> <tt/struct linesw/ Structure - -<sect2> Entry Points -<sect3> l_open() -<sect3> l_close() -<sect3> l_read() -<sect3> l_write() -<sect3> l_ioctl() -<sect3> l_rint() -<sect3> l_start() -<sect3> l_modem() - -<sect2> Header Files - -<sect> Supported Busses - -<sect1> ISA -- Industry Standard Architecture -<sect2> Data Structures - -<sect3> <tt/struct isa_device/ Structure -<p> -This structure is required, but generally it is created by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -from the kernel configuration file. It is required on a per-device -basis, meaning that if you have a driver which controls two serial -boards, you will have two isa_device structures. If you build a -device as an LKM, you must create your own isa_device structure to -reflect your configuration. (lines 85 - 131 in pcaudio_lkm.c) There is -nearly a direct mapping between the config file and the isa_device -structure. The definition from /usr/src/sys/i386/isa/isa_device.h is: -<code> -struct isa_device { - int id_id; /* device id */ - struct isa_driver *id_driver; - int id_iobase; /* base i/o address */ - u_short id_irq; /* interrupt request */ - short id_drq; /* DMA request */ - caddr_t id_maddr; /* physical i/o memory address on bus (if any)*/ - int id_msize; /* size of i/o memory */ - inthand2_t *id_intr; /* interrupt interface routine */ - int id_unit; /* unit number */ - int id_flags; /* flags */ - int id_scsiid; /* scsi id if needed */ - int id_alive; /* device is present */ -#define RI_FAST 1 /* fast interrupt handler */ - u_int id_ri_flags; /* flags for register_intr() */ - int id_reconfig; /* hot eject device support (such as PCMCIA) */ - int id_enabled; /* is device enabled */ - int id_conflicts; /* we're allowed to conflict with things */ - struct isa_device *id_next; /* used in isa_devlist in userconfig() */ -}; -</code> - -<!-- XXX add stuff here --> -<sect3> <tt/struct isa_driver/ Structure - -<p> -This structure is defined in ``/usr/src/sys/i386/isa/isa_device.h''. -These are required on a per-driver basis. The definition is: -<code> -struct isa_driver { - int (*probe) __P((struct isa_device *idp)); - /* test whether device is present */ - int (*attach) __P((struct isa_device *idp)); - /* setup driver for a device */ - char *name; /* device name */ - int sensitive_hw; /* true if other probes confuse us */ -}; -</code> - -This is the structure used by the probe/attach code to detect and -initialize your device. The <tt/probe/ member is a pointer to your -device probe function; the <tt/attach/ member is a pointer to your -attach function. The <tt/name/ member is a character pointer to the -two or three letter name for your driver. This is the name reported -during the probe/attach process (and probably also in -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?lsdev(8)" name="lsdev(8)">). The -<tt/sensitive_hw/ member is a flag which helps the probe code -determine probing order. - -A typical instantiation is: -<code> -struct isa_driver mcddriver = { mcd_probe, mcd_attach, "mcd" }; -</code> - -<sect2> Entry Points - -<sect3> probe() -<p> -probe() takes a <tt/struct isa_device/ pointer as an argument and returns -an int. The return value is ``zero'' or ``non-zero'' as to the absence -or presence of your device. This entry point may (and probably should) -be declared as <tt/static/ because it is accessed via the <tt/probe/ member -of the <tt/struct isa_driver/ structure. This function is intended -to detect the presence of your device only; it should not do any -configuration of the device itself. - -<sect3> attach() -<p> -attach() also takes a <tt/struct isa_device/ pointer as an argument and -returns an int. The return value is also ``zero'' or ``non-zero'' indicating -whether or not the attach was successful. This function is intended -to do any special initialization of the device as well as confirm that -the device is usable. It too should be declared <tt/static/ because -it is accessed through the <tt/attach/ member of the <tt/isa_driver/ -structure. - -<sect2> Header Files - -<sect1> EISA -- Extended Industry Standard Architecture - -<sect2> Data Structures - -<p> <tt/struct eisa_dev/ Structure -<p> <tt/struct isa_driver/ Structure - -<sect2> Entry Points - -<sect3> probe() -<p> Described in the ISA device section. - -<sect3> attach() -<p> Described in the ISA device section. - -<sect2> Header Files - -<sect1> PCI -- Peripheral Computer Interconnect -<sect2> Data Structures - -<p> <tt/struct pci_device/ Structure - - name: The short device name. - - probe: Checks if the driver can support a device - with this type. The tag may be used to get - more info with pci_read_conf(). See below. - It returns a string with the device's name, - or a NULL pointer, if the driver cannot - support this device. - - attach: Allocate a control structure and prepare - it. This function may use the PCI mapping - functions. See below. - (configuration id) or type. - - count: A pointer to a unit counter. - It's used by the PCI configurator to - allocate unit numbers. - -<sect2> Entry Points - -<sect3> probe() - -<sect3> attach() - -<sect3> shutdown() - -<sect2> Header Files - -<sect1> SCSI -- Small Computer Systems Interface -<sect2> Data Structures - -<p> <tt/struct scsi_adapter/ Structure -<p> <tt/struct scsi_device/ Structure -<p> <tt/struct scsi_ctlr_config/ Structure -<p> <tt/struct scsi_device_config/ Structure -<p> <tt/struct scsi_link/ Structure - -<sect2> Entry Points -<sect3> attach() -<sect3> init() - -<sect2> Header Files - -<sect1> PCCARD (PCMCIA) -<sect2> Data Structures -<p> <tt/struct slot_cont/ Structure -<p> <tt/struct pccard_drv/ Structure -<p> <tt/struct pccard_dev/ Structure -<p> <tt/struct slot/ Structure - -<sect2> Entry Points -<sect3> handler() -<sect3> unload() -<sect3> suspend() -<sect3> init() - -<sect2> Header Files - a. <pccard/slot.h> - -<sect> Linking Into the Kernel. - -<p> -In FreeBSD, support for the ISA and EISA busses is i386 specific. -While FreeBSD itself is presently available on the i386 platform, -some effort has been made to make the PCI, PCCARD, and SCSI code -portable. The ISA and EISA specific code resides in -/usr/src/sys/i386/isa and /usr/src/sys/i386/eisa respectively. -The machine independent PCI, PCCARD, and SCSI code reside in -/usr/src/sys/{pci,pccard,scsi}. The i386 specific code for these -reside in /usr/src/sys/i386/{pci,pccard,scsi}. - -<p> -In FreeBSD, a device driver can be either binary or source. There is -no ``official'' place for binary drivers to reside. BSD/OS uses -something like sys/i386/OBJ. Since most drivers are distributed -in source, the following discussion refers to a source driver. -Binary only drivers are sometimes provided by hardware vendors -who wish to maintain the source as proprietary. - -<p> -A typical driver has the source code in one c-file, say dev.c. The -driver also can have some include files; devreg.h typically contains -public device register declarations, macros, and other driver -specific declarations. Some drivers call this devvar.h instead. -Some drivers, such as the dgb (for the Digiboard PC/Xe), -require microcode to be loaded onto the board. For the dgb driver -the microcode is compiled and dumped into a header file ala -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?file2c(1)" name="file2c(1)">. - -<p> -If the driver has data structures and ioctl's which are specific to -the driver/device, and need to be accessible from user-space, they -should be put in a separate include file which will reside in -/usr/include/machine/ (some of these reside in /usr/include/sys/). -These are typically named something like ioctl_dev.h or devio.h. - -<p> -If a driver is being written which, from user space is -identical to a device which already exists, care should be taken to -use the same ioctl interface and data structures. For example, from -user space, a SCSI CDROM drive should be identical to an IDE cdrom -drive; or a serial line on an intelligent multiport card (Digiboard, -Cyclades, ...) should be identical to the sio devices. These devices -have a fairly well defined interface which should be used. - -<p> -There are two methods for linking a driver into the kernel, static and -the LKM model. The first method is fairly standard across the -*BSD family. The other method was originally developed by Sun -(I believe), and has been implemented into BSD using the Sun model. -I don't believe that the current implementation uses any Sun code. - -<sect1> Standard Model - -<p> -The steps required to add your driver to the standard FreeBSD kernel are -<itemize> -<item> Add to the driver list -<item> Add an entry to the [bc]devsw -<item> Add the driver entry to the kernel config file -<item> <htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)">, -compile, and install the kernel -<item> make required nodes. -<item> reboot. -</itemize> - -<sect2> Adding to the driver list. -<p> -The standard model for adding a device driver to the Berkeley kernel -is to add your driver to the list of known devices. This list is -dependent on the CPU architecture. If the device is not i386 specific -(PCCARD, PCI, SCSI), the file is in ``/usr/src/sys/conf/files''. -If the device is i386 specific, use ``/usr/src/sys/i386/conf/files.i386''. -A typical line looks like: -<tscreen><code> -i386/isa/joy.c optional joy device-driver -</code></tscreen> - -The first field is the pathname of the driver module relative to -/usr/src/sys. For the case of a binary driver the path would be -something like ``i386/OBJ/joy.o''. - -The second field tells -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -that this is an optional driver. Some -devices are required for the kernel to even be built. - -The third field is the name of the device. - -The fourth field tells config that it's a device driver (as opposed to -just optional). This causes config to create entries for the device -in some structures in /usr/src/sys/compile/KERNEL/ioconf.c. - -It is also possible to create a file -``/usr/src/sys/i386/conf/files.KERNEL'' whose contents will override -the default files.i386, but only for the kernel ``KERNEL''. - -<sect2>Make room in conf.c -<p> -Now you must edit ``/usr/src/sys/i386/i386/conf.c'' to make an entry -for your driver. Somewhere near the top, you need to declare your -entry points. The entry for the joystick driver is: -<code> -#include "joy.h" -#if NJOY > 0 -d_open_t joyopen; -d_close_t joyclose; -d_rdwr_t joyread; -d_ioctl_t joyioctl; -#else -#define joyopen nxopen -#define joyclose nxclose -#define joyread nxread -#define joyioctl nxioctl -#endif -</code> - -This either defines your entry points, or null entry points which -will return ENXIO when called (the #else clause). - -The include file ``joy.h'' is automatically generated by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> when -the kernel build tree is created. This usually has only one line like: -<code> -#define NJOY 1 -</code> -or -<code> -#define NJOY 0 -</code> -which defines the number of your devices in your kernel. - -You must additionally add a slot to either cdevsw[&rsqb, or to -bdevsw[&rsqb, depending on whether it is a character device or -a block device, or both if it is a block device with a raw interface. -The entry for the joystick driver is: - -<code> -/* open, close, read, write, ioctl, stop, reset, ttys, select, mmap, strat */ -struct cdevsw cdevsw[] = -{ - ... - { joyopen, joyclose, joyread, nowrite, /*51*/ - joyioctl, nostop, nullreset, nodevtotty,/*joystick */ - seltrue, nommap, NULL}, - ... -} -</code> - -Order is what determines the major number of your device. Which is why -there will always be an entry for your driver, either null entry -points, or actual entry points. It is probably worth noting that this -is significantly different from SCO and other system V derivatives, -where any device can (in theory) have any major number. This is -largely a convenience on FreeBSD, due to the way device nodes are -created. More on this later. - -<sect2>Adding your device to the config file. -<p> -This is simply adding a line describing your device. -The joystick description line is: -<verb> -device joy0 at isa? port "IO_GAME" -</verb> -This says we have a device called ``joy0'' on the isa bus using -io-port ``IO_GAME'' (IO_GAME is a macro defined in -/usr/src/sys/i386/isa/isa.h). - -A slightly more complicated entry is for the ``ix'' driver: -<verb> -device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr -</verb> -This says that we have a device called `ix0' on the ISA bus. It uses -io-port 0x300. It's interrupt will be masked with other devices in -the network class. It uses interrupt 10. It uses -32k of shared memory at physical address 0xd0000. It also defines -it's interrupt handler to be ``ixintr()'' - -<sect2><htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -the kernel. -<p> -Now with our config file in hand, we can create a kernel compile directory. -This is done by simply typing: -<verb> -# config KERNEL -</verb> -where KERNEL is the name of your config file. Config creates a -compile tree for you kernel in /usr/src/sys/compile/KERNEL. It -creates the Makefile, some .c files, and some .h files with macros -defining the number of each device in your kernel. - -Now you can go to the compile directory and build. Each time you run -config, your previous build tree will be removed, unless you config -with a -n. If you have config'ed and compiled a GENERIC kernel, you can -``make links'' to avoid compiling a few files on each iteration. I typically -run -<verb> -# make depend links all -</verb> -followed by a ``make install'' when the kernel is done to my liking. - -<sect2>Making device nodes. -<p> -On FreeBSD, you are responsible for making your own device nodes. The -major number of your device is determined by the slot number in the -device switch. Minor number is driver dependent, of course. You can -either run the mknod's from the command line, or add a section to -/dev/MAKEDEV.local, or even /dev/MAKEDEV to do the work. I sometimes -create a MAKEDEV.dev script that can be run stand-alone or pasted -into /dev/MAKEDEV.local - -<sect2>Reboot. -<p> -This is the easy part. There are a number of ways to do this, reboot, -fastboot, shutdown -r, cycle the power, etc. Upon bootup you should -see your XXprobe() called, and if all is successful, your XXattach() -too. - -<sect1> Loadable Kernel Module (LKM) - -<p> -There are really no defined procedures for writing an LKM driver. The -following is my own conception after experimenting with the LKM device -interface and looking at the standard device driver model, this is one -way of adding an LKM interface to an existing driver without touching -the original driver source (or binary). It is recommended though, -that if you plan to release source to your driver, the LKM specific -parts should be part of the driver itself, conditionally compiled -on the LKM macro (i.e. #ifdef LKM). - -This section will focus on writing the LKM specific part of the driver. We -will assume that we have written a driver which will drop into the standard -device driver model, which we would now like to implement as an LKM. We will -use the pcaudio driver as a sample driver, and develop an LKM front-end. The -source and makefile for the pcaudio LKM, ``pcaudio_lkm.c'' and ``Makefile'', -should be placed in /usr/src/lkm/pcaudio. What follows is a breakdown of -pcaudio_lkm.c. - -Lines 17 - 26 - - -- This includes the file ``pca.h'' and conditionally compiles the rest -of the LKM on whether or not we have a pcaudio device defined. This -mimics the behavior of config. In a standard device driver, -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -generates the pca.h file from the number pca devices in the config file. -<code> - 17 /* - 18 * figure out how many devices we have.. - 19 */ - 20 - 21 #include "pca.h" - 22 - 23 /* - 24 * if we have at least one ... - 25 */ - 26 #if NPCA > 0 -</code> - -Lines 27 - 37 - - -- Includes required files from various include directories. -<code> - 27 #include <sys/param.h> - 28 #include <sys/systm.h> - 29 #include <sys/exec.h> - 30 #include <sys/conf.h> - 31 #include <sys/sysent.h> - 32 #include <sys/lkm.h> - 33 #include <sys/errno.h> - 34 #include <i386/isa/isa_device.h> - 35 #include <i386/isa/isa.h> - 36 - 37 -</code> - -Lines 38 - 51 - - -- Declares the device driver entry points as external. -<code> - 38 /* - 39 * declare your entry points as externs - 40 */ - 41 - 42 extern int pcaprobe(struct isa_device *); - 43 extern int pcaattach(struct isa_device *); - 44 extern int pcaopen(dev_t, int, int, struct proc *); - 45 extern int pcaclose(dev_t, int, int, struct proc *); - 46 extern int pcawrite(dev_t, struct uio *, int); - 47 extern int pcaioctl(dev_t, int, caddr_t); - 48 extern int pcaselect(dev_t, int, struct proc *); - 49 extern void pcaintr(struct clockframe *); - 50 extern struct isa_driver pcadriver; - 51 -</code> - -Lines 52 - 70 - - -- This is creates the device switch entry table for your driver. -This table gets swapped wholesale into the system device switch at -the location specified by your major number. In the standard model, -these are in /usr/src/sys/i386/i386/conf.c. NOTE: you cannot pick a -device major number higher than what exists in conf.c, for example at -present, conf.c rev 1.85, there are 67 slots for character devices, -you cannot use a (character) major device number 67 or greater, -without first reserving space in conf.c. -<code> - 52 /* - 53 * build your device switch entry table - 54 */ - 55 - 56 static struct cdevsw pcacdevsw = { - 57 (d_open_t *) pcaopen, /* open */ - 58 (d_close_t *) pcaclose, /* close */ - 59 (d_rdwr_t *) enodev, /* read */ - 60 (d_rdwr_t *) pcawrite, /* write */ - 61 (d_ioctl_t *) pcaioctl, /* ioctl */ - 62 (d_stop_t *) enodev, /* stop?? */ - 63 (d_reset_t *) enodev, /* reset */ - 64 (d_ttycv_t *) enodev, /* ttys */ - 65 (d_select_t *) pcaselect, /* select */ - 66 (d_mmap_t *) enodev, /* mmap */ - 67 (d_strategy_t *) enodev /* strategy */ - 68 }; - 69 - 70 -</code> - -Lines 71 - 131 - - -- This section is analogous to the config file declaration of your -device. The members of the isa_device structure are filled in by what -is known about your device, I/O port, shared memory segment, etc. We -will probably never have a need for two pcaudio devices in the kernel, -but this example shows how multiple devices can be supported. -<code> - 71 /* - 72 * this lkm arbitrarily supports two - 73 * instantiations of the pc-audio device. - 74 * - 75 * this is for illustration purposes - 76 * only, it doesn't make much sense - 77 * to have two of these beasts... - 78 */ - 79 - 80 - 81 /* - 82 * these have a direct correlation to the - 83 * config file entries... - 84 */ - 85 struct isa_device pcadev[NPCA] = { - 86 { - 87 11, /* device id */ - 88 &pcadriver, /* driver pointer */ - 89 IO_TIMER1, /* base io address */ - 90 -1, /* interrupt */ - 91 -1, /* dma channel */ - 92 (caddr_t)-1, /* physical io memory */ - 93 0, /* size of io memory */ - 94 pcaintr , /* interrupt interface */ - 95 0, /* unit number */ - 96 0, /* flags */ - 97 0, /* scsi id */ - 98 0, /* is alive */ - 99 0, /* flags for register_intr */ - 100 0, /* hot eject device support */ - 101 1 /* is device enabled */ - 102 }, - 103 #if NPCA >1 - 104 { - 105 - 106 /* - 107 * these are all zeros, because it doesn't make - 108 * much sense to be here - 109 * but it may make sense for your device - 110 */ - 111 - 112 0, /* device id */ - 113 &pcadriver, /* driver pointer */ - 114 0, /* base io address */ - 115 -1, /* interrupt */ - 116 -1, /* dma channel */ - 117 -1, /* physical io memory */ - 118 0, /* size of io memory */ - 119 NULL, /* interrupt interface */ - 120 1, /* unit number */ - 121 0, /* flags */ - 122 0, /* scsi id */ - 123 0, /* is alive */ - 124 0, /* flags for register_intr */ - 125 0, /* hot eject device support */ - 126 1 /* is device enabled */ - 127 }, - 128 #endif - 129 - 130 }; - 131 -</code> - -Lines 132 - 139 - - -- This calls the C-preprocessor macro MOD_DEV, which sets up an LKM device -driver, as opposed to an LKM filesystem, or an LKM system call. -<code> - 132 /* - 133 * this macro maps to a function which - 134 * sets the LKM up for a driver - 135 * as opposed to a filesystem, system call, or misc - 136 * LKM. - 137 */ - 138 MOD_DEV("pcaudio_mod", LM_DT_CHAR, 24, &pcacdevsw); - 139 -</code> - -Lines 140 - 168 - - -- This is the function which will be called when the driver is -loaded. This function tries to work like sys/i386/isa/isa.c -which does the probe/attach calls for a driver at boot time. The -biggest trick here is that it maps the physical address of the shared -memory segment, which is specified in the isa_device structure to a -kernel virtual address. Normally the physical address is put in the -config file which builds the isa_device structures in -/usr/src/sys/compile/KERNEL/ioconf.c. The probe/attach sequence of -/usr/src/sys/isa/isa.c translates the physical address to a virtual -one so that in your probe/attach routines you can do things like -<verb> -(int *)id->id_maddr = something; -</verb> -and just refer to the shared memory segment via pointers. -<code> - 140 /* - 141 * this function is called when the module is - 142 * loaded; it tries to mimic the behavior - 143 * of the standard probe/attach stuff from - 144 * isa.c - 145 */ - 146 int - 147 pcaload(){ - 148 int i; - 149 uprintf("PC Audio Driver Loaded\n"); - 150 for (i=0; i<NPCA; i++){ - 151 /* - 152 * this maps the shared memory address - 153 * from physical to virtual, to be - 154 * consistent with the way - 155 * /usr/src/sys/i386/isa.c handles it. - 156 */ - 157 pcadev[i].id_maddr -=0xa0000; - 158 pcadev[i].id_maddr += atdevbase; - 159 if ((*pcadriver.probe)(pcadev+i)) { - 160 (*(pcadriver.attach))(pcadev+i); - 161 } else { - 162 uprintf("PC Audio Probe Failed\n"); - 163 return(1); - 164 } - 165 } - 166 return 0; - 167 } - 168 -</code> - -Lines 169 - 179 - - -- This is the function called when your driver is unloaded; it just displays -a message to that effect. -<code> - 169 /* - 170 * this function is called - 171 * when the module is unloaded - 172 */ - 173 - 174 int - 175 pcaunload(){ - 176 uprintf("PC Audio Driver Unloaded\n"); - 177 return 0; - 178 } - 179 -</code> - -Lines 180 - 190 - - -- This is the entry point which is specified on the command line of the -modload. By convention it is named <dev>_mod. This is how it is -defined in bsd.lkm.mk, the makefile which builds the LKM. If you name your -module following this convention, you can do ``make load'' and ``make -unload'' from /usr/src/lkm/pcaudio. <p> -Note: this has gone through <em/many/ revisions from release 2.0 to 2.1. -It may or may not be possible to write a module which is portable across -all three releases. <p> -<code> - 180 /* - 181 * this is the entry point specified - 182 * on the modload command line - 183 */ - 184 - 185 int - 186 pcaudio_mod(struct lkm_table *lkmtp, int cmd, int ver) - 187 { - 188 DISPATCH(lkmtp, cmd, ver, pcaload, pcaunload, nosys); - 189 } - 190 - 191 #endif /* NICP > 0 */ -</code> - -<sect1> Device Type Idiosyncrasies -<sect2> Character -<sect2> Block -<sect2> Network -<sect2> Line Discipline - -<sect1> Bus Type Idiosyncrasies -<sect2> ISA -<sect2> EISA -<sect2> PCI -<sect2> SCSI -<sect2> PCCARD - -<sect> Kernel Support - -<sect1> Data Structures - -<sect2> <tt/struct kern_devconf/ Structure -<p> - -This structure contains some information about the state of the device -and driver. It is defined in /usr/src/sys/sys/devconf.h as: -<code> -struct devconf { - char dc_name[MAXDEVNAME]; /* name */ - char dc_descr[MAXDEVDESCR]; /* description */ - int dc_unit; /* unit number */ - int dc_number; /* unique id */ - char dc_pname[MAXDEVNAME]; /* name of the parent device */ - int dc_punit; /* unit number of the parent */ - int dc_pnumber; /* unique id of the parent */ - struct machdep_devconf dc_md; /* machine-dependent stuff */ - enum dc_state dc_state; /* state of the device (see above) */ - enum dc_class dc_class; /* type of device (see above) */ - size_t dc_datalen; /* length of data */ - char dc_data[1]; /* variable-length data */ -}; -</code> - -<sect2> <tt/struct proc/ Structure -<p> - -This structure contains all the information about a process. -It is defined in /usr/src/sys/sys/proc.h: -<code> -/* - * Description of a process. - * - * This structure contains the information needed to manage a thread of - * control, known in UN*X as a process; it has references to substructures - * containing descriptions of things that the process uses, but may share - * with related processes. The process structure and the substructures - * are always addressable except for those marked "(PROC ONLY)" below, - * which might be addressable only on a processor on which the process - * is running. - */ -struct proc { - struct proc *p_forw; /* Doubly-linked run/sleep queue. */ - struct proc *p_back; - struct proc *p_next; /* Linked list of active procs */ - struct proc **p_prev; /* and zombies. */ - - /* substructures: */ - struct pcred *p_cred; /* Process owner's identity. */ - struct filedesc *p_fd; /* Ptr to open files structure. */ - struct pstats *p_stats; /* Accounting/statistics (PROC ONLY). */ struct plimit *p_limit; /* Process limits. */ - struct vmspace *p_vmspace; /* Address space. */ - struct sigacts *p_sigacts; /* Signal actions, state (PROC ONLY). */ - -#define p_ucred p_cred->pc_ucred -#define p_rlimit p_limit->pl_rlimit - - int p_flag; /* P_* flags. */ - char p_stat; /* S* process status. */ - char p_pad1[3]; - - pid_t p_pid; /* Process identifier. */ - struct proc *p_hash; /* Hashed based on p_pid for kill+exit+... */ - struct proc *p_pgrpnxt; /* Pointer to next process in process group. */ - struct proc *p_pptr; /* Pointer to process structure of parent. */ - struct proc *p_osptr; /* Pointer to older sibling processes. */ - -/* The following fields are all zeroed upon creation in fork. */ -#define p_startzero p_ysptr - struct proc *p_ysptr; /* Pointer to younger siblings. */ - struct proc *p_cptr; /* Pointer to youngest living child. */ - pid_t p_oppid; /* Save parent pid during ptrace. XXX */ - int p_dupfd; /* Sideways return value from fdopen. XXX */ - - /* scheduling */ - u_int p_estcpu; /* Time averaged value of p_cpticks. */ - int p_cpticks; /* Ticks of cpu time. */ - fixpt_t p_pctcpu; /* %cpu for this process during p_swtime */ - void *p_wchan; /* Sleep address. */ - char *p_wmesg; /* Reason for sleep. */ - u_int p_swtime; /* Time swapped in or out. */ - u_int p_slptime; /* Time since last blocked. */ - - struct itimerval p_realtimer; /* Alarm timer. */ - struct timeval p_rtime; /* Real time. */ - u_quad_t p_uticks; /* Statclock hits in user mode. */ - u_quad_t p_sticks; /* Statclock hits in system mode. */ - u_quad_t p_iticks; /* Statclock hits processing intr. */ - - int p_traceflag; /* Kernel trace points. */ - struct vnode *p_tracep; /* Trace to vnode. */ - - int p_siglist; /* Signals arrived but not delivered. */ - - struct vnode *p_textvp; /* Vnode of executable. */ - - char p_lock; /* Process lock (prevent swap) count. */ - char p_pad2[3]; /* alignment */ - -/* End area that is zeroed on creation. */ -#define p_endzero p_startcopy - -/* The following fields are all copied upon creation in fork. */ -#define p_startcopy p_sigmask - - sigset_t p_sigmask; /* Current signal mask. */ - sigset_t p_sigignore; /* Signals being ignored. */ - sigset_t p_sigcatch; /* Signals being caught by user. */ - - u_char p_priority; /* Process priority. */ - u_char p_usrpri; /* User-priority based on p_cpu and p_nice. */ - char p_nice; /* Process "nice" value. */ - char p_comm[MAXCOMLEN+1]; - - struct pgrp *p_pgrp; /* Pointer to process group. */ - - struct sysentvec *p_sysent; /* System call dispatch information. */ - - struct rtprio p_rtprio; /* Realtime priority. */ -/* End area that is copied on creation. */ -#define p_endcopy p_addr - struct user *p_addr; /* Kernel virtual addr of u-area (PROC ONLY). */ - struct mdproc p_md; /* Any machine-dependent fields. */ - - u_short p_xstat; /* Exit status for wait; also stop signal. */ - u_short p_acflag; /* Accounting flags. */ - struct rusage *p_ru; /* Exit information. XXX */ -}; -</code> - -<sect2> <tt/struct buf/ Structure -<p> -The <tt/struct buf/ structure is used to interface with the buffer cache. -It is defined in /usr/src/sys/sys/buf.h: - -<code> -/* - * The buffer header describes an I/O operation in the kernel. - */ -struct buf { - LIST_ENTRY(buf) b_hash; /* Hash chain. */ - LIST_ENTRY(buf) b_vnbufs; /* Buffer's associated vnode. */ - TAILQ_ENTRY(buf) b_freelist; /* Free list position if not active. */ - struct buf *b_actf, **b_actb; /* Device driver queue when active. */ - struct proc *b_proc; /* Associated proc; NULL if kernel. */ - volatile long b_flags; /* B_* flags. */ - int b_qindex; /* buffer queue index */ - int b_error; /* Errno value. */ - long b_bufsize; /* Allocated buffer size. */ - long b_bcount; /* Valid bytes in buffer. */ - long b_resid; /* Remaining I/O. */ - dev_t b_dev; /* Device associated with buffer. */ - struct { - caddr_t b_addr; /* Memory, superblocks, indirect etc. */ - } b_un; - void *b_saveaddr; /* Original b_addr for physio. */ - daddr_t b_lblkno; /* Logical block number. */ - daddr_t b_blkno; /* Underlying physical block number. */ - /* Function to call upon completion. */ - void (*b_iodone) __P((struct buf *)); - /* For nested b_iodone's. */ - struct iodone_chain *b_iodone_chain; - struct vnode *b_vp; /* Device vnode. */ - int b_pfcent; /* Center page when swapping cluster. */ - int b_dirtyoff; /* Offset in buffer of dirty region. */ - int b_dirtyend; /* Offset of end of dirty region. */ - struct ucred *b_rcred; /* Read credentials reference. */ - struct ucred *b_wcred; /* Write credentials reference. */ - int b_validoff; /* Offset in buffer of valid region. */ - int b_validend; /* Offset of end of valid region. */ - daddr_t b_pblkno; /* physical block number */ - caddr_t b_savekva; /* saved kva for transfer while bouncing - */ - void *b_driver1; /* for private use by the driver */ - void *b_driver2; /* for private use by the driver */ - void *b_spc; - struct vm_page *b_pages[(MAXPHYS + PAGE_SIZE - 1)/PAGE_SIZE]; - int b_npages; -}; -</code> - -<sect2> <tt/struct uio/ Structure -<p> -This structure is used for moving data between the kernel and user spaces -through read() and write() system calls. It is defined in -/usr/src/sys/sys/uio.h: -<code> -struct uio { - struct iovec *uio_iov; - int uio_iovcnt; - off_t uio_offset; - int uio_resid; - enum uio_seg uio_segflg; - enum uio_rw uio_rw; - struct proc *uio_procp; -}; - -</code> - -<sect1> Functions -lots of 'em - -<sect> References. - -<p> FreeBSD Kernel Sources http://www.freebsd.org -<p> NetBSD Kernel Sources http://www.netbsd.org -<p> Writing Device Drivers: Tutorial and Reference; -Tim Burke, Mark A. Parenti, Al, Wojtas; -Digital Press, ISBN 1-55558-141-2. - -<p> Writing A Unix Device Driver; -Janet I. Egan, Thomas J. Teixeira; -John Wiley & Sons, ISBN 0-471-62859-X. - -<p> Writing Device Drivers for SCO Unix; -Peter Kettle; - -</article> diff --git a/en/tutorials/devel/Makefile b/en/tutorials/devel/Makefile deleted file mode 100644 index 72c7507f01..0000000000 --- a/en/tutorials/devel/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $ - -DOCS= devel.docb -INDEXLINK= devel.html - -.include "../../web.mk" - diff --git a/en/tutorials/devel/devel.docb b/en/tutorials/devel/devel.docb deleted file mode 100644 index 310401db55..0000000000 --- a/en/tutorials/devel/devel.docb +++ /dev/null @@ -1,1835 +0,0 @@ -<!-- $Id: devel.docb,v 1.3 1997-08-17 17:33:49 jfieber Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> -<bookinfo> -<bookbiblio> -<title>A User's Guide to FreeBSD Programming Tools - - - -James -Raynard - -
-jraynard@freebsd.org -
- - - -August 17, 1997 - - -1997 -James Raynard - - -This document is an introduction to using some of the programming -tools supplied with FreeBSD, although much of it will be applicable to -many other versions of Unix. It does not attempt to describe -coding in any detail. Most of the document assumes little or no -previous programming knowledge, although it is hoped that most -programmers will find something of value in it - - - - -Introduction<anchor id=foo> - -FreeBSD offers an excellent development environment. Compilers -for C, C++, and Fortran and an assembler come with the basic system, -not to mention a Perl interpreter and classic Unix tools such as -sed and awk. If that is not enough, there are -many more compilers and interpreters in the Ports collection. FreeBSD -is very compatible with standards such as POSIX and -ANSI C, as well with its own BSD heritage, so it is -possible to write applications that will compile and run with little -or no modification on a wide range of platforms. - -However, all this power can be rather overwhelming at first if -you've never written programs on a Unix platform before. This -document aims to help you get up and running, without getting too -deeply into more advanced topics. The intention is that this document -should give you enough of the basics to be able to make some sense of -the documentation. - -Most of the document requires little or no knowledge of -programming, although it does assume a basic competence with using -Unix and a willingness to learn! - - - - -Introduction to Programming - -A program is a set of instructions that tell the computer to do -various things; sometimes the instruction it has to perform depends -on what happened when it performed a previous instruction. This -section gives an overview of the two main ways in which you can give -these instructions, or commands as they are usually -called. One way uses an interpreter, the other a -compiler. As human languages are too difficult for a -computer to understand in an unambiguous way, commands are usually -written in one or other languages specially designed for the -purpose. - - - - -Interpreters - -With an interpreter, the language comes as an environment, where you -type in commands at a prompt and the environment executes them for -you. For more complicated programs, you can type the commands into a -file and get the interpreter to load the file and execute the commands -in it. If anything goes wrong, many interpreters will drop you into a -debugger to help you track down the problem. - -The advantage of this is that you can see the results of your -commands immediately, and mistakes can be corrected readily. The -biggest disadvantage comes when you want to share your programs with -someone. They must have the same interpreter, or you must have some -way of giving it to them, and they need to understand how to use it. -Also users may not appreciate being thrown into a debugger if they -press the wrong key! From a performance point of view, interpreters -can use up a lot of memory, and generally do not generate code as -efficiently as compilers. - -In my opinion, interpreted languages are the best way to start -if you have not done any programming before. This kind of environment -is typically found with languages like Lisp, Smalltalk, Perl and -Basic. It could also be argued that the Unix shell (sh, -csh) is itself an interpreter, and many people do in fact -write shell scripts to help with various -housekeeping tasks on their machine. Indeed, part of the -original Unix philosophy was to provide lots of small utility -programs that could be linked together in shell scripts to perform -useful tasks. - - - - -Interpreters available with FreeBSD - -Here is a list of interpreters that are available as FreeBSD -packages, with a brief discussion of some of the more popular -interpreted languages. - -To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -$ pkg_add package name - - -as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work! - - - -BASIC - -Short for Beginner's All-purpose Symbolic Instruction -Code. Developed in the 1950s for teaching University students to -program and provided with every self-respecting personal computer in -the 1980s, BASIC has been the first programming language -for many programmers. It's also the foundation for Visual -Basic. - -The Bywater -Basic Interpreter and the Phil -Cockroft's Basic Interpreter (formerly Rabbit Basic) are -available as FreeBSD FreeBSD -packages - - - -Lisp -A language that was developed in the late 1950s as an alternative to -the number-crunching languages that were popular at the time. -Instead of being based on numbers, Lisp is based on lists; in fact -the name is short for List Processing. Very popular in AI -(Artificial Intelligence) circles. - -Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. - -FreeBSD has GNU -Common Lisp available as a package. - - - - -Perl -Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing CGI -scripts. - -Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer Perl -Version 5 is available as a package. - - - - -Scheme -A dialect of Lisp that is rather more compact and -cleaner than Common Lisp. Popular in Universities as it is simple -enough to teach to undergraduates as a first language, while it has a -high enough level of abstraction to be used in research work. - -FreeBSD has packages of the -Elk Scheme Interpreter, the -MIT Scheme Interpreter and the -SCM Scheme Interpreter. - - - - -Icon -The Icon Programming Language. - - - -Logo -Brian Harvey's LOGO Interpreter. - - - -Python -The Python Object-Oriented Programming Language - - - - - - - - - -Compilers - -Compilers are rather different. First of all, you write your -code in a file (or files) using an editor. You then run the compiler -and see if it accepts your program. If it did not compile, grit your -teeth and go back to the editor; if it did compile and gave you a -program, you can run it either at a shell command prompt or in a -debugger to see if it works properly.If you run it in -the shell, you may get a core dump. - -Obviously, this is not quite as direct as using an interpreter. -However it allows you to do a lot of things which are very difficult -or even impossible with an interpreter, such as writing code which -interacts closely with the operating system—or even writing -your own operating system! It's also useful if you need to write very -efficient code, as the compiler can take its time and optimise the -code, which would not be acceptable in an interpreter. And -distributing a program written for a compiler is usually more -straightforward than one written for an interpreter—you can just -give them a copy of the executable, assuming they have the same -operating system as you. - -Compiled languages include Pascal, C and C++. C and C++ are rather -unforgiving languages, and best suited to more experienced -programmers; Pascal, on the other hand, was designed as an educational -language, and is quite a good language to start with. Unfortunately, -FreeBSD doesn't have any Pascal support, except for a Pascal-to-C -converter in the ports. - -As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (IDEs -for short). FreeBSD does not have an IDE as such; however -it is possible to use Emacs for this purpose. This is discussed in -. - - - - - -Compiling with <command>cc</command> - -This section deals only with the GNU compiler for C and C++, -since that comes with the base FreeBSD system. It can be invoked by -either cc or gcc. The details of producing a -program with an interpreter vary considerably between interpreters, -and are usually well covered in the documentation and on-line help -for the interpreter. - -Once you've written your masterpiece, the next step is to convert it -into something that will (hopefully!) run on FreeBSD. This usually -involves several steps, each of which is done by a separate -program. - - -Pre-process your source code to remove comments and do other -tricks like expanding macros in C. - - -Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! - - -Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.To be strictly -accurate, cc converts the source code into its own, -machine-independent p-code instead of assembly language -at this stage. - -Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here. - -Check that you have used things like functions and global -variables in a consistent way. For example, if you have called a -non-existent function, it will complain. - -If you are trying to produce an executable from several -source code files, work out how to fit them all together. - -Work out how to produce something that the system's run-time -loader will be able to load into memory and run. - -Finally, write the executable on the file -system. - - - -The word compiling is often used to refer to just -steps 1 to 4—the others are referred to as -linking. Sometimes step 1 is referred to as -pre-processing and steps 3-4 as -assembling. - -Fortunately, almost all this detail is hidden from you, as -cc is a front end that manages calling all these programs -with the right arguments for you; simply typing -$ cc foobar.c - -will cause foobar.c to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -$ cc foo.c bar.c - - -Note that the syntax checking is just that—checking the -syntax. It will not check for any logical mistakes you may have made, -like putting the program into an infinite loop, or using a bubble -sort when you meant to use a binary sort.In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't. - -There are lots and lots of options for cc, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them. - - - - -The output name of the file. If you do not use this -option, cc will produce an executable called -a.out.The reasons for this are buried in -the mists of history. - - -$ cc foobar.c executable is a.out -$ cc -o foobar foobar.c executable is foobar - - - - - -Just compile the file, do not link it. Useful for toy -programs where you just want to check the syntax, or if you are using -a Makefile. - - -$ cc -c foobar.c - - -This will produce an object file (not an -executable) called foobar.o. This can be linked -together with other object files into an executable. - - - - - - -Create a debug version of the executable. This makes -the compiler put information into the executable about which line of -which source file corresponds to which function call. A debugger can -use this information to show the source code as you step through the -program, which is very useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with while you are -developing a program and then compile a release -version without when you're satisfied it -works properly. - - -$ cc -g foobar.c - - -This will produce a debug version of the -program.Note, we didn't use the -flag to specify the executable name, so we will get an executable -called a.out. Producing a debug version called -foobar is left as an exercise for the -reader! - - - - - - -Create an optimised version of the executable. The -compiler performs various clever tricks to try and produce an -executable that runs faster than normal. You can add a number after -the to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of cc that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the - option in some circumstances. - -Optimisation is usually only turned on when compiling a release -version. - - -$ cc -O -o foobar foobar.c - - -This will produce an optimised version of -foobar. - - - - - -The following three flags will force cc to -check that your code complies to the relevant international standard, -often referred to as the ANSI standard, though -strictly speaking it is an ISO standard. - - - - - -Enable all the warnings which the authors of -cc believe are worthwhile. Despite the name, it -will not enable all the warnings cc is capable -of. - - - - - - -Turn off most, but not all, of the non-ANSI C -features provided by cc. Despite the name, it does -not guarantee strictly that your code will comply to the -standard. - - - - - - - -Turn off all -cc's non-ANSI C features. - - - - - -Without these flags, cc will allow you to -use some of its non-standard extensions to the standard. Some of -these are very useful, but will not work with other compilers—in -fact, one of the main aims of the standard is to allow people to -write code that will work with any compiler on any system. This is -known as portable code. - -Generally, you should try to make your code as portable as -possible, as otherwise you may have to completely re-write the -program later to get it to work somewhere else—and who knows -what you may be using in a few years time? - - -$ cc -Wall -ansi -pedantic -o foobar foobar.c - - -This will produce an executable foobar -after checking foobar.c for standard -compliance. - - - - - -Specify a function library to be used during when -linking. - -The most common example of this is when compiling a program that -uses some of the mathematical functions in C. Unlike most other -platforms, these are in a separate library from the standard C one -and you have to tell the compiler to add it. - -The rule is that if the library is called -libsomething.a, you -give cc the argument -. For example, -the math library is libm.a, so you give -cc the argument . A common -gotcha with the math library is that it has to be the -last library on the command line. - - -$ cc -o foobar foobar.c -lm - - -This will link the math library functions into -foobar. - -If you are compiling C++ code, you need to add -, or if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run c++ -instead of cc, which does this for you. -c++ can also be invoked as g++ -on FreeBSD. - - -$ cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier -$ cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later -$ c++ -o foobar foobar.cc - - -Each of these will both produce an executable -foobar from the C++ source file -foobar.cc. Note that, on Unix systems, C++ -source files traditionally end in .C, -.cxx or .cc, rather than -the MS-DOS style .cpp -(which was already used for something else). gcc -used to rely on this to work out what kind of compiler to use on the -source file; however, this restriction no longer applies, so you may -now call your C++ files .cpp with -impunity! - - - - - - -Common <command>cc</command> Queries and Problems - -Q. I am trying to write a program which uses the -sin() function and I get an error like this. -What does it mean? - -/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - - - -A. When using mathematical functions like -sin(), you have to tell cc to -link in the math library, like so: - -$ cc -o foobar foobar.c -lm - - -Q. All right, I wrote this simple program to practice using -. All it does is raise 2.1 to the power of 6. - -#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - -and I compiled it as: - -$ cc temp.c -lm - -like you said I should, but I get this when I run it: - -$ ./a.out -2.1 ^ 6 = 1023.000000 - - - -This is not the right answer! What is -going on? - -A. When the compiler sees you call a function, it checks if it -has already seen a prototype for it. If it has not, it assumes the -function returns an int, which is -definitely not what you want here. - -Q. So how do I fix this? - -A. The prototypes for the mathematical functions are in -math.h. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! - -#include <math.h> -#include <stdio.h> - -int main() { -... - - - -After recompiling it as you did before, run it: - -$ ./a.out -2.1 ^ 6 = 85.766121 - - - -If you are using any of the mathematical functions, -always include math.h and -remember to link in the math library. - -Q. I compiled a file called foobar.c and I -cannot find an executable called foobar. Where's -it gone? - -A. Remember, cc will call the executable -a.out unless you tell it differently. Use the - option: - -$ cc -o foobar foobar.c - - - -Q. OK, I have an executable called foobar, -I can see it when I run ls, but when I type in -foobar at the command prompt it tells me there is -no such file. Why can it not find it? - -A. Unlike MS-DOS, Unix does not look in the -current directory when it is trying to find out which executable you -want it to run, unless you tell it to. Either type -./foobar, which means run the file called -foobar in the current directory, or -change your PATH -environment variable so that it looks something like - -bin:/usr/bin:/usr/local/bin:. - -The dot at the end means look in the current directory if it is not in -any of the others. - -Q. I called my executable test, but -nothing happens when I run it. What is going on? - -A. Most Unix systems have a program called -test in /usr/bin and the -shell is picking that one up before it gets to checking the current -directory. Either type: - -$ ./test - -or choose a better name for your program! - -Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about core -dumped. What does that mean? - -A. The name core dump dates back to the -very early days of Unix, when the machines used core memory for -storing data. Basically, if the program failed under certain -conditions, the system would write the contents of core memory to -disk in a file called core, which the programmer -could then pore over to find out what went wrong. - -Q. Fascinating stuff, but what I am supposed to do now? - -A. Use gdb to analyse the core (see ). - -Q. When my program dumped core, it said something about a -segmentation fault. What's that? - -A. This basically means that your program tried to perform some sort -of illegal operation on memory; Unix is designed to protect the -operating system and other programs from rogue programs. - -Common causes for this are: - -Trying to write to a NULL pointer, eg -char *foo = NULL; -strcpy(foo, "bang!"); - - -Using a pointer that hasn't been initialised, eg -char *foo; -strcpy(foo, "bang!"); -The pointer will have some random value that, with luck, -will point into an area of memory that isn't available to -your program and the kernel will kill your program before -it can do any damage. If you're unlucky, it'll point -somewhere inside your own program and corrupt one of your -data structures, causing the program to fail -mysteriously. - -Trying to access past the end of an array, eg -int bar[20]; -bar[27] = 6; - - Trying to store something in read-only memory, eg -char *foo = "My string"; -strcpy(foo, "bang!"); -Unix compilers often put string literals like -"My string" into -read-only areas of memory. - -Doing naughty things with -malloc() and free(), eg -char bar[80]; -free(bar); -or -char *foo = malloc(27); -free(foo); -free(foo); - - - - -Making one of these mistakes will not always lead to an -error, but they are always bad practice. Some systems and -compilers are more tolerant than others, which is why programs -that ran well on one system can crash when you try them on an -another. - -Q. Sometimes when I get a core dump it says bus -error. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true? - -A. No, fortunately not (unless of course you really do have a hardware -problem…). This is usually another way of saying that you -accessed memory in a way you shouldn't have. - -Q. This dumping core business sounds as though it could be quite -useful, if I can make it happen when I want to. Can I do this, or -do I have to wait until there's an error? - -A. Yes, just go to another console or xterm, do -$ ps -to find out the process ID of your program, and do -$ kill -ABRT pid -where pid is the -process ID you looked up. - -This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -SIGABRT, there are several other signals which have -a similar effect. - - - - - - -Make - - -What is <command>make</command>? - -When you're working on a simple program with only one or two source -files, typing in -$ cc file1.c file2.c -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too. - -One way to get around this is to use object files and only recompile -the source file if the source code has changed. So we could have -something like: -$ cc file1.o file2.o … file37.c &hellip -if we'd changed file37.c, but not any of the -others, since the last time we compiled. This may speed up the -compilation quite a bit, but doesn't solve the typing -problem. - -Or we could write a shell script to solve the typing problem, but it -would have to re-compile everything, making it very inefficient on a -large project. - -What happens if we have hundreds of source files lying about? What if -we're working in a team with other people who forget to tell us when -they've changed one of their source files that we use? - -Perhaps we could put the two solutions together and write something -like a shell script that would contain some kind of magic rule saying -when a source file needs compiling. Now all we need now is a program -that can understand these rules, as it's a bit too complicated for the -shell. - -This program is called make. It reads in a -file, called a makefile, that tells it how -different files depend on each other, and works out which files need -to be re-compiled and which ones don't. For example, a rule could say -something like if fromboz.o is older than -fromboz.c, that means someone must have changed -fromboz.c, so it needs to be -re-compiled. The makefile also has rules telling make -how to re-compile the source file, making it a -much more powerful tool. - -Makefiles are typically kept in the same directory as the -source they apply to, and can be called -makefile, Makefile or -MAKEFILE. Most programmers use the name -Makefile, as this puts it near the top of a -directory listing, where it can easily be seen.They -don't use the MAKEFILE form as block capitals -are often used for documentation files like -README. - - - - -Example of using <command>make</command> - -Here's a very simple make file: -foo: foo.c - cc -o foo foo.c -It consists of two lines, a dependency line and a creation line. - -The dependency line here consists of the name of the program -(known as the target), followed by a colon, -then whitespace, then the name of the source file. When -make reads this line, it looks to see if -foo exists; if it exists, it compares the time -foo was last modified to the time -foo.c was last modified. If -foo does not exist, or is older than -foo.c, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when foo.c needs to be re-compiled. - -The creation line starts with a tab (press the -tab key) and then the command you would type to -create foo if you were doing it at a command -prompt. If foo is out of date, or does not -exist, make then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile foo.c. - -So, when you type make, it will make -sure that foo is up to date with respect to your -latest changes to foo.c. This principle can be -extended to Makefiles with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing make -world in the appropriate directory! - -Another useful property of makefiles is that the targets don't have -to be programs. For instance, we could have a make file that looks -like this: -foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - -We can tell make which target we want to make by typing: -$ make target -make will then only look at that target and ignore any -others. For example, if we type make foo with the -makefile above, make will ignore the install target. - -If we just type make on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed make here, it will -just go to the foo target, re-compile -foo if necessary, and then stop without going on -to the install target. - -Notice that the install target doesn't -actually depend on anything! This means that the command on the -following line is always executed when we try to make that target by -typing make install. In this case, it will -copy foo into the user's home directory. This is -often used by application makefiles, so that the application can be -installed in the correct directory when it has been correctly -compiled. - -This is a slightly confusing subject to try and explain. If you -don't quite understand how make works, the best -thing to do is to write a simple program like hello -world and a make file like the one above and experiment. Then -progress to using more than one source file, or having the source -file include a header file. The touch command is -very useful here—it changes the date on a file without you -having to edit it. - - - - -FreeBSD Makefiles - -Makefiles can be rather complicated to write. Fortunately, -BSD-based systems like FreeBSD come with some very powerful ones as -part of the system. One very good example of this is the FreeBSD -ports system. Here's the essential part of a typical ports -Makefile: -MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - -Now, if we go to the directory for this port and type -make, the following happens: - - -A check is made to see if the source code for this port is -already on the system. - -If it isn't, an FTP connection to the URL in -MASTER_SITES is set up to download the -source. - -The checksum for the source is calculated and compared it with -one for a known, good, copy of the source. This is to make sure that -the source was not corrupted while in transit. - -Any changes required to make the source work on FreeBSD are -applied—this is known as patching. - -Any special configuration needed for the source is done. -(Many Unix program distributions try to work out which version of -Unix they are being compiled on and which optional Unix features are -present—this is where they are given the information in the -FreeBSD ports scenario). - -The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -make—the program's own make file has the -necessary information to build the program. - -We now have a compiled version of the program. If we -wish, we can test it now; when we feel confident about the program, -we can type make install. This will cause the -program and any supporting files it needs to be copied into the -correct location; an entry is also made into a package -database, so that the port can easily be uninstalled later -if we change our mind about it. - - - -Now I think you'll agree that's rather impressive for a four -line script! - -The secret lies in the last line, which tells -make to look in the system makefile called -bsd.port.mk. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells make to do all the -things above (plus a couple of other things I didn't mention, -including handling any errors that may occur) and anyone can get -access to that just by putting a single line in their own make -file! - -If you want to have a look at these system makefiles, they're -in /usr/share/mk, but it's probably best to wait -until you've had a bit of practice with makefiles, as they are very -complicated (and if you do look at them, make sure you have a flask -of strong coffee handy!) - - - - -More advanced uses of <command>make</command> - -Make is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of make, and they all -differ considerably. The best way to learn what they can do is -probably to read the documentation—hopefully this introduction will -have given you a base from which you can do this. - -The version of make that comes with FreeBSD is the Berkeley -make; there is a tutorial for it in -/usr/share/doc/psd/12.make. To view it, do -$ zmore paper.ascii.gz -in that directory. - -Many applications in the ports use GNU -make, which has a very good set of info -pages. If you have installed any of these ports, GNU -make will automatically have been installed as -gmake. It's also available as a port and package -in its own right. - -To view the info pages for GNU make, -you will have to edit the dir file in the -/usr/local/info directory to add an entry for -it. This involves adding a line like - * Make: (make). The GNU Make utility. -to the file. Once you have done this, you can type -info and then select -make from the menu (or in -Emacs, do C-h -i). - - - - - -Debugging - - -The Debugger - -The debugger that comes with FreeBSD is called -gdb (GNU -debugger). You start it up by typing -$ gdb progname -although most people prefer to run it inside -Emacs. You can do this by: -M-x gdb RET progname RET - -Using a debugger allows you to run the program under more -controlled circumstances. Typically, you can step through the program -a line at a time, inspect the value of variables, change them, tell -the debugger to run up to a certain point and then stop, and so on. -You can even attach to a program that's already running, or load a -core file to investigate why the program crashed. It's even possible -to debug the kernel, though that's a little trickier than the user -applications we'll be discussing in this section. - -gdb has quite good on-line help, as well as -a set of info pages, so this section will concentrate on a few of the -basic commands. - -Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it xxgdb -in the ports collection. - -This section is intended to be an introduction to using -gdb and does not cover specialised topics such as -debugging the kernel. - - - - -Running a program in the debugger - -You'll need to have compiled the program with the - option to get the most out of using -gdb. It will work without, but you'll only see the -name of the function you're in, instead of the source code. If you -see a line like: -… (no debugging symbols found) …when -gdb starts up, you'll know that the program wasn't -compiled with the option. - -At the gdb prompt, type break -main. This will tell the debugger to skip over the -preliminary set-up code in the program and start at the beginning of -your code. Now type run to start the -program—it will start at the beginning of the set-up code and -then get stopped by the debugger when it calls -main(). (If you've ever wondered where -main() gets called from, now you know!). - -You can now step through the program, a line at a time, by -pressing n. If you get to a function call, you can -step into it by pressing s. Once you're in a -function call, you can return from stepping into a function call by -pressing f. You can also use up and -down to take a quick look at the caller. - -Here's a simple example of how to spot a mistake in a program -with gdb. This is our program (with a deliberate -mistake): -#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - - -This program sets i to be 5 -and passes it to a function bazz() which prints -out the number we gave it. - -When we compile and run the program we get -$ cc -g -o temp temp.c -$ ./temp -This is my program -anint = 4231 - -That wasn't what we expected! Time to see what's going -on!$ gdb temp -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) break main Skip the set-up code -Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main() -(gdb) run Run as far as main() -Starting program: /home/james/tmp/temp Program starts running - -Breakpoint 1, main () at temp.c:9 gdb stops at main() -(gdb) n Go to next line -This is my program Program prints out -(gdb) s step into bazz() -bazz (anint=4231) at temp.c:17 gdb displays stack frame -(gdb) - - -Hang on a minute! How did anint get to be -4231? Didn't we set it to be 5 -in main()? Let's move up to -main() and have a look. - -(gdb) up Move up call stack -#1 0x1625 in main () at temp.c:11 gdb displays stack frame -(gdb) p i Show us the value of i -$1 = 4231 gdb displays 4231 -Oh dear! Looking at the code, we forgot to initialise -i. We meant to put -… -main() { - int i; - - i = 5; - printf("This is my program\n"); -&hellip -but we left the i=5; line out. As we didn't -initialise i, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be 4231. - -gdb displays the stack frame -every time we go into or out of a function, even if we're using -up and down to move around the -call stack. This shows the name of the function and the values of -its arguments, which helps us keep track of where we are and what's -going on. (The stack is a storage area where the program stores -information about the arguments passed to functions and where to go -when it returns from a function call). - - - - -Examining a core file - -A core file is basically a file which contains the complete -state of the process when it crashed. In the good old -days, programmers had to print out hex listings of core files -and sweat over machine code manuals, but now life is a bit easier. -Incidentally, under FreeBSD and other 4.4BSD systems, a core file is -called progname.core instead of just -core, to make it clearer which program a core -file belongs to. - -To examine a core file, start up gdb in the -usual way. Instead of typing break or -run, type -(gdb) core progname.core -If you're not in the same directory as the core file, you'll have to -do dir /path/to/core/file first. - -You should see something like this: -$ gdb a.out -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) core a.out.core -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - -In this case, the program was called -a.out, so the core file is called -a.out.core. We can see that the program crashed -due to trying to access an area in memory that was not available to -it in a function called bazz. - -Sometimes it's useful to be able to see how a function was -called, as the problem could have occurred a long way up the call -stack in a complex program. The bt command causes -gdb to print out a back-trace of the call -stack: -(gdb) bt -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)The end() function is called when -a program crashes; in this case, the bazz() -function was called from main(). - - - - -Attaching to a running program - -One of the neatest features about gdb is -that it can attach to a program that's already running. Of course, -that assumes you have sufficient permissions to do so. A common -problem is when you are stepping through a program that forks, and -you want to trace the child, but the debugger will only let you trace -the parent. - -What you do is start up another gdb, use -ps to find the process ID for the child, and -do(gdb) attach pid -in gdb, and then debug as usual. - -That's all very well, you're probably thinking, -but by the time I've done that, the child process will be over -the hill and far away. Fear not, gentle reader, here's how to -do it (courtesy of the gdb info pages): -&hellip -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - &hellip -} else { /* parent */ - &hellip -Now all you have to do is attach to the child, set -PauseMode to 0, and -wait for the sleep() call to return! - - - - - -Using Emacs as a Development Environment - - -Emacs - -Unfortunately, Unix systems don't come with the kind of -everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package -integrated development environments that other systems -have.At least, not unless you pay out very large sums -of money. However, it is possible to set up your -own environment. It may not be as pretty, and it may not be quite as -integrated, but you can set it up the way you want it. And it's free. -And you have the source to it. - -The key to it all is Emacs. Now there are some people who -loathe it, but many who love it. If you're one of the former, I'm -afraid this section will hold little of interest to you. Also, you'll -need a fair amount of memory to run it—I'd recommend 8MB in -text mode and 16MB in X as the bare minimum to get reasonable -performance. - -Emacs is basically a highly customisable editor—indeed, -it has been customised to the point where it's more like an operating -system than an editor! Many developers and sysadmins do in fact -spend practically all their time working inside Emacs, leaving it -only to log out. - -It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: - - -Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc. - -Pull-down menus and online help. - -Language-dependent syntax highlighting and -indentation. - -Completely customisable. - -You can compile and debug programs within -Emacs. - -On a compilation error, you can jump to the offending -line of source code. - -Friendly-ish front-end to the info -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself. - -Friendly front-end to gdb, -allowing you to look at the source code as you step through your -program. - -You can read Usenet news and mail while your program -is compiling. - -And doubtless many more that I've overlooked. - -Emacs can be installed on FreeBSD using the Emacs -port. - -Once it's installed, start it up and do C-h -t to read an Emacs tutorial—that means hold down -the control key, press h, let go of -the control key, and then press t. -(Alternatively, you can you use the mouse to select Emacs -Tutorial from the Help menu). - -Although Emacs does have menus, it's well worth learning the -key bindings, as it's much quicker when you're editing something to -press a couple of keys than to try and find the mouse and then click -on the right place. And, when you're talking to seasoned Emacs users, -you'll find they often casually throw around expressions like -M-x replace-s RET foo RET bar RET -so it's useful to know what they mean. And in any case, Emacs has far -too many useful functions for them to all fit on the menu -bars. - -Fortunately, it's quite easy to pick up the key-bindings, as -they're displayed next to the menu item. My advice is to use the -menu item for, say, opening a file until you understand how it works -and feel confident with it, then try doing C-x C-f. When you're happy -with that, move on to another menu command. - -If you can't remember what a particular combination of keys -does, select Describe Key from the -Help menu and type it in—Emacs will tell you -what it does. You can also use the Command -Apropos menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it. - -By the way, the expression above means hold down the -Meta key, press x, release the -Meta key, type replace-s -(short for replace-string—another feature of -Emacs is that you can abbreviate commands), press the -return key, type foo (the -string you want replaced), press the return key, -type bar (the string you want to replace foo with) -and press return again. Emacs will then do the -search-and-replace operation you've just requested. - -If you're wondering what on earth the Meta key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -alt key (or if you're unlucky, the escape -key). - -Oh, and to get out of Emacs, do C-x C-c -(that means hold down the control key, press -c, press x and release the -control key). If you have any unsaved files open, -Emacs will ask you if you want to save them. (Ignore the bit in the -documentation where it says C-z is the usual way -to leave Emacs—that leaves Emacs hanging around in the -background, and is only really useful if you're on a system which -doesn't have virtual terminals). - - - - -Configuring Emacs - -Emacs does many wonderful things; some of them are built in, -some of them need to be configured. - -Instead of using a proprietary macro language for -configuration, Emacs uses a version of Lisp specially adapted for -editors, known as Emacs Lisp. This can be quite useful if you want to -go on and learn something like Common Lisp, as it's considerably -smaller than Common Lisp (although still quite big!). - -The best way to learn Emacs Lisp is to download the Emacs -Tutorial - -However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -.emacs file, which should be enough to get you -started. Just copy it into your home directory and restart Emacs if -it's already running; it will read the commands from the file and -(hopefully) give you a useful basic setup. - - - - -A sample <filename>.emacs</filename> file - -Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning. - - - - -Everything beginning with a ; is a -comment and is ignored by Emacs. - -In the first line, the --*- Emacs-Lisp -*- is so that we can -edit the .emacs file itself within Emacs and get -all the fancy features for editing Emacs Lisp. Emacs usually tries to -guess this based on the filename, and may not get it right for -.emacs. - -The tab key is bound to an -indentation function in some modes, so when you press the tab key, it -will indent the current line of code. If you want to put a -tab character in whatever you're writing, hold the -control key down while you're pressing the -tab key. - -This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename. - -Emacs already has a pre-defined function called -next-error. In a compilation output window, this -allows you to move from one compilation error to the next by doing -M-n; we define a complementary function, -previous-error, that allows you to go to a -previous error by doing M-p. The nicest feature of -all is that C-c C-c will open up the source file -in which the error occurred and jump to the appropriate -line. - - We enable Emacs's ability to act as a server, so -that if you're doing something outside Emacs and you want to edit a -file, you can just type in -$ emacsclient filename -and then you can edit the file in your Emacs!Many -Emacs users set their EDITOR environment to -emacsclient so this happens every time they need -to edit a file. - - - - - -A sample <filename>.emacs</filename> file -;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - - - - - - -Extending the Range of Languages Emacs Understands - -Now, this is all very well if you only want to program in the -languages already catered for in the .emacs file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called whizbang comes out, full of exciting -features? - -The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in .el, short for Emacs -Lisp. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -$ find /usr/ports/lang/whizbang -name "*.el" -print -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -/usr/local/share/emacs/site-lisp. - -So for example, if the output from the find command was -/usr/ports/lang/whizbang/work/misc/whizbang.el -we would do -$ cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp - - -Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -.wiz. We need to add an entry to our -.emacs file to make sure Emacs will be able to -use the information in whizbang.el. - -Find the auto-mode-alist entry in -.emacs and add a line for whizbang, such -as: -… -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -… -This means that Emacs will automatically go into -whizbang-mode when you edit a file ending in -.wiz. - -Just below this, you'll find the -font-lock-auto-mode-list entry. Add -whizbang-mode to it like so: -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") -This means that Emacs will always enable -font-lock-mode (ie syntax highlighting) when -editing a .wiz file. - -And that's all that's needed. If there's anything else you want -done automatically when you open up a .wiz file, -you can add a whizbang-mode hook (see -my-scheme-mode-hook for a simple example that -adds auto-indent). - - - - - -Further Reading - - -Brian Harvey and Matthew Wright -Simply Scheme -MIT 1994. -ISBN 0-262-08226-8 - -Randall Schwartz -Learning Perl -O'Reilly 1993 -ISBN 1-56592-042-2 - -Patrick Henry Winston and Berthold Klaus Paul Horn -Lisp (3rd Edition) -Addison-Wesley 1989 -ISBN 0-201-08319-1 - -Brian W. Kernighan and Rob Pike -The Unix Programming Environment -Prentice-Hall 1984 -ISBN 0-13-937681-X - -Brian W. Kernighan and Dennis M. Ritchie -The C Programming Language (2nd Edition) -Prentice-Hall 1988 -ISBN 0-13-110362-8 - -Bjarne Stroustrup -The C++ Programming Language -Addison-Wesley 1991 -ISBN 0-201-53992-6 - -W. Richard Stevens -Advanced Programming in the Unix Environment -Addison-Wesley 1992 -ISBN 0-201-56317-7 - -W. Richard Stevens -Unix Network Programming -Prentice-Hall 1990 -ISBN 0-13-949876-1 - - - - - diff --git a/en/tutorials/diskformat/Makefile b/en/tutorials/diskformat/Makefile deleted file mode 100644 index 158bc4d801..0000000000 --- a/en/tutorials/diskformat/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $ - -DOCS= diskformat.docb -INDEXLINK= diskformat.html - -.include "../../web.mk" - diff --git a/en/tutorials/diskformat/diskformat.docb b/en/tutorials/diskformat/diskformat.docb deleted file mode 100644 index 996485f694..0000000000 --- a/en/tutorials/diskformat/diskformat.docb +++ /dev/null @@ -1,418 +0,0 @@ - - - - - - -Formatting Media For Use With FreeBSD 2.2-RELEASE -A Tutorial - - - -Doug -White - -
dwhite@resnet.uoregon.edu
- - - - -March 1997 -This document describes how to slice, partition, and -format hard disk drives and similar media for use with FreeBSD. The -examples given have been tested under FreeBSD 2.2-GAMMA and may work -for other releases. - - - - - -Introduction & Definitions - - -Overview -Successfully adding disks to an existing system is the mark of an -experienced system administrator. Slicing, partitioning, and adding -disks requires a careful dance of proper command and name syntax. One -slipped finger and an entire disk could disappear in seconds. This -document is written in an attempt to simplify this process and avoid -accidents. Thankfully, enhancements to existing tools (notably -sysinstall) have greatly improved this process in recent releases of -FreeBSD. - -There are two possible modes of disk formatting: - - -compatibility mode: Arranging a -disk so that it has a slice table for use with other operating -systems. - -dangerously dedicated mode: -Formatting a disk with no slice table. This makes the process of -adding disks easier, however non-FreeBSD operating systems may not -accept the disk. - - - -For most cases, dedicated mode is the easiest to set up and use -in existing systems, as a new disk is usually dedicated entirely to -FreeBSD. However, compatibility mode insures optimum interoperability -with future installations at a cost of increased complexity. - -In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -/stand/sysinstall. 2.1.7-RELEASE and later -versions of sysinstall contain code to ease setup -of disks during normal system operation, mainly allowing access to the -Label and Partition editors and a Write feature which will update just -the selected disk and slice without affecting other disks. The other -method is running the tools manually from a root command line. For -dangerously dedicated mode, only three or four commands are involved -while sysinstall requires some manipulation. - - -Definitions - -UNIX disk management over the centuries has invented many new -definitions for old words. The following glossary covers the -definitions used in this document and (hopefully) for FreeBSD in -general. - - - - -compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode. - -dangerously dedicated mode: Formatting a disk with no slice -table. This makes the process of adding disks easier, however -non-FreeBSD operating systems may not accept the disk. Oppose -compatibility mode. - -disk: A circular disc, covered with magnetic or similarly -manipulable material, spun by a motor under a head. Data is stored on -the disk by changing the pattern of magnetism on the disc, which can -be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz -removables are examples of disks. - -slice: A division of a disk. Up to four slices are permitted on one -disk in the PC standard. Slices are composed of contiguous sectors. -Slices are recorded in a slice table used by the system BIOS to -locate bootable partitions. The slice table is usually called the -Partition Table in DOS parlance. Maintained by the fdisk utility. - -partition: A division of a slice. Usually used in reference -to divisions of the FreeBSD slice of a disk. Each filesystem and swap -area on a disk resides in a partition. Maintained using the disklabel -utility. - -sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data. - - - - - -Warnings & Pitfalls - -Building disks is not something to take lightly. It is quite possible -to destroy the contents of other disks in your system if the proper -precautions are not taken. - -Check your work carefully. It is very simple to destroy -the incorrect disk when working with these commands. When -in doubt consult the kernel boot output for the proper device. - -Needless to say, we are not responsible for any damage to any data -or hardware that you may experience. You work at your own risk! - - - - -Zip, Jaz, and Other Removables - -Removable disks can be formatted in the same way as normal hard -disks. It is essential to have the disk drive connected to the system -and a disk placed in the drive during startup, so the kernel can -determine the drive's geometry. Check the dmesg -output and make sure your device and the disk's size is listed. If -the kernel reports - - -Can't get the size - - -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. - - - - - -Formatting Disks in Dedicated Mode - - -Introduction - -This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture. - - - -Making Dedicated Mode Disks using Sysinstall - -/stand/sysinstall, the system installation -utility, has been expanded in recent versions to make the process of -dividing disks properly a less tiring affair. The fdisk and disklabel -editors built into sysinstall are GUI tools that remove much of the -confusion from slicing disks. For FreeBSD versions 2.1.7 and later, -this is perhaps the simplest way to slice disks. - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - -answer No. -When asked if you still want to do this, answer -Yes. -Select Write. -When warned about Writing on installed systems, answer -Yes. -Quitthe FDISK Editor and -ESCAPE back to the Index menu. -Select Label from the Index -menu. -Label as desired. For a single partition, enter -C to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used). -Enter W when done and confirm to -continue. The filesystem will be newfs'd for you, unless you select -otherwise (for news partitions you'll want to do this!). You'll get -the error: - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - - - -Making Dedicated Mode Disks Using the Command Line - - -Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin - # We only want one partition, so using slice 'c' should be fine: - newfs /dev/rwd2c - - - - - If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: - - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/r$d > /tmp/label - # Edit disklabel to add partitions: - vi /tmp/label - disklabel -B -R -r wd2 /tmp/label - # newfs partitions appropriately - - - - -Your disk is now ready for use. - - - - - -Making Compatibility Mode Disks - - -Introduction -The command line is the easiest way to make dedicated disks, and -the worst way to make compatibility disks. The command-line fdisk -utility requires higher math skills and an in-depth understanding of -the slice table, which is more than most people want to deal with. -Use sysinstall for compatibility disks, as described below. - - - - -Making Compatibility Mode Disks Using Sysinstall - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. - -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - - answer yes. -Select Write. -When asked to install the boot manager, select None with -SPACE then hit ENTER for OK. -Quit the FDISK Editor. -You'll be asked about the boot manager, select -None -again. -Select Label from the Index -menu. -Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used). -The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error: - - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - -Your new disk is now ready for use. - - - - - -Other Disk Operations - -Adding Swap Space - -As a system grows, it's need for swap space can also grow. -Although adding swap space to existing disks is very difficult, a new -disk can be partitioned with additional swap space. - -To add swap space when adding a disk to a system: - -When partitioning the disk, edit the disklabel and -allocate the amount of swap space to add in partition `b' and the -remainder in another partition, such as `a' or `e'. The size is given -in 512 byte blocks. -When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies. -Add an entry to /etc/fstab as follows: - - -/dev/wd0b none swap sw 0 0 - - -Change /dev/wd0b to the device of the newly added -space. -To make the new space immediately available, use the -swapon command. - - - -$ swapon /dev/sd0b - -swapon: added /dev/sd0b as swap space - - - - - - - - -Copying the Contents of Disks - -Submitted By: Renaud Waldura (renaud@softway.com) - -To move file from your original base disk to the fresh new one, -do: - - - -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home - - - - - - - - -Credits - - - -The author would like to thank the following individuals for -their contributions to this project: - -Darryl Okahata -(darrylo@hpnmhjw.sr.hp.com) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions. -Jordan Hubbard -(jkh@freebsd.org) for making -sysinstall useful for this type of task. -John Fieber -(jfieber@indiana.edu) for making -information and examples of the DocBook DTD on which this document is -based. -Greg Lehey (grog@freebsd.org) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. - - - - - - - - - diff --git a/en/tutorials/disklessx/Makefile b/en/tutorials/disklessx/Makefile deleted file mode 100644 index 086d200c36..0000000000 --- a/en/tutorials/disklessx/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:12 max Exp $ - -DOCS= disklessx.sgml - -.include "../../web.mk" diff --git a/en/tutorials/disklessx/disklessx.sgml b/en/tutorials/disklessx/disklessx.sgml deleted file mode 100644 index 408ae81e91..0000000000 --- a/en/tutorials/disklessx/disklessx.sgml +++ /dev/null @@ -1,266 +0,0 @@ - - - - - %includes; -]> - - - -&header; - -

By Jerry Kendall

-

(jerry@kcis.com)

- -

With the help of some 'friends' on the FreeBSD-hackers list, I have -been able to create a diskless X terminal... The creation of the X terminal -required first creating a diskless system with minimal utilities mounted -via NFS. These same steps were used to create 2 separate diskless systems. -The first is 'altair.kcis.com'. A diskless X terminal that I run on my -old 386DX-40. It has a 340Meg hard disk but, I did not want to change it. -So, it boots from 'antares.kcis.com' across a Ethernet. The second system -is a 486DX2-66. I setup a diskless FreeBSD (complete) that uses no local -disk. The server in that case is a Sun 670MP running -SunOS 4.1.3. The same setup configuration was needed for both.

- -
-NOTE: I am sure that there is stuff that needs to be added to this. Please send me any comments.... -
- -

Creating the boot floppy (On the diskless system)

- -

Since the network boot loaders will not work with some of -the TSR's and such that MS-DOS uses, it is best to create -a dedicated boot floppy OR, if you can, create an MS-DOS menu -that will (via the config.sys/autoexec.bat files) ask what -configuration to load when the system starts. The later is the -method that I use and it works great. My MS-DOS (6.x) menu is below.

-
-	---- config.sys ----
-	[menu]
-	menuitem=normal, normal
-	menuitem=unix, unix
-	[normal]
-	....
-	normal config.sys stuff
-	...
-	[unix]
-	----
-
-	---- autoexec.bat ----
-	@ECHO OFF
-	goto %config%
-
-	:normal
-	...
-	normal autoexec.bat stuff
-	...
-	goto end
-
-	:unix
-	cd \netboot
-	nb8390.com
-
-	:end
-	----
- -

Getting the network boot programs (On the server)

- -

Compile the 'net-boot' programs that are located in -/usr/src/sys/i386/boot/netboot. You should read the comments -at the top of the makefile. Adjust as required. !!!! make a -backup of the original in case it gets fobar'd !!! When the build -is done, there should be 2 MS-DOS executables, 'nb8390.com' and -'nb3c509.com'. One of these two programs will be what you need -to run on the diskless server. It will load the kernel from the -boot server. At this point, put both programs on the MS-DOS -boot floppy created earlier. - -

Determine which program to run (On the diskless system)

- -

If you know the chipset that your Ethernet adapter uses, this is -easy. If you have the NS8390 chipset, or a NS8390 based chipset, -use NB8390.COM. If you have a 3Com 509 based chipset, use the -NB3C509.COM boot program. If you are not sure which you have, -try using one, if it says 'No adapter found', try the other. -Beyond that, you are pretty much on your own. - -

Booting across the network

- -

Boot the diskless system with out any config.sys/autoexec.bat -files. try running the boot program for your Ethernet adapter.

-
		
-	My Ethernet adapter is running in WD8013 16bit mode so
-	I run NB8390.COM
-
-	C:> cd \netboot
-	C:> nb8390
-
-		Boot from Network (Y/N) ?  Y
-
-		BOOTP/TFTP/NFS bootstrap loader     ESC for menu
-
-		Searching for adapter..
-		WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66
-
-		Searching for server..
- -

At this point, my diskless system is trying to find a machine to act -as a boot server. Make note of the addr line above, you will need this -number later. Reset the diskless system and modify your config.sys and -autoexec.bat files to do these steps automatically for you. Perhaps in -a menu. If you had to run 'nb3c509.com' instead of 'nb8390.com' the -output is the same as above. If you got 'No adapter found' at the -'Searching for adapter..' message, verify that you did indeed set the -compile time defines in the makefile correctly.

- -

Allowing systems to boot across the network (On the - server)

- -

Make sure the /etc/inetd.conf file has entries for tftp and bootps. -Mine are listed below:

-
-	---- /etc/inetd.conf ----
-	tftp	dgram	udp	wait	nobody	/usr/libexec/tftpd	tftpd
-	#
-	# Additions by who ever you are
-	bootps  dgram  udp  wait  root  /usr/libexec/bootpd bootpd /etc/bootptab
-	----
-
-

If you have to change the /etc/inetd.conf file, send a HUP signal to -inetd. To do this, get the process ID of inetd with 'ps -ax | grep -inetd | grep -v grep'. Once you have it, send it a HUP signal. Do this -by 'kill -HUP <pid>'. This will force inetd to re-read its config file.

- -

Did you remember to note the 'addr' line from the output of the boot -loader on the diskless system???? Guess what, here is where you need it.

- -

Add an entry to /etc/bootptab (maybe creating the file). It should be -laid out identical to this:

- -
-	altair:\
-		:ht=ether:\
-		:ha=004001432666:\
-		:sm=255.255.255.0:\
-		:hn:\
-		:ds=199.246.76.1:\
-		:ip=199.246.76.2:\
-		:gw=199.246.76.1:\
-		:vm=rfc1048:
-
-	The lines are as follows:
-		'altair' the diskless systems name without the domain name.
-		'ht=ether' the hardware type of 'ethernet'.
-		'ha=004001432666' the hardware address (the number noted above).
-		'sm=255.255.255.0' the subnet mask.
-		'hn' tells server to send client's hostname to the client.
-		'ds=199.246.76.1' tells the client who the domain server is.
-		'ip=199.246.76.2' tells the client what it's IP address is.
-		'gw=199.246.76.1' tells the client what the default gateway is.
-		'vm=...' just leave it there...
-
-

NOTE: -****** Be sure to setup the IP addresses correctly, the addresses -above are my own......

- -

Create the directory '/tftpboot' on the server it will contain the -configuration files for the diskless systems that the server will -serve. These files will be named 'cfg.<ip>' where <ip> is the IP -address of the diskless system. The config file for 'altair' is -/tftpboot/cfg.199.246.76.2. The contents is:

- -
-	---- /tftpboot/cfg.199.246.76.2 ----
-	rootfs 199.246.76.1:/DiskLess/rootfs/altair
-	hostname altair.kcis.com
-	----
-
-

The line 'hostname altair.kcis.com' simply tells the diskless -system what its fully qualified domain name is.

- -

The line 'rootfs 199.246.76.1:/DiskLess/rootfs/altair' tells the -diskless system where its NFS mountable root filesystem is located.

- -

NOTE:!!!!! The NFS mounted root filesystem will be mounted READ ONLY.

- -

The hierarchy for the diskless system can be re-mounted allowing -read-write operations if required.

- -

I use my spare 386DX-40 as a dedicated X terminal...

- -

The hierarchy for 'altair' is:

- -
-	/
-	/bin
-	/etc
-	/tmp
-	/sbin
-	/dev
-	/dev/fd
-	/usr
-	/var
-	/var/run
-
- -

The actual list of files is:

- -
-	-r-xr-xr-x  1 root  wheel  779984 Dec 11 23:44 ./kernel
-	-r-xr-xr-x  1 root    bin  299008 Dec 12 00:22 ./bin/sh
-	-rw-r--r--  1 root  wheel     499 Dec 15 15:54 ./etc/rc
-	-rw-r--r--  1 root  wheel    1411 Dec 11 23:19 ./etc/ttys
-	-rw-r--r--  1 root  wheel     157 Dec 15 15:42 ./etc/hosts
-	-rw-r--r--  1 root    bin    1569 Dec 15 15:26 ./etc/XF86Config.altair
-	-r-x------  1 bin     bin  151552 Jun 10  1995 ./sbin/init
-	-r-xr-xr-x  1 bin     bin  176128 Jun 10  1995 ./sbin/ifconfig
-	-r-xr-xr-x  1 bin     bin  110592 Jun 10  1995 ./sbin/mount_nfs
-	-r-xr-xr-x  1 bin     bin  135168 Jun 10  1995 ./sbin/reboot
-	-r-xr-xr-x  1 root    bin   73728 Dec 13 22:38 ./sbin/mount
-	-r-xr-xr-x  1 root  wheel    1992 Jun 10  1995 ./dev/MAKEDEV.local
-	-r-xr-xr-x  1 root  wheel   24419 Jun 10  1995 ./dev/MAKEDEV
-
-

Don't forget to 'MAKEDEV all' in the 'dev' directory.

- -

My /etc/rc for 'altair' is:

- -
-	#!/bin/sh
-	#
-	PATH=/bin:/sbin
-	export PATH
-	#
-	# configure the localhost
-	/sbin/ifconfig lo0 127.0.0.1
-	#
-	# configure the ethernet card
-	/sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00
-	#
-	# mount the root filesystem via NFS
-	/sbin/mount antares:/DiskLess/rootfs/altair /
-	#
-	# mount the /usr filesystem via NFS
-	/sbin/mount antares:/DiskLess/usr /usr
-	#
-	/usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1
-	#
-	# Reboot after X exits
-	/sbin/reboot
-	#
-	# We blew up....
-	exit 1
-
- -
-

Any comments and ALL questions welcome....

- -
-Jerry Kendall
-jerry@kcis.com -
- -&footer; - - diff --git a/en/tutorials/doc.ftr b/en/tutorials/doc.ftr deleted file mode 100644 index 5f459de742..0000000000 --- a/en/tutorials/doc.ftr +++ /dev/null @@ -1,5 +0,0 @@ -
-
- www@freebsd.org -
- diff --git a/en/tutorials/doc.hdr b/en/tutorials/doc.hdr deleted file mode 100644 index f5e32a9961..0000000000 --- a/en/tutorials/doc.hdr +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - -
diff --git a/en/tutorials/fonts/Makefile b/en/tutorials/fonts/Makefile deleted file mode 100644 index 260184f87c..0000000000 --- a/en/tutorials/fonts/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= fonts.docb -INDEXLINK= fonts.html - -.include "../../web.mk" diff --git a/en/tutorials/fonts/fonts.docb b/en/tutorials/fonts/fonts.docb deleted file mode 100644 index 5948268167..0000000000 --- a/en/tutorials/fonts/fonts.docb +++ /dev/null @@ -1,723 +0,0 @@ - - - - - - - - - - -Fonts and FreeBSD -A Tutorial - - - -Dave -Bodenstab - -
imdave@synet.net
- - - - -Wed Aug 7, 1996 - -This document contains a description of the various -font files that may be used with FreeBSD and the syscons driver, X11, -Ghostscript and Groff. Cookbook examples are provided for switching -the syscons display to 80x60 mode, and for using type 1 fonts with -the above application programs. - - - - - -Introduction - -There are many sources of fonts available, and one might ask -how they might be used with FreeBSD. The answer can be found by -carefully searching the documentation for the component that one -would like to use. This is very time consuming, so this tutorial is -an attempt to provide a shortcut for others who might be -interested. - - - - -Basic terminology - -There are many different font formats and associated font file -suffixes. A few that will be addressed here are: - - -.pfa, .pfb - -Postscript type 1 fonts. The .pfa is the -Ascii form and .pfb the -Binary form. - - - -.afm - -The font metrics associated with a type 1 -font. - - - -.pfm - -The printer font metrics associated with a type 1 -font. - - - -.ttf - -A TrueType font - - - -.fot - -An indirect reference to a TrueType font (not an -actual font) - - - -.fon, .fnt - -Bitmapped screen fonts - - - - -The .fot file is used by Windows as sort -of a symbolic link to the actual TrueType font -(.ttf) file. The .fon font -files are also used by Windows. I know of no way to use this font -format with FreeBSD. - - - - -What font formats can I use? - -Which font file format is useful depends on the application -being used. FreeBSD by itself uses no fonts. Application programs -and/or drivers may make use of the font files. Here is a small cross -reference of application/driver to the font type suffixes: - - - -Driver - - - -syscons - -.fnt - - - - - - - - - -Application - - - - -Ghostscript - -.pfa, .pfb, .ttf - - - - -X11 - - -.pfa, .pfb - - - - -Groff - - -.pfa, .afm - - - - -Povray - - -.ttf - - - - - - - - - - - -The .fnt suffix is used quite frequently. -I suspect that whenever someone wanted to create a specialized font -file for their application, more often than not they chose this -suffix. Therefore, it is likely that files with this suffix are not -all the same format; specifically, the .fnt -files used by syscons under FreeBSD may not be the same format as a -.fnt file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -.fnt files other than those provided with -FreeBSD. - - - - -Setting a virtual console to 80x60 line mode - -First, a 8x8 font must be loaded. -/etc/sysconfig should contain the lines: - -# Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt - - - -The command to actually switch the mode is -vidcontrol1: - -bash$ vidcontrol VGA_80x60 - - - -Various screen orientated programs, such as -vi1, must be able to -determine the current screen dimensions. These can be set with -stty1: - -bash$ stty crt rows 60 columns 80 - - - -To make this more seamless, one can embed these commands in the -startup scripts so it takes place when the system boots. One way to -do this is: - - - -Modify /etc/sysconfig as above - - - -Add to /etc/rc.local: - -for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done - - - - -Add to /etc/profile: - -TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi - - - - - - - -References: -stty1, -vidcontrol1. - - - - -Using type 1 fonts with X11 - -X11 can use either the .pfa or the -.pfb format fonts. The X11 fonts are located in -various subdirectories under -/usr/X11R6/lib/X11/fonts. Each font file is -cross referenced to its X11 name by the contents of the -fonts.dir file in each directory. - -There is already a directory named Type1. The most -straight forward way to add a new font is to put it into this -directory. A better way is to keep all new fonts in a separate -directory and use a symbolic link to the additional font. This -allows one to more easily keep track of ones fonts without confusing -them with the fonts that were originally provided. For -example: - -Create a directory to contain the font files -bash$ mkdir -p /usr/local/share/fonts/type1 -bash$ cd /usr/local/share/fonts/type1 - -Place the .pfa, .pfb and .afm files here -One might want to keep readme files, and other documentation -for the fonts here also -bash$ cp /cdrom/fonts/atm/showboat/showboat.pfb . -bash$ cp /cdrom/fonts/atm/showboat/showboat.afm . - -Maintain an index to cross reference the fonts -bash$ echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX - - - -Now, to use a new font with X11, one must make the font file -available and update the font name files. The X11 font names look -like: - --bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style - - - -A new name needs to be created for each new font. If you have -some information from the documentation that accompanied the font, -then it could serve as the basis for creating the name. If there is -no information, then you can get some idea by using -strings1 on the font -file. For example: - -bash$ strings showboat.pfb | more -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin-- - - -Using this information, a possible name might be: - --type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - - - -The components of our name are: - - -Foundry - -Lets just name all the new fonts type1. - - - -Family - -The name of the font. - - - -Weight - -Normal, bold, medium, semibold, etc. From the -strings1 output -above, it appears that this font has a weight of -medium. - - - -Slant - -roman, italic, oblique, -etc. Since the ItalicAngle is zero, -roman will be used. - - - -Width - -Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be normal. - - - -Additional style - -Usually omitted, but this will indicate that -the font contains decorative capital letters. - - - -Spacing - -proportional or monospaced. Proportional -is used since isFixedPitch is false. - - - - - - -All of these names are arbitrary, but one should strive to be -compatible with the existing conventions. A font is referenced by -name with possible wild cards by an X11 program, so the name chosen -should make some sense. One might begin by simply using - -…-normal-r-normal-…-p-… - -as the name, and then use -xfontsel1 to examine it -and adjust the name based on the appearance of the font. - -So, to complete our example: - -Make the font accessible to X11 -bash$ cd /usr/X11R6/lib/X11/fonts/Type1 -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line. -bash$ ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq - -fonts.scale seems to be identical to fonts.dir… -bash$ cp fonts.dir fonts.scale - -Tell X11 that things have changed -bash$ xset fp rehash - -Examine the new font -bash$ xfontsel -pattern -type1-* - - - -References: -xfontsel1, -xset1, -The X Windows System in a Nutshell, O'Reilly & Associates. - - - - -Using type 1 fonts with Ghostscript - -Ghostscript references a font via its Fontmap -file. This must be modified in a similar way to the X11 -fonts.dir file. Ghostscript can use either the -.pfa or the .pfb format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: - -Put the font in Ghostscript's font directory -bash$ cd /usr/local/share/ghostscript/fonts -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit Fontmap so Ghostscript knows about the font -bash$ cd /usr/local/share/ghostscript/4.01 -bash$ ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq - -Use Ghostscript to examine the font -bash$ gs prfont.ps -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS>Showboat DoFont -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS>quit - - - -References: fonts.txt in the Ghostscript -4.01 distribution - - - - -Using type 1 fonts with Groff - -Now that the new font can be used by both X11 and Ghostscript, -how can one use the new font with groff? First of all, since we are -dealing with type 1 postscript fonts, the groff device that is -applicable is the ps device. A font file must be -created for each font that groff can use. A groff font name is just -a file in /usr/share/groff_font/devps. With our -example, the font file could be -/usr/share/groff_font/devps/SHOWBOAT. The file -must be created using tools provided by groff. - -The first tool is afmtodit. This is not normally -installed, so it must be retrieved from the source distribution. I -found I had to change the first line of the file, so I did: - -bash$ cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp -bash$ ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq - - - -This tool will create the groff font file from the metrics file -(.afm suffix.) Continuing with our -example: - -Many .afm files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines -bash$ cd /tmp -bash$ cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm - -Now create the groff font file -bash$ cd /usr/share/groff_font/devps -bash$ /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT - - - -The font can now be referenced with the name SHOWBOAT. - -If ghostscript is used to drive the printers on the system, -then nothing more needs to be done. However, if true postscript -printers are used, then the font must be down loaded to the printer -in order for the font to be used (unless the printer happens to have -the showboat font built in or on an accessible font disk.) The final -step is to create a down loadable font. The pfbtops tool -is used to create the .pfa format of the font, -and the download file is modified to reference the new -font. The download file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: - -Create the .pfa font file -bash$ pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa - -Of course, if the .pfa file is already -available, just use a symbolic link to reference it. - -Get the internal font name -bash$ fgrep internalname SHOWBOAT -internalname Showboat - -Tell groff that the font must be down loaded -bash$ ex download -:$a -Showboat showboat.pfa -. -:wq - - - -To test the font: - -bash$ cd /tmp -bash$ cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF -bash$ groff -Tps example.t >example.ps - -To use ghostscript/ghostview -bash$ ghostview example.ps - -To print it -bash$ lpr -Ppostscript example.ps - - - -References: -/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, -groff_font5, -groff_char5, -pfbtops1. - - - - -Can TrueType fonts be used? - -The TrueType font format is used by Windows, Windows 95, -Mac's,&hellip It is quite popular and there are a great number of -fonts available in this format. Unfortunately, there are only two -applications that I am aware of that can use this format: Ghostscript -and povray. Ghostscript's support, according to the documentation, -is rudimentary and the results are likely to be inferior to type 1 -fonts. - -However, groff would need a font description file, and I know -of no tools to construct the metrics from a TrueType font. In -addition, the font would have to be down loaded to postscript -printers in the appropriate format, and again, groff cannot handle -TrueType fonts in this fashion. - -X11 has no support for TrueType fonts that I am aware -of. - -The only program that I know of that has the ability to use -TrueType fonts is povray version 3, but I rather doubt many people -will be creating documents as a series of raytraced pages! -:-) - - - - -Where can additional fonts be obtained? - -Many fonts are available on the Internet. They are either -entirely free, or are share-ware. In addition, there are many -inexpensive CDROMs available that contain many fonts. Some Internet -locations (as of August 1996) are: - - -ftp://ftp.winsite.com (Formerly -CICA) - -http://www.simtel.net/simcgi-bin/dosfind.cgi - -ftp://ftp.coast.net/ - -http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html - -http://www.esselte.com/letraset/index.html - -http://www.inil.com/users/elfring/esf.htm - - - - - - -Additional questions - - - - - -What use are the .pfm files? - - - -Can one generate the .afm file from a .pfa or .pfb? - - - -How to generate the groff character mapping files for postscript fonts -with non-standard character names? - - - -Can xditview and devX?? devices be setup to access all the new fonts? - - - -It would be good to have examples of using TrueType fonts with povray and -ghostscript. - - - - - - - diff --git a/en/tutorials/index.sgml b/en/tutorials/index.sgml deleted file mode 100644 index 086a2e6baf..0000000000 --- a/en/tutorials/index.sgml +++ /dev/null @@ -1,49 +0,0 @@ - - - - %includes; -]> - - - -&header; - -

Here lie assorted documents on various aspects of FreeBSD, - FreeBSD software, and hardware. If you have comments or - would like to contribute a document, please contact us at - freebsd-doc@FreeBSD.org.

- - - - -&footer; - - - diff --git a/en/tutorials/mh/Makefile b/en/tutorials/mh/Makefile deleted file mode 100644 index 14a686e6af..0000000000 --- a/en/tutorials/mh/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= mh.docb -INDEXLINK= mh.html - -.include "../../web.mk" - diff --git a/en/tutorials/mh/mh.docb b/en/tutorials/mh/mh.docb deleted file mode 100644 index 839f8b7611..0000000000 --- a/en/tutorials/mh/mh.docb +++ /dev/null @@ -1,704 +0,0 @@ - - - - - - - - -An MH Primer - - - -Matt -Midboe - -
-matt@garply.com -
- - - -v1.0, 16 January 1996 - -This document contains an introduction to using MH on -FreeBSD - - - - - -Introduction - -MH started back in 1977 at the RAND Corporation, where the -initial philosophies behind MH were developed. MH isn't so much a -monolithic email program but a philosophy about how best to develop -tools for reading email. The MH developers have done a great job -adhering to the KISS principle: Keep It Simple Stupid. -Rather than have one large program for reading, sending and handling -email they have written specialized programs for each part of your -email life. One might liken MH to the specialization that one finds -in insects and nature. Each tool in MH does one thing, and does it -very well. - -Beyond just the various tools that one uses to handle their -email MH has done an excellent job keeping the configuration of each -of these tools consistent and uniform. In fact, if you are not quite -sure how something is supposed to work or what the arguments for some -command are supposed to be then you can generally guess and be right. -Each MH command is consistent about how it handles reading the -configuration files and how it takes arguments on the command line. -One useful thing to remember is that you can always add a - to the command to have it display the options -for that command. - -The first thing that you need to do is to make sure that you have -installed the MH package on your FreeBSD machine. If you installed -from CDROM you should be able to execute the following to load mh: - -# pkg_add /cdrom/packages/mh-6.8.3.tgz - -You will notice that it created a /usr/local/lib/mh -directory for you as well as adding several binaries to the -/usr/local/bin directory. If you would prefer to compile -it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. - -This primer is not a full comprehensive explanation of how MH -works. This is just intended to get you started on the road to -happier, faster mail reading. You should read the man pages for the -various commands. Also you might want to read the comp.mail.mh newsgroup. Also you can -read the FAQ -for MH. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek. - - - - -Reading Mail - -This section covers how to use inc, -show, scan, next, -prev, rmm, rmf, and -msgchk. One of the best things about MH is the -consistent interface between programs. A few things to keep in mind -when using these commands is how to specify message lists. In the -case of inc this doesn't really make any sense but with -commands like show it is useful to know. - -A message list can consist of something like 23 20 -16 which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like 23-30 which will -act on all the messages between 23 and 30. You can also specify -something like cur:10 which will act on the current -message and the next 9 messages. The cur, -last, and first messages are special -messages that refer to the current, last or first message in the -folder. - - - -<command>inc</>, <command>msgchk</>—read in your new email or check it - -If you just type in inc and hit return -you will be well on your way to getting started with MH. The first -time you run inc it will setup your account to use all -the MH defaults and ask you about creating a Mail directory. If you -have mail waiting to be downloaded you will see something that looks -like: - - 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -This is the same thing you will see from a scan (see -). If you just run inc with no -arguments it will look on your computer for email that is supposed to -be coming to you. - -A lot of people like to use POP for grabbing their email. MH can do -POP to grab your email. You will need to give inc a few command -line arguments. - -tempest% inc -host mail.pop.org -user username -norpop - -That tells inc to go to mail.pop.org to -download your email, and that your username on their system is -username. The option tells -inc to use plain POP3 for downloading your email. MH has -support for a few different dialects of POP. More than likely you -will never ever need to use them though. While you can do more -complex things with inc such as audit files and scan format files -this will get you going. - -The msgchk command is used to get information on -whether or not you have new email. msgchk takes the same - and options that -inc takes. - - - - -<command>show</>, <command>next</> and <command>prev</>—displaying and moving through email - -show is to show a letter in your current folder. -Like inc, show is a fairly straightforward -command. If you just type show and hit return -then it displays the current message. You can also give specific -message numbers to show: - -tempest% show 32 45 56 - -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior show -basically just does a more on the email message. - -next is used to move onto the next message and -prev will go to the previous message. Both commands have -an implied show command so that when you go to the next -message it automatically displays it. - - - - -<command>scan</>—shows you a scan of your messages - -scan will display a brief listing of the messages -in your current folder. This is an example of what the -scan command will give you. - - 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -Like just about everything in MH this display is very configurable. -This is the typical default display. It gives you the message number, -the date on the email, the sender, the subject line, and a sentence -fragment from the very beginning of the email if it can fit it. The -+ means that message is the current message, so if you do -a show it will display that message. - -One useful option for scan is the -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -scan is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to inc it -you can do scan -file -/var/mail/username. This can be used with -any file that is in the mbox format. - - - - -<command>rmm</> and <command>rmf</>—remove the current message or folder - -rmm is used to remove a mail message. The default -is typically to not actually remove the message but to rename the -file to one that is ignored by the MH commands. You will need to -through periodically and physically delete the removed -messages. - -The rmf command is used to remove folders. This -doesn't just rename the files but actually removes the from the hard -drive so you should be careful when you use this command. - - - - -A typical session of reading with MH - -The first thing that you will want to do is inc -your new mail. So at a shell prompt just type in inc and -hit return. - -tempest% inc -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -This shows you the new email that has been added to your mailbox. So -the next thing to do is show the email and move around. - -tempest% show -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -tempest% rmm -tempest% next -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party). - - -The rmm removed the current message and the -next command moved me on to the next message. -Now if I wanted to look at ten most recent messages so I could read -one of them here is what I would do: - -tempest% scan last:10 - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -Then if I wanted to read message number 27 I would do a -show 27 and it would be displayed. As you can probably -tell from this sample session MH is pretty easy to use and looking -through emails and displaying them is fairly intuitive and easy. - - - - - - -Folders and Mail Searching - -Anybody who gets lots of email definitely wants to be able to -prioritize, stamp, brief, de-brief, and number their emails in a -variety of different ways. MH can do this better than just about -anything. One thing that we haven't really talked about is the -concept of folders. You have undoubtedly come across the folders -concept using other email programs. MH has folders too. MH can even -do sub-folders of a folder. One thing you should keep in mind with MH -is that when you ran inc for the first time and it asked -you if it could create a Mail directory it began storing -everything in that directory. If you look at that directory you will -find a directory named inbox. The inbox -directory houses all of your incoming mail that hasn't been thrown -anywhere else. - -Whenever you create a new folder a new directory is going to be -created underneath your MH Mail directory, and messages -in that folder are going to be stored in that directory. When new -email comes in that new email is thrown into your inbox -directory with a file name that is equivalent to the message number. -So even if you didn't have any of the MH tools to read your email you -could still use standard UNIX commands to munge around in those -directories and just more your files. It's this simplicity that -really gives you a lot of power with what you can do with your -email. - -Just as you can use message lists like 23 16 42 -with most MH commands there is a folder option you can specify with -just about every MH command. If you do a scan +freebsd it -will scan your freebsd folder, and your current folder -will be changed to freebsd. If you do a show -+freebsd 23 16 42, show is going to switch to your -freebsd folder and display messages 23, 16 and 42. So -remember that - - - -<command>pick</>—search email that matches certain criteria - -pick is one of the more complex commands in the MH -system. So you might want to read the -pick1 man page for a -more thorough understanding. At its simplest level you can do -something like - -tempest% pick -search pci -15 -42 -55 -56 -57 - - -This will tell pick to look through every single line in -every message in your current folder and tell you which message -numbers it found the word pci in. You can then -show those messages and read them if you wish or -rmm them. You would have to specify something like -show 15 42 55-57 to display them though. A slightly more -useful thing to do is this: - -tempest% pick -search pci -seq pick -5 hits -tempest% show pick - -This will show you the same messages you just didn't have to work as -hard to do it. The option is really an -abbreviation of and pick is -just a sequence which contains the message numbers that matched. You -can use sequences with just about any MH command. So you could have -done an rmm pick and all those messages would be removed -instead. You sequence can be named anything. If you run pick again it -will overwrite the old sequence if you use the same name. - -Doing a pick -search can be a bit more time -consuming than just searching for message from someone, or to -someone. So pick allows you to use the following -predefined search criteria: - - - - - - -search based upon who the message is to - - - - - - -search based on who is in the cc list - - - - - - -search for who sent the message - - - - - - -search for emails with this subject - - - - - - -find emails with a matching dat - - - - - - -search for any other component in the header. (i.e. - - - - - - -This allows you to do things like - -tempest% pick -to freebsd-hackers@freebsd.org -seq hackers - -to get a list of all the email send to the FreeBSD hackers mailing -list. pick also allows you to group these criteria in -different ways using the following options: - - - -… … - - - -… &hellip - - - - … - - - - … - - - -These commands allow you to do things like - -tempest% pick -to freebsd-hackers -and -cc freebsd-hackers - -That will grab all the email in your inbox that was sent to -freebsd-hackers or cc'd to that list. The brace options allow you to -group search criteria together. This is sometimes very necessary as -in the following example - -tempest% pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci - - -Basically this says pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci. It should look through your -folder and find all messages sent to the freebsd-hackers list that -aren't cc'd to the freebsd-questions list that contain something on -pci in the subject line. Ordinarily you might have to worry about -something called operator precedence. Remember in math how you -evaluate from left to right and you do multiplication and division -first and addition and subtraction second? MH has the same type of -rules for pick. It's fairly complex so you might want to study -the man page. This document is just to help you get acquainted with -MH. - - - - -<command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance - -There are three programs which are primarily just for -manipulating your folders. The folder program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a folder +newfolder and -you will be switched into newfolder. From there on -out all your MH commands like comp, repl, -scan, and show will act on that -newfolder folder. - -Sometimes when you are reading and deleting messages you will -develop holes in your folders. If you do a scan -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a folder -pack this will renumber all your -messages so that there are no holes. It doesn't actually delete any -messages though. So you may need to periodically go through and -physically delete rmm'd messages. - -If you need statistics on your folders you can do a -folders or folder -all to list all -your folders, how many messages they have, what the current message -is in each one and so on. This line of stats it displays for all your -folders is the same one you get when you change to a folder with -folder +foldername. A folders command looks -like this: - - Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. - - - -The refile command is what you use to move messages -between folders. When you do something like refile 23 -+netfuture message number 23 is moved into the -netfuture folder. You could also do something like -refile 23 +netfuture/latest which would put message -number 23 in a subfolder called latest under the -netfuture folder. If you want to keep a message in the -current folder and link it you can do a refile -link 23 -+netfuture which would keep 23 in your current -inbox but also list in your netfuture -folder. You are probably beginning to realize some of the really -powerful things you can do with MH. - - - - - -Sending Mail - -Email is a two way street for most people so you want to be -able to send something back. The way MH handles sending mail can be a -bit difficult to follow at first, but it allows for incredible -flexibility. The first thing MH does is to copy a components file -into your outgoing email. A components file is basically a skeleton -email letter with stuff like the To: and Subject: headers already in -it. You are then sent into your editor where you fill in the header -information and then type the body of your message below the dashed -lines in the message. Then to the whatnow program. When -you are at the What now? prompt you can tell it to -send, list, edit, -edit, push, and quit. Most of -these commands are self-explanatory. So the message sending process -involves copying a component file, editing your email, and then -telling the whatnow program what to do with your -email. - - - -<command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone - -The comp program has a few useful command line -options. The most important one to know right now is the - option. When MH is installed the default -editor is usually a program called prompter which comes -with MH. It's not a very exciting editor and basically just gets the -job done. So when you go to compose a message to someone you might -want to use comp -editor /usr/bin/vi/ or comp --editor /usr/local/bin/pico/ instead. Once you have run -comp you are in your editor and you see -something that looks like this: - -To: -cc: -Subject: --------- - - - -You need to put the person you are sending the mail to after the -To: line. It works the same way for the other headers -also, so you would need to put your subject after the -Subject: line. Then you would just put the body of your -message after the dashed lines. It may seem a bit simplistic since a -lot of email programs have special requesters that ask you for this -information but there really isn't any point to that. Plus this -really gives you excellent flexibility. - -To:freebsd-rave@freebsd.org -cc: -Subject:And on the 8th day God created the FreeBSD core team --------- -Wow this is an amazing operating system. Thanks! - -You can now save this message and exit your editor. You will see the -What now? prompt and you can type in -send or s and hit -return. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example quit if you don't want to send the -message. - -The forw command is stunningly similar. The big -difference being that the message you are forwarding is automatically -included in the outgoing message. When you run forw it -will forward your current message. You can always tell it to forward -something else by doing something like forw 23 and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences forw -functions exactly the same as comp. You go through the -exact same message sending process. - -The repl command will reply to whatever your -current message is, unless you give it a different message to reply -to. repl will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -To: header already has the address of the recipient in -there. Also the Subject: line will already be filled in. -You then go about the normal message composition process and you are -done. One useful command line option to know here is the - option. You can use all, -to, cc, me after the - option to have repl automatically -add the various addresses to the cc list in the message. You have -probably noticed that the original message isn't included. This is -because most MH setups are configured to do this from the -start. - - - - -<filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</> - -The components file is usually in -/usr/local/lib/mh. You can copy that file into -your MH Mail directory and edit to contain what you want it to -contain. It is a fairly basic file. You have various email headers at -the top, a dashed line and then nothing. The -comp command just copies this -components file and then edits it. You can add any -kind of valid RFC822 header you want. For instance you could have -something like this in your components file: - -To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ -------- - - -MH would then copy this components file and throw you into your -editor. The components file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that components file. - -The replcomps file is a bit more complex. The default -replcomps looks like this: - -%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- - - - -It's in the same basic format as the components file but -it contains quite a few extra formatting codes. The -%(lit) command makes room for the address. The -%(formataddr is a function that returns a proper email -address. The next part is %< which means if and -the {reply-to} means the reply-to field in the original -message. So that might be translated this way: - -%<if {reply-to} the original message has a reply-to -then give that to formataddr, %? else {from} take the -from address, %? else {sender} take the sender address, %? -else {return-path} take the return-path from the original -message, %> endif. - - -As you can tell MH formatting can get rather involved. You can -probably decipher what most of the other functions and variables -mean. All of the information on writing these format strings is in the -MH-Format man page. The really nice thing is that once you have built -your customized replcomps file you won't need to touch it -again. No other email program really gives you the power and -flexibility that MH gives you. - - - - diff --git a/en/tutorials/multios/Makefile b/en/tutorials/multios/Makefile deleted file mode 100644 index 8a591510bb..0000000000 --- a/en/tutorials/multios/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $ - -DOCS= multios.docb -INDEXLINK= multios.html - -.include "../../web.mk" - diff --git a/en/tutorials/multios/multios.docb b/en/tutorials/multios/multios.docb deleted file mode 100644 index 6349edaffa..0000000000 --- a/en/tutorials/multios/multios.docb +++ /dev/null @@ -1,680 +0,0 @@ - - - - - - -Installing and Using FreeBSD With Other Operating Systems - - - -Jay -Richmond - -
-jayrich@in.net -
- - - - -6 August 1996 - -This document discusses how to make FreeBSD coexist -nicely with other popular operating systems such as Linux, MS-DOS, -OS/2, and Windows 95. Special thanks to: Annelise Anderson -andrsn@stanford.edu, Randall Hopper -rhh@ct.picker.com, and Jordan K. Hubbard -jkh@time.cdrom.com - - - - - -Overview - -Most people can't fit these operating systems together -comfortably without having a larger hard disk, so special -information on large EIDE drives is included. Because there are so -many combinations of possible operating systems and hard disk -configurations, the section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems. - -This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the \TOOLS directory or via -ftp) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence. - - - - -Overview of Boot Managers - -These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system. - - - - -Boot Easy - - -This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys. - - - - -OS/2 Boot Manager - - -This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 -(Linux). It will also boot FAT32 partitions. Partitions are -selected using arrow keys. The OS/2 Boot Manager is the only one to -use its own separate partition, unlike the others which use the -master boot record (MBR). Therefore, it must be installed below the -1024th cylinder to avoid booting problems. It can boot Linux using -LILO when it is part of the boot sector, not the MBR. Go to Linux HOWTOs -on the World Wide Web for more information on booting Linux with -OS/2's boot manager. - - - - -OS-BS - - This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -\TOOLS directory, and via ftp. - - - -LILO, or LInux LOader - - -This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file. - - - - - -About FAT32FAT32 is the replacement to -the FAT filesystem included in Microsoft's OEM SR2 Beta release, -which is expected to utilitized on computers pre-loaded with Windows -95 towards the end of 1996. It converts the normal FAT file system -and allows you to use smaller cluster sizes for larger hard drives. -FAT32 also modifies the traditional FAT boot sector and allocation -table, making it incompatible with some boot managers. - - - - -A Typical Installation - -Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them. - -Here's how I might do it using these hard disks: - - - -/dev/wd0 (first physical hard disk) - - - -/dev/wd1 (second hard disk) - - - - - -Both disks have 1416 cylinders. - - - -I boot from a MS-DOS or Windows 95 boot disk that -contains the FDISK.EXE utility and make a small 50 meg -primary partition (35-40 for Windows 95, plus a little breathing -room) on the first disk. Also create a larger partition on the -second hard disk for my Windows applications and data. - -I reboot and install Windows 95 (easier said than done) -on the C: partition. - -The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -). When I am partitioning out my hard disk with -Linux fdisk, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space). - -After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record). - -The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the /usr and / slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the /usr/src slice and swap -space. - -When viewed with the Windows 95 fdisk utility, my hard drives -should now look something like this: - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See ). - -Install FreeBSD. I make sure to boot with my first hard -disk set at NORMAL in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (MSD.EXE), -or check your BIOS) with the parameter hd0=1416,16,63 -where 1416 is the number of cylinders on my hard -disk, 16 is the number of heads per track, and -63 is the number of sectors per track on the -drive. - -When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it. - -When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD). - - - - - - -Special Considerations - -Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary partitiin on the first hard disk. OS/2 is the exception. It -can be installed on the first or second disk in a primary or extended -partition. If you are not sure, keep the beginning of the bootable -partitions below the 1024th cylinder. - -If you install Windows 95 on an existing BSD system, it will -destroy the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via ftp. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS. - -Please keep in mind that OS/2 can read FAT and HPFS partitions, -but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows -95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most file systems, but -currently cannot read HPFS partitions. Linux can read HPFS -partitions, but can't write to them. Recent versions of the Linux -kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT -is what gives Windows 95 long file names - it's pretty much the same -as FAT). Linux can read and write to most file systems. Got that? -I hope so. - - - - -Examples - -(section needs work, please send your example to -jayrich@in.net). - -FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see DOS on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like invalid system disk under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called > 1024 cylinder support or NORMAL/LBA -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the FBSDBOOT.EXE utility on the CD (It should find your -FreeBSD partition and boot it.) - -FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem. - -FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems. - -FreeBSD+Linux+Win95: (see ) - - - - -Other Sources of Help - -There are many Linux HOW-TOs that -deal with multiple operating systems on the same hard disk. - -The Linux+OS/2+DOS -Mini-HOWTO offers help on configuring the OS/2 boot -manager. The Linux-HOWTO -is also helpful. - -The NT Loader -Hacking Guide provides good information on multibooting -Windows NT, '95, and DOS with other operating systems. - -And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip, -http://www.cs.yorku.ca/People/frank/docs/. - -Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -file:/usr/src/sys/i386/boot/biosboot/README.386BSD. - - - - -Technical Details - -(Contributed by Randall Hopper, -rhh@ct.picker.com) - -This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading. - - - -Disk Primer - -Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It's not -particularly important to know what these terms relate to except to -know that, together, they identify where data is physically on your -disk. - -Your disk has a particular number of cylinders, number of -heads, and number of sectors per cylinder-head (a cylinder-head also -known nown as a track). Collectively this information defines the -"physical disk geometry" for your hard disk. There are typically 512 -bytes per sector, and 63 sectors per track, with the number of -cylinders and heads varying widely from disk to disk. Thus you can -figure the number of bytes of data that'll fit on your own disk by -calculating: (# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect) For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: (3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect) - -which is 1,624,670,208 bytes, or around 1.6 Gig. - -You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see ), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. MSD.EXE or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -translated geometry (virtual numbers from using LBA). -Stay tuned for what that means. - -One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1. - -For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for boot -sector or master boot record. Among the useful info -you'll find are Hale Landis's How It Works document -pack. See the section for a few pointers to -this pack. - -Ok, enough terminology. We're talking about booting -here. - - - - -The Booting Process - -On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 partitions, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -slices to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system. - -Each partition entry in the MBR has a Partition -ID, a Start Cylinder/Head/Sector, and an -End Cylinder/Head/Sector. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. lists a smattering of some common -Partition IDs. - - -Partition IDs</> -<tgroup cols="2"> -<thead> -<row> -<entry>ID (hex)</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> -<row> -<entry>01</entry> -<entry>Primary DOS12 (12-bit FAT)</entry> -</row> - -<row> -<entry>04</entry> -<entry>Primary DOS16 (16-bit FAT)</entry> -</row> - -<row> -<entry>05</entry> -<entry>Extended DOS</entry> -</row> - -<row> -<entry>06</entry> -<entry>Primary big DOS (> 32MB)</entry> -</row> - -<row> -<entry>0A</entry> -<entry>OS/2</entry> -</row> - -<row> -<entry>83</entry> -<entry>Linux (EXT2FS)</entry> -</row> - -<row> -<entry>A5</entry> -<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Note that not all partitions are bootable (e.g. Extended DOS). -Some are—some aren't. What makes a partition bootable is the -configuration of the <firstterm>Partition Boot Sector</> that exists -at the beginning of each partition.</para> - -<para>When you configure your favorite boot manager, it looks up the entries -in the MBR partition tables of all your hard disks and lets you name the -entries in that list. Then when you boot, the boot manager is invoked by -special code in the Master Boot Sector of the first probed hard disk on -your system. It looks at the MBR partition table entry corresponding to -the partition choice you made, uses the Start Cylinder/Head/Sector -information for that partition, loads up the Partition Boot Sector for that -partition, and gives it control. That Boot Sector for the partition itself -contains enough information to start loading the operating system on that -partition.</para> - -<para>One thing we just brushed past that's important to know. All of your -hard disks have MBRs. However, the one that's important is the one on the -disk that's first probed by the BIOS. If you have only IDE hard disks, its -the first IDE disk (e.g. primary disk on first controller). Similarly for -SCSI only systems. If you have both IDE and SCSI hard disks though, the -IDE disk is typically probed first by the BIOS, so the first IDE disk is -the first probed disk. The boot manager you will install will be hooked into -the MBR on this first probed hard disk that we've just described.</para> - -</sect1> - -<sect1 id="limits"> -<title>Booting Limitations and Warnings - -Now the interesting stuff that you need to watch out for. - - -The dreaded 1024 cylinder limit and how BIOS LBA helps - -The first part of the booting process is all done through the -BIOS, (if that's a new term to you, the BIOS is a software chip on -your system motherboard which provides startup code for your -computer). As such, this first part of the process is subject to the -limitations of the BIOS interface. - -The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: - -1024 cylinders, max -256 heads , max -64 cylinders, max (actually 63, 0 isn't -available) - - - -Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can't boot off just anywhere on your hard disk. The boot code (the -boot manager and the OS loader hooked into all bootable partitions' -Boot Sectors) has to reside below cylinder 1024. In fact, if your -hard disk is typical and has 16 heads, this equates to: - -1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector - - - -which is around the often-mentioned 528MB limit. - -This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads). - -With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit. - -To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: - -(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) - - - -However, my BIOS LBA remaps this to: - -( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) - - - -giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA). - - - - -Boot Managers and Disk Allocation - -Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs. - -If you followed the discussion in -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically. - -That's the catch. Some operating systems (FreeBSD included) let -you start their partitions right after the Master Boot Sector at -Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give -FreeBSD's sysinstall a disk with an empty chunk up front or the whole -disk empty, that's where it'll start the FreeBSD partition by default -(at least it did when I fell into this trap). Then when you go to -install your boot manager, if it's one that occupies a few extra -sectors after the MBR, it'll overwrite the front of the first -partition's data. In the case of FreeBSD, this overwrites the -disk label, and renders your FreeBSD partition unbootable. - -The easy way to avoid this problem (and leave yourself the -flexibility to try different boot managers later) is just to always -leave the first full track on your disk unallocated when you -partition your disk. That is, leave the space from Cylinder 0, Head -0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and -start your first partition at Cylinder 0, Head 1, Sector 1. -For what it's worth, when you create a DOS partition at the -front of your disk, DOS leaves this space open by default (this is -why some boot managers assume it's free). So creating a DOS -partition up at the front of your disk avoids this problem -altogether. I like to do this myself, creating 1 Meg DOS partition -up front, because it also avoids my primary DOS drive letters -shifting later when I repartition. - -For reference, the following boot managers use the -Master Boot Sector to store their code and data: - - - -OS-BS 1.35 - - - -Boot Easy - - - -LILO - - - - - -These boot managers use a few additional sectors after the -Master Boot Sector: - - - -OS-BS 2.0 Beta 8 (sectors 2-5) - - - -OS/2's boot manager - - - - - - - - -What if your machine won't boot? - -At some point when installing boot managers, you might leave the -MBR in a state such that your machine won't boot. This is unlikely, -but possible when re-FDISKing underneath an already-installed boot -manager. - -If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: - -A:\> FDISK /MBR - - - -to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy. - - - - - diff --git a/en/tutorials/newuser/Makefile b/en/tutorials/newuser/Makefile deleted file mode 100644 index d8131087f4..0000000000 --- a/en/tutorials/newuser/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $ - -DOCS= newuser.docb -INDEXLINK= newuser.html - -.include "../../web.mk" - diff --git a/en/tutorials/newuser/newuser.docb b/en/tutorials/newuser/newuser.docb deleted file mode 100644 index 9adefd509b..0000000000 --- a/en/tutorials/newuser/newuser.docb +++ /dev/null @@ -1,943 +0,0 @@ - - - - - - - - -For People New to Both FreeBSD and Unix - - - -Annelise -Anderson - -
andrsn@andrsn.stanford.edu
- - - - -August 15, 1997 - -Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -and Un*x—so it starts with basics. It -assumes you're using version 2.0.5 or later of FreeBSD as distributed -by Walnut Creek or FreeBSD.ORG, your system (for now) has a single -user (you)—and you're probably pretty good with DOS/Windows or -OS/2. - - - - - -Logging in and Getting Out - -Log in (when you see login:) as a user you created during -installation or as root. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. - -To log out (and get a new login: prompt) type - -# exit - -as often as necessary. Yes, press enter after -commands, and remember that Unix is -case-sensitive—exit, not -EXIT. - -To shut down the machine type: - -# /sbin/shutdown -h now - -Or to reboot type - -# /sbin/shutdown -r now - -or - -# /sbin/reboot - - - -You can also reboot with -CtrlAltDelete. -Give it a little time to do its work. This is equivalent to -/sbin/reboot in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you? - - - - -Adding A User with Root Privileges - -If you didn't create any users when you installed the system and -are thus logged in as root, you should probably create a user now with - -# adduser - -The first time you use adduser, it might ask for some defaults to save. You -might want to make the default shell csh instead of sh, if it suggests -sh as the default. Otherwise just press enter to accept each default. -These defaults are saved in /etc/adduser.conf, -an editable file. - -Suppose you create a user jack with -full name Jack Benimble. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type wheel - -Login group is ``jack''. Invite jack into other groups: wheel - -This will make it possible to log in as jack and -use the su command to become root. Then you won't -get scolded any more for logging in as root. - -You can quit adduser any time by typing -CtrlC, and at -the end you'll have a chance to approve your new user or simply type -n for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong. - -Once you've done this, use exit -to get back to a login prompt and log in as -jack. In general, it's a good idea to do as -much work as possible as an ordinary user who doesn't have the -power—and risk—of root. - -If you already created a user and you want the user to be able -to su to root, you can log in as root -and edit the file /etc/group, adding jack to the -first line (the group wheel). But first you need to practice -vi, the text editor--or use the simpler text -editor, ee, installed on recent version of -FreeBSD. - -To delete a user, use the rmuser command. - - - - -Looking Around - -Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD. - -Here are some commands and what they do: - -id - -Tells you who you are! - - - - -pwd - - -Shows you where you are—the current -working directory. - - - - -ls - - -Lists the files in the current directory. - - - - -ls - - -Lists the files in the current directory with a -* after executables, a / after -directories, and an @ after symbolic links. - - - - -ls - - -Lists the files in long format—size, -date, permissions. - - - - -ls - - -Lists hidden dot -files with the others. If you're root, thedot files -show up without the switch. - - - - -cd - - -Changes directories. cd -.. backs up one level; note the -space after cd. cd -/usr/local goes there. cd -~ goes to the home directory of the -person logged in—e.g., /usr/home/jack. -Try cd /cdrom, and then -ls, to find out if your CDROM is mounted and -working. - - - - -view filename - - -Lets you look at a file (named -filename without changing it. Try -view /etc/fstab. -:q to quit. - - - - -cat filename - - - -Displays filename on screen. If -it's too long and you can see only the end of it, press -ScrollLock and use the up-arrow to -move backward; you can use ScrollLock with man pages -too. Press ScrollLock again to quit scrolling. You -might want to try cat on some of the dot files in -your home directory—cat -.cshrc, cat -.login, cat -.profile. - - - - - -You'll notice aliases in .cshrc for some of the -ls commands (they're very convenient). -You can create other aliases by editing .cshrc. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -/etc/csh.cshrc. - - - - -Getting Help and Information - -Here are some useful sources of help. -Text stands for something of your choice -that you type in—usually a command or filename. - - -apropos text - - -Everything containing string text -in the whatis database. - - - -man text - - -The man page for text. The major -source of documentation for Un*x systems. man -ls will tell you all the ways to use -the ls command. Press Enter to -move through text, -Ctrlb to go -back a page, Ctrlf to -go forward, q or -Ctrlc to -quit. - - - -which text - - -Tells you where in the user's path the command -text is found. - - - -locate text - - -All the paths where the string text -is found. - - - -whatis text - - -Tells you what the command text -does and its man page. Typing whatis * will tell -you about all the binaries in the current directory. - - - -whereis text - - -Finds the file text, giving its full -path. - - - - -You might want to try using whatis on some -common useful commands like cat, -more, grep, -mv, find, -tar, chmod, -chown, date, and -script. more lets you read a -page at a time as it does in DOS, e.g., ls -l | -more or more -filename. The -* works as a wildcard—e.g., ls -w* will show you files beginning with -w. - -Are some of these not working very well? Both -locate and whatis -depend on a database that's rebuilt weekly. If your machine isn't -going to be left on over the weekend (and running FreeBSD), you might -want to run the commands for daily, weekly, and monthly maintenance -now and then. Run them as root and give each one time to finish -before you start the next one, for now. - -# /etc/daily -output omitted -# /etc/weekly -output omitted -# /etc/monthly -output omitted - - -If you get tired waiting, press -AltF2 to get -another virtual console, and log in again. -After all, it's a multi-user, multi-tasking system. Nevertheless -these commands will probably flash messages on your screen while -they're running; you can type clear at the prompt -to clear the screen. Once they've run, you might want to look at -/var/mail/root and -/var/log/messages. - -Basically running such commands is part of system -administration—and as a single user of a Unix system, you're -your own system administrator. Virtually everything you need to be -root to do is system administration. Such responsibilities aren't -covered very well even in those big fat books on Unix, which seem to -devote a lot of space to pulling down menus in windows managers. You -might want to get one of the two leading books on systems -administration, either Evi Nemeth et.al.'s UNIX System -Administration Handbook (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's Essential System -Administration (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth. - - - - -Editing Text - -To configure your system, you need to edit text files. Most of -them will be in the /etc directory; and you'll -need to su to root to be able to change them. You -can use the easy ee, but in the long run the -text editor vi is worth learning. There's an -excellent tutorial on vi in -/usr/src/contrib/nvi/docs/tutorial if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. - -Before you edit a -file, you should probably back it up. Suppose you want to edit -/etc/rc.conf. You could just use cd -/etc to get to the /etc directory and -do: - -# cp rc.conf rc.conf.orig - - -This would copy rc.conf to -rc.conf.orig, and you could later copy -rc.conf.orig to rc.conf to recover the original. But even -better would be moving (renaming) and then copying back: - -# mv rc.conf rc.conf.orig -# cp rc.conf.orig rc.conf - - -because the mv command preserves the original date -and owner of the file. You can now edit -rc.conf. If you want the original back, you'd -then mv rc.conf rc.conf.myedit -(assuming you want to preserve your edited version) and then - -# mv rc.conf.orig rc.conf - -to put things back the way they were. - -To edit a file, type - -# vi filename - -Move through the text with the arrow keys. Esc (the -escape key) puts vi in command mode. Here are some -commands: - -x - -delete letter the cursor is on - - - - -dd - - -delete the entire line (even if it wraps on the screen) - - - - -i - - -insert text at the cursor - - - - -a - - -insert text after the cursor - - - - -Once you type i or a, you can enter text. -Esc puts you back in command mode where you can type - -:w - -to write your changes to disk and continue editing - - - - -:wq - - -to write and quit - - - - -:q! - - -to quit without saving changes - - - - -/text - - -to move the cursor to text; -/Enter (the enter key) to find -the next instance of text. - - - - -G - - -to go to the end of the file - - - - -nG - - -to go to line n in -the file, where n is a number - - - - -CtrlL - - -to redraw the screen - - - - -Ctrlb and Ctrlf - - -go back -and forward a screen, as they -do with more and view. - - - - - - -Practice with vi in your home directory by creating -a new file with vi filename and adding -and deleting text, saving the file, and calling it up again. -vi delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -vi—it's more powerful than DOS EDIT—find out -about the :r command.) Use Esc one or -more times to be sure you're in command mode and proceed from there -when it gives you trouble, save often with :w, and -use :q! to get out and start over (from -your last :w) when you need to. - -Now you can cd to /etc, -su to root, use vi to edit the file -/etc/group, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press Esc, and use -:wq to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?) - - - - -Printing Files from DOS - -At this point you probably don't have the printer working, so here's a -way to create a file from a man page, move it to a floppy, and then -print it from DOS. Suppose you want to read carefully about changing -permissions on files (pretty important). You can use the command -man chmod to read about it. The command - -# man chmod | col -b > chmod.txt - -will remove formatting codes and send the man page to -the chmod.txt file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, su to -root, and type - -# /sbin/mount -t msdos /dev/fd0 /mnt - -to mount the floppy drive on /mnt. - -Now (you no longer need to be root, and you can type -exit to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: - -% cp chmod.txt /mnt - -and use ls /mnt to get a directory listing of -/mnt, which should show the file -chmod.txt. - -You might especially want to make a file from -/sbin/dmesg by typing - -% /sbin/dmesg > dmesg.txt - -and copying dmesg.txt to the floppy. -/sbin/dmesg is the boot log record, and it's -useful to understand it because it shows what FreeBSD found when it -booted up. If you ask questions on -freebsd-questions@FreeBSD.ORG or on a USENET -group—like FreeBSD isn't finding my tape drive, what do -I do?—people will want to know what dmesg -has to say. - -You can now dismount the floppy drive (as root) to get the disk -out with - -# /sbin/umount /mnt - -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a -minor change so the file has to be saved, and print as you normally -would from DOS or Windows. Hope it works! man pages come out best if -printed with the dos print command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.) - -Getting the printer printing from FreeBSD involves creating an -appropriate entry in /etc/printcap and creating -a matching spool directory in -/var/spool/output. If your printer is on -lpt0 (what dos calls LPT1), you may only -need to go to /var/spool/output and (as root) -create the directory lpd by typing: - -mkdir lpd, if it doesn't already -exist. -Then the printer should respond if it's turned on when the system is -booted, and lp or lpr should send a file to the printer. Whether or -not the file actually prints depends on configuring it, which is -covered in the FreeBSD -handbook. - - - - -Other Useful Commands - - - -df - -shows file space and mounted systems. - - - - -ps aux - - -shows processes running. ps ax is a narrower form. - - - - -rm filename - - -remove filename. - - - - -rm -R dir - - -removes a directory dir and all -subdirectories—careful! - - - - -ls -R - - -lists files in the current -directory and all subdirectories; -I used a variant, ls -AFR > where.txt, -to get a list of all -the files in / and (separately) -/usr before I found better -ways to find files. - - - - -passwd - - -to change user's password (or root's password) - - - - -man hier - - -man page on the Unix file system - - - - - -Use find to locate filename in /usr -or any of its subdirectories with - -% find /usr -name "filename" - -You can use * as a wildcard in -"filename" (which should be in -quotes). If you tell find to search in / -instead of /usr it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition. - -An excellent book that explains Unix commands and utilities is -Abrahams & Larson, Unix for the Impatient -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the Unix Reference -Desk. - - - - -Next Steps - -You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and FreeBSD's -web site. A wide variety of packages and ports are on the -Walnut Creek CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with pkg_add -/cdrom/packages/All/packagename, -where packagename is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in cdrom/packages/index, -cdrom/packages/index.txt, and -cdrom/ports/index, with fuller descriptions in -/cdrom/ports/*/*/pkg/DESCR, where the -*s represent subdirectories of kinds of programs -and program names respectively. - -If you find the handbook too sophisticated (what with -lndir and all) on installing ports from the cdrom, -here's what usually works: - -Find the port you want, say kermit. There will be -a directory for it on the cdrom. Copy the subdirectory to -/usr/local (a good place for software you add -that should be available to all users) with: - -# cp -R /cdrom/ports/comm/kermit /usr/local - - -This should result in a /usr/local/kermit -subdirectory that has all the files that the -kermit subdirectory on the CDROM has. - -Next, create the directory /usr/ports/distfiles -if it doesn't already exist using mkdir. Now check -check /cdrom/ports/distfiles for a -file with a name that indicates it's the port you want. Copy that -file to /usr/ports/distfiles; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of kermit, there is no -distfile. - -Then cd to the subdirectory of -/usr/local/kermit that has the file -Makefile. Type - -# make all install - - - -During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -/usr/ports/distfiles. If you don't have your -network running yet and there was no file for the port in -/cdrom/ports/distfiles, you will have to get -the distfile using another machine and copy it to -/usr/ports/distfiles from a floppy or your dos -partition. Read Makefile (with cat or -more or view) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into /usr/ports/distfiles you'll have to rename -it (with the mv command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -/usr/local/kermit, find the directory with -Makefile, and type make all install. - -The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message can't find unzip or whatever, you -might need to install the package or port for unzip before you -continue. - -Once it's installed type rehash to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of path not found messages when you use -whereis or which, you might want to make additions to the -list of directories in the path statement in -.cshrc in your home directory. The path -statement in Unix does the same kind of work it does in DOS, except -the current directory is not (by default) in the path for security -reasons; if the command you want is in the directory you're in, you -need to type ./ before the command to make it -work; no space after the slash.) - -You might want to get the most recent version of Netscape from -their ftp site. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use gunzip -filename and tar xvf -filename on it, move the binary to -/usr/local/bin or some other place binaries are -kept, rehash, and then put the following lines in -.cshrc in each user's home directory or (easier) -in /etc/csh.cshrc, the system-wide csh start-up -file: - -setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls - -This assumes that the file XKeysymDB and the directory -nls are in /usr/X11R6/lib/X11; if -they're not, find them and put them there. - -If you originally got Netscape as a port using the CDROM (or -ftp), don't replace /usr/local/bin/netscape with -the new netscape binary; this is just a shell script that sets up the -environmental variables for you. Instead rename the new binary to -netscape.bin and replace the old binary, which -is /usr/local/lib/netscape/netscape.bin. - - - - - -Your Working Environment - -Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention. - -Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing echo $SHELL. - -The csh shell is okay, but tcsh does everything csh does and more. It -It allows you to recall commands with the arrow keys and edit them. -It has tab-key completion -of filenames (csh uses the escape key), and it lets you switch to the -directory you were last in with cd -. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier. - -Here are the three steps for installing a new shell: - - 1. Install the shell as a port or a package, just as you -would any other port or package. Use rehash and -which tcsh (assuming you're installing tcsh) to -make sure it got installed. - - 2. As root, edit /etc/shells, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.) - - 3. Use the chsh command to change your shell to -tcsh permanently, or type tcsh at the prompt to -change your shell without logging in again. - -Note: It can be dangerous to change root's shell -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use su -m -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -.tcshrc file as an alias with alias su su -m. - -When tcsh starts up, it will read the -/etc/csh.cshrc and /etc/csh.login -files, as does csh. It will also read the -.login file in your home directory and the -.cshrc -file as well, unless you provide a .tcshrc -file. This you can do by simply copying .cshrc -to .tcshrc. - -Now that you've installed tcsh, you can adjust your prompt. You can -find the details in the manual page for tcsh, but here is a line to -put in your .tcshrc that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a > if you're an ordinary user and -a # if you're root, but tsch will do that in any -case: - - set prompt = "%h %t %~ %# " - -This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. - -You can get a listing of other environmental variables that -have been set by typing env at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -setenv TERM vt100. - - - - -Other - -As root, you can dismount the CDROM with /sbin/umount -/cdrom, take it out of the drive, insert another one, and mount it -with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming -cd0a is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -/sbin/mount /cdrom. - -Using the live file system—the second of FreeBSD's CDROM -disks—is useful if you've got limited space. What is on the -live file system varies from release to release. You might try -playing games from the cdrom. This -involves using lndir, which gets installed with the X -Window System, to tell the program(s) where to find the necessary -files, because they're in the /cdrom file system -instead of in /usr and its subdirectories, which -is where they're expected to be. Read man lndir. - - - - -Comments Welcome - -If you use this guide I'd be interested in knowing where it was -unclear and what was left out that you think should be included, and -if it was helpful. My thanks to Eugene W. Stark, professor of -computer science at SUNY-Stony Brook, and John Fieber for helpful -comments. - -Annelise Anderson, andrsn@andrsn.stanford.edu - - - diff --git a/en/tutorials/ppp/Makefile b/en/tutorials/ppp/Makefile deleted file mode 100644 index 76ead715ae..0000000000 --- a/en/tutorials/ppp/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:16 max Exp $ - -DOC= ppp -SRCS= ppp.sgml - -.include diff --git a/en/tutorials/ppp/ppp.sgml b/en/tutorials/ppp/ppp.sgml deleted file mode 100644 index 8edeb42750..0000000000 --- a/en/tutorials/ppp/ppp.sgml +++ /dev/null @@ -1,1736 +0,0 @@ - - - -
- -PPP - Pedantic PPP Primer -<author>Maintainer: Steve Sims <tt><htmlurl -url="mailto:SimsS@IBM.NET" - name="<SimsS@IBM.NET>"></tt> - -<date>$Date: 1997-01-21 05:49:54 $ -<abstract> -This is a step-by-step guide for configuring FreeBSD systems to act as -a dial-up router/gateway in a Local Area Environment. All entries may -be assumed to be relevant to FreeBSD 2.2+, unless otherwise noted. -</abstract> - -<toc> - -<sect> -<heading>Overview:</heading> -<p>The User-Mode PPP dialer in FreeBSD Version 2.2 (also known as: -<it>"IIJ-PPP"</it> ) now supports Packet Aliasing for dial up -connections to the Internet. This feature, also known as -"<IT/Masquerading/", "<IT/IP Aliasing/", or "<IT/Network Address -Translation/", allows a FreeBSD system to act as a dial- on-demand -router between an Ethernet-based Local Area Network and an Internet -Service Provider. Systems on the LAN can use the FreeBSD system to -forward information between the Internet by means of a single -dial-connection. - -<sect1> -<heading>Purpose of this Guide.</heading> -<p> -This guide explains how to: -<itemize> -<item>Configure the FreeBSD system to support dial-out connections, -<item>Share a dial-out connection with other systems in a network, -<item>Configure Windows platforms to use the FreeBSD system as a gateway to the Internet. -</itemize> -<p> -While the focus of this guide is to assist in configuring IP Aliasing, -it also includes specific examples of the configuration steps necessary -to configure and install each individual component; each section stands -alone and may be used to assist in the configuration of various aspects -of FreeBSD internetworking. -</sect> - -<sect> -<heading>Building the Local Area Network</heading> - -<p> While the ppp program can, and usually is, be configured to provide -services to <em/only/ the local FreeBSD box it can also be used to serve as a -"Gateway" (or "router") between other LAN-connected resources and the Internet or -other Dial-Up service. - -<sect1> -<heading>Typical Network Topology</heading> - -<p>This guide assumes a typical Local Area Network lashed together as -follows: -<verb> -+---------+ ----> Dial-Up Internet Connection -| FreeBSD | \ (i.e.: NetCom, AOL, AT&T, EarthLink, -etc) -| |-------- -| "Curly" | -| | -+----+----+ - | -|----+-------------+-------------+----| <-- Ethernet Network - | | | - | | | -+----+----+ +----+----+ +----+----+ -| | | | | | -| Win95 | | WFW | | WinNT | -| "Larry" | | "Moe" | | "Shemp" | -| | | | | | -+---------+ +---------+ +---------+ -</verb> - -<sect1> -<heading>Assumptions about the Local Area Network</heading> - -<p>Some specific assumptions about this sample network are: - -<p>Three workstations and a Server are connected with Ethernet -cabling: -<itemize> -<item>a FreeBSD Server ("Curly") with an NE-2000 adapter configured as -'ed0' -<item>a Windows-95 workstation ("Larry") with Microsoft's "native" -32-bit TCP/IP drivers -<item>a Windows for Workgroups workstation ("Moe") with Microsoft's -16-bit TCP/IP extensions -<item>a Windows NT workstation ("Shemp") with Microsoft's "native" -32-bit TCP/IP drivers -</itemize> - -<p>The IP Addresses on the Ethernet side of this sample LAN have been - -taken from the pool of "reserved" addresses proposed in RFC-1597. -IP addresses are assigned as follows: -<verb>Name IP Address -"Curly" 192.168.1.1 # The FreeBSD box -"Larry" 192.168.1.2 # The Win'95 box -"Moe" 192.168.1.3 # The WfW box -"Shemp" 192.168.1.4 # The Windows NT box -</VERB> - -<p>This guide assumes that the modem on the FreeBSD box is connected -to the first serial port ('<tt>/dev/cuaa0</tt>' or '<tt>COM1:</tt>' in -DOS-terms). - -<p>Finally, we'll also assume that your Internet Service Provider (ISP) -automatically provides the IP addresses of both your PPP/FreeBSD side -as well as the ISP's side. (i.e.: Dynamic IP Addresses on both ends -of the link.) Specific details for configuring the Dial-Out side of -PPP will be addressed in Section 2, "Configuring the FreeBSD System". -</sect> - -<sect> -<heading>FreeBSD System Configuration</heading> - -<p>There are three basic pieces of information that must be known to -the FreeBSD box before you can proceed with integrating the sample -Local Area Network: - -<itemize> -<item>The Host Name of the FreeBSD system; in our example it's "Curly", -<item>The Network configuration, -<item>The <tt>/etc/hosts</tt> file (which lists the names and IP addresses of -the other systems in your network) -</itemize> - -<p>If you performed the installation of FreeBSD over a network -connection some of this information may already be configured into -your FreeBSD system. - -<p>Even if you believe that the FreeBSD system was properly configured -when it was installed you should at least verify each of these bits of -information to prevent trouble in subsequent steps. - -<sect1> -<heading>Verifying the FreeBSD Host Name</heading> - -<p>It's possible that the FreeBSD host name was specified and saved -when the system was initially installed. To verify that it was, enter -the following command at a prompt:<p> -<tscreen><verb> -# hostname -</verb></tscreen> - -<p>The name of the host FreeBSD system will be displayed on a single -line. If the name looks correct (this is very subjective :-) skip -ahead to Section 3.2, "Verifying the Ethernet Interface -Configuration". - -<p>For example, in our sample network, we would see 'curly.my.domain' -as a result of the `hostname` command if the name had been set -correctly during, or after, installation. (At this point, don't worry -too much about the ".my.domain" part, we'll sort this out later. The -important part is the name up to the first dot.) - -<p>If a host name wasn't specified when FreeBSD was installed you'll -probably see 'myname.my.domain` as a response. You'll need to edit -<tt>/etc/sysconfig</tt> to set the name of the machine. - -<sect2><heading>Configuring the FreeBSD Host Name</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies the FreeBSD system's host -name when the system boots is in <tt>/etc/sysconfig</tt>. Use the -default text editor ('<tt/ee/') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</verb></tscreen> - -<p>Using the arrow keys, scroll down until you find the line that -specifies the host name of the FreeBSD system. By default, this -section says: -<tscreen><verb> ---- -# Set to the name of your host - this is pretty important! -hostname=myname.my.domain ---- -</verb></tscreen> -Change this section to say (in our example): -<tscreen><verb> ---- -# Set to the name of your host - this is pretty important! -hostname=curly.my.domain ---- -</verb></tscreen> - -Once the change to the host name has been made, press the 'Esc' key to -access the command menu. Select "leave editor" and make sure to -specify "save changes" when prompted. - -<sect1> -<heading>Verifying the Ethernet Interface Configuration</heading> - -<p>To reiterate our basic assumption, this guide assumes that the -Ethernet Interface in the FreeBSD system is named '<tt/ed0/'. This is -the default for NE-1000, NE-2000, WD/SMC models 8003, 8013 and Elite -Ultra (8216) network adapters. - -<p>Other models of network adapters may have different device names in -FreeBSD. Check the FAQ for specifics about your network adapter. If -you're not sure of the device name of your adapter, check the FreeBSD -FAQ to determine the device name for the card you have and substitute -that name (i.e.: '<tt/de0/', '<tt/zp0/', or similar) in the following -steps. - -<p>As was the case with the host name, the configuration for the -FreeBSD system's Ethernet Interface may have been specified when the -system was installed. - -To display the configuration for the interfaces in your -FreeBSD system (Ethernet and others), enter the following command: -<tscreen><verb> -# ifconfig -a -</verb></tscreen> -(In layman's terms: "Show me the <BF/I/nter<BF/F/ace <BF/CONFIG/uration -for my network devices.") - -<p>An example: -<tscreen><verb> -# ifconfig -a - ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu -1500 - inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255 - ether 01:02:03:04:05:06 - lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 - tun0: flags=8050<POINTOPOINT,RUNNING, MULTICAST> mtu 1500 - sl0: flags=c010<POINTOPOINT,LINK2,MULTICAST> mtu 552 - ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 - lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 - inet 127.0.0.1 netmask 0xff000000 -# _ -</verb></tscreen> - -<p>In this example, the following devices were displayed:<p> -<tt/ed0:/ The Ethernet Interface<p> -<tt/lp0:/ The Parallel Port Interface (ignored in this guide)<p> -<tt/tun0:/ The "tunnel" device; <em/This is the one user-mode ppp uses!/<p> -<tt/sl0:/ The SL/IP device (ignored in this guide)<p> -<tt/ppp0:/ Another PPP device (for kernel ppp; ignored in this guide)<p> -<tt/lo0:/ The "Loopback" device (ignored in this guide)<p> - -In this example, the 'ed0' device is up and running. The key -indicators are: -<enum> -<item>Its status is "<tt/UP/", -<item>It has an Internet ("<tt/inet/") address, (in this case, 192.168.1.1) -<item>It has a valid Subnet Mask ("netmask"; 0xffffff00 is the same as -255.255.255.0), and -<item>It has a valid broadcast address (in this case, 192.168.1.255). -</enum> - -<p>If the line for the Ethernet card had shown something similar to: -<tscreen><verb> -ed0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 - ether 01:02:03:04:05:06 -</verb></tscreen> -then the Ethernet card hasn't been configured yet. - -<p>If the configuration for the Ethernet interface is correct you can -skip forward to Section 3.4, "Creating the list of other LAN hosts". -Otherwise, proceed with the next section. -<sect2> -<heading>Configuring your Ethernet Interface</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies settings for the network -interfaces when the system boots is in <tt>/etc/sysconfig</tt>. Use -the default text editor ('ee') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<p> -<tt> # ee /etc/sysconfig</tt> -<p> -About 100 lines from the top of <tt>/etc/sysconfig</tt> is the section -that describes which network interfaces should be activated when the -system boots. In the default configuration file the specific line -that controls this is: - -<tscreen><verb> -network_interfaces="lo0" -</verb></tscreen> - -<p>You'll need to amend this line to tell FreeBSD that you want to add -another device, namely the '<tt/ed0/' device. Change this line to -read: - -<tscreen><verb> -network_interfaces="lo0 ed0" -</verb></tscreen> - -<p>(Note the space between the definition for the loopback device -("lo0") -and the Ethernet device ("<tt/ed0/")! - -<p><em><bf> Reminder: If your Ethernet card isn't named '<tt/ed0/', specify -the correct device name here instead.</bf></em> - -<p>If you performed the installation of FreeBSD over a network -connection then the '<tt/network_interfaces=/' line may already -include a reference to your Ethernet adapter. If it is, verify that -it is the correct device name. - -<p>Specify the Interface Settings for the Ethernet device -('<tt/ed0/'): - -<p>Beneath the line that specifies which interfaces should be -activated are the lines that specify the actual settings for each -interface. In the default <tt>/etc/sysconfig</tt> file is a single -line that says: - -<tscreen><verb> -ifconfig_lo0="inet localhost" -</verb></tscreen> - -<p>You'll need to add another line after that to specify the settings -for your '<tt/ed0/' device. - -<p>If you performed the installation of FreeBSD over a network -connection then there may already be an '<tt>ifconfig_ed0=</tt>' line -after the loopback definition. If so, verify that it has the correct -values. - -<p>For our sample configuration we'll insert a line immediately after -the loopback device definition that says: - -<tscreen><verb> -ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0" -</verb></tscreen> - -<p>When you've finished editing <tt>/etc/sysconfig</tt> to specify and -configure the network interfaces the section should look really close -to: - -<tscreen><verb> ---- -network_interfaces="lo0 ed0" -ifconfig_lo0="inet localhost" -ifconfig_ed0="inet 192.168.1.1 netmask 0xffffff00" ---- -</verb></tscreen> - -<p>Once all of the necessary changes to <tt>/etc/sysconfig</tt> have -been made, press the 'Esc' key to invoke the control menu. Select -"leave editor" and be sure to select "save changes" when prompted. - -<sect1> -<heading>Enabling Packet Forwarding</heading> - -<p>By default the FreeBSD system will not forward IP packets between -various network interfaces. In other words, routing functions (also -known as gateway functions) are disabled. - -<p>If your intent is to use a FreeBSD system as stand-alone Internet -workstation and not as a gateway between LAN nodes and your ISP you -should skip forward to Section 3.4, "Creating the List of Other -LAN Hosts". - -<p>If you intend for the PPP program to service the local FreeBSD box -as well as LAN workstations (as a router) you'll need to enable IP -forwarding. - -<p>To enable IP Packet forwarding you'll need to edit the -<tt>/etc/sysconfig</tt> file. -Load this file into your editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</verb></tscreen> - -<p>About 250 lines down from the top of the file will be the -configuration -section which controls IP forwarding, which will look like: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=NO -===== -</verb></tscreen> - -<p>Change this line to read: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=YES -===== -</verb></tscreen> - -and exit the editor (saving the changes!). - -<p><em><bf>NOTE: This line may already be set to '<tt/gateway=YES/' if IP -forwarding was enabled when the FreeBSD system was installed.</bf></em> - -<sect1> -<heading>Creating the List of other LAN Hosts(<tt>/etc/hosts</tt>)</heading> - -<p>The final step in configuring the LAN side of the FreeBSD system is -to create a list of the names and TCP/IP addresses of the various -systems that are connected to the Local Area Network. This list is -stored in the '<tt>/etc/hosts</tt>' file. - -<p>The default version of this file has only a single host name -listing in it: the name and address of the loopback device ('lo0'). -By networking convention, this device is always named "localhost" and -always has an IP address of 127.0.0.1. (See the interface -configuration example in Section 3.2.) - -<p>To edit the <tt>/etc/hosts</tt> file enter the following command: -<tscreen><verb> # ee /etc/hosts </verb></tscreen> - -<p>Scroll all the way to the bottom of the file (paying attention to -the comments along the way; there's some good information there!) and -enter (assuming our sample network) the following IP addresses and -host names: -<tscreen><verb> -192.168.1.1 curly curly.my.domain # FreeBSD System -192.168.1.2 larry larry.my.domain # Windows '95 System -192.168.1.3 moe moe.my.domain # Windows for Workgroups -System -192.168.1.4 shemp shemp.my.domain # Windows NT System -</verb></tscreen> - -<p>(No changes are needed to the line for the '<tt>127.0.0.1 -localhost</tt>' entry.) - -<p>Once you've entered these lines, press the 'Esc' key to invoke the -control menu. Select "leave editor" and be sure to select "save -changes" when prompted. - -<sect1> -<heading>Testing the FreeBSD system</heading> - -<p>Congratulations! Once you've made it to this point, the FreeBSD -system is configured as a network-connected UNIX system! If you made -any changes to the <tt>/etc/sysconfig</tt> file you should probably -re-boot your FreeBSD system. This will accomplish two important -objectives: -<itemize> -<item>Allow the changes to the interface configurations to be applied, and -<item>Verify that the system restarts without any glaring configuration errors. -</itemize> - -Once the system has been rebooted you should test the network -interfaces. -<p> -<sect2> -<heading>Verifying the operation of the loopback device</heading> - -<p>To verify that the loopback device is configured correctly, log in as -'root' and enter: -<tscreen><verb> -# ping localhost -</verb></tscreen> - -<p>You should see: -<tscreen><verb> -# ping localhost -PING localhost.my.domain. (127.0.0.1): 56 data bytes -64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms -64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m -[...] -</verb></tscreen> -messages scroll by until you hit Ctrl-C to stop the madness. - -<sect2> -<heading>Verifying the operation of the Ethernet Device</heading> - -<p>To verify that the Ethernet device is configured correctly, enter: - -<tscreen><verb> -# ping curly -</verb></tscreen> - -You should see: -<tscreen><verb> -# ping curly -PING curly.my.domain. (192.168.1.1): 56 data bytes -64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms -[...] -</verb></tscreen> -messages. - -<p>One important thing to look at in these two examples is that the -names (loopback and curly) correctly correlate to their IP addresses -(127.0.0.1 and 192.168.1.1). This verifies that the -<tt>/etc/hosts</tt> files is correct. - -<p>If the IP address for "curly" isn't 192.168.1.1 or the address for -"localhost" isn't 127.0.0.1, return to Section 3.4 and review your -entries in '<tt>/etc/hosts</tt>'. - -<p>If the names and addresses are indicated correctly in the result of -the ping command but there are errors displayed then something is -amiss with the interface configuration(s). Return to Section 3.1 and -verify everything again. - -<p>If everything here checks out, proceed with the next section. -</sect> - -<sect> -<heading>Configuring the PPP Dial-Out Connection</heading> -<p>There are two basic modes of operation of the ppp driver: -"Interactive" and "Automatic". - -In Interactive mode you:<p> -<itemize> -<item>Manually establish a connection to your ISP, -<item>Browse, surf, transfer files and mail, etc..., -<item>Manually disconnect from your ISP. -</itemize> - -<p>In Automatic mode, the PPP program silently watches what goes on -inside the FreeBSD system and automagically connects and disconnects -with your ISP as required to make the Internet a seamless element of -your network. - -<p>In this section we'll address the configuration(s) for both modes -with emphasis on configuring your `ppp` environment to operate in -"Automatic" mode. - -<sect1> -<heading>Backing up the original PPP configuration files</heading> - -<p>Before making any changes to the files which are used by PPP you -should make a copy of the default files that were created when the -FreeBSD system was installed. - -Log in as the 'root' user and perform the following steps: - -Change to the '<tt>/etc</tt> directory: -<p><tt># cd /etc</tt> - -Make a backup copy the original files in the 'ppp' directory: -<p><tt># cp -R ppp ppp.ORIGINAL</TT> - -<p>You should now be able to see both a '<tt>ppp</tt>' and a -'<tt>ppp.ORIGINAL</tt>' subdirectory -in the '<tt>/etc</tt>' directory. - -<sect1> -<heading>Create your own PPP configuration files</heading> - -<p>By default, the FreeBSD installation process creates a number of -sample configuration files in the /etc/ppp directory. Please take -some time to review these files; they were derived from working -systems and represent the features and capabilities of the PPP -program. - -<p>I <em/strongly/ encourage you to learn from these sample files and -apply them to your own configuration as necessary. - -<p>For detailed information about the `ppp` program, read the ppp -manpage: -<tscreen><verb> -# man ppp -</verb></tscreen> - -<p>For detailed information about the `chat` scripting language used by -the PPP dialer, read the chat manpage: -<tscreen><verb> -# man chat -</verb></tscreen> - -<p>The remainder of this section describes the recommended contents of -the PPP configuration files. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.conf</tt>' file</heading> - -<p>The '<tt>/etc/ppp/ppp.conf</tt>' file contains the information and -settings required to set up a dial-out PPP connection. More than one -configuration may be contained in this file. The FreeBSD handbook -(XXX URL? XXX) describes the contents and syntax of this file in -detail. - -<p>This section will describe only the minimal configuration to get a -dial-out connection working. - -<p>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a -dial-out Internet gateway for our example LAN: -<tscreen><verb> -################################################################ -# PPP Configuration File ('/etc/ppp/ppp.conf') -# -# Default settings; These are always executed always when PPP -# is invoked and apply to all system configurations. -################################################################ -default: -set device /dev/cuaa0 -set speed 57600 -disable pred1 -deny pred1 -disable lqr -deny lqr -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -set redial 3 10 -# -# -################################################################ -# -# For interactive mode use this configuration: -# -# Invoke with `ppp -alias interactive` -# -################################################################ -interactive: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -# -################################################################ -# -# For demand-dial (automatic) mode we'll use this configuration: -# -# Invoke with: 'ppp -auto -alias demand' -# -################################################################ -demand: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -add 0 0 127.2.2.2 -################################################################ -# End of /etc/ppp/ppp.conf -</verb></tscreen> -This file, taken verbatim from a working system, has three relevant -configuration sections: - -<sect3> -<heading>The "<tt>default</tt>" Section</heading> - -<p>The '<tt>default:</tt>' section contains the values and settings -used by every other section in the file. Essentially, this section is -implicitly added to the configuration lines to each other section. - -<p>This is a good place to put "global defaults" applicable to all -dial-up sessions; especially modem settings and dialing prefixes which -typically don't change based on which destination system you're -connecting to. - -<p>Following are the descriptions of each line in the "default" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: -<tscreen><verb> -set device /dev/cuaa0 -</verb></tscreen> -This statement informs the PPP program that it should use the first -serial port. -Under FreeBSD the '<tt>/dev/cuaa0</tt>' device is the same port that's -known as "<tt>COM1:</tt>" under DOS, Windows, Windows 95, etc.... - -<p>If your modem is on <tt>COM2:</tt> you should specify -'<tt>/dev/cua01</tt>; <tt>COM3:</tt> would be '<tt>/dev/cua02</tt>'. - -<tscreen><verb> -set speed 57600 -</verb></tscreen> - -This line sets the transmit and receive speed for the connection -between the serial port and the modem. While the modem used for this -configuration is only a 28.8 device, setting this value to 57600 lets -the serial link run at a higher rate to accommodate higher throughput -as a result of the data compression built into late-model modems. - -If you have trouble communicating with your modem, try setting this -value to 38400 or even as low as 19200. - -<tscreen><verb> -disable pred1 -deny pred1 -</verb></tscreen> - -These two lines disable the "CCP/Predictor type 1" compression -features of the PPP program. The current version of `ppp` supports -data compression in accordance with draft Internet standards. -Unfortunately many ISPs use equipment that does not support this -capability. Since most modems try to perform on-the-fly compression -anyway you're probably not losing much performance by disabling this -feature on the FreeBSD side and denying the remote side from forcing -it on you. - -<tscreen><verb> -disable lqr -deny lqr -</verb></tscreen> - -These two lines control the "Line Quality Reporting" functions which -are part of the complete Point-to-Point (PPP) protocol specification. -(See RFC-1989 for details.) - -The first line, "disable lqr", instructs the PPP program to not -attempt to report line quality status to the device on the remote end. - -The second line, "deny lqr", instructs the PPP program to deny any -attempts by the remote end to reports line quality. - -As most modern dial-up modems have automatic error correction and -detection and LQR reporting is not fully implemented in many vendor's -products it's generally a safe bet to include these two lines in the -default configuration. - -<tscreen><verb> -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -</verb></tscreen> - -<em>NOTE: (This statement should appear on a single line; ignore any -line wrapping that may appear in this document.)</em> - -This line instructs the PPP program how to dial the modem and -specifies some rudimentary guidelines for doing so: -<itemize> -<item>Attempts to dial should fail if the modem returns a "BUSY" result code, -<item>Attempts to dial should also fail if the modem returns a "NO CARRIER" result code, -<item>The PPP program should expect each of the following events to complete within a -5-second timeout period: -<itemize> -<item>The PPP program will initially expect nothing (specified above -by the \"\" portion of the statement) from the modem <item>The program -will send the modem initialization string "ATE1Q0M0" to the modem and -await a response of "OK". If a response is not received, the program -should send an attention command to the modem ("AT") and look again -for a response of "OK", <item>The program should delay for one second -(specified by the "\\d" part of the statement, and send the dialing -string to the modem. The "ATDT" portion of the statement is the -standard modem prefix to dial using tone-dialing; if you do not have -touch-tone service on your local phone line, replace the "ATDT" with -"ATDP". The "\\T" string is a placeholder for the actual phone number -(which will be automatically inserted as specified by the "set dial -123-4567"). -</itemize> -<item>Finally, before a (maximum) timeout of 40 seconds, the PPP -program should expect to see a "CONNECT" result code returned from the -modem. -</itemize> - -A failure at any point in this dialog will be interpreted as a dialing -failure and the PPP program will fail to connect. - -(For a detailed description of the mini-scripting language used by the -PPP dialer, refer to the "chat" manpage.) - -<tscreen><verb> -set redial 3 10 -</verb></tscreen> -This line specifies that if a dial connection cannot immediately be made -the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds -between redialing attempts. - -<sect3> -<heading>The "<tt>interactive</tt>" Section</heading> - -<p>The '<tt>interactive:</tt>' section contains the values and -settings used to set up an "interactive" PPP session with a specific -remote system. Settings in this section will have the lines included -in the "default" section included automatically. - -<p>The example cited in this section of the guide presumes that you'll -be connecting to a remote system that understands how to authenticate -a user without any fancy scripting language. That is, this sample -uses the CHAP protocol to set up the connection. - -<p>A good rule of thumb is that if the Windows '95 dialer can set up a -connection by just clicking the "Connect" button this sample -configuration should work OK. - -<p>If, on the other hand, when you connect to your ISP using Microsoft -Windows '95 Dial-Up Networking you need to resort to using the "Dial -Up Scripting Tool" from the Microsoft Plus! pack or you have to select -"Bring up a terminal windows after dialing" in the Windows '95 -connection options then you'll need to look at the sample PPP -configuration files and the ppp manpage for examples of "expect / -response" scripting to make your ISP connection. - -<p>Or even better, find an ISP who knows how to provide PAP or CHAP -authentication! - -<p>The configuration examples shown here have been successfully used to -connect to: -<itemize> -<item>Various Shiva LanRovers -<item>The IBM Network (<url url="http://www.ibm.net">) -<item>AT&T WorldNet (<url url="http://att.com/worldnet">) -<item>Erol's (<url url="http://www.erols.com">) -</itemize> - -Following are descriptions for each line in the "interactive" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. If you're inside a PBX -you can -prepend '<tt>9, </tt>' to the number here. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> -This tells the PPP program that it should automatically hang up the -phone if no data has -be exchanged for 300 seconds (5 minutes). You may wish to tailor this -number to your -specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<sect3> -<heading>The "<tt>demand</tt>" Section</heading> - -<p>The "<tt>demand</tt>" section contains the values and settings used -to set up a "Dial-on-demand" PPP session with a specific remote -system. Settings in this section will also have the lines included in -the "default" section included automatically. - -<p>Except for the last two lines in this section it is identical to -the configuration section which defines the "interactive" -configuration. - -<p>As noted in Paragraph ???, the examples cited in this section of -the guide presume that you'll be connecting to a remote system that -understands how to use the CHAP protocol to set up the connection. - -<p>Following are descriptions for each line in the "demand" section of -the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> - -This tells the PPP program that it should automatically hang up the -phone if no data has be exchanged for 300 seconds (5 minutes). You -may wish to tailor this number to your specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> - -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> - -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<tscreen><verb> -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -</verb></tscreen> - -This command sets up a pair of "fake" IP addresses for the local and -remote sides of the PPP link. It instructs the PPP program to create -an IP address of 127.1.1.1 for the local side of the '<tt/tun0/' -(tunnel) device (refer back to section ?? for a description of this -device) and 127.2.2.2 for the remote side. Appending '<tt>/0</tt>' to -each address tells the PPP program that zero of the bits that make up -these addresses are significant and can (in fact, must!) be negotiated -between the local and remote systems when the link is established. -The 255.255.255.0 string tells the PPP program what Subnet mask to -apply to these pseudo-interfaces. - -<p>Remember, we've assumed that your ISP provides the IP addresses for -both ends of the link! If your ISP assigned you a specific IP address -that you should use on your side when configuring your system, enter -that IP address here <em/instead/ of <tt>127.1.1.1</tt>. - -Conversly, if your ISP gave you a specific IP address that he uses on -his end you should enter that IP address here <em/instead/ of -<tt>127.2.2.2</tt>. - -In both cases, it's probably a good idea to leave the '<tt>/0</tt>' on -the end of each address. This gives the PPP program the opportunity -to change the address(es) of the link if it <em/has/ to. - -<tscreen><verb> -add 0 0 127.2.2.2 -</verb></tscreen> - -This last line tells the PPP program that it should add a default -route for IP traffic that points to the (fake) IP address of the ISP's -system. - -<em><bf>Note: If you used an ISP-specified address instead of -<tt>127.2.2.2</tt> on the preceeding line, use the same number here -instead of <tt>127.2.2.2</tt></bf></em>. - -<p>By adding this "fake" route for IP traffic, the PPP program can, -while idle: -<itemize> -<item>Accept packets that FreeBSD doesn't already know how to forward, -<item>Establish a connection to the ISP "<em/on-the-fly/", -<item>Reconfigure the IP addresses of the local and remote side of the link, -<item>Forward packets between your workstation and the ISP. -</itemize> -automatically! - -<p>Once the number of seconds specified by the timeout value in the -"default" section have elapsed without any TCP/IP traffic the PPP -program will automatically close the dial-up connection and the -process will begin again. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.linkup</tt>' file</heading> - -<p>The other file needed to complete the PPP configuration is found in -'<tt>/etc/ppp/ppp.linkup</tt>'. This file contains instructions for -the PPP program on what actions to take after a dial-up link is -established. - -In the case of dial-on-demand configurations the PPP program will need -to delete the default route that was created to the fake IP address of -the remote side (127.2.2.2 in our example in the previous section) and -install a new default route that points the actual IP address of the -remote end (discovered during the dial-up connection setup). - -A representative '<tt>/etc/ppp/ppp.linkup</tt>' file: -<tscreen><verb> -#########################################################################= - -# PPP Link Up File ('/etc/ppp/ppp.linkup') -# -# This file is checked after PPP establishes a network connection. -# -# This file is searched in the following order. -# -# 1) First, the IP address assigned to us is searched and -# the associated command(s) are executed. -# -# 2) If the IP Address is not found, then the label name specified at - -# PPP startup time is searched and the associated command(s) -# are executed. -# -# 3) If neither of the above are found then commands under the label -# 'MYADDR:' are executed. -# -#########################################################################= - -# -# This section is used for the "demand" configuration in -# /etc/ppp/ppp.conf: -demand: - delete ALL - add 0 0 HISADDR -# -# All other configurations in /etc/ppp/ppp.conf use this: -# -MYADDR: - add 0 0 HISADDR -######################################################################## -# End of /etc/ppp/ppp.linkup -</verb></tscreen> -Notice that there is a section in this file named "demand:", identical -to the configuration name used in the '<tt>/etc/ppp/ppp.conf</tt>' -file. This section instructs the PPP program that once a link is -established using this configuration, it must: -<enum> - <item>Remove any IP routing information that the PPP program has created - <item>Add a default route the remote end's actual address. -</enum> - -<p>It's critical that those configurations in -'<tt>/etc/ppp/ppp.conf</tt>' which include the '<tt/set ifaddr/' and -'<tt/add 0 0/' statements (i.e.: those configurations used for -Dial-on-Demand configurations) execute the "delete ALL" and "add 0 0 -HISADDR" commands in <tt>/etc/ppp/ppp.linkup</tt>. - -<p><em><bf>This is the mechanism that controls the actual on-demand -configuration of the link.</bf></em> - -<p>All configurations not explicitly named in -<tt>/etc/ppp/ppp.linkup</tt> will use whatever commands are in the -"MYADDR:" section of the file. This is where non-Demand-Dial -configurations (such as our "interactive:" sample) will fall through -to. This section simply adds a default route to the ISP's IP address -(at the remote end). - -<sect1> -<heading>IP Aliasing</heading> - -<p>All of the configuration steps described thus far are relevant to -any FreeBSD system which will be used to connect to an ISP via dial-up -connection. - -<p>If your sole objective in reading this guide is to connect your -FreeBSD box to the Internet using dial-out ppp you can proceed to -Section 6, "Testing the Network". - -One very attractive feature of the PPP program in on-demand mode is -its ability to route IP traffic between other systems on the Local -Area Network automatically. This feature is known by various names, -"<em/IP Aliasing/", "<em/Network Address Translation/", "<em/Address -Masquerading/" or "<em/Transparent Proxying/". - -<p>Regardless of the terminology used, this mode is not, however, -automatic. If the PPP program is started normally then the program -will not forward packets between LAN interface(s) and the dial-out -connection. In effect, only the FreeBSD system is connected to the -ISP; other workstations cannot "share" the same connection. - -For example, if the program is started with either of the following -command lines: -<p><tt># ppp interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto demand (Dial-on-Demand mode)</tt> -<p>then the system will function as an Internet-connected workstation -<em/only/ for the -FreeBSD box. - -To start the PPP program as a gateway between LAN resources and the -Internet, one of the following command lines would be used instead: -<p><tt># ppp -alias interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto -alias demand (Dial-on-Demand mode)</tt> -<p>Keep this in mind if you intend to proceed with Section 5, -"Configuring Windows Systems". -</sect> - -<sect> -<heading>Configuring Windows Systems</heading> - -<p>As indicated in Section 1, our example network consists of a -FreeBSD system ("Curly") which acts as a gateway (or router) between a -Local Area Network consisting of two different flavors of Windows -Workstations. In order for the LAN nodes to use Curly as a router -they need to be properly configured. Note that this section does not -explain how to configure the Windows workstations for Dial-Up -networking. If you need a good explanation of that procedure, I -recommend <url url="http://www.aladdin.co.uk/techweb">. - -<sect1> -<heading> Configuring Windows 95</heading> - -<p>Configuring Windows 95 to act as an attached resource on your LAN -is relatively simple. The Windows 95 network configuration must be -slightly modified to use the FreeBSD system as the default gateway to -the ISP. Perform the following steps: - -<p><bf>Create the Windows 95 "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it.<p> -The settings for all Network Elements are displayed. -<item>With the "Configuration" tab selected, scroll down the list of -installed components and highlight the "TCP/IP-><em/YourInterfaceType/" line -(where "<em/YourInterfaceType/" is the name or type of Ethernet adapter in your system). -<p>If TCP/IP is not listed in the list of installed network -components, click the "Add" button and install it before proceeding. -<p>(Hint: "Add | Protocol | Microsoft | TCP/IP | OK") -<item>Click on the "Properties" button to display a list of the -settings associated with the TCP component. -</itemize> - -<p><bf>Configure the IP Address Information:</bf> -<itemize> -<item>Click the "IP Address" tab -<item>Click the "Specify an IP address" radio button. - <p>(In our example LAN the Windows 95 system is the one we've called "Larry".) -<item>In the "IP Address" field enter "192.168.1.2". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> -<itemize> -<item>Click on the "Gateway" tab -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection. Enter the IP address of the FreeBSD -Ethernet interface, 192.168.1.1, in the "New gateway" field and click -the "Add" button. If any other gateways are defined in the "Installed -gateways" list you may wish to consider removing them. -</itemize> - -<p><bf>Configure the DNS Information:</bf> - -<p>This guide assumes that your Internet Service Provider has given -you a list of Domain Name Servers (or "DNS Servers") that you should -use. If you wish to run a DNS server on your local FreeBSD system, -refer to Section 6, "Exercise for the Interested Student" for tips on -setting up DNS on your FreeBSD system. - -<itemize> -<item>Click the "DNS Configuration" tab -<item>Make sure that the "Enable DNS" radio button is selected. -<p>(If this button is not selected only the entries that -we put in the host file(s) will be available and your Net-Surfing -will not work as you expect!) -<item>In the "Host" field enter the name of the Windows 95 box, in this -case: "Larry". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address -of the DNS server(s) that your ISP provided, clicking the "Add" button -after every address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows 95 TCP/IP options:</bf> - -<p>For our purposes the settings under the "Advanced", "WINS -Configuration" and "Bindings" tabs are not necessary. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties window. -<item>Click on the "OK" button to close the Network Control Panel. -<item>Reboot your computer if prompted to do so. -</itemize> - -<p> That's it! -<sect1> -<heading>Configuring Windows NT</heading> - -<p>Configuring Windows NT to act as a LAN resource is also relatively -straightforward. The procedures for configuring Windows NT are -similar to Windows 95 with minor exceptions in the user interface. - -<p>The steps shown here are appropriate for a Windows NT 4.0 -Workstation, but the principles are the same for NT 3.5x. You may -wish to refer to the "Configuring Windows for Workgroups" section if -you're configuring Windows NT 3.5<it/x/, since the user interface is -the same for NT 3.5 and WfW. - -<p>Perform the following steps: - -<p><bf>Create the Windows NT "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4 -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\SYSTEM\DRIVERS\ETC\HOSTS" (without the quotes) and click -"OK" -<item>In the editor, enter the addresses and system names from Section -3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows NT TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it. -<item>With the "Identification" tab selected, verify the "Computer Name" -and "Workgroup" fields. In this example we'll use "Shemp" for the name -and "Stooges" for the workgroup. Click the "Change" button and amend -these entries as necessary. -<item>Select the "Protocols" tab. - -<p>The installed Network Protocols will be displayed. There may be a -number of protocols listed but the one of interest to this guide is -the "TCP/IP Protocol". If "TCP/IP Protocol" is not listed, click the -"Add" button to load it. -<p>(Hint: "Add | TCP/IP Protocol | OK") <item>Highlight "TCP/IP -Protocol" and click the "Properties" button. -<p>Tabs for specifying various settings for TCP/IP will be displayed. - </itemize> - -<p><bf>Configuring the IP Address:</bf> - -<p>Make sure that the Ethernet Interface is shown in the "Adapter" -box; if not, scroll through the list of adapters until the correct -interface is shown. -<itemize> -<item>Click the "Specify an IP address" radio button to enable the three -text boxes. -<p>In our example LAN the Windows NT system is the one we've called -"Shemp" -<item>In the "IP Address" field enter "192.168.1.4". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our gateway -to the Internet (routing packets between the Ethernet LAN and the PPP dial-up -connection. -<itemize> -<item>Enter the IP address of the FreeBSD Ethernet interface, -192.168.1.1, in the "New gateway" field and click the "Add" button. -<p>If any other gateways are defined in the "Installed gateways" list -you may wish to consider removing them. -</itemize> -<p><bf>Configuring DNS:</bf> -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. - -If you wish to run a DNS server on your local FreeBSD system, refer to -Section 6, "Exercise for the Interested Student" for tips on setting -up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" tab -<item>In the "Host Name" field enter the name of the Windows NT box, in -this case: "Shemp". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address of -the DNS server that your ISP provided, clicking the "Add" button after -every address is entered. Repeat this step as many times as necessary -to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows NT TCP/IP options:</bf> - -<p>For our purposes the settings under the "WINS Address" and -"Routing" tabs are not used. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties section. - -<item>Click on the "Close" button to close the Network Control Panel. - -<item>Restart your computer if prompted to do so. -</itemize> - -<p>That's it! - -<sect1> -<heading>Configuring Windows for Workgroups</heading> - -<p>Configuring Windows for Workgroups to act as a network client -requires that the Microsoft TCP/IP-32 driver diskette has been -installed on the workstation. The TCP/IP drivers are not included -with the WfW CD or diskettes; if you need a copy they're available at -<url url="ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip">. - -<p>Once the TCP/IP drivers have been loaded, perform the following -steps: - -<p><bf>Create the Windows for Workgroups "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>In Program Manager, click the "File" button; select "Run"; and -enter: "notepad \WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf> -<itemize> -<item>In the main window of Program Manager, open the "Network" group by -double-clicking the icon. -<item>Double click on the "Network Setup" icon. -<item>In the "Network Drivers Box" double-click the "Microsoft -TCP/IP-32" entry. -</itemize> - -<p><bf>Configure the Windows for Workgroups IP Address:</bf> <p>Ensure -the correct Ethernet Interface is selected in the "Adapter" list. If -not, scroll down until it is displayed and select it by clicking on -it. -<itemize> -<item>Ensure that the "Enable Automatic DHCP Configuration" check box is -blank. If it is checked, click it to remove the "X". -<item>In our example LAN the Windows for Workgroups system is the one -we've called "Moe"; in the "IP Address" field enter "192.168.1.3". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection). -<itemize> -<item>Enter the IP address of the FreeBSD system, 192.168.1.1, in the -"Default Gateway" field. -</itemize> - -<p><bf>Configuring DNS:</bf> - -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. If you wish to run a DNS server on your local FreeBSD -system, refer to Section 6, "Exercise for the Interested Student" for -tips on setting up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" button. -<item>In the "Host Name" field enter the name of the Windows for -Workgroups box, in this case: "Moe". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "Domain Name Service (DNS) Search Order" section, enter the -IP address of the DNS server that your ISP provided, clicking the "Add" -button after each address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -<item>Click on the "OK" button to close the DNS Configuration window. - -</itemize> - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Configuration window. - -<item>Click on the "OK" button to close the Network Setup window. -<item>Reboot your computer if prompted. -</itemize> - -<p>That's it! - -<sect> -<heading>Testing the Network</heading> - -<p> Once you've completed that appropriate tasks above you should have -a functioning PPP gateway to the Internet. - -<sect1> -<heading>Testing the Dial-Up link:</heading> - -<p> The first thing to test is that the connection is being made -between your modem and the ISP. - -<sect1> -<heading>Testing the Ethernet LAN</heading> - -<p> *** TBD *** -</sect> - -<sect> -<heading>Exercises for the Interested Student</heading> - -<p> -<sect1> -<heading>Creating a mini-DNS system</heading> - -<p>While managing a Domain Name Service (DNS) hierarchy can be a black -art, it is possible to set up a Mini-DNS server on the FreeBSD system -that also acts as your gateway to your ISP. - -<p>Building on the files in <tt>/etc/namedb</tt> when the FreeBSD -system was installed it's possible to create a name server that is -both authoritative for the example network shown here as well as a -front-door to the Internet DNS architecture. - -<p>In this minimal DNS configuration, only three files are necessary: -<tscreen><verb> -/etc/namedb/named.boot -/etc/namedb/named.root -/etc/namedb/mydomain.db -</verb></tscreen> - -<p>The <tt>/etc/namedb/named.root</tt> file is automatically installed -as part of the FreeBSD base installation; the other two files must be -created manually. - -<sect2> -<heading>The <tt>/etc/namedb/named.boot</tt> file</heading> -<p>The <tt>/etc/namedb/named.boot</tt> file controls the startup -settings of the DNS server. -Esentially, it tells the Name Server: -<enum> -<item>Where to find configuration files, -<item>What "domain names" it's responsible for, and -<item>Where to find other DNS servers. -</enum> - -<p>Using the '<tt/ee/' editor, create a -<tt>/etc/namedb/named.boot</tt> with the following contents: -<tscreen><verb> -; boot file for mini-name server - -directory /etc/namedb - -; type domain source host/file backup file - -cache . named.root -primary my.domain. mydomain.db -</verb></tscreen> -<p>Lines that begin with a semi-colon are comments. The significant -lines in this file are: -<itemize> -<item><tt>directory /etc/namedb</tt> -<p>Tells the Name Server where to find the configuration files -referenced in the remaining sections of the -'<tt>/etc/namedb/named.boot</tt>' file. -<item><tt>cache . named.root</tt> -<p>Tells the Name Server that the list of "Top-Level" DNS servers for -the Internet can be found in a file called '<tt>named.root</tt>'. -(This file is included in the base installation and its -contents are not described in this document.) -<item><tt>primary my.domain. mydomain.db</tt> -<p>Tells the Name Server that it will be "authoritative" for a DNS -domain called "my.domain" and that a list of names and IP addresses -for the systems in "my.domain" (the local network) -can be found in a file named '<tt>mydomain.db</tt>'. -</itemize> -<p>Once the <tt>/etc/namedb/named.boot</tt> file has been created and -saved, proceed to the next section to create the -<tt>/etc/namedb/mydomain.db</tt> file. - -<sect2> -<heading>The <tt>/etc/namedb/mydomain.db</tt> file</heading> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file lists the names and IP -addresses of <em/every/ system in the Local Area Network. - -<p><em>For a detailed description of the statements used in this file, -refer to the <tt/named/ manpage.</em> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file for our minimal DNS -server has the following contents: -<tscreen><verb> -@ IN SOA my.domain. root.my.domain. ( - 961230 ; Serial - 3600 ; Refresh - 300 ; Retry - 3600000 ; Expire - 3600 ) ; Minimum - IN NS curly.my.domain. - -curly.my.domain. IN A 192.168.1.1 # The FreeBSD box -larry.my.domain. IN A 192.168.1.2 # The Win'95 box -moe.my.domain. IN A 192.168.1.3 # The WfW box -shemp.my.domain. IN A 192.168.1.4 # The Windows NT box - -$ORIGIN 1.168.192.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR curly.my.domain. -2 IN PTR larry.my.domain. -3 IN PTR moe.my.domain. -4 IN PTR shemp.my.domain. - -$ORIGIN 0.0.127.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR localhost.my.domain. -</verb></tscreen> -<p>In simple terms, this file declares that the local DNS server is: -<itemize> -<item>The Start of Authority for ("SOA") for a domain called -'my.domain', -<item>The Name Server ("NS") for 'my.domain', -<item>Responsible for the reverse-mapping for all IP addresses that -start with '192.168.1.' and -'127.0.0.' ("$ORIGIN ...") -</itemize> - -<p>To add workstation entries to this file you'll need to add two -lines for each system; one in the top section where the name(s) are -mapped into Internet Addresses ("IN A"), and another line that maps -the addresses back into names in the <tt>$ORIGIN -1.168.192.IN-ADDR.ARPA</tt> section. - -<sect2> -<heading>Starting the DNS Server</heading> - -<p>By default the DNS server ('<tt>/usr/sbin/named</tt>') is not -started when the system boots. You can modify this behavior by -changing a single line in '<tt>/etc/sysconfig</tt>' as follows: - -<p> Using the '<tt/ee/' editor, load <tt>/etc/sysconfig</tt>. Scroll -down approximately 200 lines until you come to the section that says: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="NO" ---- -</verb></tscreen> -Change this section to read: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="-b /etc/namedb/named.boot" ---- -</verb></tscreen> -Save the file and reboot. - -Alternatively, start the Name Server daemon by entering the following -command: -<tscreen><verb> -# named -b /etc/namedb/named.boot -</verb></tscreen> - -<p>Whenever you modify any of the files in <tt>/etc/namedb</tt> you'll -need to kick-start the Name Server process to make it pick up the -modifications. This is performed with the following system command: -<tscreen><verb> -# kill -HUP `cat /var/run/named.pid` -</verb></tscreen> - -<sect1> -<heading>Playing with PPP filters</heading> - -<p>The PPP program has the ability to apply selected filtering rules -to the traffic it routes. While this is not nearly as secure as a -formal firewall it does provide some access control as to how the link -is used. - -<p>('<tt>man ipfw</tt>' for information on setting up a more secure -FreeBSD system.) - -<p>The complete documentation for the various filters and rules under -PPP are availabe in the PPP manpage. - -<p>There are four distinct classes of rules which may be applied to -the PPP program: -<itemize> -<item><tt/afilter/ - Access Counter (or "Keep Alive") filters -<p>These control which events are ignored by the <tt/set timeout=/ -statement in the configuration file. -<item><tt/dfilter/ - Dialing filters -<p>These filtering rules control which events are ignored by the -demand-dial mode of PPP. -<item><tt/ifilter/ - Input filters -<p>Control whether incoming packets should be discarded or passed into -the system. -<item><tt/ofilter/ - Output filters -<p>Control whether outgoing packets should be discarded or passed into -the system. -</itemize> -<p> - -What follows is a snippet from an operating system which provides a -good foundation for "normal" Internet operations while preventing PPP -from pumping <em/all/ data over the dial-up connection. Comments -briefly describe the logic of each rule set: -<tscreen><verb> -# -# KeepAlive filters -# Don't keep Alive with ICMP,DNS and RIP packet -# - set afilter 0 deny icmp - set afilter 1 deny udp src eq 53 - set afilter 2 deny udp dst eq 53 - set afilter 3 deny udp src eq 520 - set afilter 4 deny udp dst eq 520 - set afilter 5 permit 0/0 0/0 -# -# Dial Filters: -# Note: ICMP will trigger a dial-out in this configuration! -# - set dfilter 0 permit 0/0 0/0 -# -# Allow ident packet pass through -# - set ifilter 0 permit tcp dst eq 113 - set ofilter 0 permit tcp src eq 113 -# -# Allow telnet connection to the Internet -# - set ifilter 1 permit tcp src eq 23 estab - set ofilter 1 permit tcp dst eq 23 -# -# Allow ftp access to the Internet -# - set ifilter 2 permit tcp src eq 21 estab - set ofilter 2 permit tcp dst eq 21 - set ifilter 3 permit tcp src eq 20 dst gt 1023 - set ofilter 3 permit tcp dst eq 20 -# -# Allow access to DNS lookups -# - set ifilter 4 permit udp src eq 53 - set ofilter 4 permit udp dst eq 53 -# -# Allow DNS Zone Transfers -# - set ifilter 5 permit tcp src eq 53 - set ofilter 5 permit tcp dst eq 53 -# -# Allow access from/to local network -# - set ifilter 6 permit 0/0 192.168.1.0/24 - set ofilter 6 permit 192.168.1.0/24 0/0 -# -# Allow ping and traceroute response -# - set ifilter 7 permit icmp - set ofilter 7 permit icmp - set ifilter 8 permit udp dst gt 33433 - set ofilter 9 permit udp dst gt 33433 -# -# Allow cvsup -# - set ifilter 9 permit tcp src eq 5998 - set ofilter 9 permit tcp dst eq 5998 - set ifilter 10 permit tcp src eq 5999 - set ofilter 10 permit tcp dst eq 5999 -# -# Allow NTP for Time Synchronization -# - set ifilter 11 permit tcp src eq 123 dst eq 123 - set ofilter 11 permit tcp src eq 123 dst eq 123 - set ifilter 12 permit udp src eq 123 dst eq 123 - set ofilter 12 permit udp src eq 123 dst eq 123 -# -# SMTP'd be a good idea! -# - set ifilter 13 permit tcp src eq 25 - set ofilter 13 permit tcp dst eq 25 -# -# -# We use a lot of `whois`, let's pass that -# - set ifilter 14 permit tcp src eq 43 - set ofilter 14 permit tcp dst eq 43 - set ifilter 15 permit udp src eq 43 - set ofilter 15 permit udp dst eq 43 -# -# If none of above rules matches, then packet is blocked. -#------- -</verb></tscreen> -<p>Up to 20 distinct filtering rules can be applied to each class of -filter. Rules in each class are number sequentially from 0 to 20 -<em/but none of the rules for a particular filter class take affect -until ruleset '0' is defined!/ - -<p>If you choose <em/not/ to use Filtering Rules in the PPP -configuration then <em/ALL/ traffic will be permitted both into and -out of your system while it's connected to your ISP. - -If you decide that you want to implement filtering rules, add the -above lines to your <tt>/etc/ppp/ppp.conf</tt> file in either the -"default:", "demand:", or "interactive:" section (or all of them - the -choice is yours). - -</sect> - -</article> - diff --git a/en/tutorials/upgrade/Makefile b/en/tutorials/upgrade/Makefile deleted file mode 100644 index f751bbe481..0000000000 --- a/en/tutorials/upgrade/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.1 1997-06-25 16:57:01 jfieber Exp $ -DOCS= upgrade.docb -INDEXLINK= upgrade.html - -.include "../../web.mk" - diff --git a/en/tutorials/upgrade/upgrade.docb b/en/tutorials/upgrade/upgrade.docb deleted file mode 100644 index 6ec62e4b0a..0000000000 --- a/en/tutorials/upgrade/upgrade.docb +++ /dev/null @@ -1,758 +0,0 @@ -<!-- $Id: upgrade.docb,v 1.2 1997-09-14 03:53:16 jfieber Exp $ --> -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> - -<book> - <bookinfo> - <bookbiblio> - <title/<quote>Making the world</quote> your own/ - - <authorgroup> - <author> - <firstname/Nik/ - <surname/Clayton/ - <affiliation> - <address><email/Nik.Clayton@iii.co.uk/</address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$Date: 1997-09-14 03:53:16 $</pubdate> - </bookbiblio> - </bookinfo> - - <preface> - <title/Overview/ - - <para>This document assumes that you have downloaded a version of the - FreeBSD source code and placed it in <filename>/usr/src</filename>. This - might be the latest version from the -current development branch, or - perhaps you're just tracking -stable. Either way, you have the source - code and now need to update your system.</para> - - <para>There are a number of steps to perform to do this, and a few - pitfalls to avoid along the way. This document takes you through - those necessary steps one by one.</para> - - <warning> - <title>Take a backup - - I cannot stress highly enough how important it is to take a backup - of your system before you do this. While remaking - the world is (as long as you follow these instructions) an easy task to - do, there will inevitably be times when you make mistakes, or when - mistakes made by others in the source tree render your system - unbootable. - - Make sure you've taken a backup. And have a fixit floppy to - hand. I've never needed to use them, and, touch wood, I never will, - but it's always better to be safe than sorry. - - - - 2.1.7 specific - - This document was written and tested with FreeBSD - 2.1.7-RELEASE. That was a while ago (at the time of writing - 2.2.5-RELEASE is perhaps 30 days away. Most of the information pertains - to all versions of FreeBSD greater than 2.1. Where there are specific - differences between versions (and where I'm aware of them) I'll note - them. If you know of a difference between different versions that - impacts on this document, please let me know. - - - - - Check <filename>/etc/make.conf</filename> - - Examine the file /etc/make.conf. This contains - some default defines for - - Everything is, by default, commented out. Uncomment those entries - that look useful. For a typical user (not a developer), you'll probably - want to uncomment the CFLAGS and NOPROFILE definitions. If your machine - has a floating point unit (386DX, 486DX, Pentium and up class machines) - then you can also uncomment the HAVE_FPU line. - - - - - - You want to compile the system in single user mode. Apart from the - obvious benefit of making things go slightly faster, re-making the system - will touch a lot of important system files, all the standard system - binaries, libraries, include files and so on. Try to change these on a - running system and you're asking for trouble.</para> - - <para>As the superuser, you can execute - - <informalexample> -<screen><prompt/#/ <userinput/shutdown now/</screen> - </informalexample> - - from a running system, which will drop it to single user mode.</para> - - <para>Alternatively, reboot the system, and at the boot prompt, enter the - <option>-s</option> flag. The system will then boot single user. At the - shell prompt you should then run - - <informalexample> -<screen><prompt/#/ <userinput/fsck -p/ -<prompt/#/ <userinput>mount -u /</userinput> -<prompt/#/ <userinput/mount -a -t ufs/ -<prompt/#/ <userinput/swapon -a/</screen> - </informalexample> - - which check the filesystems, remounts <filename>/</filename> read/write, - mounts all the other UFS filesystems referenced in - <filename>/etc/fstbab</filename> and then turns swapping on.</para> - - <para>For extra speed, you can also do - - <informalexample> - <screen><prompt/#/ <userinput/mount -u -o async -t ufs -a/</screen> - </informalexample> - - which remounts all your UFS filesystems for asynchronous access. The - trade off is that if the power suddenly fails while the system is being - rebuilt you are more likely to suffer from filesystem corruption.</para> - </chapter> - - <chapter> - <title/Recompile the source/ - - <para>In general, this is as simple as - - <informalexample> -<screen><prompt/#/ <userinput>cd /usr/src</userinput> -<prompt/#/ <userinput>make world 2>&1 | tee /var/tmp/mw.out</userinput></screen> - </informalexample> - - which will re-make the world, storing a copy of all the STDOUT and STDERR - messages in <filename>/var/tmp/mw.out</filename>. It's important to use - <filename>/var/tmp</filename>, as plain <filename>/tmp</filename> is - generally cleared out when you reboot, and you want this output to stay - around for a while.</para> - - <note> - <title><filename>/bin/sh</filename> specific - - The 2>&1 construct is specific to the - /bin/sh shell. Under /bin/csh - you could use - - -make world |& tee /var/tmp/mw.out - - - - - - Other shells have their own constructs to do the same - thing. - - Alternatively, if you don't care to use shell redirection, you - could use script to save a copy of all the - output. - - - script /var/tmp/mw.out -Script started, output file is /var/tmp/mw.out -… compile, compile, compile … - - - - - Then go and make yourself several cups of tea. Remaking the world is - a long process. One of our servers, a 200Mhz P6 with fairly - run-of-the-mill SCSI disks, 64MB RAM and 256MB swap it takes a shade - under two hours to complete. - - One of the 32MB (128MB swap), P133 machines takes about 5 - hours. - - The only caveat I am aware of is that (at least the last few times I - tried it with 2.1.5), - - Which means, whenever I have to install a new machine, I generally - download the - - This may have changed up to 2.1.7. I unfortunately do not have the - spare machines to test it. - - - - Remaking the world will not update certain directories (in - particular, <filename>/etc</filename>, <filename>/var</filename> and - <filename>/usr</filename>) with new or changed configuration files. This - is something you have to do by hand, eyeball, and judicious use of the - <command/diff/ command.</para> - - <sect1> - <title>Backup your existing <filename>/etc</filename> - - Although, in theory, nothing's going to touch this directory - automatically, it's always better to be sure. So copy your existing - /etc directory somewhere safe. Something like - - -cp -rp /etc /etc.old - - - will do the trick ( does a recursive copy, - preserves times, ownerships on files and - suchlike). - - - - You need to build a dummy set of directories to install the new - <filename>/etc</filename> and other files into. I generally choose to - put this dummy dir in <filename>/var/tmp/root</filename>, and there are - a number of subdirectories required under this as well. So execute - - <informalexample> - <screen><prompt/#/ <userinput>mkdir /var/tmp/root</userinput> -<prompt/#/ <userinput>mtree -deU -f /usr/src/etc/mtree/BSD.root.dist -p /var/tmp/root/</userinput> -<prompt/#/ <userinput>mtree -deU -f /usr/src/etc/mtree/BSD.var.dist -p /var/tmp/root/var/</userinput> -<prompt/#/ <userinput>mtree -deU -f /usr/src/etc/mtree/BSD.usr.dist -p /var/tmp/root/usr/</userinput></screen> - </informalexample> - - which will build the necessary directory structure.</para> - - <para>A lot of these subdirs are extraneous, but you can ignore them - for the time being, they'll be removed in the next - step.</para> - </sect1> - - <sect1> - <title/Install the updated files/ - - <para>Now that the directory tree has been built, you have to install - the new files from <filename>/usr/src/etc</filename> into it. - - <informalexample> -<screen><prompt/#/ <userinput>cd /usr/src/etc</userinput> -<prompt/#/ <userinput>make DESTDIR=/var/tmp/root distribution</userinput></screen> - </informalexample> - - This will leave several redundant empty directories scattered - around, cluttering up your <command/ls/ output. The simplest way - to get rid of them is to do - - <informalexample> - <screen><prompt/#/ <userinput>cd /var/tmp/root</userinput> -<prompt/#/ <userinput>find -d . -type d | /usr/bin/perl -lne \ - 'opendir(D,$_);@f=readdir(D);rmdir if $#f != 1;closedir(D);'</userinput></screen> - </informalexample> - - which does a depth first search, examines each directory, and if the - number of files in that directory is 2 ('1' is not a typo in the - script) i.e., '.' and '..' then it removes the - directory.</para> - </sect1> - </chapter> - - <chapter> - <title>Merge in the changed files from - <filename>/var/tmp/root/*</filename> - - /var/tmp/root now contains all the files that - should be placed in appropriate locations below - /. You now have to go through each of these files, - determining how they differ with your existing files. This is not a task - that can be automated (at the moment). - - Note that some of the files that will have been installed in - /var/tmp/root have a leading '.'. Make sure you use - - - The simplest way to do this is to use the -c for the context - output format, or for the unified output format. I - find it easier to read context diffs. - - For example, - - -diff -c /etc/shells /var/tmp/root/etc/shells - - - will show you the differences between your - /etc/shells file and the new - /etc/shells file. Use these to decide whether to - merge in changes that you've made or whether to copy over your old - file. - - When it comes to /var/tmp/root/dev, you should - just copy over the - - You will use those scripts a little later to update your - /dev directory. - - Here is a (probably incomplete) list of files that you will - probably want to merge or copy by hand. - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - namedb/* - - ppp/* - - - - - - That is not an exhaustive list, and changes to FreeBSD in the future - may necessitate moving files from the - - Those filenames shown in - - - <filename>/etc/rc.conf</filename> and - <filename>/etc/rc.network</filename> - - Starting with FreeBSD 2.2.2-RELEASE, - - - - - - Update <filename>/dev</filename> - - For safety's sake, this is a multistep process. You should already - have copied in the /dev. Do the following, - - -ls -la /dev > /var/tmp/dev1.out -ls -la /var/tmp/root/dev > /var/tmp/dev2.out - - - This gives you a reference for when things go wrong… Run a - quick diff over these two files to see if anything's missing. If you use - slices in your disk partitioning (which may not be necessary on a - dangerously dedicated disk) then these slices have almost - certainly not been made. - - Note down the devices that exist in - - Now do, - - -cd /dev -sh MAKEDEV all - - - - This will generate all the standard devices. You must now do whatever's - necessary to recreate devices that you noticed as missing in the previous - step. For my setup, that involved doing - - -sh MAKEDEV sd0s1a -sh MAKEDEV sd1s1a - - - - to create the slice entries on my two disks. Your circumstances may - vary. If at all in doubt, make sure you have a handy boot and fixit - floppy, and a very recent backup of your system. - - - - If you didn't copy over the <filename/localtime/ file from your old - <filename>/etc</filename> (which is probably a good idea, you may as well - generate it fresh), run <command/tzsetup/ (in - <filename>/usr/sbin</filename>) to set your timezone.</para> - </chapter> - - <chapter> - <title/Compiling a new kernel/ - - <para>To take full advantage of your new system you should recompile the - kernel. This is practically a necessity, as certain memory structures may - have changed, and programs like <command/ps/ and <command/top/ will fail - to work until the kernel and source code versions are the same.</para> - - <para>Follow the handbook instructions for compiling a new kernel. If you - have previously built a custom kernel then carefully examine the - <filename/LINT/ config file to see if there are any new options which you - should take advantage of.</para> - - <para>A previous version of this document suggested rebooting before - rebuilding the kernel. This is wrong because: </para> - - <itemizedlist> - <listitem><para>Commands like <command/ps/, <command/ifconfig/ and - <command/sysctl/ may fail. This could leave your machine unable to - connect to the network.</para></listitem> - - <listitem><para>Basic utilities like <command/mount/ could fail, - making it impossible to mount <filename>/</filename>, - <filename>/usr</filename> and so on. This is unlikely if you're - tracking a -stable candidate, but more likely if you're tracking - -current during a large merge.</para></listitem> - </itemizedlist> - - <para>For these reasons, it is always best to rebuild and install a - new kernel before rebooting.</para> - </chapter> - - <chapter> - <title/Rebooting/ - - <para>You're now done. After you've verified that everything appears to be - in the right place (pay particular attention to the <emphasis/emphasised/ - files listed earlier), you can reboot the system. A simple - <command/fastboot/ should do it.</para> - </chapter> - - <chapter> - <title>That's it - - You should now have successfully upgraded your FreeBSD system. - Congratulations. It's likely that over the next few days you'll notice - little oddities that don't work as expected, or small upgrades you've - forgotten to do. Something I missed for several days was that - /etc/magic was missing. It was only when I went to - run /usr/src/usr.bin/file sorted that one out. - - - - - <title/Do I need to re-make the world for every change?/ - - <para>There's no easy answer to this one, as it depends on the nature of - the change. For example, I've just run CVSup, and it's shown the - following files as being updated since I last ran it;</para> - - <informalexample> -<screen><filename>src/games/cribbage/instr.c</filename> -<filename>src/games/sail/pl_main.c</filename> -<filename>src/release/sysinstall/config.c</filename> -<filename>src/release/sysinstall/media.c</filename> -<filename>src/share/mk/bsd.port.mk</filename></screen> - </informalexample> - - <para>There's nothing in there that I'd re-make the world for. I'd go to - the appropriate sub-directories and <command/make all install/, and - that's about it. But if something major changed, like, say, - <filename>src/lib/libc/stdlib</filename> then I'd probably either - re-make the world, or at least those parts of it that are statically - linked (as well as anything else I might have added that's statically - linked).</para> - - <para>At the end of the day, it's your call. You might be happy - re-making the world every fortnight say, and let changes accumulate - over that fortnight. Or you might want to re-make just those things - that have changed, and are confident you can spot all the - dependencies.</para> - - <para>And, of course, this all depends on how often you want to upgrade, - and whether you are tracking -stable, a release candidate (2.2 at the - time of writing), or -current.</para> - - <para>In any case, it's always worthwhile to subscribe to the relevant - mailing lists, depending on which version of FreeBSD you are staying up - to date with. Not only will this give you a <quote/heads up/ of - forthcoming changes, but it also means you'll see problems other people - might be having making the world, and lets you learn from their - problems.</para> - </sect1> - - <sect1> - <title>My compile failed with lots of signal 12 (or other signal number) - errors - - This is normally indicative of hardware problems. (Re)making the - world is an effective way to stress test your hardware, and will - frequently throw up memory problems. These normally manifest themselves - as the compiler mysteriously dieing on receipt of strange - signals. - - A sure indicator of this is if you can restart the make and it - dies at a different point in the process. - - In this instance there is little you can do except start swapping - around the components in your machine to determine which one is - failing. - - - - Can I remove <filename>/usr/obj</filename> when I've - finished? - - That depends on how you want to make the world on future - occasions. - - /usr/obj contains all the object files - that were produced during the compilation phase. Normally, one of the - first steps in the /usr/obj around after you've finished makes - little sense, and will free up a large chunk of disk space (currently - about 150MB). - - However, if you know what you're doing you can have - - If you want to live dangerously then make the world, passing the - - make -DNOCLEAN world - - - - - - My compile failed with a particular error, which I've now - fixed. Do I need to remake the world (and lose the result of the - previous build) or can I continue from where I left off? - - This depends on how far through the process you got before you - found a problem. - - In general (and this is not a hard and fast - rule) the make world process builds new copies - essential tools (such as gcc, and - make) and the system libraries. These tools and - libraries are then installed. The new tools and libraries are then - used to rebuild themselves, and are installed again. The entire system - (now including regular user programs, such as ls or - grep) is then rebuilt with the new system - files. - - If you're at the last state, and you know it (because you've - looked through the output that you were storing) then you can (fairly - safely) do - - - … fix the problem … -cd /usr/src - - - - which will not undo the work of the previous make - world. - - If you see the message - - --------------------------------------------------------------- - Building everything.. --------------------------------------------------------------- - - - in the make world output then it's probably fairly safe - to do so. - - If you don't see that message, or you're not sure, then it's always - better to be safe than sorry, and restart the build from - scratch. - - - - People often ask on the FreeBSD mailing lists whether they can do - all the compiling on one machine, and then use the results of that - compile to <command/make install/ on to other machines around the - network.</para> - - <para>This is not something I've done. However, in a message to - questions@freebsd.org, Antonio Bemfica suggested the following - approach:</para> - -<screen> -Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST) -From: Antonio Bemfica <bemfica@militzer.me.tuns.ca> -To: freebsd-questions@freebsd.org -Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca> - -Josef Karthauser asked: - -> Has anybody got a good method for upgrading machines on a network - -First make world, etc. on your main machine -Second, mount / and /usr from the remote machine: - -main_machine% mount remote_machine:/ /mnt -main_machine% mount remote_machine:/usr /mnt/usr - -Third, do a 'make install' with /mnt as the destination: - -main_machine% make install DESTDIR=/mnt - -Repeat for every other remote machine on your network. It works fine -for me. - -Antonio -</screen> - - <para>Which sounds interesting. Note that, of course, you will not - upgrade the target machines <filename>/etc</filename> directory (and - others as outlined above) by doing this.</para> - - <note> - <title>2.2.2-RELEASE and up - - My FreeBSD 2.2.2-RELEASE system shows a reinstall - target in /usr/src/Makefile. The comment for - this includes: - - -# reinstall -# -# If you have a build server, you can NFS mount the source and obj directories -# and do a 'make reinstall' on the *client* to install new binaries from the -# most recent server build. - - - I have no idea how well this works, or whether it is present in - earlier versions of FreeBSD. I mention it here for - completeness. - - - - - - Contributors - - The following people have contributed to this document in some form - or another. Either by directly suggesting alterations and improvements, - or by their messages to the FreeBSD mailing lists, from which I have - shamelessly cribbed information. My thanks to them. - - - - Kees Jan Koster, <kjk1@ukc.ac.uk> - - - - A Joseph Kosy, <koshy@india.hp.com> - - - - Greg Lehey, <grog@lemis.com> - - - - Wes Peters, <softweyr@xmission.com> - - - - Joseph Stein, <joes@joes.users.spiritone.com> - - - - diff --git a/en_US.ISO8859-1/articles/fonts/Makefile b/en_US.ISO8859-1/articles/fonts/Makefile deleted file mode 100644 index 260184f87c..0000000000 --- a/en_US.ISO8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= fonts.docb -INDEXLINK= fonts.html - -.include "../../web.mk" diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml deleted file mode 100644 index 4d46efb511..0000000000 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,723 +0,0 @@ - - - - - - - - - - -Fonts and FreeBSD -A Tutorial - - - -Dave -Bodenstab - -
imdave@synet.net
- - - - -Wed Aug 7, 1996 - -This document contains a description of the various -font files that may be used with FreeBSD and the syscons driver, X11, -Ghostscript and Groff. Cookbook examples are provided for switching -the syscons display to 80x60 mode, and for using type 1 fonts with -the above application programs. - - - - - -Introduction - -There are many sources of fonts available, and one might ask -how they might be used with FreeBSD. The answer can be found by -carefully searching the documentation for the component that one -would like to use. This is very time consuming, so this tutorial is -an attempt to provide a shortcut for others who might be -interested. - - - - -Basic terminology - -There are many different font formats and associated font file -suffixes. A few that will be addressed here are: - - -.pfa, .pfb - -Postscript type 1 fonts. The .pfa is the -Ascii form and .pfb the -Binary form. - - - -.afm - -The font metrics associated with a type 1 -font. - - - -.pfm - -The printer font metrics associated with a type 1 -font. - - - -.ttf - -A TrueType font - - - -.fot - -An indirect reference to a TrueType font (not an -actual font) - - - -.fon, .fnt - -Bitmapped screen fonts - - - - -The .fot file is used by Windows as sort -of a symbolic link to the actual TrueType font -(.ttf) file. The .fon font -files are also used by Windows. I know of no way to use this font -format with FreeBSD. - - - - -What font formats can I use? - -Which font file format is useful depends on the application -being used. FreeBSD by itself uses no fonts. Application programs -and/or drivers may make use of the font files. Here is a small cross -reference of application/driver to the font type suffixes: - - - -Driver - - - -syscons - -.fnt - - - - - - - - - -Application - - - - -Ghostscript - -.pfa, .pfb, .ttf - - - - -X11 - - -.pfa, .pfb - - - - -Groff - - -.pfa, .afm - - - - -Povray - - -.ttf - - - - - - - - - - - -The .fnt suffix is used quite frequently. -I suspect that whenever someone wanted to create a specialized font -file for their application, more often than not they chose this -suffix. Therefore, it is likely that files with this suffix are not -all the same format; specifically, the .fnt -files used by syscons under FreeBSD may not be the same format as a -.fnt file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -.fnt files other than those provided with -FreeBSD. - - - - -Setting a virtual console to 80x60 line mode - -First, a 8x8 font must be loaded. -/etc/sysconfig should contain the lines: - -# Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt - - - -The command to actually switch the mode is -vidcontrol1: - -bash$ vidcontrol VGA_80x60 - - - -Various screen orientated programs, such as -vi1, must be able to -determine the current screen dimensions. These can be set with -stty1: - -bash$ stty crt rows 60 columns 80 - - - -To make this more seamless, one can embed these commands in the -startup scripts so it takes place when the system boots. One way to -do this is: - - - -Modify /etc/sysconfig as above - - - -Add to /etc/rc.local: - -for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done - - - - -Add to /etc/profile: - -TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi - - - - - - - -References: -stty1, -vidcontrol1. - - - - -Using type 1 fonts with X11 - -X11 can use either the .pfa or the -.pfb format fonts. The X11 fonts are located in -various subdirectories under -/usr/X11R6/lib/X11/fonts. Each font file is -cross referenced to its X11 name by the contents of the -fonts.dir file in each directory. - -There is already a directory named Type1. The most -straight forward way to add a new font is to put it into this -directory. A better way is to keep all new fonts in a separate -directory and use a symbolic link to the additional font. This -allows one to more easily keep track of ones fonts without confusing -them with the fonts that were originally provided. For -example: - -Create a directory to contain the font files -bash$ mkdir -p /usr/local/share/fonts/type1 -bash$ cd /usr/local/share/fonts/type1 - -Place the .pfa, .pfb and .afm files here -One might want to keep readme files, and other documentation -for the fonts here also -bash$ cp /cdrom/fonts/atm/showboat/showboat.pfb . -bash$ cp /cdrom/fonts/atm/showboat/showboat.afm . - -Maintain an index to cross reference the fonts -bash$ echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX - - - -Now, to use a new font with X11, one must make the font file -available and update the font name files. The X11 font names look -like: - --bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style - - - -A new name needs to be created for each new font. If you have -some information from the documentation that accompanied the font, -then it could serve as the basis for creating the name. If there is -no information, then you can get some idea by using -strings1 on the font -file. For example: - -bash$ strings showboat.pfb | more -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin-- - - -Using this information, a possible name might be: - --type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - - - -The components of our name are: - - -Foundry - -Lets just name all the new fonts type1. - - - -Family - -The name of the font. - - - -Weight - -Normal, bold, medium, semibold, etc. From the -strings1 output -above, it appears that this font has a weight of -medium. - - - -Slant - -roman, italic, oblique, -etc. Since the ItalicAngle is zero, -roman will be used. - - - -Width - -Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be normal. - - - -Additional style - -Usually omitted, but this will indicate that -the font contains decorative capital letters. - - - -Spacing - -proportional or monospaced. Proportional -is used since isFixedPitch is false. - - - - - - -All of these names are arbitrary, but one should strive to be -compatible with the existing conventions. A font is referenced by -name with possible wild cards by an X11 program, so the name chosen -should make some sense. One might begin by simply using - -…-normal-r-normal-…-p-… - -as the name, and then use -xfontsel1 to examine it -and adjust the name based on the appearance of the font. - -So, to complete our example: - -Make the font accessible to X11 -bash$ cd /usr/X11R6/lib/X11/fonts/Type1 -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line. -bash$ ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq - -fonts.scale seems to be identical to fonts.dir… -bash$ cp fonts.dir fonts.scale - -Tell X11 that things have changed -bash$ xset fp rehash - -Examine the new font -bash$ xfontsel -pattern -type1-* - - - -References: -xfontsel1, -xset1, -The X Windows System in a Nutshell, O'Reilly & Associates. - - - - -Using type 1 fonts with Ghostscript - -Ghostscript references a font via its Fontmap -file. This must be modified in a similar way to the X11 -fonts.dir file. Ghostscript can use either the -.pfa or the .pfb format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: - -Put the font in Ghostscript's font directory -bash$ cd /usr/local/share/ghostscript/fonts -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit Fontmap so Ghostscript knows about the font -bash$ cd /usr/local/share/ghostscript/4.01 -bash$ ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq - -Use Ghostscript to examine the font -bash$ gs prfont.ps -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS>Showboat DoFont -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS>quit - - - -References: fonts.txt in the Ghostscript -4.01 distribution - - - - -Using type 1 fonts with Groff - -Now that the new font can be used by both X11 and Ghostscript, -how can one use the new font with groff? First of all, since we are -dealing with type 1 postscript fonts, the groff device that is -applicable is the ps device. A font file must be -created for each font that groff can use. A groff font name is just -a file in /usr/share/groff_font/devps. With our -example, the font file could be -/usr/share/groff_font/devps/SHOWBOAT. The file -must be created using tools provided by groff. - -The first tool is afmtodit. This is not normally -installed, so it must be retrieved from the source distribution. I -found I had to change the first line of the file, so I did: - -bash$ cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp -bash$ ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq - - - -This tool will create the groff font file from the metrics file -(.afm suffix.) Continuing with our -example: - -Many .afm files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines -bash$ cd /tmp -bash$ cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm - -Now create the groff font file -bash$ cd /usr/share/groff_font/devps -bash$ /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT - - - -The font can now be referenced with the name SHOWBOAT. - -If ghostscript is used to drive the printers on the system, -then nothing more needs to be done. However, if true postscript -printers are used, then the font must be down loaded to the printer -in order for the font to be used (unless the printer happens to have -the showboat font built in or on an accessible font disk.) The final -step is to create a down loadable font. The pfbtops tool -is used to create the .pfa format of the font, -and the download file is modified to reference the new -font. The download file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: - -Create the .pfa font file -bash$ pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa - -Of course, if the .pfa file is already -available, just use a symbolic link to reference it. - -Get the internal font name -bash$ fgrep internalname SHOWBOAT -internalname Showboat - -Tell groff that the font must be down loaded -bash$ ex download -:$a -Showboat showboat.pfa -. -:wq - - - -To test the font: - -bash$ cd /tmp -bash$ cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF -bash$ groff -Tps example.t >example.ps - -To use ghostscript/ghostview -bash$ ghostview example.ps - -To print it -bash$ lpr -Ppostscript example.ps - - - -References: -/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, -groff_font5, -groff_char5, -pfbtops1. - - - - -Can TrueType fonts be used? - -The TrueType font format is used by Windows, Windows 95, -Mac's,&hellip It is quite popular and there are a great number of -fonts available in this format. Unfortunately, there are only two -applications that I am aware of that can use this format: Ghostscript -and povray. Ghostscript's support, according to the documentation, -is rudimentary and the results are likely to be inferior to type 1 -fonts. - -However, groff would need a font description file, and I know -of no tools to construct the metrics from a TrueType font. In -addition, the font would have to be down loaded to postscript -printers in the appropriate format, and again, groff cannot handle -TrueType fonts in this fashion. - -X11 has no support for TrueType fonts that I am aware -of. - -The only program that I know of that has the ability to use -TrueType fonts is povray version 3, but I rather doubt many people -will be creating documents as a series of raytraced pages! -:-) - - - - -Where can additional fonts be obtained? - -Many fonts are available on the Internet. They are either -entirely free, or are share-ware. In addition, there are many -inexpensive CDROMs available that contain many fonts. Some Internet -locations (as of August 1996) are: - - -ftp://ftp.winsite.com (Formerly -CICA) - -http://www.simtel.net/simcgi-bin/dosfind.cgi - -ftp://ftp.coast.net/ - -http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html - -http://www.esselte.com/letraset/index.html - -http://www.inil.com/users/elfring/esf.htm - - - - - - -Additional questions - - - - - -What use are the .pfm files? - - - -Can one generate the .afm file from a .pfa or .pfb? - - - -How to generate the groff character mapping files for postscript fonts -with non-standard character names? - - - -Can xditview and devX?? devices be setup to access all the new fonts? - - - -It would be good to have examples of using TrueType fonts with povray and -ghostscript. - - - - - - - diff --git a/en_US.ISO8859-1/articles/formatting-media/Makefile b/en_US.ISO8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 158bc4d801..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $ - -DOCS= diskformat.docb -INDEXLINK= diskformat.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index 96f12cc1a4..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,418 +0,0 @@ - - - - - - -Formatting Media For Use With FreeBSD 2.2-RELEASE -A Tutorial - - - -Doug -White - -
dwhite@resnet.uoregon.edu
- - - - -March 1997 -This document describes how to slice, partition, and -format hard disk drives and similar media for use with FreeBSD. The -examples given have been tested under FreeBSD 2.2-GAMMA and may work -for other releases. - - - - - -Introduction & Definitions - - -Overview -Successfully adding disks to an existing system is the mark of an -experienced system administrator. Slicing, partitioning, and adding -disks requires a careful dance of proper command and name syntax. One -slipped finger and an entire disk could disappear in seconds. This -document is written in an attempt to simplify this process and avoid -accidents. Thankfully, enhancements to existing tools (notably -sysinstall) have greatly improved this process in recent releases of -FreeBSD. - -There are two possible modes of disk formatting: - - -compatibility mode: Arranging a -disk so that it has a slice table for use with other operating -systems. - -dangerously dedicated mode: -Formatting a disk with no slice table. This makes the process of -adding disks easier, however non-FreeBSD operating systems may not -accept the disk. - - - -For most cases, dedicated mode is the easiest to set up and use -in existing systems, as a new disk is usually dedicated entirely to -FreeBSD. However, compatibility mode insures optimum interoperability -with future installations at a cost of increased complexity. - -In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -/stand/sysinstall. 2.1.7-RELEASE and later -versions of sysinstall contain code to ease setup -of disks during normal system operation, mainly allowing access to the -Label and Partition editors and a Write feature which will update just -the selected disk and slice without affecting other disks. The other -method is running the tools manually from a root command line. For -dangerously dedicated mode, only three or four commands are involved -while sysinstall requires some manipulation. - - -Definitions - -UNIX disk management over the centuries has invented many new -definitions for old words. The following glossary covers the -definitions used in this document and (hopefully) for FreeBSD in -general. - - - - -compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode. - -dangerously dedicated mode: Formatting a disk with no slice -table. This makes the process of adding disks easier, however -non-FreeBSD operating systems may not accept the disk. Oppose -compatibility mode. - -disk: A circular disc, covered with magnetic or similarly -manipulable material, spun by a motor under a head. Data is stored on -the disk by changing the pattern of magnetism on the disc, which can -be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz -removables are examples of disks. - -slice: A division of a disk. Up to four slices are permitted on one -disk in the PC standard. Slices are composed of contiguous sectors. -Slices are recorded in a slice table used by the system BIOS to -locate bootable partitions. The slice table is usually called the -Partition Table in DOS parlance. Maintained by the fdisk utility. - -partition: A division of a slice. Usually used in reference -to divisions of the FreeBSD slice of a disk. Each filesystem and swap -area on a disk resides in a partition. Maintained using the disklabel -utility. - -sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data. - - - - - -Warnings & Pitfalls - -Building disks is not something to take lightly. It is quite possible -to destroy the contents of other disks in your system if the proper -precautions are not taken. - -Check your work carefully. It is very simple to destroy -the incorrect disk when working with these commands. When -in doubt consult the kernel boot output for the proper device. - -Needless to say, we are not responsible for any damage to any data -or hardware that you may experience. You work at your own risk! - - - - -Zip, Jaz, and Other Removables - -Removable disks can be formatted in the same way as normal hard -disks. It is essential to have the disk drive connected to the system -and a disk placed in the drive during startup, so the kernel can -determine the drive's geometry. Check the dmesg -output and make sure your device and the disk's size is listed. If -the kernel reports - - -Can't get the size - - -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. - - - - - -Formatting Disks in Dedicated Mode - - -Introduction - -This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture. - - - -Making Dedicated Mode Disks using Sysinstall - -/stand/sysinstall, the system installation -utility, has been expanded in recent versions to make the process of -dividing disks properly a less tiring affair. The fdisk and disklabel -editors built into sysinstall are GUI tools that remove much of the -confusion from slicing disks. For FreeBSD versions 2.1.7 and later, -this is perhaps the simplest way to slice disks. - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - -answer No. -When asked if you still want to do this, answer -Yes. -Select Write. -When warned about Writing on installed systems, answer -Yes. -Quitthe FDISK Editor and -ESCAPE back to the Index menu. -Select Label from the Index -menu. -Label as desired. For a single partition, enter -C to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used). -Enter W when done and confirm to -continue. The filesystem will be newfs'd for you, unless you select -otherwise (for news partitions you'll want to do this!). You'll get -the error: - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - - - -Making Dedicated Mode Disks Using the Command Line - - -Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin - # We only want one partition, so using slice 'c' should be fine: - newfs /dev/rwd2c - - - - - If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: - - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/r$d > /tmp/label - # Edit disklabel to add partitions: - vi /tmp/label - disklabel -B -R -r wd2 /tmp/label - # newfs partitions appropriately - - - - -Your disk is now ready for use. - - - - - -Making Compatibility Mode Disks - - -Introduction -The command line is the easiest way to make dedicated disks, and -the worst way to make compatibility disks. The command-line fdisk -utility requires higher math skills and an in-depth understanding of -the slice table, which is more than most people want to deal with. -Use sysinstall for compatibility disks, as described below. - - - - -Making Compatibility Mode Disks Using Sysinstall - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. - -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - - answer yes. -Select Write. -When asked to install the boot manager, select None with -SPACE then hit ENTER for OK. -Quit the FDISK Editor. -You'll be asked about the boot manager, select -None -again. -Select Label from the Index -menu. -Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used). -The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error: - - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - -Your new disk is now ready for use. - - - - - -Other Disk Operations - -Adding Swap Space - -As a system grows, it's need for swap space can also grow. -Although adding swap space to existing disks is very difficult, a new -disk can be partitioned with additional swap space. - -To add swap space when adding a disk to a system: - -When partitioning the disk, edit the disklabel and -allocate the amount of swap space to add in partition `b' and the -remainder in another partition, such as `a' or `e'. The size is given -in 512 byte blocks. -When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies. -Add an entry to /etc/fstab as follows: - - -/dev/wd0b none swap sw 0 0 - - -Change /dev/wd0b to the device of the newly added -space. -To make the new space immediately available, use the -swapon command. - - - -$ swapon /dev/sd0b - -swapon: added /dev/sd0b as swap space - - - - - - - - -Copying the Contents of Disks - -Submitted By: Renaud Waldura (renaud@softway.com) - -To move file from your original base disk to the fresh new one, -do: - - - -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home - - - - - - - - -Credits - - - -The author would like to thank the following individuals for -their contributions to this project: - -Darryl Okahata -(darrylo@hpnmhjw.sr.hp.com) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions. -Jordan Hubbard -(jkh@freebsd.org) for making -sysinstall useful for this type of task. -John Fieber -(jfieber@indiana.edu) for making -information and examples of the DocBook DTD on which this document is -based. -Greg Lehey (grog@freebsd.org) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. - - - - - - - - - diff --git a/en_US.ISO8859-1/articles/mh/Makefile b/en_US.ISO8859-1/articles/mh/Makefile deleted file mode 100644 index 14a686e6af..0000000000 --- a/en_US.ISO8859-1/articles/mh/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= mh.docb -INDEXLINK= mh.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml deleted file mode 100644 index 3c33cf92ea..0000000000 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,704 +0,0 @@ - - - - - - - - -An MH Primer - - - -Matt -Midboe - -
-matt@garply.com -
- - - -v1.0, 16 January 1996 - -This document contains an introduction to using MH on -FreeBSD - - - - - -Introduction - -MH started back in 1977 at the RAND Corporation, where the -initial philosophies behind MH were developed. MH isn't so much a -monolithic email program but a philosophy about how best to develop -tools for reading email. The MH developers have done a great job -adhering to the KISS principle: Keep It Simple Stupid. -Rather than have one large program for reading, sending and handling -email they have written specialized programs for each part of your -email life. One might liken MH to the specialization that one finds -in insects and nature. Each tool in MH does one thing, and does it -very well. - -Beyond just the various tools that one uses to handle their -email MH has done an excellent job keeping the configuration of each -of these tools consistent and uniform. In fact, if you are not quite -sure how something is supposed to work or what the arguments for some -command are supposed to be then you can generally guess and be right. -Each MH command is consistent about how it handles reading the -configuration files and how it takes arguments on the command line. -One useful thing to remember is that you can always add a - to the command to have it display the options -for that command. - -The first thing that you need to do is to make sure that you have -installed the MH package on your FreeBSD machine. If you installed -from CDROM you should be able to execute the following to load mh: - -# pkg_add /cdrom/packages/mh-6.8.3.tgz - -You will notice that it created a /usr/local/lib/mh -directory for you as well as adding several binaries to the -/usr/local/bin directory. If you would prefer to compile -it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. - -This primer is not a full comprehensive explanation of how MH -works. This is just intended to get you started on the road to -happier, faster mail reading. You should read the man pages for the -various commands. Also you might want to read the comp.mail.mh newsgroup. Also you can -read the FAQ -for MH. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek. - - - - -Reading Mail - -This section covers how to use inc, -show, scan, next, -prev, rmm, rmf, and -msgchk. One of the best things about MH is the -consistent interface between programs. A few things to keep in mind -when using these commands is how to specify message lists. In the -case of inc this doesn't really make any sense but with -commands like show it is useful to know. - -A message list can consist of something like 23 20 -16 which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like 23-30 which will -act on all the messages between 23 and 30. You can also specify -something like cur:10 which will act on the current -message and the next 9 messages. The cur, -last, and first messages are special -messages that refer to the current, last or first message in the -folder. - - - -<command>inc</>, <command>msgchk</>—read in your new email or check it - -If you just type in inc and hit return -you will be well on your way to getting started with MH. The first -time you run inc it will setup your account to use all -the MH defaults and ask you about creating a Mail directory. If you -have mail waiting to be downloaded you will see something that looks -like: - - 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -This is the same thing you will see from a scan (see -). If you just run inc with no -arguments it will look on your computer for email that is supposed to -be coming to you. - -A lot of people like to use POP for grabbing their email. MH can do -POP to grab your email. You will need to give inc a few command -line arguments. - -tempest% inc -host mail.pop.org -user username -norpop - -That tells inc to go to mail.pop.org to -download your email, and that your username on their system is -username. The option tells -inc to use plain POP3 for downloading your email. MH has -support for a few different dialects of POP. More than likely you -will never ever need to use them though. While you can do more -complex things with inc such as audit files and scan format files -this will get you going. - -The msgchk command is used to get information on -whether or not you have new email. msgchk takes the same - and options that -inc takes. - - - - -<command>show</>, <command>next</> and <command>prev</>—displaying and moving through email - -show is to show a letter in your current folder. -Like inc, show is a fairly straightforward -command. If you just type show and hit return -then it displays the current message. You can also give specific -message numbers to show: - -tempest% show 32 45 56 - -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior show -basically just does a more on the email message. - -next is used to move onto the next message and -prev will go to the previous message. Both commands have -an implied show command so that when you go to the next -message it automatically displays it. - - - - -<command>scan</>—shows you a scan of your messages - -scan will display a brief listing of the messages -in your current folder. This is an example of what the -scan command will give you. - - 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -Like just about everything in MH this display is very configurable. -This is the typical default display. It gives you the message number, -the date on the email, the sender, the subject line, and a sentence -fragment from the very beginning of the email if it can fit it. The -+ means that message is the current message, so if you do -a show it will display that message. - -One useful option for scan is the -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -scan is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to inc it -you can do scan -file -/var/mail/username. This can be used with -any file that is in the mbox format. - - - - -<command>rmm</> and <command>rmf</>—remove the current message or folder - -rmm is used to remove a mail message. The default -is typically to not actually remove the message but to rename the -file to one that is ignored by the MH commands. You will need to -through periodically and physically delete the removed -messages. - -The rmf command is used to remove folders. This -doesn't just rename the files but actually removes the from the hard -drive so you should be careful when you use this command. - - - - -A typical session of reading with MH - -The first thing that you will want to do is inc -your new mail. So at a shell prompt just type in inc and -hit return. - -tempest% inc -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -This shows you the new email that has been added to your mailbox. So -the next thing to do is show the email and move around. - -tempest% show -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -tempest% rmm -tempest% next -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party). - - -The rmm removed the current message and the -next command moved me on to the next message. -Now if I wanted to look at ten most recent messages so I could read -one of them here is what I would do: - -tempest% scan last:10 - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -Then if I wanted to read message number 27 I would do a -show 27 and it would be displayed. As you can probably -tell from this sample session MH is pretty easy to use and looking -through emails and displaying them is fairly intuitive and easy. - - - - - - -Folders and Mail Searching - -Anybody who gets lots of email definitely wants to be able to -prioritize, stamp, brief, de-brief, and number their emails in a -variety of different ways. MH can do this better than just about -anything. One thing that we haven't really talked about is the -concept of folders. You have undoubtedly come across the folders -concept using other email programs. MH has folders too. MH can even -do sub-folders of a folder. One thing you should keep in mind with MH -is that when you ran inc for the first time and it asked -you if it could create a Mail directory it began storing -everything in that directory. If you look at that directory you will -find a directory named inbox. The inbox -directory houses all of your incoming mail that hasn't been thrown -anywhere else. - -Whenever you create a new folder a new directory is going to be -created underneath your MH Mail directory, and messages -in that folder are going to be stored in that directory. When new -email comes in that new email is thrown into your inbox -directory with a file name that is equivalent to the message number. -So even if you didn't have any of the MH tools to read your email you -could still use standard UNIX commands to munge around in those -directories and just more your files. It's this simplicity that -really gives you a lot of power with what you can do with your -email. - -Just as you can use message lists like 23 16 42 -with most MH commands there is a folder option you can specify with -just about every MH command. If you do a scan +freebsd it -will scan your freebsd folder, and your current folder -will be changed to freebsd. If you do a show -+freebsd 23 16 42, show is going to switch to your -freebsd folder and display messages 23, 16 and 42. So -remember that - - - -<command>pick</>—search email that matches certain criteria - -pick is one of the more complex commands in the MH -system. So you might want to read the -pick1 man page for a -more thorough understanding. At its simplest level you can do -something like - -tempest% pick -search pci -15 -42 -55 -56 -57 - - -This will tell pick to look through every single line in -every message in your current folder and tell you which message -numbers it found the word pci in. You can then -show those messages and read them if you wish or -rmm them. You would have to specify something like -show 15 42 55-57 to display them though. A slightly more -useful thing to do is this: - -tempest% pick -search pci -seq pick -5 hits -tempest% show pick - -This will show you the same messages you just didn't have to work as -hard to do it. The option is really an -abbreviation of and pick is -just a sequence which contains the message numbers that matched. You -can use sequences with just about any MH command. So you could have -done an rmm pick and all those messages would be removed -instead. You sequence can be named anything. If you run pick again it -will overwrite the old sequence if you use the same name. - -Doing a pick -search can be a bit more time -consuming than just searching for message from someone, or to -someone. So pick allows you to use the following -predefined search criteria: - - - - - - -search based upon who the message is to - - - - - - -search based on who is in the cc list - - - - - - -search for who sent the message - - - - - - -search for emails with this subject - - - - - - -find emails with a matching dat - - - - - - -search for any other component in the header. (i.e. - - - - - - -This allows you to do things like - -tempest% pick -to freebsd-hackers@freebsd.org -seq hackers - -to get a list of all the email send to the FreeBSD hackers mailing -list. pick also allows you to group these criteria in -different ways using the following options: - - - -… … - - - -… &hellip - - - - … - - - - … - - - -These commands allow you to do things like - -tempest% pick -to freebsd-hackers -and -cc freebsd-hackers - -That will grab all the email in your inbox that was sent to -freebsd-hackers or cc'd to that list. The brace options allow you to -group search criteria together. This is sometimes very necessary as -in the following example - -tempest% pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci - - -Basically this says pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci. It should look through your -folder and find all messages sent to the freebsd-hackers list that -aren't cc'd to the freebsd-questions list that contain something on -pci in the subject line. Ordinarily you might have to worry about -something called operator precedence. Remember in math how you -evaluate from left to right and you do multiplication and division -first and addition and subtraction second? MH has the same type of -rules for pick. It's fairly complex so you might want to study -the man page. This document is just to help you get acquainted with -MH. - - - - -<command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance - -There are three programs which are primarily just for -manipulating your folders. The folder program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a folder +newfolder and -you will be switched into newfolder. From there on -out all your MH commands like comp, repl, -scan, and show will act on that -newfolder folder. - -Sometimes when you are reading and deleting messages you will -develop holes in your folders. If you do a scan -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a folder -pack this will renumber all your -messages so that there are no holes. It doesn't actually delete any -messages though. So you may need to periodically go through and -physically delete rmm'd messages. - -If you need statistics on your folders you can do a -folders or folder -all to list all -your folders, how many messages they have, what the current message -is in each one and so on. This line of stats it displays for all your -folders is the same one you get when you change to a folder with -folder +foldername. A folders command looks -like this: - - Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. - - - -The refile command is what you use to move messages -between folders. When you do something like refile 23 -+netfuture message number 23 is moved into the -netfuture folder. You could also do something like -refile 23 +netfuture/latest which would put message -number 23 in a subfolder called latest under the -netfuture folder. If you want to keep a message in the -current folder and link it you can do a refile -link 23 -+netfuture which would keep 23 in your current -inbox but also list in your netfuture -folder. You are probably beginning to realize some of the really -powerful things you can do with MH. - - - - - -Sending Mail - -Email is a two way street for most people so you want to be -able to send something back. The way MH handles sending mail can be a -bit difficult to follow at first, but it allows for incredible -flexibility. The first thing MH does is to copy a components file -into your outgoing email. A components file is basically a skeleton -email letter with stuff like the To: and Subject: headers already in -it. You are then sent into your editor where you fill in the header -information and then type the body of your message below the dashed -lines in the message. Then to the whatnow program. When -you are at the What now? prompt you can tell it to -send, list, edit, -edit, push, and quit. Most of -these commands are self-explanatory. So the message sending process -involves copying a component file, editing your email, and then -telling the whatnow program what to do with your -email. - - - -<command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone - -The comp program has a few useful command line -options. The most important one to know right now is the - option. When MH is installed the default -editor is usually a program called prompter which comes -with MH. It's not a very exciting editor and basically just gets the -job done. So when you go to compose a message to someone you might -want to use comp -editor /usr/bin/vi/ or comp --editor /usr/local/bin/pico/ instead. Once you have run -comp you are in your editor and you see -something that looks like this: - -To: -cc: -Subject: --------- - - - -You need to put the person you are sending the mail to after the -To: line. It works the same way for the other headers -also, so you would need to put your subject after the -Subject: line. Then you would just put the body of your -message after the dashed lines. It may seem a bit simplistic since a -lot of email programs have special requesters that ask you for this -information but there really isn't any point to that. Plus this -really gives you excellent flexibility. - -To:freebsd-rave@freebsd.org -cc: -Subject:And on the 8th day God created the FreeBSD core team --------- -Wow this is an amazing operating system. Thanks! - -You can now save this message and exit your editor. You will see the -What now? prompt and you can type in -send or s and hit -return. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example quit if you don't want to send the -message. - -The forw command is stunningly similar. The big -difference being that the message you are forwarding is automatically -included in the outgoing message. When you run forw it -will forward your current message. You can always tell it to forward -something else by doing something like forw 23 and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences forw -functions exactly the same as comp. You go through the -exact same message sending process. - -The repl command will reply to whatever your -current message is, unless you give it a different message to reply -to. repl will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -To: header already has the address of the recipient in -there. Also the Subject: line will already be filled in. -You then go about the normal message composition process and you are -done. One useful command line option to know here is the - option. You can use all, -to, cc, me after the - option to have repl automatically -add the various addresses to the cc list in the message. You have -probably noticed that the original message isn't included. This is -because most MH setups are configured to do this from the -start. - - - - -<filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</> - -The components file is usually in -/usr/local/lib/mh. You can copy that file into -your MH Mail directory and edit to contain what you want it to -contain. It is a fairly basic file. You have various email headers at -the top, a dashed line and then nothing. The -comp command just copies this -components file and then edits it. You can add any -kind of valid RFC822 header you want. For instance you could have -something like this in your components file: - -To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ -------- - - -MH would then copy this components file and throw you into your -editor. The components file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that components file. - -The replcomps file is a bit more complex. The default -replcomps looks like this: - -%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- - - - -It's in the same basic format as the components file but -it contains quite a few extra formatting codes. The -%(lit) command makes room for the address. The -%(formataddr is a function that returns a proper email -address. The next part is %< which means if and -the {reply-to} means the reply-to field in the original -message. So that might be translated this way: - -%<if {reply-to} the original message has a reply-to -then give that to formataddr, %? else {from} take the -from address, %? else {sender} take the sender address, %? -else {return-path} take the return-path from the original -message, %> endif. - - -As you can tell MH formatting can get rather involved. You can -probably decipher what most of the other functions and variables -mean. All of the information on writing these format strings is in the -MH-Format man page. The really nice thing is that once you have built -your customized replcomps file you won't need to touch it -again. No other email program really gives you the power and -flexibility that MH gives you. - - - - diff --git a/en_US.ISO8859-1/articles/multi-os/Makefile b/en_US.ISO8859-1/articles/multi-os/Makefile deleted file mode 100644 index 8a591510bb..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $ - -DOCS= multios.docb -INDEXLINK= multios.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml deleted file mode 100644 index e7b1d68d68..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,680 +0,0 @@ - - - - - - -Installing and Using FreeBSD With Other Operating Systems - - - -Jay -Richmond - -
-jayrich@in.net -
- - - - -6 August 1996 - -This document discusses how to make FreeBSD coexist -nicely with other popular operating systems such as Linux, MS-DOS, -OS/2, and Windows 95. Special thanks to: Annelise Anderson -andrsn@stanford.edu, Randall Hopper -rhh@ct.picker.com, and Jordan K. Hubbard -jkh@time.cdrom.com - - - - - -Overview - -Most people can't fit these operating systems together -comfortably without having a larger hard disk, so special -information on large EIDE drives is included. Because there are so -many combinations of possible operating systems and hard disk -configurations, the section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems. - -This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the \TOOLS directory or via -ftp) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence. - - - - -Overview of Boot Managers - -These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system. - - - - -Boot Easy - - -This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys. - - - - -OS/2 Boot Manager - - -This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 -(Linux). It will also boot FAT32 partitions. Partitions are -selected using arrow keys. The OS/2 Boot Manager is the only one to -use its own separate partition, unlike the others which use the -master boot record (MBR). Therefore, it must be installed below the -1024th cylinder to avoid booting problems. It can boot Linux using -LILO when it is part of the boot sector, not the MBR. Go to Linux HOWTOs -on the World Wide Web for more information on booting Linux with -OS/2's boot manager. - - - - -OS-BS - - This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -\TOOLS directory, and via ftp. - - - -LILO, or LInux LOader - - -This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file. - - - - - -About FAT32FAT32 is the replacement to -the FAT filesystem included in Microsoft's OEM SR2 Beta release, -which is expected to utilitized on computers pre-loaded with Windows -95 towards the end of 1996. It converts the normal FAT file system -and allows you to use smaller cluster sizes for larger hard drives. -FAT32 also modifies the traditional FAT boot sector and allocation -table, making it incompatible with some boot managers. - - - - -A Typical Installation - -Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them. - -Here's how I might do it using these hard disks: - - - -/dev/wd0 (first physical hard disk) - - - -/dev/wd1 (second hard disk) - - - - - -Both disks have 1416 cylinders. - - - -I boot from a MS-DOS or Windows 95 boot disk that -contains the FDISK.EXE utility and make a small 50 meg -primary partition (35-40 for Windows 95, plus a little breathing -room) on the first disk. Also create a larger partition on the -second hard disk for my Windows applications and data. - -I reboot and install Windows 95 (easier said than done) -on the C: partition. - -The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -). When I am partitioning out my hard disk with -Linux fdisk, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space). - -After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record). - -The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the /usr and / slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the /usr/src slice and swap -space. - -When viewed with the Windows 95 fdisk utility, my hard drives -should now look something like this: - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See ). - -Install FreeBSD. I make sure to boot with my first hard -disk set at NORMAL in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (MSD.EXE), -or check your BIOS) with the parameter hd0=1416,16,63 -where 1416 is the number of cylinders on my hard -disk, 16 is the number of heads per track, and -63 is the number of sectors per track on the -drive. - -When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it. - -When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD). - - - - - - -Special Considerations - -Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary partitiin on the first hard disk. OS/2 is the exception. It -can be installed on the first or second disk in a primary or extended -partition. If you are not sure, keep the beginning of the bootable -partitions below the 1024th cylinder. - -If you install Windows 95 on an existing BSD system, it will -destroy the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via ftp. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS. - -Please keep in mind that OS/2 can read FAT and HPFS partitions, -but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows -95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most file systems, but -currently cannot read HPFS partitions. Linux can read HPFS -partitions, but can't write to them. Recent versions of the Linux -kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT -is what gives Windows 95 long file names - it's pretty much the same -as FAT). Linux can read and write to most file systems. Got that? -I hope so. - - - - -Examples - -(section needs work, please send your example to -jayrich@in.net). - -FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see DOS on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like invalid system disk under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called > 1024 cylinder support or NORMAL/LBA -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the FBSDBOOT.EXE utility on the CD (It should find your -FreeBSD partition and boot it.) - -FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem. - -FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems. - -FreeBSD+Linux+Win95: (see ) - - - - -Other Sources of Help - -There are many Linux HOW-TOs that -deal with multiple operating systems on the same hard disk. - -The Linux+OS/2+DOS -Mini-HOWTO offers help on configuring the OS/2 boot -manager. The Linux-HOWTO -is also helpful. - -The NT Loader -Hacking Guide provides good information on multibooting -Windows NT, '95, and DOS with other operating systems. - -And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip, -http://www.cs.yorku.ca/People/frank/docs/. - -Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -file:/usr/src/sys/i386/boot/biosboot/README.386BSD. - - - - -Technical Details - -(Contributed by Randall Hopper, -rhh@ct.picker.com) - -This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading. - - - -Disk Primer - -Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It's not -particularly important to know what these terms relate to except to -know that, together, they identify where data is physically on your -disk. - -Your disk has a particular number of cylinders, number of -heads, and number of sectors per cylinder-head (a cylinder-head also -known nown as a track). Collectively this information defines the -"physical disk geometry" for your hard disk. There are typically 512 -bytes per sector, and 63 sectors per track, with the number of -cylinders and heads varying widely from disk to disk. Thus you can -figure the number of bytes of data that'll fit on your own disk by -calculating: (# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect) For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: (3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect) - -which is 1,624,670,208 bytes, or around 1.6 Gig. - -You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see ), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. MSD.EXE or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -translated geometry (virtual numbers from using LBA). -Stay tuned for what that means. - -One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1. - -For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for boot -sector or master boot record. Among the useful info -you'll find are Hale Landis's How It Works document -pack. See the section for a few pointers to -this pack. - -Ok, enough terminology. We're talking about booting -here. - - - - -The Booting Process - -On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 partitions, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -slices to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system. - -Each partition entry in the MBR has a Partition -ID, a Start Cylinder/Head/Sector, and an -End Cylinder/Head/Sector. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. lists a smattering of some common -Partition IDs. - -
-Partition IDs</> -<tgroup cols="2"> -<thead> -<row> -<entry>ID (hex)</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> -<row> -<entry>01</entry> -<entry>Primary DOS12 (12-bit FAT)</entry> -</row> - -<row> -<entry>04</entry> -<entry>Primary DOS16 (16-bit FAT)</entry> -</row> - -<row> -<entry>05</entry> -<entry>Extended DOS</entry> -</row> - -<row> -<entry>06</entry> -<entry>Primary big DOS (> 32MB)</entry> -</row> - -<row> -<entry>0A</entry> -<entry>OS/2</entry> -</row> - -<row> -<entry>83</entry> -<entry>Linux (EXT2FS)</entry> -</row> - -<row> -<entry>A5</entry> -<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Note that not all partitions are bootable (e.g. Extended DOS). -Some are—some aren't. What makes a partition bootable is the -configuration of the <firstterm>Partition Boot Sector</> that exists -at the beginning of each partition.</para> - -<para>When you configure your favorite boot manager, it looks up the entries -in the MBR partition tables of all your hard disks and lets you name the -entries in that list. Then when you boot, the boot manager is invoked by -special code in the Master Boot Sector of the first probed hard disk on -your system. It looks at the MBR partition table entry corresponding to -the partition choice you made, uses the Start Cylinder/Head/Sector -information for that partition, loads up the Partition Boot Sector for that -partition, and gives it control. That Boot Sector for the partition itself -contains enough information to start loading the operating system on that -partition.</para> - -<para>One thing we just brushed past that's important to know. All of your -hard disks have MBRs. However, the one that's important is the one on the -disk that's first probed by the BIOS. If you have only IDE hard disks, its -the first IDE disk (e.g. primary disk on first controller). Similarly for -SCSI only systems. If you have both IDE and SCSI hard disks though, the -IDE disk is typically probed first by the BIOS, so the first IDE disk is -the first probed disk. The boot manager you will install will be hooked into -the MBR on this first probed hard disk that we've just described.</para> - -</sect1> - -<sect1 id="limits"> -<title>Booting Limitations and Warnings - -Now the interesting stuff that you need to watch out for. - - -The dreaded 1024 cylinder limit and how BIOS LBA helps - -The first part of the booting process is all done through the -BIOS, (if that's a new term to you, the BIOS is a software chip on -your system motherboard which provides startup code for your -computer). As such, this first part of the process is subject to the -limitations of the BIOS interface. - -The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: - -1024 cylinders, max -256 heads , max -64 cylinders, max (actually 63, 0 isn't -available) - - - -Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can't boot off just anywhere on your hard disk. The boot code (the -boot manager and the OS loader hooked into all bootable partitions' -Boot Sectors) has to reside below cylinder 1024. In fact, if your -hard disk is typical and has 16 heads, this equates to: - -1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector - - - -which is around the often-mentioned 528MB limit. - -This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads). - -With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit. - -To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: - -(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) - - - -However, my BIOS LBA remaps this to: - -( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) - - - -giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA). - - - - -Boot Managers and Disk Allocation - -Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs. - -If you followed the discussion in -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically. - -That's the catch. Some operating systems (FreeBSD included) let -you start their partitions right after the Master Boot Sector at -Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give -FreeBSD's sysinstall a disk with an empty chunk up front or the whole -disk empty, that's where it'll start the FreeBSD partition by default -(at least it did when I fell into this trap). Then when you go to -install your boot manager, if it's one that occupies a few extra -sectors after the MBR, it'll overwrite the front of the first -partition's data. In the case of FreeBSD, this overwrites the -disk label, and renders your FreeBSD partition unbootable. - -The easy way to avoid this problem (and leave yourself the -flexibility to try different boot managers later) is just to always -leave the first full track on your disk unallocated when you -partition your disk. That is, leave the space from Cylinder 0, Head -0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and -start your first partition at Cylinder 0, Head 1, Sector 1. -For what it's worth, when you create a DOS partition at the -front of your disk, DOS leaves this space open by default (this is -why some boot managers assume it's free). So creating a DOS -partition up at the front of your disk avoids this problem -altogether. I like to do this myself, creating 1 Meg DOS partition -up front, because it also avoids my primary DOS drive letters -shifting later when I repartition. - -For reference, the following boot managers use the -Master Boot Sector to store their code and data: - - - -OS-BS 1.35 - - - -Boot Easy - - - -LILO - - - - - -These boot managers use a few additional sectors after the -Master Boot Sector: - - - -OS-BS 2.0 Beta 8 (sectors 2-5) - - - -OS/2's boot manager - - - - - - - - -What if your machine won't boot? - -At some point when installing boot managers, you might leave the -MBR in a state such that your machine won't boot. This is unlikely, -but possible when re-FDISKing underneath an already-installed boot -manager. - -If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: - -A:\> FDISK /MBR - - - -to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy. - - - - - diff --git a/en_US.ISO8859-1/articles/new-users/Makefile b/en_US.ISO8859-1/articles/new-users/Makefile deleted file mode 100644 index d8131087f4..0000000000 --- a/en_US.ISO8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $ - -DOCS= newuser.docb -INDEXLINK= newuser.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml deleted file mode 100644 index 67568b5590..0000000000 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,943 +0,0 @@ - - - - - - - - -For People New to Both FreeBSD and Unix - - - -Annelise -Anderson - -
andrsn@andrsn.stanford.edu
- - - - -August 15, 1997 - -Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -and Un*x—so it starts with basics. It -assumes you're using version 2.0.5 or later of FreeBSD as distributed -by Walnut Creek or FreeBSD.ORG, your system (for now) has a single -user (you)—and you're probably pretty good with DOS/Windows or -OS/2. - - - - - -Logging in and Getting Out - -Log in (when you see login:) as a user you created during -installation or as root. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. - -To log out (and get a new login: prompt) type - -# exit - -as often as necessary. Yes, press enter after -commands, and remember that Unix is -case-sensitive—exit, not -EXIT. - -To shut down the machine type: - -# /sbin/shutdown -h now - -Or to reboot type - -# /sbin/shutdown -r now - -or - -# /sbin/reboot - - - -You can also reboot with -CtrlAltDelete. -Give it a little time to do its work. This is equivalent to -/sbin/reboot in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you? - - - - -Adding A User with Root Privileges - -If you didn't create any users when you installed the system and -are thus logged in as root, you should probably create a user now with - -# adduser - -The first time you use adduser, it might ask for some defaults to save. You -might want to make the default shell csh instead of sh, if it suggests -sh as the default. Otherwise just press enter to accept each default. -These defaults are saved in /etc/adduser.conf, -an editable file. - -Suppose you create a user jack with -full name Jack Benimble. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type wheel - -Login group is ``jack''. Invite jack into other groups: wheel - -This will make it possible to log in as jack and -use the su command to become root. Then you won't -get scolded any more for logging in as root. - -You can quit adduser any time by typing -CtrlC, and at -the end you'll have a chance to approve your new user or simply type -n for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong. - -Once you've done this, use exit -to get back to a login prompt and log in as -jack. In general, it's a good idea to do as -much work as possible as an ordinary user who doesn't have the -power—and risk—of root. - -If you already created a user and you want the user to be able -to su to root, you can log in as root -and edit the file /etc/group, adding jack to the -first line (the group wheel). But first you need to practice -vi, the text editor--or use the simpler text -editor, ee, installed on recent version of -FreeBSD. - -To delete a user, use the rmuser command. - - - - -Looking Around - -Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD. - -Here are some commands and what they do: - -id - -Tells you who you are! - - - - -pwd - - -Shows you where you are—the current -working directory. - - - - -ls - - -Lists the files in the current directory. - - - - -ls - - -Lists the files in the current directory with a -* after executables, a / after -directories, and an @ after symbolic links. - - - - -ls - - -Lists the files in long format—size, -date, permissions. - - - - -ls - - -Lists hidden dot -files with the others. If you're root, thedot files -show up without the switch. - - - - -cd - - -Changes directories. cd -.. backs up one level; note the -space after cd. cd -/usr/local goes there. cd -~ goes to the home directory of the -person logged in—e.g., /usr/home/jack. -Try cd /cdrom, and then -ls, to find out if your CDROM is mounted and -working. - - - - -view filename - - -Lets you look at a file (named -filename without changing it. Try -view /etc/fstab. -:q to quit. - - - - -cat filename - - - -Displays filename on screen. If -it's too long and you can see only the end of it, press -ScrollLock and use the up-arrow to -move backward; you can use ScrollLock with man pages -too. Press ScrollLock again to quit scrolling. You -might want to try cat on some of the dot files in -your home directory—cat -.cshrc, cat -.login, cat -.profile. - - - - - -You'll notice aliases in .cshrc for some of the -ls commands (they're very convenient). -You can create other aliases by editing .cshrc. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -/etc/csh.cshrc. - - - - -Getting Help and Information - -Here are some useful sources of help. -Text stands for something of your choice -that you type in—usually a command or filename. - - -apropos text - - -Everything containing string text -in the whatis database. - - - -man text - - -The man page for text. The major -source of documentation for Un*x systems. man -ls will tell you all the ways to use -the ls command. Press Enter to -move through text, -Ctrlb to go -back a page, Ctrlf to -go forward, q or -Ctrlc to -quit. - - - -which text - - -Tells you where in the user's path the command -text is found. - - - -locate text - - -All the paths where the string text -is found. - - - -whatis text - - -Tells you what the command text -does and its man page. Typing whatis * will tell -you about all the binaries in the current directory. - - - -whereis text - - -Finds the file text, giving its full -path. - - - - -You might want to try using whatis on some -common useful commands like cat, -more, grep, -mv, find, -tar, chmod, -chown, date, and -script. more lets you read a -page at a time as it does in DOS, e.g., ls -l | -more or more -filename. The -* works as a wildcard—e.g., ls -w* will show you files beginning with -w. - -Are some of these not working very well? Both -locate and whatis -depend on a database that's rebuilt weekly. If your machine isn't -going to be left on over the weekend (and running FreeBSD), you might -want to run the commands for daily, weekly, and monthly maintenance -now and then. Run them as root and give each one time to finish -before you start the next one, for now. - -# /etc/daily -output omitted -# /etc/weekly -output omitted -# /etc/monthly -output omitted - - -If you get tired waiting, press -AltF2 to get -another virtual console, and log in again. -After all, it's a multi-user, multi-tasking system. Nevertheless -these commands will probably flash messages on your screen while -they're running; you can type clear at the prompt -to clear the screen. Once they've run, you might want to look at -/var/mail/root and -/var/log/messages. - -Basically running such commands is part of system -administration—and as a single user of a Unix system, you're -your own system administrator. Virtually everything you need to be -root to do is system administration. Such responsibilities aren't -covered very well even in those big fat books on Unix, which seem to -devote a lot of space to pulling down menus in windows managers. You -might want to get one of the two leading books on systems -administration, either Evi Nemeth et.al.'s UNIX System -Administration Handbook (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's Essential System -Administration (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth. - - - - -Editing Text - -To configure your system, you need to edit text files. Most of -them will be in the /etc directory; and you'll -need to su to root to be able to change them. You -can use the easy ee, but in the long run the -text editor vi is worth learning. There's an -excellent tutorial on vi in -/usr/src/contrib/nvi/docs/tutorial if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. - -Before you edit a -file, you should probably back it up. Suppose you want to edit -/etc/rc.conf. You could just use cd -/etc to get to the /etc directory and -do: - -# cp rc.conf rc.conf.orig - - -This would copy rc.conf to -rc.conf.orig, and you could later copy -rc.conf.orig to rc.conf to recover the original. But even -better would be moving (renaming) and then copying back: - -# mv rc.conf rc.conf.orig -# cp rc.conf.orig rc.conf - - -because the mv command preserves the original date -and owner of the file. You can now edit -rc.conf. If you want the original back, you'd -then mv rc.conf rc.conf.myedit -(assuming you want to preserve your edited version) and then - -# mv rc.conf.orig rc.conf - -to put things back the way they were. - -To edit a file, type - -# vi filename - -Move through the text with the arrow keys. Esc (the -escape key) puts vi in command mode. Here are some -commands: - -x - -delete letter the cursor is on - - - - -dd - - -delete the entire line (even if it wraps on the screen) - - - - -i - - -insert text at the cursor - - - - -a - - -insert text after the cursor - - - - -Once you type i or a, you can enter text. -Esc puts you back in command mode where you can type - -:w - -to write your changes to disk and continue editing - - - - -:wq - - -to write and quit - - - - -:q! - - -to quit without saving changes - - - - -/text - - -to move the cursor to text; -/Enter (the enter key) to find -the next instance of text. - - - - -G - - -to go to the end of the file - - - - -nG - - -to go to line n in -the file, where n is a number - - - - -CtrlL - - -to redraw the screen - - - - -Ctrlb and Ctrlf - - -go back -and forward a screen, as they -do with more and view. - - - - - - -Practice with vi in your home directory by creating -a new file with vi filename and adding -and deleting text, saving the file, and calling it up again. -vi delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -vi—it's more powerful than DOS EDIT—find out -about the :r command.) Use Esc one or -more times to be sure you're in command mode and proceed from there -when it gives you trouble, save often with :w, and -use :q! to get out and start over (from -your last :w) when you need to. - -Now you can cd to /etc, -su to root, use vi to edit the file -/etc/group, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press Esc, and use -:wq to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?) - - - - -Printing Files from DOS - -At this point you probably don't have the printer working, so here's a -way to create a file from a man page, move it to a floppy, and then -print it from DOS. Suppose you want to read carefully about changing -permissions on files (pretty important). You can use the command -man chmod to read about it. The command - -# man chmod | col -b > chmod.txt - -will remove formatting codes and send the man page to -the chmod.txt file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, su to -root, and type - -# /sbin/mount -t msdos /dev/fd0 /mnt - -to mount the floppy drive on /mnt. - -Now (you no longer need to be root, and you can type -exit to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: - -% cp chmod.txt /mnt - -and use ls /mnt to get a directory listing of -/mnt, which should show the file -chmod.txt. - -You might especially want to make a file from -/sbin/dmesg by typing - -% /sbin/dmesg > dmesg.txt - -and copying dmesg.txt to the floppy. -/sbin/dmesg is the boot log record, and it's -useful to understand it because it shows what FreeBSD found when it -booted up. If you ask questions on -freebsd-questions@FreeBSD.ORG or on a USENET -group—like FreeBSD isn't finding my tape drive, what do -I do?—people will want to know what dmesg -has to say. - -You can now dismount the floppy drive (as root) to get the disk -out with - -# /sbin/umount /mnt - -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a -minor change so the file has to be saved, and print as you normally -would from DOS or Windows. Hope it works! man pages come out best if -printed with the dos print command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.) - -Getting the printer printing from FreeBSD involves creating an -appropriate entry in /etc/printcap and creating -a matching spool directory in -/var/spool/output. If your printer is on -lpt0 (what dos calls LPT1), you may only -need to go to /var/spool/output and (as root) -create the directory lpd by typing: - -mkdir lpd, if it doesn't already -exist. -Then the printer should respond if it's turned on when the system is -booted, and lp or lpr should send a file to the printer. Whether or -not the file actually prints depends on configuring it, which is -covered in the FreeBSD -handbook. - - - - -Other Useful Commands - - - -df - -shows file space and mounted systems. - - - - -ps aux - - -shows processes running. ps ax is a narrower form. - - - - -rm filename - - -remove filename. - - - - -rm -R dir - - -removes a directory dir and all -subdirectories—careful! - - - - -ls -R - - -lists files in the current -directory and all subdirectories; -I used a variant, ls -AFR > where.txt, -to get a list of all -the files in / and (separately) -/usr before I found better -ways to find files. - - - - -passwd - - -to change user's password (or root's password) - - - - -man hier - - -man page on the Unix file system - - - - - -Use find to locate filename in /usr -or any of its subdirectories with - -% find /usr -name "filename" - -You can use * as a wildcard in -"filename" (which should be in -quotes). If you tell find to search in / -instead of /usr it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition. - -An excellent book that explains Unix commands and utilities is -Abrahams & Larson, Unix for the Impatient -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the Unix Reference -Desk. - - - - -Next Steps - -You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and FreeBSD's -web site. A wide variety of packages and ports are on the -Walnut Creek CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with pkg_add -/cdrom/packages/All/packagename, -where packagename is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in cdrom/packages/index, -cdrom/packages/index.txt, and -cdrom/ports/index, with fuller descriptions in -/cdrom/ports/*/*/pkg/DESCR, where the -*s represent subdirectories of kinds of programs -and program names respectively. - -If you find the handbook too sophisticated (what with -lndir and all) on installing ports from the cdrom, -here's what usually works: - -Find the port you want, say kermit. There will be -a directory for it on the cdrom. Copy the subdirectory to -/usr/local (a good place for software you add -that should be available to all users) with: - -# cp -R /cdrom/ports/comm/kermit /usr/local - - -This should result in a /usr/local/kermit -subdirectory that has all the files that the -kermit subdirectory on the CDROM has. - -Next, create the directory /usr/ports/distfiles -if it doesn't already exist using mkdir. Now check -check /cdrom/ports/distfiles for a -file with a name that indicates it's the port you want. Copy that -file to /usr/ports/distfiles; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of kermit, there is no -distfile. - -Then cd to the subdirectory of -/usr/local/kermit that has the file -Makefile. Type - -# make all install - - - -During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -/usr/ports/distfiles. If you don't have your -network running yet and there was no file for the port in -/cdrom/ports/distfiles, you will have to get -the distfile using another machine and copy it to -/usr/ports/distfiles from a floppy or your dos -partition. Read Makefile (with cat or -more or view) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into /usr/ports/distfiles you'll have to rename -it (with the mv command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -/usr/local/kermit, find the directory with -Makefile, and type make all install. - -The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message can't find unzip or whatever, you -might need to install the package or port for unzip before you -continue. - -Once it's installed type rehash to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of path not found messages when you use -whereis or which, you might want to make additions to the -list of directories in the path statement in -.cshrc in your home directory. The path -statement in Unix does the same kind of work it does in DOS, except -the current directory is not (by default) in the path for security -reasons; if the command you want is in the directory you're in, you -need to type ./ before the command to make it -work; no space after the slash.) - -You might want to get the most recent version of Netscape from -their ftp site. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use gunzip -filename and tar xvf -filename on it, move the binary to -/usr/local/bin or some other place binaries are -kept, rehash, and then put the following lines in -.cshrc in each user's home directory or (easier) -in /etc/csh.cshrc, the system-wide csh start-up -file: - -setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls - -This assumes that the file XKeysymDB and the directory -nls are in /usr/X11R6/lib/X11; if -they're not, find them and put them there. - -If you originally got Netscape as a port using the CDROM (or -ftp), don't replace /usr/local/bin/netscape with -the new netscape binary; this is just a shell script that sets up the -environmental variables for you. Instead rename the new binary to -netscape.bin and replace the old binary, which -is /usr/local/lib/netscape/netscape.bin. - - - - - -Your Working Environment - -Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention. - -Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing echo $SHELL. - -The csh shell is okay, but tcsh does everything csh does and more. It -It allows you to recall commands with the arrow keys and edit them. -It has tab-key completion -of filenames (csh uses the escape key), and it lets you switch to the -directory you were last in with cd -. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier. - -Here are the three steps for installing a new shell: - - 1. Install the shell as a port or a package, just as you -would any other port or package. Use rehash and -which tcsh (assuming you're installing tcsh) to -make sure it got installed. - - 2. As root, edit /etc/shells, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.) - - 3. Use the chsh command to change your shell to -tcsh permanently, or type tcsh at the prompt to -change your shell without logging in again. - -Note: It can be dangerous to change root's shell -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use su -m -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -.tcshrc file as an alias with alias su su -m. - -When tcsh starts up, it will read the -/etc/csh.cshrc and /etc/csh.login -files, as does csh. It will also read the -.login file in your home directory and the -.cshrc -file as well, unless you provide a .tcshrc -file. This you can do by simply copying .cshrc -to .tcshrc. - -Now that you've installed tcsh, you can adjust your prompt. You can -find the details in the manual page for tcsh, but here is a line to -put in your .tcshrc that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a > if you're an ordinary user and -a # if you're root, but tsch will do that in any -case: - - set prompt = "%h %t %~ %# " - -This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. - -You can get a listing of other environmental variables that -have been set by typing env at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -setenv TERM vt100. - - - - -Other - -As root, you can dismount the CDROM with /sbin/umount -/cdrom, take it out of the drive, insert another one, and mount it -with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming -cd0a is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -/sbin/mount /cdrom. - -Using the live file system—the second of FreeBSD's CDROM -disks—is useful if you've got limited space. What is on the -live file system varies from release to release. You might try -playing games from the cdrom. This -involves using lndir, which gets installed with the X -Window System, to tell the program(s) where to find the necessary -files, because they're in the /cdrom file system -instead of in /usr and its subdirectories, which -is where they're expected to be. Read man lndir. - - - - -Comments Welcome - -If you use this guide I'd be interested in knowing where it was -unclear and what was left out that you think should be included, and -if it was helpful. My thanks to Eugene W. Stark, professor of -computer science at SUNY-Stony Brook, and John Fieber for helpful -comments. - -Annelise Anderson, andrsn@andrsn.stanford.edu - - - diff --git a/en_US.ISO8859-1/articles/programming-tools/Makefile b/en_US.ISO8859-1/articles/programming-tools/Makefile deleted file mode 100644 index 72c7507f01..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $ - -DOCS= devel.docb -INDEXLINK= devel.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/programming-tools/article.sgml b/en_US.ISO8859-1/articles/programming-tools/article.sgml deleted file mode 100644 index addd185ee8..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/article.sgml +++ /dev/null @@ -1,1835 +0,0 @@ - - - - - - - -A User's Guide to FreeBSD Programming Tools - - - -James -Raynard - -
-jraynard@freebsd.org -
- - - -August 17, 1997 - - -1997 -James Raynard - - -This document is an introduction to using some of the programming -tools supplied with FreeBSD, although much of it will be applicable to -many other versions of Unix. It does not attempt to describe -coding in any detail. Most of the document assumes little or no -previous programming knowledge, although it is hoped that most -programmers will find something of value in it - - - - -Introduction<anchor id=foo> - -FreeBSD offers an excellent development environment. Compilers -for C, C++, and Fortran and an assembler come with the basic system, -not to mention a Perl interpreter and classic Unix tools such as -sed and awk. If that is not enough, there are -many more compilers and interpreters in the Ports collection. FreeBSD -is very compatible with standards such as POSIX and -ANSI C, as well with its own BSD heritage, so it is -possible to write applications that will compile and run with little -or no modification on a wide range of platforms. - -However, all this power can be rather overwhelming at first if -you've never written programs on a Unix platform before. This -document aims to help you get up and running, without getting too -deeply into more advanced topics. The intention is that this document -should give you enough of the basics to be able to make some sense of -the documentation. - -Most of the document requires little or no knowledge of -programming, although it does assume a basic competence with using -Unix and a willingness to learn! - - - - -Introduction to Programming - -A program is a set of instructions that tell the computer to do -various things; sometimes the instruction it has to perform depends -on what happened when it performed a previous instruction. This -section gives an overview of the two main ways in which you can give -these instructions, or commands as they are usually -called. One way uses an interpreter, the other a -compiler. As human languages are too difficult for a -computer to understand in an unambiguous way, commands are usually -written in one or other languages specially designed for the -purpose. - - - - -Interpreters - -With an interpreter, the language comes as an environment, where you -type in commands at a prompt and the environment executes them for -you. For more complicated programs, you can type the commands into a -file and get the interpreter to load the file and execute the commands -in it. If anything goes wrong, many interpreters will drop you into a -debugger to help you track down the problem. - -The advantage of this is that you can see the results of your -commands immediately, and mistakes can be corrected readily. The -biggest disadvantage comes when you want to share your programs with -someone. They must have the same interpreter, or you must have some -way of giving it to them, and they need to understand how to use it. -Also users may not appreciate being thrown into a debugger if they -press the wrong key! From a performance point of view, interpreters -can use up a lot of memory, and generally do not generate code as -efficiently as compilers. - -In my opinion, interpreted languages are the best way to start -if you have not done any programming before. This kind of environment -is typically found with languages like Lisp, Smalltalk, Perl and -Basic. It could also be argued that the Unix shell (sh, -csh) is itself an interpreter, and many people do in fact -write shell scripts to help with various -housekeeping tasks on their machine. Indeed, part of the -original Unix philosophy was to provide lots of small utility -programs that could be linked together in shell scripts to perform -useful tasks. - - - - -Interpreters available with FreeBSD - -Here is a list of interpreters that are available as FreeBSD -packages, with a brief discussion of some of the more popular -interpreted languages. - -To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -$ pkg_add package name - - -as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work! - - - -BASIC - -Short for Beginner's All-purpose Symbolic Instruction -Code. Developed in the 1950s for teaching University students to -program and provided with every self-respecting personal computer in -the 1980s, BASIC has been the first programming language -for many programmers. It's also the foundation for Visual -Basic. - -The Bywater -Basic Interpreter and the Phil -Cockroft's Basic Interpreter (formerly Rabbit Basic) are -available as FreeBSD FreeBSD -packages - - - -Lisp -A language that was developed in the late 1950s as an alternative to -the number-crunching languages that were popular at the time. -Instead of being based on numbers, Lisp is based on lists; in fact -the name is short for List Processing. Very popular in AI -(Artificial Intelligence) circles. - -Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. - -FreeBSD has GNU -Common Lisp available as a package. - - - - -Perl -Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing CGI -scripts. - -Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer Perl -Version 5 is available as a package. - - - - -Scheme -A dialect of Lisp that is rather more compact and -cleaner than Common Lisp. Popular in Universities as it is simple -enough to teach to undergraduates as a first language, while it has a -high enough level of abstraction to be used in research work. - -FreeBSD has packages of the -Elk Scheme Interpreter, the -MIT Scheme Interpreter and the -SCM Scheme Interpreter. - - - - -Icon -The Icon Programming Language. - - - -Logo -Brian Harvey's LOGO Interpreter. - - - -Python -The Python Object-Oriented Programming Language - - - - - - - - - -Compilers - -Compilers are rather different. First of all, you write your -code in a file (or files) using an editor. You then run the compiler -and see if it accepts your program. If it did not compile, grit your -teeth and go back to the editor; if it did compile and gave you a -program, you can run it either at a shell command prompt or in a -debugger to see if it works properly.If you run it in -the shell, you may get a core dump. - -Obviously, this is not quite as direct as using an interpreter. -However it allows you to do a lot of things which are very difficult -or even impossible with an interpreter, such as writing code which -interacts closely with the operating system—or even writing -your own operating system! It's also useful if you need to write very -efficient code, as the compiler can take its time and optimise the -code, which would not be acceptable in an interpreter. And -distributing a program written for a compiler is usually more -straightforward than one written for an interpreter—you can just -give them a copy of the executable, assuming they have the same -operating system as you. - -Compiled languages include Pascal, C and C++. C and C++ are rather -unforgiving languages, and best suited to more experienced -programmers; Pascal, on the other hand, was designed as an educational -language, and is quite a good language to start with. Unfortunately, -FreeBSD doesn't have any Pascal support, except for a Pascal-to-C -converter in the ports. - -As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (IDEs -for short). FreeBSD does not have an IDE as such; however -it is possible to use Emacs for this purpose. This is discussed in -. - - - - - -Compiling with <command>cc</command> - -This section deals only with the GNU compiler for C and C++, -since that comes with the base FreeBSD system. It can be invoked by -either cc or gcc. The details of producing a -program with an interpreter vary considerably between interpreters, -and are usually well covered in the documentation and on-line help -for the interpreter. - -Once you've written your masterpiece, the next step is to convert it -into something that will (hopefully!) run on FreeBSD. This usually -involves several steps, each of which is done by a separate -program. - - -Pre-process your source code to remove comments and do other -tricks like expanding macros in C. - - -Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! - - -Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.To be strictly -accurate, cc converts the source code into its own, -machine-independent p-code instead of assembly language -at this stage. - -Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here. - -Check that you have used things like functions and global -variables in a consistent way. For example, if you have called a -non-existent function, it will complain. - -If you are trying to produce an executable from several -source code files, work out how to fit them all together. - -Work out how to produce something that the system's run-time -loader will be able to load into memory and run. - -Finally, write the executable on the file -system. - - - -The word compiling is often used to refer to just -steps 1 to 4—the others are referred to as -linking. Sometimes step 1 is referred to as -pre-processing and steps 3-4 as -assembling. - -Fortunately, almost all this detail is hidden from you, as -cc is a front end that manages calling all these programs -with the right arguments for you; simply typing -$ cc foobar.c - -will cause foobar.c to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -$ cc foo.c bar.c - - -Note that the syntax checking is just that—checking the -syntax. It will not check for any logical mistakes you may have made, -like putting the program into an infinite loop, or using a bubble -sort when you meant to use a binary sort.In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't. - -There are lots and lots of options for cc, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them. - - - - -The output name of the file. If you do not use this -option, cc will produce an executable called -a.out.The reasons for this are buried in -the mists of history. - - -$ cc foobar.c executable is a.out -$ cc -o foobar foobar.c executable is foobar - - - - - -Just compile the file, do not link it. Useful for toy -programs where you just want to check the syntax, or if you are using -a Makefile. - - -$ cc -c foobar.c - - -This will produce an object file (not an -executable) called foobar.o. This can be linked -together with other object files into an executable. - - - - - - -Create a debug version of the executable. This makes -the compiler put information into the executable about which line of -which source file corresponds to which function call. A debugger can -use this information to show the source code as you step through the -program, which is very useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with while you are -developing a program and then compile a release -version without when you're satisfied it -works properly. - - -$ cc -g foobar.c - - -This will produce a debug version of the -program.Note, we didn't use the -flag to specify the executable name, so we will get an executable -called a.out. Producing a debug version called -foobar is left as an exercise for the -reader! - - - - - - -Create an optimised version of the executable. The -compiler performs various clever tricks to try and produce an -executable that runs faster than normal. You can add a number after -the to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of cc that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the - option in some circumstances. - -Optimisation is usually only turned on when compiling a release -version. - - -$ cc -O -o foobar foobar.c - - -This will produce an optimised version of -foobar. - - - - - -The following three flags will force cc to -check that your code complies to the relevant international standard, -often referred to as the ANSI standard, though -strictly speaking it is an ISO standard. - - - - - -Enable all the warnings which the authors of -cc believe are worthwhile. Despite the name, it -will not enable all the warnings cc is capable -of. - - - - - - -Turn off most, but not all, of the non-ANSI C -features provided by cc. Despite the name, it does -not guarantee strictly that your code will comply to the -standard. - - - - - - - -Turn off all -cc's non-ANSI C features. - - - - - -Without these flags, cc will allow you to -use some of its non-standard extensions to the standard. Some of -these are very useful, but will not work with other compilers—in -fact, one of the main aims of the standard is to allow people to -write code that will work with any compiler on any system. This is -known as portable code. - -Generally, you should try to make your code as portable as -possible, as otherwise you may have to completely re-write the -program later to get it to work somewhere else—and who knows -what you may be using in a few years time? - - -$ cc -Wall -ansi -pedantic -o foobar foobar.c - - -This will produce an executable foobar -after checking foobar.c for standard -compliance. - - - - - -Specify a function library to be used during when -linking. - -The most common example of this is when compiling a program that -uses some of the mathematical functions in C. Unlike most other -platforms, these are in a separate library from the standard C one -and you have to tell the compiler to add it. - -The rule is that if the library is called -libsomething.a, you -give cc the argument -. For example, -the math library is libm.a, so you give -cc the argument . A common -gotcha with the math library is that it has to be the -last library on the command line. - - -$ cc -o foobar foobar.c -lm - - -This will link the math library functions into -foobar. - -If you are compiling C++ code, you need to add -, or if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run c++ -instead of cc, which does this for you. -c++ can also be invoked as g++ -on FreeBSD. - - -$ cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier -$ cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later -$ c++ -o foobar foobar.cc - - -Each of these will both produce an executable -foobar from the C++ source file -foobar.cc. Note that, on Unix systems, C++ -source files traditionally end in .C, -.cxx or .cc, rather than -the MS-DOS style .cpp -(which was already used for something else). gcc -used to rely on this to work out what kind of compiler to use on the -source file; however, this restriction no longer applies, so you may -now call your C++ files .cpp with -impunity! - - - - - - -Common <command>cc</command> Queries and Problems - -Q. I am trying to write a program which uses the -sin() function and I get an error like this. -What does it mean? - -/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - - - -A. When using mathematical functions like -sin(), you have to tell cc to -link in the math library, like so: - -$ cc -o foobar foobar.c -lm - - -Q. All right, I wrote this simple program to practice using -. All it does is raise 2.1 to the power of 6. - -#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - -and I compiled it as: - -$ cc temp.c -lm - -like you said I should, but I get this when I run it: - -$ ./a.out -2.1 ^ 6 = 1023.000000 - - - -This is not the right answer! What is -going on? - -A. When the compiler sees you call a function, it checks if it -has already seen a prototype for it. If it has not, it assumes the -function returns an int, which is -definitely not what you want here. - -Q. So how do I fix this? - -A. The prototypes for the mathematical functions are in -math.h. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! - -#include <math.h> -#include <stdio.h> - -int main() { -... - - - -After recompiling it as you did before, run it: - -$ ./a.out -2.1 ^ 6 = 85.766121 - - - -If you are using any of the mathematical functions, -always include math.h and -remember to link in the math library. - -Q. I compiled a file called foobar.c and I -cannot find an executable called foobar. Where's -it gone? - -A. Remember, cc will call the executable -a.out unless you tell it differently. Use the - option: - -$ cc -o foobar foobar.c - - - -Q. OK, I have an executable called foobar, -I can see it when I run ls, but when I type in -foobar at the command prompt it tells me there is -no such file. Why can it not find it? - -A. Unlike MS-DOS, Unix does not look in the -current directory when it is trying to find out which executable you -want it to run, unless you tell it to. Either type -./foobar, which means run the file called -foobar in the current directory, or -change your PATH -environment variable so that it looks something like - -bin:/usr/bin:/usr/local/bin:. - -The dot at the end means look in the current directory if it is not in -any of the others. - -Q. I called my executable test, but -nothing happens when I run it. What is going on? - -A. Most Unix systems have a program called -test in /usr/bin and the -shell is picking that one up before it gets to checking the current -directory. Either type: - -$ ./test - -or choose a better name for your program! - -Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about core -dumped. What does that mean? - -A. The name core dump dates back to the -very early days of Unix, when the machines used core memory for -storing data. Basically, if the program failed under certain -conditions, the system would write the contents of core memory to -disk in a file called core, which the programmer -could then pore over to find out what went wrong. - -Q. Fascinating stuff, but what I am supposed to do now? - -A. Use gdb to analyse the core (see ). - -Q. When my program dumped core, it said something about a -segmentation fault. What's that? - -A. This basically means that your program tried to perform some sort -of illegal operation on memory; Unix is designed to protect the -operating system and other programs from rogue programs. - -Common causes for this are: - -Trying to write to a NULL pointer, eg -char *foo = NULL; -strcpy(foo, "bang!"); - - -Using a pointer that hasn't been initialised, eg -char *foo; -strcpy(foo, "bang!"); -The pointer will have some random value that, with luck, -will point into an area of memory that isn't available to -your program and the kernel will kill your program before -it can do any damage. If you're unlucky, it'll point -somewhere inside your own program and corrupt one of your -data structures, causing the program to fail -mysteriously. - -Trying to access past the end of an array, eg -int bar[20]; -bar[27] = 6; - - Trying to store something in read-only memory, eg -char *foo = "My string"; -strcpy(foo, "bang!"); -Unix compilers often put string literals like -"My string" into -read-only areas of memory. - -Doing naughty things with -malloc() and free(), eg -char bar[80]; -free(bar); -or -char *foo = malloc(27); -free(foo); -free(foo); - - - - -Making one of these mistakes will not always lead to an -error, but they are always bad practice. Some systems and -compilers are more tolerant than others, which is why programs -that ran well on one system can crash when you try them on an -another. - -Q. Sometimes when I get a core dump it says bus -error. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true? - -A. No, fortunately not (unless of course you really do have a hardware -problem…). This is usually another way of saying that you -accessed memory in a way you shouldn't have. - -Q. This dumping core business sounds as though it could be quite -useful, if I can make it happen when I want to. Can I do this, or -do I have to wait until there's an error? - -A. Yes, just go to another console or xterm, do -$ ps -to find out the process ID of your program, and do -$ kill -ABRT pid -where pid is the -process ID you looked up. - -This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -SIGABRT, there are several other signals which have -a similar effect. - - - - - - -Make - - -What is <command>make</command>? - -When you're working on a simple program with only one or two source -files, typing in -$ cc file1.c file2.c -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too. - -One way to get around this is to use object files and only recompile -the source file if the source code has changed. So we could have -something like: -$ cc file1.o file2.o … file37.c &hellip -if we'd changed file37.c, but not any of the -others, since the last time we compiled. This may speed up the -compilation quite a bit, but doesn't solve the typing -problem. - -Or we could write a shell script to solve the typing problem, but it -would have to re-compile everything, making it very inefficient on a -large project. - -What happens if we have hundreds of source files lying about? What if -we're working in a team with other people who forget to tell us when -they've changed one of their source files that we use? - -Perhaps we could put the two solutions together and write something -like a shell script that would contain some kind of magic rule saying -when a source file needs compiling. Now all we need now is a program -that can understand these rules, as it's a bit too complicated for the -shell. - -This program is called make. It reads in a -file, called a makefile, that tells it how -different files depend on each other, and works out which files need -to be re-compiled and which ones don't. For example, a rule could say -something like if fromboz.o is older than -fromboz.c, that means someone must have changed -fromboz.c, so it needs to be -re-compiled. The makefile also has rules telling make -how to re-compile the source file, making it a -much more powerful tool. - -Makefiles are typically kept in the same directory as the -source they apply to, and can be called -makefile, Makefile or -MAKEFILE. Most programmers use the name -Makefile, as this puts it near the top of a -directory listing, where it can easily be seen.They -don't use the MAKEFILE form as block capitals -are often used for documentation files like -README. - - - - -Example of using <command>make</command> - -Here's a very simple make file: -foo: foo.c - cc -o foo foo.c -It consists of two lines, a dependency line and a creation line. - -The dependency line here consists of the name of the program -(known as the target), followed by a colon, -then whitespace, then the name of the source file. When -make reads this line, it looks to see if -foo exists; if it exists, it compares the time -foo was last modified to the time -foo.c was last modified. If -foo does not exist, or is older than -foo.c, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when foo.c needs to be re-compiled. - -The creation line starts with a tab (press the -tab key) and then the command you would type to -create foo if you were doing it at a command -prompt. If foo is out of date, or does not -exist, make then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile foo.c. - -So, when you type make, it will make -sure that foo is up to date with respect to your -latest changes to foo.c. This principle can be -extended to Makefiles with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing make -world in the appropriate directory! - -Another useful property of makefiles is that the targets don't have -to be programs. For instance, we could have a make file that looks -like this: -foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - -We can tell make which target we want to make by typing: -$ make target -make will then only look at that target and ignore any -others. For example, if we type make foo with the -makefile above, make will ignore the install target. - -If we just type make on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed make here, it will -just go to the foo target, re-compile -foo if necessary, and then stop without going on -to the install target. - -Notice that the install target doesn't -actually depend on anything! This means that the command on the -following line is always executed when we try to make that target by -typing make install. In this case, it will -copy foo into the user's home directory. This is -often used by application makefiles, so that the application can be -installed in the correct directory when it has been correctly -compiled. - -This is a slightly confusing subject to try and explain. If you -don't quite understand how make works, the best -thing to do is to write a simple program like hello -world and a make file like the one above and experiment. Then -progress to using more than one source file, or having the source -file include a header file. The touch command is -very useful here—it changes the date on a file without you -having to edit it. - - - - -FreeBSD Makefiles - -Makefiles can be rather complicated to write. Fortunately, -BSD-based systems like FreeBSD come with some very powerful ones as -part of the system. One very good example of this is the FreeBSD -ports system. Here's the essential part of a typical ports -Makefile: -MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - -Now, if we go to the directory for this port and type -make, the following happens: - - -A check is made to see if the source code for this port is -already on the system. - -If it isn't, an FTP connection to the URL in -MASTER_SITES is set up to download the -source. - -The checksum for the source is calculated and compared it with -one for a known, good, copy of the source. This is to make sure that -the source was not corrupted while in transit. - -Any changes required to make the source work on FreeBSD are -applied—this is known as patching. - -Any special configuration needed for the source is done. -(Many Unix program distributions try to work out which version of -Unix they are being compiled on and which optional Unix features are -present—this is where they are given the information in the -FreeBSD ports scenario). - -The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -make—the program's own make file has the -necessary information to build the program. - -We now have a compiled version of the program. If we -wish, we can test it now; when we feel confident about the program, -we can type make install. This will cause the -program and any supporting files it needs to be copied into the -correct location; an entry is also made into a package -database, so that the port can easily be uninstalled later -if we change our mind about it. - - - -Now I think you'll agree that's rather impressive for a four -line script! - -The secret lies in the last line, which tells -make to look in the system makefile called -bsd.port.mk. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells make to do all the -things above (plus a couple of other things I didn't mention, -including handling any errors that may occur) and anyone can get -access to that just by putting a single line in their own make -file! - -If you want to have a look at these system makefiles, they're -in /usr/share/mk, but it's probably best to wait -until you've had a bit of practice with makefiles, as they are very -complicated (and if you do look at them, make sure you have a flask -of strong coffee handy!) - - - - -More advanced uses of <command>make</command> - -Make is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of make, and they all -differ considerably. The best way to learn what they can do is -probably to read the documentation—hopefully this introduction will -have given you a base from which you can do this. - -The version of make that comes with FreeBSD is the Berkeley -make; there is a tutorial for it in -/usr/share/doc/psd/12.make. To view it, do -$ zmore paper.ascii.gz -in that directory. - -Many applications in the ports use GNU -make, which has a very good set of info -pages. If you have installed any of these ports, GNU -make will automatically have been installed as -gmake. It's also available as a port and package -in its own right. - -To view the info pages for GNU make, -you will have to edit the dir file in the -/usr/local/info directory to add an entry for -it. This involves adding a line like - * Make: (make). The GNU Make utility. -to the file. Once you have done this, you can type -info and then select -make from the menu (or in -Emacs, do C-h -i). - - - - - -Debugging - - -The Debugger - -The debugger that comes with FreeBSD is called -gdb (GNU -debugger). You start it up by typing -$ gdb progname -although most people prefer to run it inside -Emacs. You can do this by: -M-x gdb RET progname RET - -Using a debugger allows you to run the program under more -controlled circumstances. Typically, you can step through the program -a line at a time, inspect the value of variables, change them, tell -the debugger to run up to a certain point and then stop, and so on. -You can even attach to a program that's already running, or load a -core file to investigate why the program crashed. It's even possible -to debug the kernel, though that's a little trickier than the user -applications we'll be discussing in this section. - -gdb has quite good on-line help, as well as -a set of info pages, so this section will concentrate on a few of the -basic commands. - -Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it xxgdb -in the ports collection. - -This section is intended to be an introduction to using -gdb and does not cover specialised topics such as -debugging the kernel. - - - - -Running a program in the debugger - -You'll need to have compiled the program with the - option to get the most out of using -gdb. It will work without, but you'll only see the -name of the function you're in, instead of the source code. If you -see a line like: -… (no debugging symbols found) …when -gdb starts up, you'll know that the program wasn't -compiled with the option. - -At the gdb prompt, type break -main. This will tell the debugger to skip over the -preliminary set-up code in the program and start at the beginning of -your code. Now type run to start the -program—it will start at the beginning of the set-up code and -then get stopped by the debugger when it calls -main(). (If you've ever wondered where -main() gets called from, now you know!). - -You can now step through the program, a line at a time, by -pressing n. If you get to a function call, you can -step into it by pressing s. Once you're in a -function call, you can return from stepping into a function call by -pressing f. You can also use up and -down to take a quick look at the caller. - -Here's a simple example of how to spot a mistake in a program -with gdb. This is our program (with a deliberate -mistake): -#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - - -This program sets i to be 5 -and passes it to a function bazz() which prints -out the number we gave it. - -When we compile and run the program we get -$ cc -g -o temp temp.c -$ ./temp -This is my program -anint = 4231 - -That wasn't what we expected! Time to see what's going -on!$ gdb temp -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) break main Skip the set-up code -Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main() -(gdb) run Run as far as main() -Starting program: /home/james/tmp/temp Program starts running - -Breakpoint 1, main () at temp.c:9 gdb stops at main() -(gdb) n Go to next line -This is my program Program prints out -(gdb) s step into bazz() -bazz (anint=4231) at temp.c:17 gdb displays stack frame -(gdb) - - -Hang on a minute! How did anint get to be -4231? Didn't we set it to be 5 -in main()? Let's move up to -main() and have a look. - -(gdb) up Move up call stack -#1 0x1625 in main () at temp.c:11 gdb displays stack frame -(gdb) p i Show us the value of i -$1 = 4231 gdb displays 4231 -Oh dear! Looking at the code, we forgot to initialise -i. We meant to put -… -main() { - int i; - - i = 5; - printf("This is my program\n"); -&hellip -but we left the i=5; line out. As we didn't -initialise i, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be 4231. - -gdb displays the stack frame -every time we go into or out of a function, even if we're using -up and down to move around the -call stack. This shows the name of the function and the values of -its arguments, which helps us keep track of where we are and what's -going on. (The stack is a storage area where the program stores -information about the arguments passed to functions and where to go -when it returns from a function call). - - - - -Examining a core file - -A core file is basically a file which contains the complete -state of the process when it crashed. In the good old -days, programmers had to print out hex listings of core files -and sweat over machine code manuals, but now life is a bit easier. -Incidentally, under FreeBSD and other 4.4BSD systems, a core file is -called progname.core instead of just -core, to make it clearer which program a core -file belongs to. - -To examine a core file, start up gdb in the -usual way. Instead of typing break or -run, type -(gdb) core progname.core -If you're not in the same directory as the core file, you'll have to -do dir /path/to/core/file first. - -You should see something like this: -$ gdb a.out -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) core a.out.core -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - -In this case, the program was called -a.out, so the core file is called -a.out.core. We can see that the program crashed -due to trying to access an area in memory that was not available to -it in a function called bazz. - -Sometimes it's useful to be able to see how a function was -called, as the problem could have occurred a long way up the call -stack in a complex program. The bt command causes -gdb to print out a back-trace of the call -stack: -(gdb) bt -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)The end() function is called when -a program crashes; in this case, the bazz() -function was called from main(). - - - - -Attaching to a running program - -One of the neatest features about gdb is -that it can attach to a program that's already running. Of course, -that assumes you have sufficient permissions to do so. A common -problem is when you are stepping through a program that forks, and -you want to trace the child, but the debugger will only let you trace -the parent. - -What you do is start up another gdb, use -ps to find the process ID for the child, and -do(gdb) attach pid -in gdb, and then debug as usual. - -That's all very well, you're probably thinking, -but by the time I've done that, the child process will be over -the hill and far away. Fear not, gentle reader, here's how to -do it (courtesy of the gdb info pages): -&hellip -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - &hellip -} else { /* parent */ - &hellip -Now all you have to do is attach to the child, set -PauseMode to 0, and -wait for the sleep() call to return! - - - - - -Using Emacs as a Development Environment - - -Emacs - -Unfortunately, Unix systems don't come with the kind of -everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package -integrated development environments that other systems -have.At least, not unless you pay out very large sums -of money. However, it is possible to set up your -own environment. It may not be as pretty, and it may not be quite as -integrated, but you can set it up the way you want it. And it's free. -And you have the source to it. - -The key to it all is Emacs. Now there are some people who -loathe it, but many who love it. If you're one of the former, I'm -afraid this section will hold little of interest to you. Also, you'll -need a fair amount of memory to run it—I'd recommend 8MB in -text mode and 16MB in X as the bare minimum to get reasonable -performance. - -Emacs is basically a highly customisable editor—indeed, -it has been customised to the point where it's more like an operating -system than an editor! Many developers and sysadmins do in fact -spend practically all their time working inside Emacs, leaving it -only to log out. - -It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: - - -Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc. - -Pull-down menus and online help. - -Language-dependent syntax highlighting and -indentation. - -Completely customisable. - -You can compile and debug programs within -Emacs. - -On a compilation error, you can jump to the offending -line of source code. - -Friendly-ish front-end to the info -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself. - -Friendly front-end to gdb, -allowing you to look at the source code as you step through your -program. - -You can read Usenet news and mail while your program -is compiling. - -And doubtless many more that I've overlooked. - -Emacs can be installed on FreeBSD using the Emacs -port. - -Once it's installed, start it up and do C-h -t to read an Emacs tutorial—that means hold down -the control key, press h, let go of -the control key, and then press t. -(Alternatively, you can you use the mouse to select Emacs -Tutorial from the Help menu). - -Although Emacs does have menus, it's well worth learning the -key bindings, as it's much quicker when you're editing something to -press a couple of keys than to try and find the mouse and then click -on the right place. And, when you're talking to seasoned Emacs users, -you'll find they often casually throw around expressions like -M-x replace-s RET foo RET bar RET -so it's useful to know what they mean. And in any case, Emacs has far -too many useful functions for them to all fit on the menu -bars. - -Fortunately, it's quite easy to pick up the key-bindings, as -they're displayed next to the menu item. My advice is to use the -menu item for, say, opening a file until you understand how it works -and feel confident with it, then try doing C-x C-f. When you're happy -with that, move on to another menu command. - -If you can't remember what a particular combination of keys -does, select Describe Key from the -Help menu and type it in—Emacs will tell you -what it does. You can also use the Command -Apropos menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it. - -By the way, the expression above means hold down the -Meta key, press x, release the -Meta key, type replace-s -(short for replace-string—another feature of -Emacs is that you can abbreviate commands), press the -return key, type foo (the -string you want replaced), press the return key, -type bar (the string you want to replace foo with) -and press return again. Emacs will then do the -search-and-replace operation you've just requested. - -If you're wondering what on earth the Meta key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -alt key (or if you're unlucky, the escape -key). - -Oh, and to get out of Emacs, do C-x C-c -(that means hold down the control key, press -c, press x and release the -control key). If you have any unsaved files open, -Emacs will ask you if you want to save them. (Ignore the bit in the -documentation where it says C-z is the usual way -to leave Emacs—that leaves Emacs hanging around in the -background, and is only really useful if you're on a system which -doesn't have virtual terminals). - - - - -Configuring Emacs - -Emacs does many wonderful things; some of them are built in, -some of them need to be configured. - -Instead of using a proprietary macro language for -configuration, Emacs uses a version of Lisp specially adapted for -editors, known as Emacs Lisp. This can be quite useful if you want to -go on and learn something like Common Lisp, as it's considerably -smaller than Common Lisp (although still quite big!). - -The best way to learn Emacs Lisp is to download the Emacs -Tutorial - -However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -.emacs file, which should be enough to get you -started. Just copy it into your home directory and restart Emacs if -it's already running; it will read the commands from the file and -(hopefully) give you a useful basic setup. - - - - -A sample <filename>.emacs</filename> file - -Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning. - - - - -Everything beginning with a ; is a -comment and is ignored by Emacs. - -In the first line, the --*- Emacs-Lisp -*- is so that we can -edit the .emacs file itself within Emacs and get -all the fancy features for editing Emacs Lisp. Emacs usually tries to -guess this based on the filename, and may not get it right for -.emacs. - -The tab key is bound to an -indentation function in some modes, so when you press the tab key, it -will indent the current line of code. If you want to put a -tab character in whatever you're writing, hold the -control key down while you're pressing the -tab key. - -This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename. - -Emacs already has a pre-defined function called -next-error. In a compilation output window, this -allows you to move from one compilation error to the next by doing -M-n; we define a complementary function, -previous-error, that allows you to go to a -previous error by doing M-p. The nicest feature of -all is that C-c C-c will open up the source file -in which the error occurred and jump to the appropriate -line. - - We enable Emacs's ability to act as a server, so -that if you're doing something outside Emacs and you want to edit a -file, you can just type in -$ emacsclient filename -and then you can edit the file in your Emacs!Many -Emacs users set their EDITOR environment to -emacsclient so this happens every time they need -to edit a file. - - - - - -A sample <filename>.emacs</filename> file -;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - - - - - - -Extending the Range of Languages Emacs Understands - -Now, this is all very well if you only want to program in the -languages already catered for in the .emacs file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called whizbang comes out, full of exciting -features? - -The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in .el, short for Emacs -Lisp. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -$ find /usr/ports/lang/whizbang -name "*.el" -print -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -/usr/local/share/emacs/site-lisp. - -So for example, if the output from the find command was -/usr/ports/lang/whizbang/work/misc/whizbang.el -we would do -$ cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp - - -Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -.wiz. We need to add an entry to our -.emacs file to make sure Emacs will be able to -use the information in whizbang.el. - -Find the auto-mode-alist entry in -.emacs and add a line for whizbang, such -as: -… -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -… -This means that Emacs will automatically go into -whizbang-mode when you edit a file ending in -.wiz. - -Just below this, you'll find the -font-lock-auto-mode-list entry. Add -whizbang-mode to it like so: -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") -This means that Emacs will always enable -font-lock-mode (ie syntax highlighting) when -editing a .wiz file. - -And that's all that's needed. If there's anything else you want -done automatically when you open up a .wiz file, -you can add a whizbang-mode hook (see -my-scheme-mode-hook for a simple example that -adds auto-indent). - - - - - -Further Reading - - -Brian Harvey and Matthew Wright -Simply Scheme -MIT 1994. -ISBN 0-262-08226-8 - -Randall Schwartz -Learning Perl -O'Reilly 1993 -ISBN 1-56592-042-2 - -Patrick Henry Winston and Berthold Klaus Paul Horn -Lisp (3rd Edition) -Addison-Wesley 1989 -ISBN 0-201-08319-1 - -Brian W. Kernighan and Rob Pike -The Unix Programming Environment -Prentice-Hall 1984 -ISBN 0-13-937681-X - -Brian W. Kernighan and Dennis M. Ritchie -The C Programming Language (2nd Edition) -Prentice-Hall 1988 -ISBN 0-13-110362-8 - -Bjarne Stroustrup -The C++ Programming Language -Addison-Wesley 1991 -ISBN 0-201-53992-6 - -W. Richard Stevens -Advanced Programming in the Unix Environment -Addison-Wesley 1992 -ISBN 0-201-56317-7 - -W. Richard Stevens -Unix Network Programming -Prentice-Hall 1990 -ISBN 0-13-949876-1 - - - - - diff --git a/en_US.ISO_8859-1/articles/fonts/Makefile b/en_US.ISO_8859-1/articles/fonts/Makefile deleted file mode 100644 index 260184f87c..0000000000 --- a/en_US.ISO_8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= fonts.docb -INDEXLINK= fonts.html - -.include "../../web.mk" diff --git a/en_US.ISO_8859-1/articles/fonts/article.sgml b/en_US.ISO_8859-1/articles/fonts/article.sgml deleted file mode 100644 index 4d46efb511..0000000000 --- a/en_US.ISO_8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,723 +0,0 @@ - - - - - - - - - - -Fonts and FreeBSD -A Tutorial - - - -Dave -Bodenstab - -
imdave@synet.net
- - - - -Wed Aug 7, 1996 - -This document contains a description of the various -font files that may be used with FreeBSD and the syscons driver, X11, -Ghostscript and Groff. Cookbook examples are provided for switching -the syscons display to 80x60 mode, and for using type 1 fonts with -the above application programs. - - - - - -Introduction - -There are many sources of fonts available, and one might ask -how they might be used with FreeBSD. The answer can be found by -carefully searching the documentation for the component that one -would like to use. This is very time consuming, so this tutorial is -an attempt to provide a shortcut for others who might be -interested. - - - - -Basic terminology - -There are many different font formats and associated font file -suffixes. A few that will be addressed here are: - - -.pfa, .pfb - -Postscript type 1 fonts. The .pfa is the -Ascii form and .pfb the -Binary form. - - - -.afm - -The font metrics associated with a type 1 -font. - - - -.pfm - -The printer font metrics associated with a type 1 -font. - - - -.ttf - -A TrueType font - - - -.fot - -An indirect reference to a TrueType font (not an -actual font) - - - -.fon, .fnt - -Bitmapped screen fonts - - - - -The .fot file is used by Windows as sort -of a symbolic link to the actual TrueType font -(.ttf) file. The .fon font -files are also used by Windows. I know of no way to use this font -format with FreeBSD. - - - - -What font formats can I use? - -Which font file format is useful depends on the application -being used. FreeBSD by itself uses no fonts. Application programs -and/or drivers may make use of the font files. Here is a small cross -reference of application/driver to the font type suffixes: - - - -Driver - - - -syscons - -.fnt - - - - - - - - - -Application - - - - -Ghostscript - -.pfa, .pfb, .ttf - - - - -X11 - - -.pfa, .pfb - - - - -Groff - - -.pfa, .afm - - - - -Povray - - -.ttf - - - - - - - - - - - -The .fnt suffix is used quite frequently. -I suspect that whenever someone wanted to create a specialized font -file for their application, more often than not they chose this -suffix. Therefore, it is likely that files with this suffix are not -all the same format; specifically, the .fnt -files used by syscons under FreeBSD may not be the same format as a -.fnt file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -.fnt files other than those provided with -FreeBSD. - - - - -Setting a virtual console to 80x60 line mode - -First, a 8x8 font must be loaded. -/etc/sysconfig should contain the lines: - -# Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt - - - -The command to actually switch the mode is -vidcontrol1: - -bash$ vidcontrol VGA_80x60 - - - -Various screen orientated programs, such as -vi1, must be able to -determine the current screen dimensions. These can be set with -stty1: - -bash$ stty crt rows 60 columns 80 - - - -To make this more seamless, one can embed these commands in the -startup scripts so it takes place when the system boots. One way to -do this is: - - - -Modify /etc/sysconfig as above - - - -Add to /etc/rc.local: - -for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done - - - - -Add to /etc/profile: - -TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi - - - - - - - -References: -stty1, -vidcontrol1. - - - - -Using type 1 fonts with X11 - -X11 can use either the .pfa or the -.pfb format fonts. The X11 fonts are located in -various subdirectories under -/usr/X11R6/lib/X11/fonts. Each font file is -cross referenced to its X11 name by the contents of the -fonts.dir file in each directory. - -There is already a directory named Type1. The most -straight forward way to add a new font is to put it into this -directory. A better way is to keep all new fonts in a separate -directory and use a symbolic link to the additional font. This -allows one to more easily keep track of ones fonts without confusing -them with the fonts that were originally provided. For -example: - -Create a directory to contain the font files -bash$ mkdir -p /usr/local/share/fonts/type1 -bash$ cd /usr/local/share/fonts/type1 - -Place the .pfa, .pfb and .afm files here -One might want to keep readme files, and other documentation -for the fonts here also -bash$ cp /cdrom/fonts/atm/showboat/showboat.pfb . -bash$ cp /cdrom/fonts/atm/showboat/showboat.afm . - -Maintain an index to cross reference the fonts -bash$ echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX - - - -Now, to use a new font with X11, one must make the font file -available and update the font name files. The X11 font names look -like: - --bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style - - - -A new name needs to be created for each new font. If you have -some information from the documentation that accompanied the font, -then it could serve as the basis for creating the name. If there is -no information, then you can get some idea by using -strings1 on the font -file. For example: - -bash$ strings showboat.pfb | more -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin-- - - -Using this information, a possible name might be: - --type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - - - -The components of our name are: - - -Foundry - -Lets just name all the new fonts type1. - - - -Family - -The name of the font. - - - -Weight - -Normal, bold, medium, semibold, etc. From the -strings1 output -above, it appears that this font has a weight of -medium. - - - -Slant - -roman, italic, oblique, -etc. Since the ItalicAngle is zero, -roman will be used. - - - -Width - -Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be normal. - - - -Additional style - -Usually omitted, but this will indicate that -the font contains decorative capital letters. - - - -Spacing - -proportional or monospaced. Proportional -is used since isFixedPitch is false. - - - - - - -All of these names are arbitrary, but one should strive to be -compatible with the existing conventions. A font is referenced by -name with possible wild cards by an X11 program, so the name chosen -should make some sense. One might begin by simply using - -…-normal-r-normal-…-p-… - -as the name, and then use -xfontsel1 to examine it -and adjust the name based on the appearance of the font. - -So, to complete our example: - -Make the font accessible to X11 -bash$ cd /usr/X11R6/lib/X11/fonts/Type1 -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line. -bash$ ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq - -fonts.scale seems to be identical to fonts.dir… -bash$ cp fonts.dir fonts.scale - -Tell X11 that things have changed -bash$ xset fp rehash - -Examine the new font -bash$ xfontsel -pattern -type1-* - - - -References: -xfontsel1, -xset1, -The X Windows System in a Nutshell, O'Reilly & Associates. - - - - -Using type 1 fonts with Ghostscript - -Ghostscript references a font via its Fontmap -file. This must be modified in a similar way to the X11 -fonts.dir file. Ghostscript can use either the -.pfa or the .pfb format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: - -Put the font in Ghostscript's font directory -bash$ cd /usr/local/share/ghostscript/fonts -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit Fontmap so Ghostscript knows about the font -bash$ cd /usr/local/share/ghostscript/4.01 -bash$ ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq - -Use Ghostscript to examine the font -bash$ gs prfont.ps -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS>Showboat DoFont -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS>quit - - - -References: fonts.txt in the Ghostscript -4.01 distribution - - - - -Using type 1 fonts with Groff - -Now that the new font can be used by both X11 and Ghostscript, -how can one use the new font with groff? First of all, since we are -dealing with type 1 postscript fonts, the groff device that is -applicable is the ps device. A font file must be -created for each font that groff can use. A groff font name is just -a file in /usr/share/groff_font/devps. With our -example, the font file could be -/usr/share/groff_font/devps/SHOWBOAT. The file -must be created using tools provided by groff. - -The first tool is afmtodit. This is not normally -installed, so it must be retrieved from the source distribution. I -found I had to change the first line of the file, so I did: - -bash$ cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp -bash$ ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq - - - -This tool will create the groff font file from the metrics file -(.afm suffix.) Continuing with our -example: - -Many .afm files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines -bash$ cd /tmp -bash$ cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm - -Now create the groff font file -bash$ cd /usr/share/groff_font/devps -bash$ /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT - - - -The font can now be referenced with the name SHOWBOAT. - -If ghostscript is used to drive the printers on the system, -then nothing more needs to be done. However, if true postscript -printers are used, then the font must be down loaded to the printer -in order for the font to be used (unless the printer happens to have -the showboat font built in or on an accessible font disk.) The final -step is to create a down loadable font. The pfbtops tool -is used to create the .pfa format of the font, -and the download file is modified to reference the new -font. The download file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: - -Create the .pfa font file -bash$ pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa - -Of course, if the .pfa file is already -available, just use a symbolic link to reference it. - -Get the internal font name -bash$ fgrep internalname SHOWBOAT -internalname Showboat - -Tell groff that the font must be down loaded -bash$ ex download -:$a -Showboat showboat.pfa -. -:wq - - - -To test the font: - -bash$ cd /tmp -bash$ cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF -bash$ groff -Tps example.t >example.ps - -To use ghostscript/ghostview -bash$ ghostview example.ps - -To print it -bash$ lpr -Ppostscript example.ps - - - -References: -/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, -groff_font5, -groff_char5, -pfbtops1. - - - - -Can TrueType fonts be used? - -The TrueType font format is used by Windows, Windows 95, -Mac's,&hellip It is quite popular and there are a great number of -fonts available in this format. Unfortunately, there are only two -applications that I am aware of that can use this format: Ghostscript -and povray. Ghostscript's support, according to the documentation, -is rudimentary and the results are likely to be inferior to type 1 -fonts. - -However, groff would need a font description file, and I know -of no tools to construct the metrics from a TrueType font. In -addition, the font would have to be down loaded to postscript -printers in the appropriate format, and again, groff cannot handle -TrueType fonts in this fashion. - -X11 has no support for TrueType fonts that I am aware -of. - -The only program that I know of that has the ability to use -TrueType fonts is povray version 3, but I rather doubt many people -will be creating documents as a series of raytraced pages! -:-) - - - - -Where can additional fonts be obtained? - -Many fonts are available on the Internet. They are either -entirely free, or are share-ware. In addition, there are many -inexpensive CDROMs available that contain many fonts. Some Internet -locations (as of August 1996) are: - - -ftp://ftp.winsite.com (Formerly -CICA) - -http://www.simtel.net/simcgi-bin/dosfind.cgi - -ftp://ftp.coast.net/ - -http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html - -http://www.esselte.com/letraset/index.html - -http://www.inil.com/users/elfring/esf.htm - - - - - - -Additional questions - - - - - -What use are the .pfm files? - - - -Can one generate the .afm file from a .pfa or .pfb? - - - -How to generate the groff character mapping files for postscript fonts -with non-standard character names? - - - -Can xditview and devX?? devices be setup to access all the new fonts? - - - -It would be good to have examples of using TrueType fonts with povray and -ghostscript. - - - - - - - diff --git a/en_US.ISO_8859-1/articles/formatting-media/Makefile b/en_US.ISO_8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 158bc4d801..0000000000 --- a/en_US.ISO_8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $ - -DOCS= diskformat.docb -INDEXLINK= diskformat.html - -.include "../../web.mk" - diff --git a/en_US.ISO_8859-1/articles/formatting-media/article.sgml b/en_US.ISO_8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index 96f12cc1a4..0000000000 --- a/en_US.ISO_8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,418 +0,0 @@ - - - - - - -Formatting Media For Use With FreeBSD 2.2-RELEASE -A Tutorial - - - -Doug -White - -
dwhite@resnet.uoregon.edu
- - - - -March 1997 -This document describes how to slice, partition, and -format hard disk drives and similar media for use with FreeBSD. The -examples given have been tested under FreeBSD 2.2-GAMMA and may work -for other releases. - - - - - -Introduction & Definitions - - -Overview -Successfully adding disks to an existing system is the mark of an -experienced system administrator. Slicing, partitioning, and adding -disks requires a careful dance of proper command and name syntax. One -slipped finger and an entire disk could disappear in seconds. This -document is written in an attempt to simplify this process and avoid -accidents. Thankfully, enhancements to existing tools (notably -sysinstall) have greatly improved this process in recent releases of -FreeBSD. - -There are two possible modes of disk formatting: - - -compatibility mode: Arranging a -disk so that it has a slice table for use with other operating -systems. - -dangerously dedicated mode: -Formatting a disk with no slice table. This makes the process of -adding disks easier, however non-FreeBSD operating systems may not -accept the disk. - - - -For most cases, dedicated mode is the easiest to set up and use -in existing systems, as a new disk is usually dedicated entirely to -FreeBSD. However, compatibility mode insures optimum interoperability -with future installations at a cost of increased complexity. - -In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -/stand/sysinstall. 2.1.7-RELEASE and later -versions of sysinstall contain code to ease setup -of disks during normal system operation, mainly allowing access to the -Label and Partition editors and a Write feature which will update just -the selected disk and slice without affecting other disks. The other -method is running the tools manually from a root command line. For -dangerously dedicated mode, only three or four commands are involved -while sysinstall requires some manipulation. - - -Definitions - -UNIX disk management over the centuries has invented many new -definitions for old words. The following glossary covers the -definitions used in this document and (hopefully) for FreeBSD in -general. - - - - -compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode. - -dangerously dedicated mode: Formatting a disk with no slice -table. This makes the process of adding disks easier, however -non-FreeBSD operating systems may not accept the disk. Oppose -compatibility mode. - -disk: A circular disc, covered with magnetic or similarly -manipulable material, spun by a motor under a head. Data is stored on -the disk by changing the pattern of magnetism on the disc, which can -be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz -removables are examples of disks. - -slice: A division of a disk. Up to four slices are permitted on one -disk in the PC standard. Slices are composed of contiguous sectors. -Slices are recorded in a slice table used by the system BIOS to -locate bootable partitions. The slice table is usually called the -Partition Table in DOS parlance. Maintained by the fdisk utility. - -partition: A division of a slice. Usually used in reference -to divisions of the FreeBSD slice of a disk. Each filesystem and swap -area on a disk resides in a partition. Maintained using the disklabel -utility. - -sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data. - - - - - -Warnings & Pitfalls - -Building disks is not something to take lightly. It is quite possible -to destroy the contents of other disks in your system if the proper -precautions are not taken. - -Check your work carefully. It is very simple to destroy -the incorrect disk when working with these commands. When -in doubt consult the kernel boot output for the proper device. - -Needless to say, we are not responsible for any damage to any data -or hardware that you may experience. You work at your own risk! - - - - -Zip, Jaz, and Other Removables - -Removable disks can be formatted in the same way as normal hard -disks. It is essential to have the disk drive connected to the system -and a disk placed in the drive during startup, so the kernel can -determine the drive's geometry. Check the dmesg -output and make sure your device and the disk's size is listed. If -the kernel reports - - -Can't get the size - - -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. - - - - - -Formatting Disks in Dedicated Mode - - -Introduction - -This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture. - - - -Making Dedicated Mode Disks using Sysinstall - -/stand/sysinstall, the system installation -utility, has been expanded in recent versions to make the process of -dividing disks properly a less tiring affair. The fdisk and disklabel -editors built into sysinstall are GUI tools that remove much of the -confusion from slicing disks. For FreeBSD versions 2.1.7 and later, -this is perhaps the simplest way to slice disks. - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - -answer No. -When asked if you still want to do this, answer -Yes. -Select Write. -When warned about Writing on installed systems, answer -Yes. -Quitthe FDISK Editor and -ESCAPE back to the Index menu. -Select Label from the Index -menu. -Label as desired. For a single partition, enter -C to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used). -Enter W when done and confirm to -continue. The filesystem will be newfs'd for you, unless you select -otherwise (for news partitions you'll want to do this!). You'll get -the error: - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - - - -Making Dedicated Mode Disks Using the Command Line - - -Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin - # We only want one partition, so using slice 'c' should be fine: - newfs /dev/rwd2c - - - - - If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: - - - - - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/r$d > /tmp/label - # Edit disklabel to add partitions: - vi /tmp/label - disklabel -B -R -r wd2 /tmp/label - # newfs partitions appropriately - - - - -Your disk is now ready for use. - - - - - -Making Compatibility Mode Disks - - -Introduction -The command line is the easiest way to make dedicated disks, and -the worst way to make compatibility disks. The command-line fdisk -utility requires higher math skills and an in-depth understanding of -the slice table, which is more than most people want to deal with. -Use sysinstall for compatibility disks, as described below. - - - - -Making Compatibility Mode Disks Using Sysinstall - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. - -When asked: - - -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - - answer yes. -Select Write. -When asked to install the boot manager, select None with -SPACE then hit ENTER for OK. -Quit the FDISK Editor. -You'll be asked about the boot manager, select -None -again. -Select Label from the Index -menu. -Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used). -The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error: - - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - -Your new disk is now ready for use. - - - - - -Other Disk Operations - -Adding Swap Space - -As a system grows, it's need for swap space can also grow. -Although adding swap space to existing disks is very difficult, a new -disk can be partitioned with additional swap space. - -To add swap space when adding a disk to a system: - -When partitioning the disk, edit the disklabel and -allocate the amount of swap space to add in partition `b' and the -remainder in another partition, such as `a' or `e'. The size is given -in 512 byte blocks. -When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies. -Add an entry to /etc/fstab as follows: - - -/dev/wd0b none swap sw 0 0 - - -Change /dev/wd0b to the device of the newly added -space. -To make the new space immediately available, use the -swapon command. - - - -$ swapon /dev/sd0b - -swapon: added /dev/sd0b as swap space - - - - - - - - -Copying the Contents of Disks - -Submitted By: Renaud Waldura (renaud@softway.com) - -To move file from your original base disk to the fresh new one, -do: - - - -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home - - - - - - - - -Credits - - - -The author would like to thank the following individuals for -their contributions to this project: - -Darryl Okahata -(darrylo@hpnmhjw.sr.hp.com) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions. -Jordan Hubbard -(jkh@freebsd.org) for making -sysinstall useful for this type of task. -John Fieber -(jfieber@indiana.edu) for making -information and examples of the DocBook DTD on which this document is -based. -Greg Lehey (grog@freebsd.org) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. - - - - - - - - - diff --git a/en_US.ISO_8859-1/articles/mh/Makefile b/en_US.ISO_8859-1/articles/mh/Makefile deleted file mode 100644 index 14a686e6af..0000000000 --- a/en_US.ISO_8859-1/articles/mh/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= mh.docb -INDEXLINK= mh.html - -.include "../../web.mk" - diff --git a/en_US.ISO_8859-1/articles/mh/article.sgml b/en_US.ISO_8859-1/articles/mh/article.sgml deleted file mode 100644 index 3c33cf92ea..0000000000 --- a/en_US.ISO_8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,704 +0,0 @@ - - - - - - - - -An MH Primer - - - -Matt -Midboe - -
-matt@garply.com -
- - - -v1.0, 16 January 1996 - -This document contains an introduction to using MH on -FreeBSD - - - - - -Introduction - -MH started back in 1977 at the RAND Corporation, where the -initial philosophies behind MH were developed. MH isn't so much a -monolithic email program but a philosophy about how best to develop -tools for reading email. The MH developers have done a great job -adhering to the KISS principle: Keep It Simple Stupid. -Rather than have one large program for reading, sending and handling -email they have written specialized programs for each part of your -email life. One might liken MH to the specialization that one finds -in insects and nature. Each tool in MH does one thing, and does it -very well. - -Beyond just the various tools that one uses to handle their -email MH has done an excellent job keeping the configuration of each -of these tools consistent and uniform. In fact, if you are not quite -sure how something is supposed to work or what the arguments for some -command are supposed to be then you can generally guess and be right. -Each MH command is consistent about how it handles reading the -configuration files and how it takes arguments on the command line. -One useful thing to remember is that you can always add a - to the command to have it display the options -for that command. - -The first thing that you need to do is to make sure that you have -installed the MH package on your FreeBSD machine. If you installed -from CDROM you should be able to execute the following to load mh: - -# pkg_add /cdrom/packages/mh-6.8.3.tgz - -You will notice that it created a /usr/local/lib/mh -directory for you as well as adding several binaries to the -/usr/local/bin directory. If you would prefer to compile -it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. - -This primer is not a full comprehensive explanation of how MH -works. This is just intended to get you started on the road to -happier, faster mail reading. You should read the man pages for the -various commands. Also you might want to read the comp.mail.mh newsgroup. Also you can -read the FAQ -for MH. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek. - - - - -Reading Mail - -This section covers how to use inc, -show, scan, next, -prev, rmm, rmf, and -msgchk. One of the best things about MH is the -consistent interface between programs. A few things to keep in mind -when using these commands is how to specify message lists. In the -case of inc this doesn't really make any sense but with -commands like show it is useful to know. - -A message list can consist of something like 23 20 -16 which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like 23-30 which will -act on all the messages between 23 and 30. You can also specify -something like cur:10 which will act on the current -message and the next 9 messages. The cur, -last, and first messages are special -messages that refer to the current, last or first message in the -folder. - - - -<command>inc</>, <command>msgchk</>—read in your new email or check it - -If you just type in inc and hit return -you will be well on your way to getting started with MH. The first -time you run inc it will setup your account to use all -the MH defaults and ask you about creating a Mail directory. If you -have mail waiting to be downloaded you will see something that looks -like: - - 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -This is the same thing you will see from a scan (see -). If you just run inc with no -arguments it will look on your computer for email that is supposed to -be coming to you. - -A lot of people like to use POP for grabbing their email. MH can do -POP to grab your email. You will need to give inc a few command -line arguments. - -tempest% inc -host mail.pop.org -user username -norpop - -That tells inc to go to mail.pop.org to -download your email, and that your username on their system is -username. The option tells -inc to use plain POP3 for downloading your email. MH has -support for a few different dialects of POP. More than likely you -will never ever need to use them though. While you can do more -complex things with inc such as audit files and scan format files -this will get you going. - -The msgchk command is used to get information on -whether or not you have new email. msgchk takes the same - and options that -inc takes. - - - - -<command>show</>, <command>next</> and <command>prev</>—displaying and moving through email - -show is to show a letter in your current folder. -Like inc, show is a fairly straightforward -command. If you just type show and hit return -then it displays the current message. You can also give specific -message numbers to show: - -tempest% show 32 45 56 - -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior show -basically just does a more on the email message. - -next is used to move onto the next message and -prev will go to the previous message. Both commands have -an implied show command so that when you go to the next -message it automatically displays it. - - - - -<command>scan</>—shows you a scan of your messages - -scan will display a brief listing of the messages -in your current folder. This is an example of what the -scan command will give you. - - 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - -Like just about everything in MH this display is very configurable. -This is the typical default display. It gives you the message number, -the date on the email, the sender, the subject line, and a sentence -fragment from the very beginning of the email if it can fit it. The -+ means that message is the current message, so if you do -a show it will display that message. - -One useful option for scan is the -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -scan is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to inc it -you can do scan -file -/var/mail/username. This can be used with -any file that is in the mbox format. - - - - -<command>rmm</> and <command>rmf</>—remove the current message or folder - -rmm is used to remove a mail message. The default -is typically to not actually remove the message but to rename the -file to one that is ignored by the MH commands. You will need to -through periodically and physically delete the removed -messages. - -The rmf command is used to remove folders. This -doesn't just rename the files but actually removes the from the hard -drive so you should be careful when you use this command. - - - - -A typical session of reading with MH - -The first thing that you will want to do is inc -your new mail. So at a shell prompt just type in inc and -hit return. - -tempest% inc -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -This shows you the new email that has been added to your mailbox. So -the next thing to do is show the email and move around. - -tempest% show -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -tempest% rmm -tempest% next -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party). - - -The rmm removed the current message and the -next command moved me on to the next message. -Now if I wanted to look at ten most recent messages so I could read -one of them here is what I would do: - -tempest% scan last:10 - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest% - -Then if I wanted to read message number 27 I would do a -show 27 and it would be displayed. As you can probably -tell from this sample session MH is pretty easy to use and looking -through emails and displaying them is fairly intuitive and easy. - - - - - - -Folders and Mail Searching - -Anybody who gets lots of email definitely wants to be able to -prioritize, stamp, brief, de-brief, and number their emails in a -variety of different ways. MH can do this better than just about -anything. One thing that we haven't really talked about is the -concept of folders. You have undoubtedly come across the folders -concept using other email programs. MH has folders too. MH can even -do sub-folders of a folder. One thing you should keep in mind with MH -is that when you ran inc for the first time and it asked -you if it could create a Mail directory it began storing -everything in that directory. If you look at that directory you will -find a directory named inbox. The inbox -directory houses all of your incoming mail that hasn't been thrown -anywhere else. - -Whenever you create a new folder a new directory is going to be -created underneath your MH Mail directory, and messages -in that folder are going to be stored in that directory. When new -email comes in that new email is thrown into your inbox -directory with a file name that is equivalent to the message number. -So even if you didn't have any of the MH tools to read your email you -could still use standard UNIX commands to munge around in those -directories and just more your files. It's this simplicity that -really gives you a lot of power with what you can do with your -email. - -Just as you can use message lists like 23 16 42 -with most MH commands there is a folder option you can specify with -just about every MH command. If you do a scan +freebsd it -will scan your freebsd folder, and your current folder -will be changed to freebsd. If you do a show -+freebsd 23 16 42, show is going to switch to your -freebsd folder and display messages 23, 16 and 42. So -remember that - - - -<command>pick</>—search email that matches certain criteria - -pick is one of the more complex commands in the MH -system. So you might want to read the -pick1 man page for a -more thorough understanding. At its simplest level you can do -something like - -tempest% pick -search pci -15 -42 -55 -56 -57 - - -This will tell pick to look through every single line in -every message in your current folder and tell you which message -numbers it found the word pci in. You can then -show those messages and read them if you wish or -rmm them. You would have to specify something like -show 15 42 55-57 to display them though. A slightly more -useful thing to do is this: - -tempest% pick -search pci -seq pick -5 hits -tempest% show pick - -This will show you the same messages you just didn't have to work as -hard to do it. The option is really an -abbreviation of and pick is -just a sequence which contains the message numbers that matched. You -can use sequences with just about any MH command. So you could have -done an rmm pick and all those messages would be removed -instead. You sequence can be named anything. If you run pick again it -will overwrite the old sequence if you use the same name. - -Doing a pick -search can be a bit more time -consuming than just searching for message from someone, or to -someone. So pick allows you to use the following -predefined search criteria: - - - - - - -search based upon who the message is to - - - - - - -search based on who is in the cc list - - - - - - -search for who sent the message - - - - - - -search for emails with this subject - - - - - - -find emails with a matching dat - - - - - - -search for any other component in the header. (i.e. - - - - - - -This allows you to do things like - -tempest% pick -to freebsd-hackers@freebsd.org -seq hackers - -to get a list of all the email send to the FreeBSD hackers mailing -list. pick also allows you to group these criteria in -different ways using the following options: - - - -… … - - - -… &hellip - - - - … - - - - … - - - -These commands allow you to do things like - -tempest% pick -to freebsd-hackers -and -cc freebsd-hackers - -That will grab all the email in your inbox that was sent to -freebsd-hackers or cc'd to that list. The brace options allow you to -group search criteria together. This is sometimes very necessary as -in the following example - -tempest% pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci - - -Basically this says pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci. It should look through your -folder and find all messages sent to the freebsd-hackers list that -aren't cc'd to the freebsd-questions list that contain something on -pci in the subject line. Ordinarily you might have to worry about -something called operator precedence. Remember in math how you -evaluate from left to right and you do multiplication and division -first and addition and subtraction second? MH has the same type of -rules for pick. It's fairly complex so you might want to study -the man page. This document is just to help you get acquainted with -MH. - - - - -<command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance - -There are three programs which are primarily just for -manipulating your folders. The folder program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a folder +newfolder and -you will be switched into newfolder. From there on -out all your MH commands like comp, repl, -scan, and show will act on that -newfolder folder. - -Sometimes when you are reading and deleting messages you will -develop holes in your folders. If you do a scan -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a folder -pack this will renumber all your -messages so that there are no holes. It doesn't actually delete any -messages though. So you may need to periodically go through and -physically delete rmm'd messages. - -If you need statistics on your folders you can do a -folders or folder -all to list all -your folders, how many messages they have, what the current message -is in each one and so on. This line of stats it displays for all your -folders is the same one you get when you change to a folder with -folder +foldername. A folders command looks -like this: - - Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. - - - -The refile command is what you use to move messages -between folders. When you do something like refile 23 -+netfuture message number 23 is moved into the -netfuture folder. You could also do something like -refile 23 +netfuture/latest which would put message -number 23 in a subfolder called latest under the -netfuture folder. If you want to keep a message in the -current folder and link it you can do a refile -link 23 -+netfuture which would keep 23 in your current -inbox but also list in your netfuture -folder. You are probably beginning to realize some of the really -powerful things you can do with MH. - - - - - -Sending Mail - -Email is a two way street for most people so you want to be -able to send something back. The way MH handles sending mail can be a -bit difficult to follow at first, but it allows for incredible -flexibility. The first thing MH does is to copy a components file -into your outgoing email. A components file is basically a skeleton -email letter with stuff like the To: and Subject: headers already in -it. You are then sent into your editor where you fill in the header -information and then type the body of your message below the dashed -lines in the message. Then to the whatnow program. When -you are at the What now? prompt you can tell it to -send, list, edit, -edit, push, and quit. Most of -these commands are self-explanatory. So the message sending process -involves copying a component file, editing your email, and then -telling the whatnow program what to do with your -email. - - - -<command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone - -The comp program has a few useful command line -options. The most important one to know right now is the - option. When MH is installed the default -editor is usually a program called prompter which comes -with MH. It's not a very exciting editor and basically just gets the -job done. So when you go to compose a message to someone you might -want to use comp -editor /usr/bin/vi/ or comp --editor /usr/local/bin/pico/ instead. Once you have run -comp you are in your editor and you see -something that looks like this: - -To: -cc: -Subject: --------- - - - -You need to put the person you are sending the mail to after the -To: line. It works the same way for the other headers -also, so you would need to put your subject after the -Subject: line. Then you would just put the body of your -message after the dashed lines. It may seem a bit simplistic since a -lot of email programs have special requesters that ask you for this -information but there really isn't any point to that. Plus this -really gives you excellent flexibility. - -To:freebsd-rave@freebsd.org -cc: -Subject:And on the 8th day God created the FreeBSD core team --------- -Wow this is an amazing operating system. Thanks! - -You can now save this message and exit your editor. You will see the -What now? prompt and you can type in -send or s and hit -return. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example quit if you don't want to send the -message. - -The forw command is stunningly similar. The big -difference being that the message you are forwarding is automatically -included in the outgoing message. When you run forw it -will forward your current message. You can always tell it to forward -something else by doing something like forw 23 and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences forw -functions exactly the same as comp. You go through the -exact same message sending process. - -The repl command will reply to whatever your -current message is, unless you give it a different message to reply -to. repl will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -To: header already has the address of the recipient in -there. Also the Subject: line will already be filled in. -You then go about the normal message composition process and you are -done. One useful command line option to know here is the - option. You can use all, -to, cc, me after the - option to have repl automatically -add the various addresses to the cc list in the message. You have -probably noticed that the original message isn't included. This is -because most MH setups are configured to do this from the -start. - - - - -<filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</> - -The components file is usually in -/usr/local/lib/mh. You can copy that file into -your MH Mail directory and edit to contain what you want it to -contain. It is a fairly basic file. You have various email headers at -the top, a dashed line and then nothing. The -comp command just copies this -components file and then edits it. You can add any -kind of valid RFC822 header you want. For instance you could have -something like this in your components file: - -To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ -------- - - -MH would then copy this components file and throw you into your -editor. The components file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that components file. - -The replcomps file is a bit more complex. The default -replcomps looks like this: - -%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- - - - -It's in the same basic format as the components file but -it contains quite a few extra formatting codes. The -%(lit) command makes room for the address. The -%(formataddr is a function that returns a proper email -address. The next part is %< which means if and -the {reply-to} means the reply-to field in the original -message. So that might be translated this way: - -%<if {reply-to} the original message has a reply-to -then give that to formataddr, %? else {from} take the -from address, %? else {sender} take the sender address, %? -else {return-path} take the return-path from the original -message, %> endif. - - -As you can tell MH formatting can get rather involved. You can -probably decipher what most of the other functions and variables -mean. All of the information on writing these format strings is in the -MH-Format man page. The really nice thing is that once you have built -your customized replcomps file you won't need to touch it -again. No other email program really gives you the power and -flexibility that MH gives you. - - - - diff --git a/en_US.ISO_8859-1/articles/multi-os/Makefile b/en_US.ISO_8859-1/articles/multi-os/Makefile deleted file mode 100644 index 8a591510bb..0000000000 --- a/en_US.ISO_8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $ - -DOCS= multios.docb -INDEXLINK= multios.html - -.include "../../web.mk" - diff --git a/en_US.ISO_8859-1/articles/multi-os/article.sgml b/en_US.ISO_8859-1/articles/multi-os/article.sgml deleted file mode 100644 index e7b1d68d68..0000000000 --- a/en_US.ISO_8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,680 +0,0 @@ - - - - - - -Installing and Using FreeBSD With Other Operating Systems - - - -Jay -Richmond - -
-jayrich@in.net -
- - - - -6 August 1996 - -This document discusses how to make FreeBSD coexist -nicely with other popular operating systems such as Linux, MS-DOS, -OS/2, and Windows 95. Special thanks to: Annelise Anderson -andrsn@stanford.edu, Randall Hopper -rhh@ct.picker.com, and Jordan K. Hubbard -jkh@time.cdrom.com - - - - - -Overview - -Most people can't fit these operating systems together -comfortably without having a larger hard disk, so special -information on large EIDE drives is included. Because there are so -many combinations of possible operating systems and hard disk -configurations, the section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems. - -This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the \TOOLS directory or via -ftp) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence. - - - - -Overview of Boot Managers - -These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system. - - - - -Boot Easy - - -This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys. - - - - -OS/2 Boot Manager - - -This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 -(Linux). It will also boot FAT32 partitions. Partitions are -selected using arrow keys. The OS/2 Boot Manager is the only one to -use its own separate partition, unlike the others which use the -master boot record (MBR). Therefore, it must be installed below the -1024th cylinder to avoid booting problems. It can boot Linux using -LILO when it is part of the boot sector, not the MBR. Go to Linux HOWTOs -on the World Wide Web for more information on booting Linux with -OS/2's boot manager. - - - - -OS-BS - - This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -\TOOLS directory, and via ftp. - - - -LILO, or LInux LOader - - -This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file. - - - - - -About FAT32FAT32 is the replacement to -the FAT filesystem included in Microsoft's OEM SR2 Beta release, -which is expected to utilitized on computers pre-loaded with Windows -95 towards the end of 1996. It converts the normal FAT file system -and allows you to use smaller cluster sizes for larger hard drives. -FAT32 also modifies the traditional FAT boot sector and allocation -table, making it incompatible with some boot managers. - - - - -A Typical Installation - -Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them. - -Here's how I might do it using these hard disks: - - - -/dev/wd0 (first physical hard disk) - - - -/dev/wd1 (second hard disk) - - - - - -Both disks have 1416 cylinders. - - - -I boot from a MS-DOS or Windows 95 boot disk that -contains the FDISK.EXE utility and make a small 50 meg -primary partition (35-40 for Windows 95, plus a little breathing -room) on the first disk. Also create a larger partition on the -second hard disk for my Windows applications and data. - -I reboot and install Windows 95 (easier said than done) -on the C: partition. - -The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -). When I am partitioning out my hard disk with -Linux fdisk, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space). - -After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record). - -The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the /usr and / slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the /usr/src slice and swap -space. - -When viewed with the Windows 95 fdisk utility, my hard drives -should now look something like this: - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See ). - -Install FreeBSD. I make sure to boot with my first hard -disk set at NORMAL in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (MSD.EXE), -or check your BIOS) with the parameter hd0=1416,16,63 -where 1416 is the number of cylinders on my hard -disk, 16 is the number of heads per track, and -63 is the number of sectors per track on the -drive. - -When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it. - -When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD). - - - - - - -Special Considerations - -Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary partitiin on the first hard disk. OS/2 is the exception. It -can be installed on the first or second disk in a primary or extended -partition. If you are not sure, keep the beginning of the bootable -partitions below the 1024th cylinder. - -If you install Windows 95 on an existing BSD system, it will -destroy the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via ftp. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS. - -Please keep in mind that OS/2 can read FAT and HPFS partitions, -but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows -95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most file systems, but -currently cannot read HPFS partitions. Linux can read HPFS -partitions, but can't write to them. Recent versions of the Linux -kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT -is what gives Windows 95 long file names - it's pretty much the same -as FAT). Linux can read and write to most file systems. Got that? -I hope so. - - - - -Examples - -(section needs work, please send your example to -jayrich@in.net). - -FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see DOS on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like invalid system disk under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called > 1024 cylinder support or NORMAL/LBA -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the FBSDBOOT.EXE utility on the CD (It should find your -FreeBSD partition and boot it.) - -FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem. - -FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems. - -FreeBSD+Linux+Win95: (see ) - - - - -Other Sources of Help - -There are many Linux HOW-TOs that -deal with multiple operating systems on the same hard disk. - -The Linux+OS/2+DOS -Mini-HOWTO offers help on configuring the OS/2 boot -manager. The Linux-HOWTO -is also helpful. - -The NT Loader -Hacking Guide provides good information on multibooting -Windows NT, '95, and DOS with other operating systems. - -And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip, -http://www.cs.yorku.ca/People/frank/docs/. - -Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -file:/usr/src/sys/i386/boot/biosboot/README.386BSD. - - - - -Technical Details - -(Contributed by Randall Hopper, -rhh@ct.picker.com) - -This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading. - - - -Disk Primer - -Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It's not -particularly important to know what these terms relate to except to -know that, together, they identify where data is physically on your -disk. - -Your disk has a particular number of cylinders, number of -heads, and number of sectors per cylinder-head (a cylinder-head also -known nown as a track). Collectively this information defines the -"physical disk geometry" for your hard disk. There are typically 512 -bytes per sector, and 63 sectors per track, with the number of -cylinders and heads varying widely from disk to disk. Thus you can -figure the number of bytes of data that'll fit on your own disk by -calculating: (# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect) For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: (3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect) - -which is 1,624,670,208 bytes, or around 1.6 Gig. - -You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see ), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. MSD.EXE or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -translated geometry (virtual numbers from using LBA). -Stay tuned for what that means. - -One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1. - -For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for boot -sector or master boot record. Among the useful info -you'll find are Hale Landis's How It Works document -pack. See the section for a few pointers to -this pack. - -Ok, enough terminology. We're talking about booting -here. - - - - -The Booting Process - -On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 partitions, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -slices to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system. - -Each partition entry in the MBR has a Partition -ID, a Start Cylinder/Head/Sector, and an -End Cylinder/Head/Sector. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. lists a smattering of some common -Partition IDs. - -
-Partition IDs</> -<tgroup cols="2"> -<thead> -<row> -<entry>ID (hex)</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> -<row> -<entry>01</entry> -<entry>Primary DOS12 (12-bit FAT)</entry> -</row> - -<row> -<entry>04</entry> -<entry>Primary DOS16 (16-bit FAT)</entry> -</row> - -<row> -<entry>05</entry> -<entry>Extended DOS</entry> -</row> - -<row> -<entry>06</entry> -<entry>Primary big DOS (> 32MB)</entry> -</row> - -<row> -<entry>0A</entry> -<entry>OS/2</entry> -</row> - -<row> -<entry>83</entry> -<entry>Linux (EXT2FS)</entry> -</row> - -<row> -<entry>A5</entry> -<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Note that not all partitions are bootable (e.g. Extended DOS). -Some are—some aren't. What makes a partition bootable is the -configuration of the <firstterm>Partition Boot Sector</> that exists -at the beginning of each partition.</para> - -<para>When you configure your favorite boot manager, it looks up the entries -in the MBR partition tables of all your hard disks and lets you name the -entries in that list. Then when you boot, the boot manager is invoked by -special code in the Master Boot Sector of the first probed hard disk on -your system. It looks at the MBR partition table entry corresponding to -the partition choice you made, uses the Start Cylinder/Head/Sector -information for that partition, loads up the Partition Boot Sector for that -partition, and gives it control. That Boot Sector for the partition itself -contains enough information to start loading the operating system on that -partition.</para> - -<para>One thing we just brushed past that's important to know. All of your -hard disks have MBRs. However, the one that's important is the one on the -disk that's first probed by the BIOS. If you have only IDE hard disks, its -the first IDE disk (e.g. primary disk on first controller). Similarly for -SCSI only systems. If you have both IDE and SCSI hard disks though, the -IDE disk is typically probed first by the BIOS, so the first IDE disk is -the first probed disk. The boot manager you will install will be hooked into -the MBR on this first probed hard disk that we've just described.</para> - -</sect1> - -<sect1 id="limits"> -<title>Booting Limitations and Warnings - -Now the interesting stuff that you need to watch out for. - - -The dreaded 1024 cylinder limit and how BIOS LBA helps - -The first part of the booting process is all done through the -BIOS, (if that's a new term to you, the BIOS is a software chip on -your system motherboard which provides startup code for your -computer). As such, this first part of the process is subject to the -limitations of the BIOS interface. - -The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: - -1024 cylinders, max -256 heads , max -64 cylinders, max (actually 63, 0 isn't -available) - - - -Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can't boot off just anywhere on your hard disk. The boot code (the -boot manager and the OS loader hooked into all bootable partitions' -Boot Sectors) has to reside below cylinder 1024. In fact, if your -hard disk is typical and has 16 heads, this equates to: - -1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector - - - -which is around the often-mentioned 528MB limit. - -This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads). - -With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit. - -To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: - -(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) - - - -However, my BIOS LBA remaps this to: - -( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) - - - -giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA). - - - - -Boot Managers and Disk Allocation - -Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs. - -If you followed the discussion in -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically. - -That's the catch. Some operating systems (FreeBSD included) let -you start their partitions right after the Master Boot Sector at -Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give -FreeBSD's sysinstall a disk with an empty chunk up front or the whole -disk empty, that's where it'll start the FreeBSD partition by default -(at least it did when I fell into this trap). Then when you go to -install your boot manager, if it's one that occupies a few extra -sectors after the MBR, it'll overwrite the front of the first -partition's data. In the case of FreeBSD, this overwrites the -disk label, and renders your FreeBSD partition unbootable. - -The easy way to avoid this problem (and leave yourself the -flexibility to try different boot managers later) is just to always -leave the first full track on your disk unallocated when you -partition your disk. That is, leave the space from Cylinder 0, Head -0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and -start your first partition at Cylinder 0, Head 1, Sector 1. -For what it's worth, when you create a DOS partition at the -front of your disk, DOS leaves this space open by default (this is -why some boot managers assume it's free). So creating a DOS -partition up at the front of your disk avoids this problem -altogether. I like to do this myself, creating 1 Meg DOS partition -up front, because it also avoids my primary DOS drive letters -shifting later when I repartition. - -For reference, the following boot managers use the -Master Boot Sector to store their code and data: - - - -OS-BS 1.35 - - - -Boot Easy - - - -LILO - - - - - -These boot managers use a few additional sectors after the -Master Boot Sector: - - - -OS-BS 2.0 Beta 8 (sectors 2-5) - - - -OS/2's boot manager - - - - - - - - -What if your machine won't boot? - -At some point when installing boot managers, you might leave the -MBR in a state such that your machine won't boot. This is unlikely, -but possible when re-FDISKing underneath an already-installed boot -manager. - -If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: - -A:\> FDISK /MBR - - - -to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy. - - - - - diff --git a/en_US.ISO_8859-1/articles/new-users/Makefile b/en_US.ISO_8859-1/articles/new-users/Makefile deleted file mode 100644 index d8131087f4..0000000000 --- a/en_US.ISO_8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $ - -DOCS= newuser.docb -INDEXLINK= newuser.html - -.include "../../web.mk" - diff --git a/en_US.ISO_8859-1/articles/new-users/article.sgml b/en_US.ISO_8859-1/articles/new-users/article.sgml deleted file mode 100644 index 67568b5590..0000000000 --- a/en_US.ISO_8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,943 +0,0 @@ - - - - - - - - -For People New to Both FreeBSD and Unix - - - -Annelise -Anderson - -
andrsn@andrsn.stanford.edu
- - - - -August 15, 1997 - -Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -and Un*x—so it starts with basics. It -assumes you're using version 2.0.5 or later of FreeBSD as distributed -by Walnut Creek or FreeBSD.ORG, your system (for now) has a single -user (you)—and you're probably pretty good with DOS/Windows or -OS/2. - - - - - -Logging in and Getting Out - -Log in (when you see login:) as a user you created during -installation or as root. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. - -To log out (and get a new login: prompt) type - -# exit - -as often as necessary. Yes, press enter after -commands, and remember that Unix is -case-sensitive—exit, not -EXIT. - -To shut down the machine type: - -# /sbin/shutdown -h now - -Or to reboot type - -# /sbin/shutdown -r now - -or - -# /sbin/reboot - - - -You can also reboot with -CtrlAltDelete. -Give it a little time to do its work. This is equivalent to -/sbin/reboot in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you? - - - - -Adding A User with Root Privileges - -If you didn't create any users when you installed the system and -are thus logged in as root, you should probably create a user now with - -# adduser - -The first time you use adduser, it might ask for some defaults to save. You -might want to make the default shell csh instead of sh, if it suggests -sh as the default. Otherwise just press enter to accept each default. -These defaults are saved in /etc/adduser.conf, -an editable file. - -Suppose you create a user jack with -full name Jack Benimble. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type wheel - -Login group is ``jack''. Invite jack into other groups: wheel - -This will make it possible to log in as jack and -use the su command to become root. Then you won't -get scolded any more for logging in as root. - -You can quit adduser any time by typing -CtrlC, and at -the end you'll have a chance to approve your new user or simply type -n for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong. - -Once you've done this, use exit -to get back to a login prompt and log in as -jack. In general, it's a good idea to do as -much work as possible as an ordinary user who doesn't have the -power—and risk—of root. - -If you already created a user and you want the user to be able -to su to root, you can log in as root -and edit the file /etc/group, adding jack to the -first line (the group wheel). But first you need to practice -vi, the text editor--or use the simpler text -editor, ee, installed on recent version of -FreeBSD. - -To delete a user, use the rmuser command. - - - - -Looking Around - -Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD. - -Here are some commands and what they do: - -id - -Tells you who you are! - - - - -pwd - - -Shows you where you are—the current -working directory. - - - - -ls - - -Lists the files in the current directory. - - - - -ls - - -Lists the files in the current directory with a -* after executables, a / after -directories, and an @ after symbolic links. - - - - -ls - - -Lists the files in long format—size, -date, permissions. - - - - -ls - - -Lists hidden dot -files with the others. If you're root, thedot files -show up without the switch. - - - - -cd - - -Changes directories. cd -.. backs up one level; note the -space after cd. cd -/usr/local goes there. cd -~ goes to the home directory of the -person logged in—e.g., /usr/home/jack. -Try cd /cdrom, and then -ls, to find out if your CDROM is mounted and -working. - - - - -view filename - - -Lets you look at a file (named -filename without changing it. Try -view /etc/fstab. -:q to quit. - - - - -cat filename - - - -Displays filename on screen. If -it's too long and you can see only the end of it, press -ScrollLock and use the up-arrow to -move backward; you can use ScrollLock with man pages -too. Press ScrollLock again to quit scrolling. You -might want to try cat on some of the dot files in -your home directory—cat -.cshrc, cat -.login, cat -.profile. - - - - - -You'll notice aliases in .cshrc for some of the -ls commands (they're very convenient). -You can create other aliases by editing .cshrc. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -/etc/csh.cshrc. - - - - -Getting Help and Information - -Here are some useful sources of help. -Text stands for something of your choice -that you type in—usually a command or filename. - - -apropos text - - -Everything containing string text -in the whatis database. - - - -man text - - -The man page for text. The major -source of documentation for Un*x systems. man -ls will tell you all the ways to use -the ls command. Press Enter to -move through text, -Ctrlb to go -back a page, Ctrlf to -go forward, q or -Ctrlc to -quit. - - - -which text - - -Tells you where in the user's path the command -text is found. - - - -locate text - - -All the paths where the string text -is found. - - - -whatis text - - -Tells you what the command text -does and its man page. Typing whatis * will tell -you about all the binaries in the current directory. - - - -whereis text - - -Finds the file text, giving its full -path. - - - - -You might want to try using whatis on some -common useful commands like cat, -more, grep, -mv, find, -tar, chmod, -chown, date, and -script. more lets you read a -page at a time as it does in DOS, e.g., ls -l | -more or more -filename. The -* works as a wildcard—e.g., ls -w* will show you files beginning with -w. - -Are some of these not working very well? Both -locate and whatis -depend on a database that's rebuilt weekly. If your machine isn't -going to be left on over the weekend (and running FreeBSD), you might -want to run the commands for daily, weekly, and monthly maintenance -now and then. Run them as root and give each one time to finish -before you start the next one, for now. - -# /etc/daily -output omitted -# /etc/weekly -output omitted -# /etc/monthly -output omitted - - -If you get tired waiting, press -AltF2 to get -another virtual console, and log in again. -After all, it's a multi-user, multi-tasking system. Nevertheless -these commands will probably flash messages on your screen while -they're running; you can type clear at the prompt -to clear the screen. Once they've run, you might want to look at -/var/mail/root and -/var/log/messages. - -Basically running such commands is part of system -administration—and as a single user of a Unix system, you're -your own system administrator. Virtually everything you need to be -root to do is system administration. Such responsibilities aren't -covered very well even in those big fat books on Unix, which seem to -devote a lot of space to pulling down menus in windows managers. You -might want to get one of the two leading books on systems -administration, either Evi Nemeth et.al.'s UNIX System -Administration Handbook (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's Essential System -Administration (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth. - - - - -Editing Text - -To configure your system, you need to edit text files. Most of -them will be in the /etc directory; and you'll -need to su to root to be able to change them. You -can use the easy ee, but in the long run the -text editor vi is worth learning. There's an -excellent tutorial on vi in -/usr/src/contrib/nvi/docs/tutorial if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. - -Before you edit a -file, you should probably back it up. Suppose you want to edit -/etc/rc.conf. You could just use cd -/etc to get to the /etc directory and -do: - -# cp rc.conf rc.conf.orig - - -This would copy rc.conf to -rc.conf.orig, and you could later copy -rc.conf.orig to rc.conf to recover the original. But even -better would be moving (renaming) and then copying back: - -# mv rc.conf rc.conf.orig -# cp rc.conf.orig rc.conf - - -because the mv command preserves the original date -and owner of the file. You can now edit -rc.conf. If you want the original back, you'd -then mv rc.conf rc.conf.myedit -(assuming you want to preserve your edited version) and then - -# mv rc.conf.orig rc.conf - -to put things back the way they were. - -To edit a file, type - -# vi filename - -Move through the text with the arrow keys. Esc (the -escape key) puts vi in command mode. Here are some -commands: - -x - -delete letter the cursor is on - - - - -dd - - -delete the entire line (even if it wraps on the screen) - - - - -i - - -insert text at the cursor - - - - -a - - -insert text after the cursor - - - - -Once you type i or a, you can enter text. -Esc puts you back in command mode where you can type - -:w - -to write your changes to disk and continue editing - - - - -:wq - - -to write and quit - - - - -:q! - - -to quit without saving changes - - - - -/text - - -to move the cursor to text; -/Enter (the enter key) to find -the next instance of text. - - - - -G - - -to go to the end of the file - - - - -nG - - -to go to line n in -the file, where n is a number - - - - -CtrlL - - -to redraw the screen - - - - -Ctrlb and Ctrlf - - -go back -and forward a screen, as they -do with more and view. - - - - - - -Practice with vi in your home directory by creating -a new file with vi filename and adding -and deleting text, saving the file, and calling it up again. -vi delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -vi—it's more powerful than DOS EDIT—find out -about the :r command.) Use Esc one or -more times to be sure you're in command mode and proceed from there -when it gives you trouble, save often with :w, and -use :q! to get out and start over (from -your last :w) when you need to. - -Now you can cd to /etc, -su to root, use vi to edit the file -/etc/group, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press Esc, and use -:wq to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?) - - - - -Printing Files from DOS - -At this point you probably don't have the printer working, so here's a -way to create a file from a man page, move it to a floppy, and then -print it from DOS. Suppose you want to read carefully about changing -permissions on files (pretty important). You can use the command -man chmod to read about it. The command - -# man chmod | col -b > chmod.txt - -will remove formatting codes and send the man page to -the chmod.txt file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, su to -root, and type - -# /sbin/mount -t msdos /dev/fd0 /mnt - -to mount the floppy drive on /mnt. - -Now (you no longer need to be root, and you can type -exit to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: - -% cp chmod.txt /mnt - -and use ls /mnt to get a directory listing of -/mnt, which should show the file -chmod.txt. - -You might especially want to make a file from -/sbin/dmesg by typing - -% /sbin/dmesg > dmesg.txt - -and copying dmesg.txt to the floppy. -/sbin/dmesg is the boot log record, and it's -useful to understand it because it shows what FreeBSD found when it -booted up. If you ask questions on -freebsd-questions@FreeBSD.ORG or on a USENET -group—like FreeBSD isn't finding my tape drive, what do -I do?—people will want to know what dmesg -has to say. - -You can now dismount the floppy drive (as root) to get the disk -out with - -# /sbin/umount /mnt - -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a -minor change so the file has to be saved, and print as you normally -would from DOS or Windows. Hope it works! man pages come out best if -printed with the dos print command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.) - -Getting the printer printing from FreeBSD involves creating an -appropriate entry in /etc/printcap and creating -a matching spool directory in -/var/spool/output. If your printer is on -lpt0 (what dos calls LPT1), you may only -need to go to /var/spool/output and (as root) -create the directory lpd by typing: - -mkdir lpd, if it doesn't already -exist. -Then the printer should respond if it's turned on when the system is -booted, and lp or lpr should send a file to the printer. Whether or -not the file actually prints depends on configuring it, which is -covered in the FreeBSD -handbook. - - - - -Other Useful Commands - - - -df - -shows file space and mounted systems. - - - - -ps aux - - -shows processes running. ps ax is a narrower form. - - - - -rm filename - - -remove filename. - - - - -rm -R dir - - -removes a directory dir and all -subdirectories—careful! - - - - -ls -R - - -lists files in the current -directory and all subdirectories; -I used a variant, ls -AFR > where.txt, -to get a list of all -the files in / and (separately) -/usr before I found better -ways to find files. - - - - -passwd - - -to change user's password (or root's password) - - - - -man hier - - -man page on the Unix file system - - - - - -Use find to locate filename in /usr -or any of its subdirectories with - -% find /usr -name "filename" - -You can use * as a wildcard in -"filename" (which should be in -quotes). If you tell find to search in / -instead of /usr it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition. - -An excellent book that explains Unix commands and utilities is -Abrahams & Larson, Unix for the Impatient -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the Unix Reference -Desk. - - - - -Next Steps - -You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and FreeBSD's -web site. A wide variety of packages and ports are on the -Walnut Creek CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with pkg_add -/cdrom/packages/All/packagename, -where packagename is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in cdrom/packages/index, -cdrom/packages/index.txt, and -cdrom/ports/index, with fuller descriptions in -/cdrom/ports/*/*/pkg/DESCR, where the -*s represent subdirectories of kinds of programs -and program names respectively. - -If you find the handbook too sophisticated (what with -lndir and all) on installing ports from the cdrom, -here's what usually works: - -Find the port you want, say kermit. There will be -a directory for it on the cdrom. Copy the subdirectory to -/usr/local (a good place for software you add -that should be available to all users) with: - -# cp -R /cdrom/ports/comm/kermit /usr/local - - -This should result in a /usr/local/kermit -subdirectory that has all the files that the -kermit subdirectory on the CDROM has. - -Next, create the directory /usr/ports/distfiles -if it doesn't already exist using mkdir. Now check -check /cdrom/ports/distfiles for a -file with a name that indicates it's the port you want. Copy that -file to /usr/ports/distfiles; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of kermit, there is no -distfile. - -Then cd to the subdirectory of -/usr/local/kermit that has the file -Makefile. Type - -# make all install - - - -During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -/usr/ports/distfiles. If you don't have your -network running yet and there was no file for the port in -/cdrom/ports/distfiles, you will have to get -the distfile using another machine and copy it to -/usr/ports/distfiles from a floppy or your dos -partition. Read Makefile (with cat or -more or view) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into /usr/ports/distfiles you'll have to rename -it (with the mv command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -/usr/local/kermit, find the directory with -Makefile, and type make all install. - -The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message can't find unzip or whatever, you -might need to install the package or port for unzip before you -continue. - -Once it's installed type rehash to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of path not found messages when you use -whereis or which, you might want to make additions to the -list of directories in the path statement in -.cshrc in your home directory. The path -statement in Unix does the same kind of work it does in DOS, except -the current directory is not (by default) in the path for security -reasons; if the command you want is in the directory you're in, you -need to type ./ before the command to make it -work; no space after the slash.) - -You might want to get the most recent version of Netscape from -their ftp site. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use gunzip -filename and tar xvf -filename on it, move the binary to -/usr/local/bin or some other place binaries are -kept, rehash, and then put the following lines in -.cshrc in each user's home directory or (easier) -in /etc/csh.cshrc, the system-wide csh start-up -file: - -setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls - -This assumes that the file XKeysymDB and the directory -nls are in /usr/X11R6/lib/X11; if -they're not, find them and put them there. - -If you originally got Netscape as a port using the CDROM (or -ftp), don't replace /usr/local/bin/netscape with -the new netscape binary; this is just a shell script that sets up the -environmental variables for you. Instead rename the new binary to -netscape.bin and replace the old binary, which -is /usr/local/lib/netscape/netscape.bin. - - - - - -Your Working Environment - -Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention. - -Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing echo $SHELL. - -The csh shell is okay, but tcsh does everything csh does and more. It -It allows you to recall commands with the arrow keys and edit them. -It has tab-key completion -of filenames (csh uses the escape key), and it lets you switch to the -directory you were last in with cd -. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier. - -Here are the three steps for installing a new shell: - - 1. Install the shell as a port or a package, just as you -would any other port or package. Use rehash and -which tcsh (assuming you're installing tcsh) to -make sure it got installed. - - 2. As root, edit /etc/shells, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.) - - 3. Use the chsh command to change your shell to -tcsh permanently, or type tcsh at the prompt to -change your shell without logging in again. - -Note: It can be dangerous to change root's shell -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use su -m -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -.tcshrc file as an alias with alias su su -m. - -When tcsh starts up, it will read the -/etc/csh.cshrc and /etc/csh.login -files, as does csh. It will also read the -.login file in your home directory and the -.cshrc -file as well, unless you provide a .tcshrc -file. This you can do by simply copying .cshrc -to .tcshrc. - -Now that you've installed tcsh, you can adjust your prompt. You can -find the details in the manual page for tcsh, but here is a line to -put in your .tcshrc that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a > if you're an ordinary user and -a # if you're root, but tsch will do that in any -case: - - set prompt = "%h %t %~ %# " - -This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. - -You can get a listing of other environmental variables that -have been set by typing env at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -setenv TERM vt100. - - - - -Other - -As root, you can dismount the CDROM with /sbin/umount -/cdrom, take it out of the drive, insert another one, and mount it -with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming -cd0a is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -/sbin/mount /cdrom. - -Using the live file system—the second of FreeBSD's CDROM -disks—is useful if you've got limited space. What is on the -live file system varies from release to release. You might try -playing games from the cdrom. This -involves using lndir, which gets installed with the X -Window System, to tell the program(s) where to find the necessary -files, because they're in the /cdrom file system -instead of in /usr and its subdirectories, which -is where they're expected to be. Read man lndir. - - - - -Comments Welcome - -If you use this guide I'd be interested in knowing where it was -unclear and what was left out that you think should be included, and -if it was helpful. My thanks to Eugene W. Stark, professor of -computer science at SUNY-Stony Brook, and John Fieber for helpful -comments. - -Annelise Anderson, andrsn@andrsn.stanford.edu - - - diff --git a/en_US.ISO_8859-1/articles/programming-tools/Makefile b/en_US.ISO_8859-1/articles/programming-tools/Makefile deleted file mode 100644 index 72c7507f01..0000000000 --- a/en_US.ISO_8859-1/articles/programming-tools/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $ - -DOCS= devel.docb -INDEXLINK= devel.html - -.include "../../web.mk" - diff --git a/en_US.ISO_8859-1/articles/programming-tools/article.sgml b/en_US.ISO_8859-1/articles/programming-tools/article.sgml deleted file mode 100644 index addd185ee8..0000000000 --- a/en_US.ISO_8859-1/articles/programming-tools/article.sgml +++ /dev/null @@ -1,1835 +0,0 @@ - - - - - - - -A User's Guide to FreeBSD Programming Tools - - - -James -Raynard - -
-jraynard@freebsd.org -
- - - -August 17, 1997 - - -1997 -James Raynard - - -This document is an introduction to using some of the programming -tools supplied with FreeBSD, although much of it will be applicable to -many other versions of Unix. It does not attempt to describe -coding in any detail. Most of the document assumes little or no -previous programming knowledge, although it is hoped that most -programmers will find something of value in it - - - - -Introduction<anchor id=foo> - -FreeBSD offers an excellent development environment. Compilers -for C, C++, and Fortran and an assembler come with the basic system, -not to mention a Perl interpreter and classic Unix tools such as -sed and awk. If that is not enough, there are -many more compilers and interpreters in the Ports collection. FreeBSD -is very compatible with standards such as POSIX and -ANSI C, as well with its own BSD heritage, so it is -possible to write applications that will compile and run with little -or no modification on a wide range of platforms. - -However, all this power can be rather overwhelming at first if -you've never written programs on a Unix platform before. This -document aims to help you get up and running, without getting too -deeply into more advanced topics. The intention is that this document -should give you enough of the basics to be able to make some sense of -the documentation. - -Most of the document requires little or no knowledge of -programming, although it does assume a basic competence with using -Unix and a willingness to learn! - - - - -Introduction to Programming - -A program is a set of instructions that tell the computer to do -various things; sometimes the instruction it has to perform depends -on what happened when it performed a previous instruction. This -section gives an overview of the two main ways in which you can give -these instructions, or commands as they are usually -called. One way uses an interpreter, the other a -compiler. As human languages are too difficult for a -computer to understand in an unambiguous way, commands are usually -written in one or other languages specially designed for the -purpose. - - - - -Interpreters - -With an interpreter, the language comes as an environment, where you -type in commands at a prompt and the environment executes them for -you. For more complicated programs, you can type the commands into a -file and get the interpreter to load the file and execute the commands -in it. If anything goes wrong, many interpreters will drop you into a -debugger to help you track down the problem. - -The advantage of this is that you can see the results of your -commands immediately, and mistakes can be corrected readily. The -biggest disadvantage comes when you want to share your programs with -someone. They must have the same interpreter, or you must have some -way of giving it to them, and they need to understand how to use it. -Also users may not appreciate being thrown into a debugger if they -press the wrong key! From a performance point of view, interpreters -can use up a lot of memory, and generally do not generate code as -efficiently as compilers. - -In my opinion, interpreted languages are the best way to start -if you have not done any programming before. This kind of environment -is typically found with languages like Lisp, Smalltalk, Perl and -Basic. It could also be argued that the Unix shell (sh, -csh) is itself an interpreter, and many people do in fact -write shell scripts to help with various -housekeeping tasks on their machine. Indeed, part of the -original Unix philosophy was to provide lots of small utility -programs that could be linked together in shell scripts to perform -useful tasks. - - - - -Interpreters available with FreeBSD - -Here is a list of interpreters that are available as FreeBSD -packages, with a brief discussion of some of the more popular -interpreted languages. - -To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -$ pkg_add package name - - -as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work! - - - -BASIC - -Short for Beginner's All-purpose Symbolic Instruction -Code. Developed in the 1950s for teaching University students to -program and provided with every self-respecting personal computer in -the 1980s, BASIC has been the first programming language -for many programmers. It's also the foundation for Visual -Basic. - -The Bywater -Basic Interpreter and the Phil -Cockroft's Basic Interpreter (formerly Rabbit Basic) are -available as FreeBSD FreeBSD -packages - - - -Lisp -A language that was developed in the late 1950s as an alternative to -the number-crunching languages that were popular at the time. -Instead of being based on numbers, Lisp is based on lists; in fact -the name is short for List Processing. Very popular in AI -(Artificial Intelligence) circles. - -Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. - -FreeBSD has GNU -Common Lisp available as a package. - - - - -Perl -Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing CGI -scripts. - -Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer Perl -Version 5 is available as a package. - - - - -Scheme -A dialect of Lisp that is rather more compact and -cleaner than Common Lisp. Popular in Universities as it is simple -enough to teach to undergraduates as a first language, while it has a -high enough level of abstraction to be used in research work. - -FreeBSD has packages of the -Elk Scheme Interpreter, the -MIT Scheme Interpreter and the -SCM Scheme Interpreter. - - - - -Icon -The Icon Programming Language. - - - -Logo -Brian Harvey's LOGO Interpreter. - - - -Python -The Python Object-Oriented Programming Language - - - - - - - - - -Compilers - -Compilers are rather different. First of all, you write your -code in a file (or files) using an editor. You then run the compiler -and see if it accepts your program. If it did not compile, grit your -teeth and go back to the editor; if it did compile and gave you a -program, you can run it either at a shell command prompt or in a -debugger to see if it works properly.If you run it in -the shell, you may get a core dump. - -Obviously, this is not quite as direct as using an interpreter. -However it allows you to do a lot of things which are very difficult -or even impossible with an interpreter, such as writing code which -interacts closely with the operating system—or even writing -your own operating system! It's also useful if you need to write very -efficient code, as the compiler can take its time and optimise the -code, which would not be acceptable in an interpreter. And -distributing a program written for a compiler is usually more -straightforward than one written for an interpreter—you can just -give them a copy of the executable, assuming they have the same -operating system as you. - -Compiled languages include Pascal, C and C++. C and C++ are rather -unforgiving languages, and best suited to more experienced -programmers; Pascal, on the other hand, was designed as an educational -language, and is quite a good language to start with. Unfortunately, -FreeBSD doesn't have any Pascal support, except for a Pascal-to-C -converter in the ports. - -As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (IDEs -for short). FreeBSD does not have an IDE as such; however -it is possible to use Emacs for this purpose. This is discussed in -. - - - - - -Compiling with <command>cc</command> - -This section deals only with the GNU compiler for C and C++, -since that comes with the base FreeBSD system. It can be invoked by -either cc or gcc. The details of producing a -program with an interpreter vary considerably between interpreters, -and are usually well covered in the documentation and on-line help -for the interpreter. - -Once you've written your masterpiece, the next step is to convert it -into something that will (hopefully!) run on FreeBSD. This usually -involves several steps, each of which is done by a separate -program. - - -Pre-process your source code to remove comments and do other -tricks like expanding macros in C. - - -Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! - - -Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.To be strictly -accurate, cc converts the source code into its own, -machine-independent p-code instead of assembly language -at this stage. - -Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here. - -Check that you have used things like functions and global -variables in a consistent way. For example, if you have called a -non-existent function, it will complain. - -If you are trying to produce an executable from several -source code files, work out how to fit them all together. - -Work out how to produce something that the system's run-time -loader will be able to load into memory and run. - -Finally, write the executable on the file -system. - - - -The word compiling is often used to refer to just -steps 1 to 4—the others are referred to as -linking. Sometimes step 1 is referred to as -pre-processing and steps 3-4 as -assembling. - -Fortunately, almost all this detail is hidden from you, as -cc is a front end that manages calling all these programs -with the right arguments for you; simply typing -$ cc foobar.c - -will cause foobar.c to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -$ cc foo.c bar.c - - -Note that the syntax checking is just that—checking the -syntax. It will not check for any logical mistakes you may have made, -like putting the program into an infinite loop, or using a bubble -sort when you meant to use a binary sort.In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't. - -There are lots and lots of options for cc, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them. - - - - -The output name of the file. If you do not use this -option, cc will produce an executable called -a.out.The reasons for this are buried in -the mists of history. - - -$ cc foobar.c executable is a.out -$ cc -o foobar foobar.c executable is foobar - - - - - -Just compile the file, do not link it. Useful for toy -programs where you just want to check the syntax, or if you are using -a Makefile. - - -$ cc -c foobar.c - - -This will produce an object file (not an -executable) called foobar.o. This can be linked -together with other object files into an executable. - - - - - - -Create a debug version of the executable. This makes -the compiler put information into the executable about which line of -which source file corresponds to which function call. A debugger can -use this information to show the source code as you step through the -program, which is very useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with while you are -developing a program and then compile a release -version without when you're satisfied it -works properly. - - -$ cc -g foobar.c - - -This will produce a debug version of the -program.Note, we didn't use the -flag to specify the executable name, so we will get an executable -called a.out. Producing a debug version called -foobar is left as an exercise for the -reader! - - - - - - -Create an optimised version of the executable. The -compiler performs various clever tricks to try and produce an -executable that runs faster than normal. You can add a number after -the to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of cc that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the - option in some circumstances. - -Optimisation is usually only turned on when compiling a release -version. - - -$ cc -O -o foobar foobar.c - - -This will produce an optimised version of -foobar. - - - - - -The following three flags will force cc to -check that your code complies to the relevant international standard, -often referred to as the ANSI standard, though -strictly speaking it is an ISO standard. - - - - - -Enable all the warnings which the authors of -cc believe are worthwhile. Despite the name, it -will not enable all the warnings cc is capable -of. - - - - - - -Turn off most, but not all, of the non-ANSI C -features provided by cc. Despite the name, it does -not guarantee strictly that your code will comply to the -standard. - - - - - - - -Turn off all -cc's non-ANSI C features. - - - - - -Without these flags, cc will allow you to -use some of its non-standard extensions to the standard. Some of -these are very useful, but will not work with other compilers—in -fact, one of the main aims of the standard is to allow people to -write code that will work with any compiler on any system. This is -known as portable code. - -Generally, you should try to make your code as portable as -possible, as otherwise you may have to completely re-write the -program later to get it to work somewhere else—and who knows -what you may be using in a few years time? - - -$ cc -Wall -ansi -pedantic -o foobar foobar.c - - -This will produce an executable foobar -after checking foobar.c for standard -compliance. - - - - - -Specify a function library to be used during when -linking. - -The most common example of this is when compiling a program that -uses some of the mathematical functions in C. Unlike most other -platforms, these are in a separate library from the standard C one -and you have to tell the compiler to add it. - -The rule is that if the library is called -libsomething.a, you -give cc the argument -. For example, -the math library is libm.a, so you give -cc the argument . A common -gotcha with the math library is that it has to be the -last library on the command line. - - -$ cc -o foobar foobar.c -lm - - -This will link the math library functions into -foobar. - -If you are compiling C++ code, you need to add -, or if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run c++ -instead of cc, which does this for you. -c++ can also be invoked as g++ -on FreeBSD. - - -$ cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier -$ cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later -$ c++ -o foobar foobar.cc - - -Each of these will both produce an executable -foobar from the C++ source file -foobar.cc. Note that, on Unix systems, C++ -source files traditionally end in .C, -.cxx or .cc, rather than -the MS-DOS style .cpp -(which was already used for something else). gcc -used to rely on this to work out what kind of compiler to use on the -source file; however, this restriction no longer applies, so you may -now call your C++ files .cpp with -impunity! - - - - - - -Common <command>cc</command> Queries and Problems - -Q. I am trying to write a program which uses the -sin() function and I get an error like this. -What does it mean? - -/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - - - -A. When using mathematical functions like -sin(), you have to tell cc to -link in the math library, like so: - -$ cc -o foobar foobar.c -lm - - -Q. All right, I wrote this simple program to practice using -. All it does is raise 2.1 to the power of 6. - -#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - -and I compiled it as: - -$ cc temp.c -lm - -like you said I should, but I get this when I run it: - -$ ./a.out -2.1 ^ 6 = 1023.000000 - - - -This is not the right answer! What is -going on? - -A. When the compiler sees you call a function, it checks if it -has already seen a prototype for it. If it has not, it assumes the -function returns an int, which is -definitely not what you want here. - -Q. So how do I fix this? - -A. The prototypes for the mathematical functions are in -math.h. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! - -#include <math.h> -#include <stdio.h> - -int main() { -... - - - -After recompiling it as you did before, run it: - -$ ./a.out -2.1 ^ 6 = 85.766121 - - - -If you are using any of the mathematical functions, -always include math.h and -remember to link in the math library. - -Q. I compiled a file called foobar.c and I -cannot find an executable called foobar. Where's -it gone? - -A. Remember, cc will call the executable -a.out unless you tell it differently. Use the - option: - -$ cc -o foobar foobar.c - - - -Q. OK, I have an executable called foobar, -I can see it when I run ls, but when I type in -foobar at the command prompt it tells me there is -no such file. Why can it not find it? - -A. Unlike MS-DOS, Unix does not look in the -current directory when it is trying to find out which executable you -want it to run, unless you tell it to. Either type -./foobar, which means run the file called -foobar in the current directory, or -change your PATH -environment variable so that it looks something like - -bin:/usr/bin:/usr/local/bin:. - -The dot at the end means look in the current directory if it is not in -any of the others. - -Q. I called my executable test, but -nothing happens when I run it. What is going on? - -A. Most Unix systems have a program called -test in /usr/bin and the -shell is picking that one up before it gets to checking the current -directory. Either type: - -$ ./test - -or choose a better name for your program! - -Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about core -dumped. What does that mean? - -A. The name core dump dates back to the -very early days of Unix, when the machines used core memory for -storing data. Basically, if the program failed under certain -conditions, the system would write the contents of core memory to -disk in a file called core, which the programmer -could then pore over to find out what went wrong. - -Q. Fascinating stuff, but what I am supposed to do now? - -A. Use gdb to analyse the core (see ). - -Q. When my program dumped core, it said something about a -segmentation fault. What's that? - -A. This basically means that your program tried to perform some sort -of illegal operation on memory; Unix is designed to protect the -operating system and other programs from rogue programs. - -Common causes for this are: - -Trying to write to a NULL pointer, eg -char *foo = NULL; -strcpy(foo, "bang!"); - - -Using a pointer that hasn't been initialised, eg -char *foo; -strcpy(foo, "bang!"); -The pointer will have some random value that, with luck, -will point into an area of memory that isn't available to -your program and the kernel will kill your program before -it can do any damage. If you're unlucky, it'll point -somewhere inside your own program and corrupt one of your -data structures, causing the program to fail -mysteriously. - -Trying to access past the end of an array, eg -int bar[20]; -bar[27] = 6; - - Trying to store something in read-only memory, eg -char *foo = "My string"; -strcpy(foo, "bang!"); -Unix compilers often put string literals like -"My string" into -read-only areas of memory. - -Doing naughty things with -malloc() and free(), eg -char bar[80]; -free(bar); -or -char *foo = malloc(27); -free(foo); -free(foo); - - - - -Making one of these mistakes will not always lead to an -error, but they are always bad practice. Some systems and -compilers are more tolerant than others, which is why programs -that ran well on one system can crash when you try them on an -another. - -Q. Sometimes when I get a core dump it says bus -error. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true? - -A. No, fortunately not (unless of course you really do have a hardware -problem…). This is usually another way of saying that you -accessed memory in a way you shouldn't have. - -Q. This dumping core business sounds as though it could be quite -useful, if I can make it happen when I want to. Can I do this, or -do I have to wait until there's an error? - -A. Yes, just go to another console or xterm, do -$ ps -to find out the process ID of your program, and do -$ kill -ABRT pid -where pid is the -process ID you looked up. - -This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -SIGABRT, there are several other signals which have -a similar effect. - - - - - - -Make - - -What is <command>make</command>? - -When you're working on a simple program with only one or two source -files, typing in -$ cc file1.c file2.c -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too. - -One way to get around this is to use object files and only recompile -the source file if the source code has changed. So we could have -something like: -$ cc file1.o file2.o … file37.c &hellip -if we'd changed file37.c, but not any of the -others, since the last time we compiled. This may speed up the -compilation quite a bit, but doesn't solve the typing -problem. - -Or we could write a shell script to solve the typing problem, but it -would have to re-compile everything, making it very inefficient on a -large project. - -What happens if we have hundreds of source files lying about? What if -we're working in a team with other people who forget to tell us when -they've changed one of their source files that we use? - -Perhaps we could put the two solutions together and write something -like a shell script that would contain some kind of magic rule saying -when a source file needs compiling. Now all we need now is a program -that can understand these rules, as it's a bit too complicated for the -shell. - -This program is called make. It reads in a -file, called a makefile, that tells it how -different files depend on each other, and works out which files need -to be re-compiled and which ones don't. For example, a rule could say -something like if fromboz.o is older than -fromboz.c, that means someone must have changed -fromboz.c, so it needs to be -re-compiled. The makefile also has rules telling make -how to re-compile the source file, making it a -much more powerful tool. - -Makefiles are typically kept in the same directory as the -source they apply to, and can be called -makefile, Makefile or -MAKEFILE. Most programmers use the name -Makefile, as this puts it near the top of a -directory listing, where it can easily be seen.They -don't use the MAKEFILE form as block capitals -are often used for documentation files like -README. - - - - -Example of using <command>make</command> - -Here's a very simple make file: -foo: foo.c - cc -o foo foo.c -It consists of two lines, a dependency line and a creation line. - -The dependency line here consists of the name of the program -(known as the target), followed by a colon, -then whitespace, then the name of the source file. When -make reads this line, it looks to see if -foo exists; if it exists, it compares the time -foo was last modified to the time -foo.c was last modified. If -foo does not exist, or is older than -foo.c, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when foo.c needs to be re-compiled. - -The creation line starts with a tab (press the -tab key) and then the command you would type to -create foo if you were doing it at a command -prompt. If foo is out of date, or does not -exist, make then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile foo.c. - -So, when you type make, it will make -sure that foo is up to date with respect to your -latest changes to foo.c. This principle can be -extended to Makefiles with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing make -world in the appropriate directory! - -Another useful property of makefiles is that the targets don't have -to be programs. For instance, we could have a make file that looks -like this: -foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - -We can tell make which target we want to make by typing: -$ make target -make will then only look at that target and ignore any -others. For example, if we type make foo with the -makefile above, make will ignore the install target. - -If we just type make on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed make here, it will -just go to the foo target, re-compile -foo if necessary, and then stop without going on -to the install target. - -Notice that the install target doesn't -actually depend on anything! This means that the command on the -following line is always executed when we try to make that target by -typing make install. In this case, it will -copy foo into the user's home directory. This is -often used by application makefiles, so that the application can be -installed in the correct directory when it has been correctly -compiled. - -This is a slightly confusing subject to try and explain. If you -don't quite understand how make works, the best -thing to do is to write a simple program like hello -world and a make file like the one above and experiment. Then -progress to using more than one source file, or having the source -file include a header file. The touch command is -very useful here—it changes the date on a file without you -having to edit it. - - - - -FreeBSD Makefiles - -Makefiles can be rather complicated to write. Fortunately, -BSD-based systems like FreeBSD come with some very powerful ones as -part of the system. One very good example of this is the FreeBSD -ports system. Here's the essential part of a typical ports -Makefile: -MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - -Now, if we go to the directory for this port and type -make, the following happens: - - -A check is made to see if the source code for this port is -already on the system. - -If it isn't, an FTP connection to the URL in -MASTER_SITES is set up to download the -source. - -The checksum for the source is calculated and compared it with -one for a known, good, copy of the source. This is to make sure that -the source was not corrupted while in transit. - -Any changes required to make the source work on FreeBSD are -applied—this is known as patching. - -Any special configuration needed for the source is done. -(Many Unix program distributions try to work out which version of -Unix they are being compiled on and which optional Unix features are -present—this is where they are given the information in the -FreeBSD ports scenario). - -The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -make—the program's own make file has the -necessary information to build the program. - -We now have a compiled version of the program. If we -wish, we can test it now; when we feel confident about the program, -we can type make install. This will cause the -program and any supporting files it needs to be copied into the -correct location; an entry is also made into a package -database, so that the port can easily be uninstalled later -if we change our mind about it. - - - -Now I think you'll agree that's rather impressive for a four -line script! - -The secret lies in the last line, which tells -make to look in the system makefile called -bsd.port.mk. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells make to do all the -things above (plus a couple of other things I didn't mention, -including handling any errors that may occur) and anyone can get -access to that just by putting a single line in their own make -file! - -If you want to have a look at these system makefiles, they're -in /usr/share/mk, but it's probably best to wait -until you've had a bit of practice with makefiles, as they are very -complicated (and if you do look at them, make sure you have a flask -of strong coffee handy!) - - - - -More advanced uses of <command>make</command> - -Make is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of make, and they all -differ considerably. The best way to learn what they can do is -probably to read the documentation—hopefully this introduction will -have given you a base from which you can do this. - -The version of make that comes with FreeBSD is the Berkeley -make; there is a tutorial for it in -/usr/share/doc/psd/12.make. To view it, do -$ zmore paper.ascii.gz -in that directory. - -Many applications in the ports use GNU -make, which has a very good set of info -pages. If you have installed any of these ports, GNU -make will automatically have been installed as -gmake. It's also available as a port and package -in its own right. - -To view the info pages for GNU make, -you will have to edit the dir file in the -/usr/local/info directory to add an entry for -it. This involves adding a line like - * Make: (make). The GNU Make utility. -to the file. Once you have done this, you can type -info and then select -make from the menu (or in -Emacs, do C-h -i). - - - - - -Debugging - - -The Debugger - -The debugger that comes with FreeBSD is called -gdb (GNU -debugger). You start it up by typing -$ gdb progname -although most people prefer to run it inside -Emacs. You can do this by: -M-x gdb RET progname RET - -Using a debugger allows you to run the program under more -controlled circumstances. Typically, you can step through the program -a line at a time, inspect the value of variables, change them, tell -the debugger to run up to a certain point and then stop, and so on. -You can even attach to a program that's already running, or load a -core file to investigate why the program crashed. It's even possible -to debug the kernel, though that's a little trickier than the user -applications we'll be discussing in this section. - -gdb has quite good on-line help, as well as -a set of info pages, so this section will concentrate on a few of the -basic commands. - -Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it xxgdb -in the ports collection. - -This section is intended to be an introduction to using -gdb and does not cover specialised topics such as -debugging the kernel. - - - - -Running a program in the debugger - -You'll need to have compiled the program with the - option to get the most out of using -gdb. It will work without, but you'll only see the -name of the function you're in, instead of the source code. If you -see a line like: -… (no debugging symbols found) …when -gdb starts up, you'll know that the program wasn't -compiled with the option. - -At the gdb prompt, type break -main. This will tell the debugger to skip over the -preliminary set-up code in the program and start at the beginning of -your code. Now type run to start the -program—it will start at the beginning of the set-up code and -then get stopped by the debugger when it calls -main(). (If you've ever wondered where -main() gets called from, now you know!). - -You can now step through the program, a line at a time, by -pressing n. If you get to a function call, you can -step into it by pressing s. Once you're in a -function call, you can return from stepping into a function call by -pressing f. You can also use up and -down to take a quick look at the caller. - -Here's a simple example of how to spot a mistake in a program -with gdb. This is our program (with a deliberate -mistake): -#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - - -This program sets i to be 5 -and passes it to a function bazz() which prints -out the number we gave it. - -When we compile and run the program we get -$ cc -g -o temp temp.c -$ ./temp -This is my program -anint = 4231 - -That wasn't what we expected! Time to see what's going -on!$ gdb temp -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) break main Skip the set-up code -Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main() -(gdb) run Run as far as main() -Starting program: /home/james/tmp/temp Program starts running - -Breakpoint 1, main () at temp.c:9 gdb stops at main() -(gdb) n Go to next line -This is my program Program prints out -(gdb) s step into bazz() -bazz (anint=4231) at temp.c:17 gdb displays stack frame -(gdb) - - -Hang on a minute! How did anint get to be -4231? Didn't we set it to be 5 -in main()? Let's move up to -main() and have a look. - -(gdb) up Move up call stack -#1 0x1625 in main () at temp.c:11 gdb displays stack frame -(gdb) p i Show us the value of i -$1 = 4231 gdb displays 4231 -Oh dear! Looking at the code, we forgot to initialise -i. We meant to put -… -main() { - int i; - - i = 5; - printf("This is my program\n"); -&hellip -but we left the i=5; line out. As we didn't -initialise i, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be 4231. - -gdb displays the stack frame -every time we go into or out of a function, even if we're using -up and down to move around the -call stack. This shows the name of the function and the values of -its arguments, which helps us keep track of where we are and what's -going on. (The stack is a storage area where the program stores -information about the arguments passed to functions and where to go -when it returns from a function call). - - - - -Examining a core file - -A core file is basically a file which contains the complete -state of the process when it crashed. In the good old -days, programmers had to print out hex listings of core files -and sweat over machine code manuals, but now life is a bit easier. -Incidentally, under FreeBSD and other 4.4BSD systems, a core file is -called progname.core instead of just -core, to make it clearer which program a core -file belongs to. - -To examine a core file, start up gdb in the -usual way. Instead of typing break or -run, type -(gdb) core progname.core -If you're not in the same directory as the core file, you'll have to -do dir /path/to/core/file first. - -You should see something like this: -$ gdb a.out -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) core a.out.core -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - -In this case, the program was called -a.out, so the core file is called -a.out.core. We can see that the program crashed -due to trying to access an area in memory that was not available to -it in a function called bazz. - -Sometimes it's useful to be able to see how a function was -called, as the problem could have occurred a long way up the call -stack in a complex program. The bt command causes -gdb to print out a back-trace of the call -stack: -(gdb) bt -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)The end() function is called when -a program crashes; in this case, the bazz() -function was called from main(). - - - - -Attaching to a running program - -One of the neatest features about gdb is -that it can attach to a program that's already running. Of course, -that assumes you have sufficient permissions to do so. A common -problem is when you are stepping through a program that forks, and -you want to trace the child, but the debugger will only let you trace -the parent. - -What you do is start up another gdb, use -ps to find the process ID for the child, and -do(gdb) attach pid -in gdb, and then debug as usual. - -That's all very well, you're probably thinking, -but by the time I've done that, the child process will be over -the hill and far away. Fear not, gentle reader, here's how to -do it (courtesy of the gdb info pages): -&hellip -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - &hellip -} else { /* parent */ - &hellip -Now all you have to do is attach to the child, set -PauseMode to 0, and -wait for the sleep() call to return! - - - - - -Using Emacs as a Development Environment - - -Emacs - -Unfortunately, Unix systems don't come with the kind of -everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package -integrated development environments that other systems -have.At least, not unless you pay out very large sums -of money. However, it is possible to set up your -own environment. It may not be as pretty, and it may not be quite as -integrated, but you can set it up the way you want it. And it's free. -And you have the source to it. - -The key to it all is Emacs. Now there are some people who -loathe it, but many who love it. If you're one of the former, I'm -afraid this section will hold little of interest to you. Also, you'll -need a fair amount of memory to run it—I'd recommend 8MB in -text mode and 16MB in X as the bare minimum to get reasonable -performance. - -Emacs is basically a highly customisable editor—indeed, -it has been customised to the point where it's more like an operating -system than an editor! Many developers and sysadmins do in fact -spend practically all their time working inside Emacs, leaving it -only to log out. - -It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: - - -Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc. - -Pull-down menus and online help. - -Language-dependent syntax highlighting and -indentation. - -Completely customisable. - -You can compile and debug programs within -Emacs. - -On a compilation error, you can jump to the offending -line of source code. - -Friendly-ish front-end to the info -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself. - -Friendly front-end to gdb, -allowing you to look at the source code as you step through your -program. - -You can read Usenet news and mail while your program -is compiling. - -And doubtless many more that I've overlooked. - -Emacs can be installed on FreeBSD using the Emacs -port. - -Once it's installed, start it up and do C-h -t to read an Emacs tutorial—that means hold down -the control key, press h, let go of -the control key, and then press t. -(Alternatively, you can you use the mouse to select Emacs -Tutorial from the Help menu). - -Although Emacs does have menus, it's well worth learning the -key bindings, as it's much quicker when you're editing something to -press a couple of keys than to try and find the mouse and then click -on the right place. And, when you're talking to seasoned Emacs users, -you'll find they often casually throw around expressions like -M-x replace-s RET foo RET bar RET -so it's useful to know what they mean. And in any case, Emacs has far -too many useful functions for them to all fit on the menu -bars. - -Fortunately, it's quite easy to pick up the key-bindings, as -they're displayed next to the menu item. My advice is to use the -menu item for, say, opening a file until you understand how it works -and feel confident with it, then try doing C-x C-f. When you're happy -with that, move on to another menu command. - -If you can't remember what a particular combination of keys -does, select Describe Key from the -Help menu and type it in—Emacs will tell you -what it does. You can also use the Command -Apropos menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it. - -By the way, the expression above means hold down the -Meta key, press x, release the -Meta key, type replace-s -(short for replace-string—another feature of -Emacs is that you can abbreviate commands), press the -return key, type foo (the -string you want replaced), press the return key, -type bar (the string you want to replace foo with) -and press return again. Emacs will then do the -search-and-replace operation you've just requested. - -If you're wondering what on earth the Meta key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -alt key (or if you're unlucky, the escape -key). - -Oh, and to get out of Emacs, do C-x C-c -(that means hold down the control key, press -c, press x and release the -control key). If you have any unsaved files open, -Emacs will ask you if you want to save them. (Ignore the bit in the -documentation where it says C-z is the usual way -to leave Emacs—that leaves Emacs hanging around in the -background, and is only really useful if you're on a system which -doesn't have virtual terminals). - - - - -Configuring Emacs - -Emacs does many wonderful things; some of them are built in, -some of them need to be configured. - -Instead of using a proprietary macro language for -configuration, Emacs uses a version of Lisp specially adapted for -editors, known as Emacs Lisp. This can be quite useful if you want to -go on and learn something like Common Lisp, as it's considerably -smaller than Common Lisp (although still quite big!). - -The best way to learn Emacs Lisp is to download the Emacs -Tutorial - -However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -.emacs file, which should be enough to get you -started. Just copy it into your home directory and restart Emacs if -it's already running; it will read the commands from the file and -(hopefully) give you a useful basic setup. - - - - -A sample <filename>.emacs</filename> file - -Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning. - - - - -Everything beginning with a ; is a -comment and is ignored by Emacs. - -In the first line, the --*- Emacs-Lisp -*- is so that we can -edit the .emacs file itself within Emacs and get -all the fancy features for editing Emacs Lisp. Emacs usually tries to -guess this based on the filename, and may not get it right for -.emacs. - -The tab key is bound to an -indentation function in some modes, so when you press the tab key, it -will indent the current line of code. If you want to put a -tab character in whatever you're writing, hold the -control key down while you're pressing the -tab key. - -This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename. - -Emacs already has a pre-defined function called -next-error. In a compilation output window, this -allows you to move from one compilation error to the next by doing -M-n; we define a complementary function, -previous-error, that allows you to go to a -previous error by doing M-p. The nicest feature of -all is that C-c C-c will open up the source file -in which the error occurred and jump to the appropriate -line. - - We enable Emacs's ability to act as a server, so -that if you're doing something outside Emacs and you want to edit a -file, you can just type in -$ emacsclient filename -and then you can edit the file in your Emacs!Many -Emacs users set their EDITOR environment to -emacsclient so this happens every time they need -to edit a file. - - - - - -A sample <filename>.emacs</filename> file -;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - - - - - - -Extending the Range of Languages Emacs Understands - -Now, this is all very well if you only want to program in the -languages already catered for in the .emacs file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called whizbang comes out, full of exciting -features? - -The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in .el, short for Emacs -Lisp. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -$ find /usr/ports/lang/whizbang -name "*.el" -print -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -/usr/local/share/emacs/site-lisp. - -So for example, if the output from the find command was -/usr/ports/lang/whizbang/work/misc/whizbang.el -we would do -$ cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp - - -Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -.wiz. We need to add an entry to our -.emacs file to make sure Emacs will be able to -use the information in whizbang.el. - -Find the auto-mode-alist entry in -.emacs and add a line for whizbang, such -as: -… -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -… -This means that Emacs will automatically go into -whizbang-mode when you edit a file ending in -.wiz. - -Just below this, you'll find the -font-lock-auto-mode-list entry. Add -whizbang-mode to it like so: -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") -This means that Emacs will always enable -font-lock-mode (ie syntax highlighting) when -editing a .wiz file. - -And that's all that's needed. If there's anything else you want -done automatically when you open up a .wiz file, -you can add a whizbang-mode hook (see -my-scheme-mode-hook for a simple example that -adds auto-indent). - - - - - -Further Reading - - -Brian Harvey and Matthew Wright -Simply Scheme -MIT 1994. -ISBN 0-262-08226-8 - -Randall Schwartz -Learning Perl -O'Reilly 1993 -ISBN 1-56592-042-2 - -Patrick Henry Winston and Berthold Klaus Paul Horn -Lisp (3rd Edition) -Addison-Wesley 1989 -ISBN 0-201-08319-1 - -Brian W. Kernighan and Rob Pike -The Unix Programming Environment -Prentice-Hall 1984 -ISBN 0-13-937681-X - -Brian W. Kernighan and Dennis M. Ritchie -The C Programming Language (2nd Edition) -Prentice-Hall 1988 -ISBN 0-13-110362-8 - -Bjarne Stroustrup -The C++ Programming Language -Addison-Wesley 1991 -ISBN 0-201-53992-6 - -W. Richard Stevens -Advanced Programming in the Unix Environment -Addison-Wesley 1992 -ISBN 0-201-56317-7 - -W. Richard Stevens -Unix Network Programming -Prentice-Hall 1990 -ISBN 0-13-949876-1 - - - - - diff --git a/en_US.ISO_8859-1/tutorials/Makefile b/en_US.ISO_8859-1/tutorials/Makefile deleted file mode 100644 index 0434928bee..0000000000 --- a/en_US.ISO_8859-1/tutorials/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -# $Id: Makefile,v 1.11 1997-09-13 04:24:09 jfieber Exp $ - -DOCS?= index.sgml -SUBDIR= devel diskformat disklessx fonts mh multios newuser upgrade -DOCSUBDIR= ddwg ppp - -.if defined $(NEW_BUILD) -SUBDIR= -.endif - -.include "../web.mk" diff --git a/en_US.ISO_8859-1/tutorials/Makefile.inc b/en_US.ISO_8859-1/tutorials/Makefile.inc deleted file mode 100644 index 7da7fe75c2..0000000000 --- a/en_US.ISO_8859-1/tutorials/Makefile.inc +++ /dev/null @@ -1,4 +0,0 @@ -# $Id: Makefile.inc,v 1.4 1997-07-01 03:52:21 max Exp $ - -WEBBASE?= /data/tutorials -SGMLOPTS+= -hdr ${.CURDIR}/../doc.hdr -ftr ${.CURDIR}/../doc.ftr diff --git a/en_US.ISO_8859-1/tutorials/ddwg/Makefile b/en_US.ISO_8859-1/tutorials/ddwg/Makefile deleted file mode 100644 index f28e8dcab7..0000000000 --- a/en_US.ISO_8859-1/tutorials/ddwg/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:11 max Exp $ - -DOC= ddwg -SRCS= ddwg.sgml - -.include diff --git a/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml b/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml deleted file mode 100644 index 9cb25739aa..0000000000 --- a/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml +++ /dev/null @@ -1,1142 +0,0 @@ - - - - -
- -FreeBSD Device Driver Writer's Guide -<author>Eric L. Hernes, <tt/erich@rrnet.com/ -<date>Wednesday, May 29, 1996 - -<abstract> - -This document describes how to add a device driver to FreeBSD. It is -<it/not/ intended to be a tutorial on UNIX device drivers in general. -It is intended for device driver authors, familiar with the UNIX -device driver model, to work on FreeBSD. - -</abstract> - -<toc> - -<sect> Overview - -<p> <it> -The FreeBSD kernel is very well documented, unfortunately it's all -in `C'. -</it> - -<sect> Types of drivers. - -<sect1> Character - -<sect2> Data Structures -<p> <tt/struct cdevsw/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> -d_open() takes several arguments, the formal list looks something like: -<code> -int -d_open(dev_t dev, int flag, int mode, struct proc *p) -</code> -d_open() is called on <em/every/ open of the device. -<p> - -The <tt/dev/ argument contains the major and minor number of the -device opened. These are available through the macros <tt/major()/ and -<tt/minor()/ -<p> - -The <tt/flag/ and <tt/mode/ arguments are as described in the -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?open(2)" name="open(2)"> -manual page. It is recommended that you check these for access modes -in <sys/fcntl.h> and do what is required. For example if <tt/flag/ -is (O_NONBLOCK | O_EXLOCK) the open should fail if either it would -block, or exclusive access cannot be granted. -<p> - -The <tt/p/ argument contains all the information about the current -process. - -<sect3> d_close() -<p> -d_close() takes the same argument list as d_open(): -<code> -int -d_close(dev_t dev , int flag , int mode , struct proc *p) -</code> - -d_close() is only called on the last close of your device (per minor -device). For example in the following code fragment, d_open() is called -3 times, but d_close() is called only once. -<code> - ... - fd1=open("/dev/mydev", O_RDONLY); - fd2=open("/dev/mydev", O_RDONLY); - fd3=open("/dev/mydev", O_RDONLY); - ... - <useful stuff with fd1, fd2, fd3 here> - ... - close(fd1); - close(fd2); - close(fd3); - ... -</code> - -The arguments are similar to those described above for -d_open(). - -<sect3> d_read() and d_write() -<p> -d_read() and d_write take the following argument lists: -<code> -int -d_read(dev_t dev, struct uio *uio, int flat) -int -d_write(dev_t dev, struct uio *uio, int flat) -</code> - -The d_read() and d_write() entry points are called when -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?read(2)" name="read(2)"> and -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?write(2)" name="write(2)"> -are called on your device from user-space. The transfer -of data can be handled through the kernel support routine uiomove(). - -<sect3> d_ioctl() -<p> -It's argument list is as follows: -<code> -int -d_ioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p) -</code> - -d_ioctl() is a catch-all for operations which don't make sense in -a read/write paradigm. Probably the most famous of all ioctl's is on -tty devices, through -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?stty(1)" name="stty(1)">. -The ioctl entry point is called from -ioctl() in sys/kern/sys_generic.c<p> - -There are four different types of ioctl's which can be implemented. -<sys/ioccom.h> contains convenience macros for defining these ioctls. - -<tt/_IO(g,n)/ for control type operations. &nl; - -<tt/_IOR(g,n,t)/ for operations that read data from a device. &nl; - -<tt/_IOW(g,n,t)/ for operations that write data to a device. &nl; - -<tt/_IOWR(g,n,t)/ for operations that write to a device, and then -read data back. &nl; - -Here <tt/g/ refers to a <em/group/. This is an 8-bit value, typically -indicative of the device; for example, 't' is used in tty ioctls. -<tt/n/ refers to the number of the ioctl within the group. On SCO, this -number alone denotes the ioctl. <tt/t/ is the data type which will -get passed to the driver; this gets handed to a sizeof() operator in -the kernel. The ioctl() system call will either copyin() or copyout() -or both for your driver, then hand you a pointer to the data structure -in the <tt/arg/ argument of the d_ioctl call. Currently the data size -is limited to one page (4k on the i386). - -<sect3> d_stop() -<sect3> d_reset() -<sect3> d_devtotty() -<sect3> d_select() -<sect3> d_mmap() -<sect3> d_strategy() -<p> -d_strategy()'s argument list is as follows: -<code> -void -d_strategy(struct buf *bp) -</code> - -<p> d_strategy() is used for devices which use some form of scatter-gather -io. It is most common in a block device. This is significantly different -than the System V model, where only the block driver performs scatter-gather -io. Under BSD, character devices are sometimes requested to perform -scatter-gather io via the readv() and writev() system calls. - -<sect2> Header Files - -<sect1> Block -<sect2> Data Structures -<p> <tt/struct bdevsw/ Structure -<p> <tt/struct buf/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> Described in the Character device section. - -<sect3> d_close() -<p> Described in the Character device section. - -<sect3> d_strategy() -<p> Described in the Character device section. - -<sect3> d_ioctl() -<p> Described in the Character device section. - -<sect3> d_dump() - -<sect3> d_psize() - -<sect2> Header Files - -<sect1> Network -<sect2> Data Structures -<p> <tt/struct ifnet/ Structure - -<sect2> Entry Points -<sect3> if_init() -<sect3> if_output() -<sect3> if_start() -<sect3> if_done() -<sect3> if_ioctl() -<sect3> if_watchdog() - -<sect2> Header Files - -<sect1> Line Discipline -<sect2> Data Structures - -<p> <tt/struct linesw/ Structure - -<sect2> Entry Points -<sect3> l_open() -<sect3> l_close() -<sect3> l_read() -<sect3> l_write() -<sect3> l_ioctl() -<sect3> l_rint() -<sect3> l_start() -<sect3> l_modem() - -<sect2> Header Files - -<sect> Supported Busses - -<sect1> ISA -- Industry Standard Architecture -<sect2> Data Structures - -<sect3> <tt/struct isa_device/ Structure -<p> -This structure is required, but generally it is created by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -from the kernel configuration file. It is required on a per-device -basis, meaning that if you have a driver which controls two serial -boards, you will have two isa_device structures. If you build a -device as an LKM, you must create your own isa_device structure to -reflect your configuration. (lines 85 - 131 in pcaudio_lkm.c) There is -nearly a direct mapping between the config file and the isa_device -structure. The definition from /usr/src/sys/i386/isa/isa_device.h is: -<code> -struct isa_device { - int id_id; /* device id */ - struct isa_driver *id_driver; - int id_iobase; /* base i/o address */ - u_short id_irq; /* interrupt request */ - short id_drq; /* DMA request */ - caddr_t id_maddr; /* physical i/o memory address on bus (if any)*/ - int id_msize; /* size of i/o memory */ - inthand2_t *id_intr; /* interrupt interface routine */ - int id_unit; /* unit number */ - int id_flags; /* flags */ - int id_scsiid; /* scsi id if needed */ - int id_alive; /* device is present */ -#define RI_FAST 1 /* fast interrupt handler */ - u_int id_ri_flags; /* flags for register_intr() */ - int id_reconfig; /* hot eject device support (such as PCMCIA) */ - int id_enabled; /* is device enabled */ - int id_conflicts; /* we're allowed to conflict with things */ - struct isa_device *id_next; /* used in isa_devlist in userconfig() */ -}; -</code> - -<!-- XXX add stuff here --> -<sect3> <tt/struct isa_driver/ Structure - -<p> -This structure is defined in ``/usr/src/sys/i386/isa/isa_device.h''. -These are required on a per-driver basis. The definition is: -<code> -struct isa_driver { - int (*probe) __P((struct isa_device *idp)); - /* test whether device is present */ - int (*attach) __P((struct isa_device *idp)); - /* setup driver for a device */ - char *name; /* device name */ - int sensitive_hw; /* true if other probes confuse us */ -}; -</code> - -This is the structure used by the probe/attach code to detect and -initialize your device. The <tt/probe/ member is a pointer to your -device probe function; the <tt/attach/ member is a pointer to your -attach function. The <tt/name/ member is a character pointer to the -two or three letter name for your driver. This is the name reported -during the probe/attach process (and probably also in -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?lsdev(8)" name="lsdev(8)">). The -<tt/sensitive_hw/ member is a flag which helps the probe code -determine probing order. - -A typical instantiation is: -<code> -struct isa_driver mcddriver = { mcd_probe, mcd_attach, "mcd" }; -</code> - -<sect2> Entry Points - -<sect3> probe() -<p> -probe() takes a <tt/struct isa_device/ pointer as an argument and returns -an int. The return value is ``zero'' or ``non-zero'' as to the absence -or presence of your device. This entry point may (and probably should) -be declared as <tt/static/ because it is accessed via the <tt/probe/ member -of the <tt/struct isa_driver/ structure. This function is intended -to detect the presence of your device only; it should not do any -configuration of the device itself. - -<sect3> attach() -<p> -attach() also takes a <tt/struct isa_device/ pointer as an argument and -returns an int. The return value is also ``zero'' or ``non-zero'' indicating -whether or not the attach was successful. This function is intended -to do any special initialization of the device as well as confirm that -the device is usable. It too should be declared <tt/static/ because -it is accessed through the <tt/attach/ member of the <tt/isa_driver/ -structure. - -<sect2> Header Files - -<sect1> EISA -- Extended Industry Standard Architecture - -<sect2> Data Structures - -<p> <tt/struct eisa_dev/ Structure -<p> <tt/struct isa_driver/ Structure - -<sect2> Entry Points - -<sect3> probe() -<p> Described in the ISA device section. - -<sect3> attach() -<p> Described in the ISA device section. - -<sect2> Header Files - -<sect1> PCI -- Peripheral Computer Interconnect -<sect2> Data Structures - -<p> <tt/struct pci_device/ Structure - - name: The short device name. - - probe: Checks if the driver can support a device - with this type. The tag may be used to get - more info with pci_read_conf(). See below. - It returns a string with the device's name, - or a NULL pointer, if the driver cannot - support this device. - - attach: Allocate a control structure and prepare - it. This function may use the PCI mapping - functions. See below. - (configuration id) or type. - - count: A pointer to a unit counter. - It's used by the PCI configurator to - allocate unit numbers. - -<sect2> Entry Points - -<sect3> probe() - -<sect3> attach() - -<sect3> shutdown() - -<sect2> Header Files - -<sect1> SCSI -- Small Computer Systems Interface -<sect2> Data Structures - -<p> <tt/struct scsi_adapter/ Structure -<p> <tt/struct scsi_device/ Structure -<p> <tt/struct scsi_ctlr_config/ Structure -<p> <tt/struct scsi_device_config/ Structure -<p> <tt/struct scsi_link/ Structure - -<sect2> Entry Points -<sect3> attach() -<sect3> init() - -<sect2> Header Files - -<sect1> PCCARD (PCMCIA) -<sect2> Data Structures -<p> <tt/struct slot_cont/ Structure -<p> <tt/struct pccard_drv/ Structure -<p> <tt/struct pccard_dev/ Structure -<p> <tt/struct slot/ Structure - -<sect2> Entry Points -<sect3> handler() -<sect3> unload() -<sect3> suspend() -<sect3> init() - -<sect2> Header Files - a. <pccard/slot.h> - -<sect> Linking Into the Kernel. - -<p> -In FreeBSD, support for the ISA and EISA busses is i386 specific. -While FreeBSD itself is presently available on the i386 platform, -some effort has been made to make the PCI, PCCARD, and SCSI code -portable. The ISA and EISA specific code resides in -/usr/src/sys/i386/isa and /usr/src/sys/i386/eisa respectively. -The machine independent PCI, PCCARD, and SCSI code reside in -/usr/src/sys/{pci,pccard,scsi}. The i386 specific code for these -reside in /usr/src/sys/i386/{pci,pccard,scsi}. - -<p> -In FreeBSD, a device driver can be either binary or source. There is -no ``official'' place for binary drivers to reside. BSD/OS uses -something like sys/i386/OBJ. Since most drivers are distributed -in source, the following discussion refers to a source driver. -Binary only drivers are sometimes provided by hardware vendors -who wish to maintain the source as proprietary. - -<p> -A typical driver has the source code in one c-file, say dev.c. The -driver also can have some include files; devreg.h typically contains -public device register declarations, macros, and other driver -specific declarations. Some drivers call this devvar.h instead. -Some drivers, such as the dgb (for the Digiboard PC/Xe), -require microcode to be loaded onto the board. For the dgb driver -the microcode is compiled and dumped into a header file ala -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?file2c(1)" name="file2c(1)">. - -<p> -If the driver has data structures and ioctl's which are specific to -the driver/device, and need to be accessible from user-space, they -should be put in a separate include file which will reside in -/usr/include/machine/ (some of these reside in /usr/include/sys/). -These are typically named something like ioctl_dev.h or devio.h. - -<p> -If a driver is being written which, from user space is -identical to a device which already exists, care should be taken to -use the same ioctl interface and data structures. For example, from -user space, a SCSI CDROM drive should be identical to an IDE cdrom -drive; or a serial line on an intelligent multiport card (Digiboard, -Cyclades, ...) should be identical to the sio devices. These devices -have a fairly well defined interface which should be used. - -<p> -There are two methods for linking a driver into the kernel, static and -the LKM model. The first method is fairly standard across the -*BSD family. The other method was originally developed by Sun -(I believe), and has been implemented into BSD using the Sun model. -I don't believe that the current implementation uses any Sun code. - -<sect1> Standard Model - -<p> -The steps required to add your driver to the standard FreeBSD kernel are -<itemize> -<item> Add to the driver list -<item> Add an entry to the [bc]devsw -<item> Add the driver entry to the kernel config file -<item> <htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)">, -compile, and install the kernel -<item> make required nodes. -<item> reboot. -</itemize> - -<sect2> Adding to the driver list. -<p> -The standard model for adding a device driver to the Berkeley kernel -is to add your driver to the list of known devices. This list is -dependent on the CPU architecture. If the device is not i386 specific -(PCCARD, PCI, SCSI), the file is in ``/usr/src/sys/conf/files''. -If the device is i386 specific, use ``/usr/src/sys/i386/conf/files.i386''. -A typical line looks like: -<tscreen><code> -i386/isa/joy.c optional joy device-driver -</code></tscreen> - -The first field is the pathname of the driver module relative to -/usr/src/sys. For the case of a binary driver the path would be -something like ``i386/OBJ/joy.o''. - -The second field tells -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -that this is an optional driver. Some -devices are required for the kernel to even be built. - -The third field is the name of the device. - -The fourth field tells config that it's a device driver (as opposed to -just optional). This causes config to create entries for the device -in some structures in /usr/src/sys/compile/KERNEL/ioconf.c. - -It is also possible to create a file -``/usr/src/sys/i386/conf/files.KERNEL'' whose contents will override -the default files.i386, but only for the kernel ``KERNEL''. - -<sect2>Make room in conf.c -<p> -Now you must edit ``/usr/src/sys/i386/i386/conf.c'' to make an entry -for your driver. Somewhere near the top, you need to declare your -entry points. The entry for the joystick driver is: -<code> -#include "joy.h" -#if NJOY > 0 -d_open_t joyopen; -d_close_t joyclose; -d_rdwr_t joyread; -d_ioctl_t joyioctl; -#else -#define joyopen nxopen -#define joyclose nxclose -#define joyread nxread -#define joyioctl nxioctl -#endif -</code> - -This either defines your entry points, or null entry points which -will return ENXIO when called (the #else clause). - -The include file ``joy.h'' is automatically generated by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> when -the kernel build tree is created. This usually has only one line like: -<code> -#define NJOY 1 -</code> -or -<code> -#define NJOY 0 -</code> -which defines the number of your devices in your kernel. - -You must additionally add a slot to either cdevsw[&rsqb, or to -bdevsw[&rsqb, depending on whether it is a character device or -a block device, or both if it is a block device with a raw interface. -The entry for the joystick driver is: - -<code> -/* open, close, read, write, ioctl, stop, reset, ttys, select, mmap, strat */ -struct cdevsw cdevsw[] = -{ - ... - { joyopen, joyclose, joyread, nowrite, /*51*/ - joyioctl, nostop, nullreset, nodevtotty,/*joystick */ - seltrue, nommap, NULL}, - ... -} -</code> - -Order is what determines the major number of your device. Which is why -there will always be an entry for your driver, either null entry -points, or actual entry points. It is probably worth noting that this -is significantly different from SCO and other system V derivatives, -where any device can (in theory) have any major number. This is -largely a convenience on FreeBSD, due to the way device nodes are -created. More on this later. - -<sect2>Adding your device to the config file. -<p> -This is simply adding a line describing your device. -The joystick description line is: -<verb> -device joy0 at isa? port "IO_GAME" -</verb> -This says we have a device called ``joy0'' on the isa bus using -io-port ``IO_GAME'' (IO_GAME is a macro defined in -/usr/src/sys/i386/isa/isa.h). - -A slightly more complicated entry is for the ``ix'' driver: -<verb> -device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr -</verb> -This says that we have a device called `ix0' on the ISA bus. It uses -io-port 0x300. It's interrupt will be masked with other devices in -the network class. It uses interrupt 10. It uses -32k of shared memory at physical address 0xd0000. It also defines -it's interrupt handler to be ``ixintr()'' - -<sect2><htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -the kernel. -<p> -Now with our config file in hand, we can create a kernel compile directory. -This is done by simply typing: -<verb> -# config KERNEL -</verb> -where KERNEL is the name of your config file. Config creates a -compile tree for you kernel in /usr/src/sys/compile/KERNEL. It -creates the Makefile, some .c files, and some .h files with macros -defining the number of each device in your kernel. - -Now you can go to the compile directory and build. Each time you run -config, your previous build tree will be removed, unless you config -with a -n. If you have config'ed and compiled a GENERIC kernel, you can -``make links'' to avoid compiling a few files on each iteration. I typically -run -<verb> -# make depend links all -</verb> -followed by a ``make install'' when the kernel is done to my liking. - -<sect2>Making device nodes. -<p> -On FreeBSD, you are responsible for making your own device nodes. The -major number of your device is determined by the slot number in the -device switch. Minor number is driver dependent, of course. You can -either run the mknod's from the command line, or add a section to -/dev/MAKEDEV.local, or even /dev/MAKEDEV to do the work. I sometimes -create a MAKEDEV.dev script that can be run stand-alone or pasted -into /dev/MAKEDEV.local - -<sect2>Reboot. -<p> -This is the easy part. There are a number of ways to do this, reboot, -fastboot, shutdown -r, cycle the power, etc. Upon bootup you should -see your XXprobe() called, and if all is successful, your XXattach() -too. - -<sect1> Loadable Kernel Module (LKM) - -<p> -There are really no defined procedures for writing an LKM driver. The -following is my own conception after experimenting with the LKM device -interface and looking at the standard device driver model, this is one -way of adding an LKM interface to an existing driver without touching -the original driver source (or binary). It is recommended though, -that if you plan to release source to your driver, the LKM specific -parts should be part of the driver itself, conditionally compiled -on the LKM macro (i.e. #ifdef LKM). - -This section will focus on writing the LKM specific part of the driver. We -will assume that we have written a driver which will drop into the standard -device driver model, which we would now like to implement as an LKM. We will -use the pcaudio driver as a sample driver, and develop an LKM front-end. The -source and makefile for the pcaudio LKM, ``pcaudio_lkm.c'' and ``Makefile'', -should be placed in /usr/src/lkm/pcaudio. What follows is a breakdown of -pcaudio_lkm.c. - -Lines 17 - 26 - - -- This includes the file ``pca.h'' and conditionally compiles the rest -of the LKM on whether or not we have a pcaudio device defined. This -mimics the behavior of config. In a standard device driver, -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -generates the pca.h file from the number pca devices in the config file. -<code> - 17 /* - 18 * figure out how many devices we have.. - 19 */ - 20 - 21 #include "pca.h" - 22 - 23 /* - 24 * if we have at least one ... - 25 */ - 26 #if NPCA > 0 -</code> - -Lines 27 - 37 - - -- Includes required files from various include directories. -<code> - 27 #include <sys/param.h> - 28 #include <sys/systm.h> - 29 #include <sys/exec.h> - 30 #include <sys/conf.h> - 31 #include <sys/sysent.h> - 32 #include <sys/lkm.h> - 33 #include <sys/errno.h> - 34 #include <i386/isa/isa_device.h> - 35 #include <i386/isa/isa.h> - 36 - 37 -</code> - -Lines 38 - 51 - - -- Declares the device driver entry points as external. -<code> - 38 /* - 39 * declare your entry points as externs - 40 */ - 41 - 42 extern int pcaprobe(struct isa_device *); - 43 extern int pcaattach(struct isa_device *); - 44 extern int pcaopen(dev_t, int, int, struct proc *); - 45 extern int pcaclose(dev_t, int, int, struct proc *); - 46 extern int pcawrite(dev_t, struct uio *, int); - 47 extern int pcaioctl(dev_t, int, caddr_t); - 48 extern int pcaselect(dev_t, int, struct proc *); - 49 extern void pcaintr(struct clockframe *); - 50 extern struct isa_driver pcadriver; - 51 -</code> - -Lines 52 - 70 - - -- This is creates the device switch entry table for your driver. -This table gets swapped wholesale into the system device switch at -the location specified by your major number. In the standard model, -these are in /usr/src/sys/i386/i386/conf.c. NOTE: you cannot pick a -device major number higher than what exists in conf.c, for example at -present, conf.c rev 1.85, there are 67 slots for character devices, -you cannot use a (character) major device number 67 or greater, -without first reserving space in conf.c. -<code> - 52 /* - 53 * build your device switch entry table - 54 */ - 55 - 56 static struct cdevsw pcacdevsw = { - 57 (d_open_t *) pcaopen, /* open */ - 58 (d_close_t *) pcaclose, /* close */ - 59 (d_rdwr_t *) enodev, /* read */ - 60 (d_rdwr_t *) pcawrite, /* write */ - 61 (d_ioctl_t *) pcaioctl, /* ioctl */ - 62 (d_stop_t *) enodev, /* stop?? */ - 63 (d_reset_t *) enodev, /* reset */ - 64 (d_ttycv_t *) enodev, /* ttys */ - 65 (d_select_t *) pcaselect, /* select */ - 66 (d_mmap_t *) enodev, /* mmap */ - 67 (d_strategy_t *) enodev /* strategy */ - 68 }; - 69 - 70 -</code> - -Lines 71 - 131 - - -- This section is analogous to the config file declaration of your -device. The members of the isa_device structure are filled in by what -is known about your device, I/O port, shared memory segment, etc. We -will probably never have a need for two pcaudio devices in the kernel, -but this example shows how multiple devices can be supported. -<code> - 71 /* - 72 * this lkm arbitrarily supports two - 73 * instantiations of the pc-audio device. - 74 * - 75 * this is for illustration purposes - 76 * only, it doesn't make much sense - 77 * to have two of these beasts... - 78 */ - 79 - 80 - 81 /* - 82 * these have a direct correlation to the - 83 * config file entries... - 84 */ - 85 struct isa_device pcadev[NPCA] = { - 86 { - 87 11, /* device id */ - 88 &pcadriver, /* driver pointer */ - 89 IO_TIMER1, /* base io address */ - 90 -1, /* interrupt */ - 91 -1, /* dma channel */ - 92 (caddr_t)-1, /* physical io memory */ - 93 0, /* size of io memory */ - 94 pcaintr , /* interrupt interface */ - 95 0, /* unit number */ - 96 0, /* flags */ - 97 0, /* scsi id */ - 98 0, /* is alive */ - 99 0, /* flags for register_intr */ - 100 0, /* hot eject device support */ - 101 1 /* is device enabled */ - 102 }, - 103 #if NPCA >1 - 104 { - 105 - 106 /* - 107 * these are all zeros, because it doesn't make - 108 * much sense to be here - 109 * but it may make sense for your device - 110 */ - 111 - 112 0, /* device id */ - 113 &pcadriver, /* driver pointer */ - 114 0, /* base io address */ - 115 -1, /* interrupt */ - 116 -1, /* dma channel */ - 117 -1, /* physical io memory */ - 118 0, /* size of io memory */ - 119 NULL, /* interrupt interface */ - 120 1, /* unit number */ - 121 0, /* flags */ - 122 0, /* scsi id */ - 123 0, /* is alive */ - 124 0, /* flags for register_intr */ - 125 0, /* hot eject device support */ - 126 1 /* is device enabled */ - 127 }, - 128 #endif - 129 - 130 }; - 131 -</code> - -Lines 132 - 139 - - -- This calls the C-preprocessor macro MOD_DEV, which sets up an LKM device -driver, as opposed to an LKM filesystem, or an LKM system call. -<code> - 132 /* - 133 * this macro maps to a function which - 134 * sets the LKM up for a driver - 135 * as opposed to a filesystem, system call, or misc - 136 * LKM. - 137 */ - 138 MOD_DEV("pcaudio_mod", LM_DT_CHAR, 24, &pcacdevsw); - 139 -</code> - -Lines 140 - 168 - - -- This is the function which will be called when the driver is -loaded. This function tries to work like sys/i386/isa/isa.c -which does the probe/attach calls for a driver at boot time. The -biggest trick here is that it maps the physical address of the shared -memory segment, which is specified in the isa_device structure to a -kernel virtual address. Normally the physical address is put in the -config file which builds the isa_device structures in -/usr/src/sys/compile/KERNEL/ioconf.c. The probe/attach sequence of -/usr/src/sys/isa/isa.c translates the physical address to a virtual -one so that in your probe/attach routines you can do things like -<verb> -(int *)id->id_maddr = something; -</verb> -and just refer to the shared memory segment via pointers. -<code> - 140 /* - 141 * this function is called when the module is - 142 * loaded; it tries to mimic the behavior - 143 * of the standard probe/attach stuff from - 144 * isa.c - 145 */ - 146 int - 147 pcaload(){ - 148 int i; - 149 uprintf("PC Audio Driver Loaded\n"); - 150 for (i=0; i<NPCA; i++){ - 151 /* - 152 * this maps the shared memory address - 153 * from physical to virtual, to be - 154 * consistent with the way - 155 * /usr/src/sys/i386/isa.c handles it. - 156 */ - 157 pcadev[i].id_maddr -=0xa0000; - 158 pcadev[i].id_maddr += atdevbase; - 159 if ((*pcadriver.probe)(pcadev+i)) { - 160 (*(pcadriver.attach))(pcadev+i); - 161 } else { - 162 uprintf("PC Audio Probe Failed\n"); - 163 return(1); - 164 } - 165 } - 166 return 0; - 167 } - 168 -</code> - -Lines 169 - 179 - - -- This is the function called when your driver is unloaded; it just displays -a message to that effect. -<code> - 169 /* - 170 * this function is called - 171 * when the module is unloaded - 172 */ - 173 - 174 int - 175 pcaunload(){ - 176 uprintf("PC Audio Driver Unloaded\n"); - 177 return 0; - 178 } - 179 -</code> - -Lines 180 - 190 - - -- This is the entry point which is specified on the command line of the -modload. By convention it is named <dev>_mod. This is how it is -defined in bsd.lkm.mk, the makefile which builds the LKM. If you name your -module following this convention, you can do ``make load'' and ``make -unload'' from /usr/src/lkm/pcaudio. <p> -Note: this has gone through <em/many/ revisions from release 2.0 to 2.1. -It may or may not be possible to write a module which is portable across -all three releases. <p> -<code> - 180 /* - 181 * this is the entry point specified - 182 * on the modload command line - 183 */ - 184 - 185 int - 186 pcaudio_mod(struct lkm_table *lkmtp, int cmd, int ver) - 187 { - 188 DISPATCH(lkmtp, cmd, ver, pcaload, pcaunload, nosys); - 189 } - 190 - 191 #endif /* NICP > 0 */ -</code> - -<sect1> Device Type Idiosyncrasies -<sect2> Character -<sect2> Block -<sect2> Network -<sect2> Line Discipline - -<sect1> Bus Type Idiosyncrasies -<sect2> ISA -<sect2> EISA -<sect2> PCI -<sect2> SCSI -<sect2> PCCARD - -<sect> Kernel Support - -<sect1> Data Structures - -<sect2> <tt/struct kern_devconf/ Structure -<p> - -This structure contains some information about the state of the device -and driver. It is defined in /usr/src/sys/sys/devconf.h as: -<code> -struct devconf { - char dc_name[MAXDEVNAME]; /* name */ - char dc_descr[MAXDEVDESCR]; /* description */ - int dc_unit; /* unit number */ - int dc_number; /* unique id */ - char dc_pname[MAXDEVNAME]; /* name of the parent device */ - int dc_punit; /* unit number of the parent */ - int dc_pnumber; /* unique id of the parent */ - struct machdep_devconf dc_md; /* machine-dependent stuff */ - enum dc_state dc_state; /* state of the device (see above) */ - enum dc_class dc_class; /* type of device (see above) */ - size_t dc_datalen; /* length of data */ - char dc_data[1]; /* variable-length data */ -}; -</code> - -<sect2> <tt/struct proc/ Structure -<p> - -This structure contains all the information about a process. -It is defined in /usr/src/sys/sys/proc.h: -<code> -/* - * Description of a process. - * - * This structure contains the information needed to manage a thread of - * control, known in UN*X as a process; it has references to substructures - * containing descriptions of things that the process uses, but may share - * with related processes. The process structure and the substructures - * are always addressable except for those marked "(PROC ONLY)" below, - * which might be addressable only on a processor on which the process - * is running. - */ -struct proc { - struct proc *p_forw; /* Doubly-linked run/sleep queue. */ - struct proc *p_back; - struct proc *p_next; /* Linked list of active procs */ - struct proc **p_prev; /* and zombies. */ - - /* substructures: */ - struct pcred *p_cred; /* Process owner's identity. */ - struct filedesc *p_fd; /* Ptr to open files structure. */ - struct pstats *p_stats; /* Accounting/statistics (PROC ONLY). */ struct plimit *p_limit; /* Process limits. */ - struct vmspace *p_vmspace; /* Address space. */ - struct sigacts *p_sigacts; /* Signal actions, state (PROC ONLY). */ - -#define p_ucred p_cred->pc_ucred -#define p_rlimit p_limit->pl_rlimit - - int p_flag; /* P_* flags. */ - char p_stat; /* S* process status. */ - char p_pad1[3]; - - pid_t p_pid; /* Process identifier. */ - struct proc *p_hash; /* Hashed based on p_pid for kill+exit+... */ - struct proc *p_pgrpnxt; /* Pointer to next process in process group. */ - struct proc *p_pptr; /* Pointer to process structure of parent. */ - struct proc *p_osptr; /* Pointer to older sibling processes. */ - -/* The following fields are all zeroed upon creation in fork. */ -#define p_startzero p_ysptr - struct proc *p_ysptr; /* Pointer to younger siblings. */ - struct proc *p_cptr; /* Pointer to youngest living child. */ - pid_t p_oppid; /* Save parent pid during ptrace. XXX */ - int p_dupfd; /* Sideways return value from fdopen. XXX */ - - /* scheduling */ - u_int p_estcpu; /* Time averaged value of p_cpticks. */ - int p_cpticks; /* Ticks of cpu time. */ - fixpt_t p_pctcpu; /* %cpu for this process during p_swtime */ - void *p_wchan; /* Sleep address. */ - char *p_wmesg; /* Reason for sleep. */ - u_int p_swtime; /* Time swapped in or out. */ - u_int p_slptime; /* Time since last blocked. */ - - struct itimerval p_realtimer; /* Alarm timer. */ - struct timeval p_rtime; /* Real time. */ - u_quad_t p_uticks; /* Statclock hits in user mode. */ - u_quad_t p_sticks; /* Statclock hits in system mode. */ - u_quad_t p_iticks; /* Statclock hits processing intr. */ - - int p_traceflag; /* Kernel trace points. */ - struct vnode *p_tracep; /* Trace to vnode. */ - - int p_siglist; /* Signals arrived but not delivered. */ - - struct vnode *p_textvp; /* Vnode of executable. */ - - char p_lock; /* Process lock (prevent swap) count. */ - char p_pad2[3]; /* alignment */ - -/* End area that is zeroed on creation. */ -#define p_endzero p_startcopy - -/* The following fields are all copied upon creation in fork. */ -#define p_startcopy p_sigmask - - sigset_t p_sigmask; /* Current signal mask. */ - sigset_t p_sigignore; /* Signals being ignored. */ - sigset_t p_sigcatch; /* Signals being caught by user. */ - - u_char p_priority; /* Process priority. */ - u_char p_usrpri; /* User-priority based on p_cpu and p_nice. */ - char p_nice; /* Process "nice" value. */ - char p_comm[MAXCOMLEN+1]; - - struct pgrp *p_pgrp; /* Pointer to process group. */ - - struct sysentvec *p_sysent; /* System call dispatch information. */ - - struct rtprio p_rtprio; /* Realtime priority. */ -/* End area that is copied on creation. */ -#define p_endcopy p_addr - struct user *p_addr; /* Kernel virtual addr of u-area (PROC ONLY). */ - struct mdproc p_md; /* Any machine-dependent fields. */ - - u_short p_xstat; /* Exit status for wait; also stop signal. */ - u_short p_acflag; /* Accounting flags. */ - struct rusage *p_ru; /* Exit information. XXX */ -}; -</code> - -<sect2> <tt/struct buf/ Structure -<p> -The <tt/struct buf/ structure is used to interface with the buffer cache. -It is defined in /usr/src/sys/sys/buf.h: - -<code> -/* - * The buffer header describes an I/O operation in the kernel. - */ -struct buf { - LIST_ENTRY(buf) b_hash; /* Hash chain. */ - LIST_ENTRY(buf) b_vnbufs; /* Buffer's associated vnode. */ - TAILQ_ENTRY(buf) b_freelist; /* Free list position if not active. */ - struct buf *b_actf, **b_actb; /* Device driver queue when active. */ - struct proc *b_proc; /* Associated proc; NULL if kernel. */ - volatile long b_flags; /* B_* flags. */ - int b_qindex; /* buffer queue index */ - int b_error; /* Errno value. */ - long b_bufsize; /* Allocated buffer size. */ - long b_bcount; /* Valid bytes in buffer. */ - long b_resid; /* Remaining I/O. */ - dev_t b_dev; /* Device associated with buffer. */ - struct { - caddr_t b_addr; /* Memory, superblocks, indirect etc. */ - } b_un; - void *b_saveaddr; /* Original b_addr for physio. */ - daddr_t b_lblkno; /* Logical block number. */ - daddr_t b_blkno; /* Underlying physical block number. */ - /* Function to call upon completion. */ - void (*b_iodone) __P((struct buf *)); - /* For nested b_iodone's. */ - struct iodone_chain *b_iodone_chain; - struct vnode *b_vp; /* Device vnode. */ - int b_pfcent; /* Center page when swapping cluster. */ - int b_dirtyoff; /* Offset in buffer of dirty region. */ - int b_dirtyend; /* Offset of end of dirty region. */ - struct ucred *b_rcred; /* Read credentials reference. */ - struct ucred *b_wcred; /* Write credentials reference. */ - int b_validoff; /* Offset in buffer of valid region. */ - int b_validend; /* Offset of end of valid region. */ - daddr_t b_pblkno; /* physical block number */ - caddr_t b_savekva; /* saved kva for transfer while bouncing - */ - void *b_driver1; /* for private use by the driver */ - void *b_driver2; /* for private use by the driver */ - void *b_spc; - struct vm_page *b_pages[(MAXPHYS + PAGE_SIZE - 1)/PAGE_SIZE]; - int b_npages; -}; -</code> - -<sect2> <tt/struct uio/ Structure -<p> -This structure is used for moving data between the kernel and user spaces -through read() and write() system calls. It is defined in -/usr/src/sys/sys/uio.h: -<code> -struct uio { - struct iovec *uio_iov; - int uio_iovcnt; - off_t uio_offset; - int uio_resid; - enum uio_seg uio_segflg; - enum uio_rw uio_rw; - struct proc *uio_procp; -}; - -</code> - -<sect1> Functions -lots of 'em - -<sect> References. - -<p> FreeBSD Kernel Sources http://www.freebsd.org -<p> NetBSD Kernel Sources http://www.netbsd.org -<p> Writing Device Drivers: Tutorial and Reference; -Tim Burke, Mark A. Parenti, Al, Wojtas; -Digital Press, ISBN 1-55558-141-2. - -<p> Writing A Unix Device Driver; -Janet I. Egan, Thomas J. Teixeira; -John Wiley & Sons, ISBN 0-471-62859-X. - -<p> Writing Device Drivers for SCO Unix; -Peter Kettle; - -</article> diff --git a/en_US.ISO_8859-1/tutorials/disklessx/Makefile b/en_US.ISO_8859-1/tutorials/disklessx/Makefile deleted file mode 100644 index 086d200c36..0000000000 --- a/en_US.ISO_8859-1/tutorials/disklessx/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:12 max Exp $ - -DOCS= disklessx.sgml - -.include "../../web.mk" diff --git a/en_US.ISO_8859-1/tutorials/doc.ftr b/en_US.ISO_8859-1/tutorials/doc.ftr deleted file mode 100644 index 5f459de742..0000000000 --- a/en_US.ISO_8859-1/tutorials/doc.ftr +++ /dev/null @@ -1,5 +0,0 @@ -<hr> -<address> - <a href="../../mailto.html">www@freebsd.org</a> -</address> - diff --git a/en_US.ISO_8859-1/tutorials/doc.hdr b/en_US.ISO_8859-1/tutorials/doc.hdr deleted file mode 100644 index f5e32a9961..0000000000 --- a/en_US.ISO_8859-1/tutorials/doc.hdr +++ /dev/null @@ -1,14 +0,0 @@ -<IMG SRC="../../gifs/bar.gif" ALT="" WIDTH="565" HEIGHT="33" BORDER=0 usemap="#bar"> -<map name="bar"> -<area shape="rect" coords="1,1,111,31" href="../../index.html" ALT=""> -<area shape="rect" coords="112,11,196,31" href="../../ports/index.html" ALT=""> -<area shape="rect" coords="196,12,257,33" href="../../support.html" ALT=""> -<area shape="rect" coords="256,12,365,33" href="../../docs.html" ALT=""> -<area shape="rect" coords="366,13,424,32" href="../../commercial.html" ALT=""> -<area shape="rect" coords="425,16,475,32" href="../../search.html" ALT=""> -<area shape="rect" coords="477,16,516,33" href="../../index-site.html" ALT=""> -<area shape="rect" coords="516,15,562,33" href="../../index.html" ALT=""> -<area shape="rect" href="../../index.html" coords="0,0,564,32" ALT=""> -</map> - -<br clear=all> diff --git a/en_US.ISO_8859-1/tutorials/index.sgml b/en_US.ISO_8859-1/tutorials/index.sgml deleted file mode 100644 index 086a2e6baf..0000000000 --- a/en_US.ISO_8859-1/tutorials/index.sgml +++ /dev/null @@ -1,49 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ -<!ENTITY base CDATA ".."> -<!ENTITY date "$Date: 1997-09-13 04:24:12 $"> -<!ENTITY title "FreeBSD Tutorials"> -<!ENTITY % includes SYSTEM "../includes.sgml"> %includes; -]> -<!-- $Id: index.sgml,v 1.15 1997-09-13 04:24:12 jfieber Exp $ --> - -<html> -&header; - - <p>Here lie assorted documents on various aspects of FreeBSD, - FreeBSD software, and hardware. If you have comments or - would like to contribute a document, please contact us at - <a href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.org</a>.</p> - - <ul> - <li><a href="newuser/newuser.html">For People New to Both FreeBSD - <em>and</em> Unix</a></li> - - <li><a href="mh/mh.html">An introduction to the MH mail software</a></li> - - <li><a href="devel/devel.html">A User's Guide to FreeBSD Programming - Tools</a></li> - - <li><a href="ddwg/ddwg.html">Writing device drivers for FreeBSD</a> - (<a href="ddwg/ddwg.ps">postscript</a>, - <a href="ddwg/ddwg-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="ppp/ppp.html">Pedantic PPP primer - IP Aliasing</a> - (<a href="ppp/ppp.ps">postscript</a>, - <a href="ppp/ppp-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="multios/multios.html">Using FreeBSD with other operating systems</a></li> - - <li><a href="fonts/fonts.html">Fonts and FreeBSD</a></li> - - <li><a href="http://www.cypher.net/~black/ipalias.html">IP Aliasing</a></li> - <li><a href="upgrade/upgrade.html">Upgrading FreeBSD from source</a></li> - <li><a href="diskformat/diskformat.html">Formatting Media For Use With FreeBSD -2.2-RELEASE</a></li> - - </ul> - - -&footer; -</body> -</html> - diff --git a/en_US.ISO_8859-1/tutorials/ppp/Makefile b/en_US.ISO_8859-1/tutorials/ppp/Makefile deleted file mode 100644 index 76ead715ae..0000000000 --- a/en_US.ISO_8859-1/tutorials/ppp/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:16 max Exp $ - -DOC= ppp -SRCS= ppp.sgml - -.include <bsd.sgml.mk> diff --git a/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml b/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml deleted file mode 100644 index 8edeb42750..0000000000 --- a/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml +++ /dev/null @@ -1,1736 +0,0 @@ -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> -<!-- $Id: ppp.sgml,v 1.3 1997-01-21 05:49:54 jkh Exp $ --> - -<article> - -<title>PPP - Pedantic PPP Primer -<author>Maintainer: Steve Sims <tt><htmlurl -url="mailto:SimsS@IBM.NET" - name="<SimsS@IBM.NET>"></tt> - -<date>$Date: 1997-01-21 05:49:54 $ -<abstract> -This is a step-by-step guide for configuring FreeBSD systems to act as -a dial-up router/gateway in a Local Area Environment. All entries may -be assumed to be relevant to FreeBSD 2.2+, unless otherwise noted. -</abstract> - -<toc> - -<sect> -<heading>Overview:</heading> -<p>The User-Mode PPP dialer in FreeBSD Version 2.2 (also known as: -<it>"IIJ-PPP"</it> ) now supports Packet Aliasing for dial up -connections to the Internet. This feature, also known as -"<IT/Masquerading/", "<IT/IP Aliasing/", or "<IT/Network Address -Translation/", allows a FreeBSD system to act as a dial- on-demand -router between an Ethernet-based Local Area Network and an Internet -Service Provider. Systems on the LAN can use the FreeBSD system to -forward information between the Internet by means of a single -dial-connection. - -<sect1> -<heading>Purpose of this Guide.</heading> -<p> -This guide explains how to: -<itemize> -<item>Configure the FreeBSD system to support dial-out connections, -<item>Share a dial-out connection with other systems in a network, -<item>Configure Windows platforms to use the FreeBSD system as a gateway to the Internet. -</itemize> -<p> -While the focus of this guide is to assist in configuring IP Aliasing, -it also includes specific examples of the configuration steps necessary -to configure and install each individual component; each section stands -alone and may be used to assist in the configuration of various aspects -of FreeBSD internetworking. -</sect> - -<sect> -<heading>Building the Local Area Network</heading> - -<p> While the ppp program can, and usually is, be configured to provide -services to <em/only/ the local FreeBSD box it can also be used to serve as a -"Gateway" (or "router") between other LAN-connected resources and the Internet or -other Dial-Up service. - -<sect1> -<heading>Typical Network Topology</heading> - -<p>This guide assumes a typical Local Area Network lashed together as -follows: -<verb> -+---------+ ----> Dial-Up Internet Connection -| FreeBSD | \ (i.e.: NetCom, AOL, AT&T, EarthLink, -etc) -| |-------- -| "Curly" | -| | -+----+----+ - | -|----+-------------+-------------+----| <-- Ethernet Network - | | | - | | | -+----+----+ +----+----+ +----+----+ -| | | | | | -| Win95 | | WFW | | WinNT | -| "Larry" | | "Moe" | | "Shemp" | -| | | | | | -+---------+ +---------+ +---------+ -</verb> - -<sect1> -<heading>Assumptions about the Local Area Network</heading> - -<p>Some specific assumptions about this sample network are: - -<p>Three workstations and a Server are connected with Ethernet -cabling: -<itemize> -<item>a FreeBSD Server ("Curly") with an NE-2000 adapter configured as -'ed0' -<item>a Windows-95 workstation ("Larry") with Microsoft's "native" -32-bit TCP/IP drivers -<item>a Windows for Workgroups workstation ("Moe") with Microsoft's -16-bit TCP/IP extensions -<item>a Windows NT workstation ("Shemp") with Microsoft's "native" -32-bit TCP/IP drivers -</itemize> - -<p>The IP Addresses on the Ethernet side of this sample LAN have been - -taken from the pool of "reserved" addresses proposed in RFC-1597. -IP addresses are assigned as follows: -<verb>Name IP Address -"Curly" 192.168.1.1 # The FreeBSD box -"Larry" 192.168.1.2 # The Win'95 box -"Moe" 192.168.1.3 # The WfW box -"Shemp" 192.168.1.4 # The Windows NT box -</VERB> - -<p>This guide assumes that the modem on the FreeBSD box is connected -to the first serial port ('<tt>/dev/cuaa0</tt>' or '<tt>COM1:</tt>' in -DOS-terms). - -<p>Finally, we'll also assume that your Internet Service Provider (ISP) -automatically provides the IP addresses of both your PPP/FreeBSD side -as well as the ISP's side. (i.e.: Dynamic IP Addresses on both ends -of the link.) Specific details for configuring the Dial-Out side of -PPP will be addressed in Section 2, "Configuring the FreeBSD System". -</sect> - -<sect> -<heading>FreeBSD System Configuration</heading> - -<p>There are three basic pieces of information that must be known to -the FreeBSD box before you can proceed with integrating the sample -Local Area Network: - -<itemize> -<item>The Host Name of the FreeBSD system; in our example it's "Curly", -<item>The Network configuration, -<item>The <tt>/etc/hosts</tt> file (which lists the names and IP addresses of -the other systems in your network) -</itemize> - -<p>If you performed the installation of FreeBSD over a network -connection some of this information may already be configured into -your FreeBSD system. - -<p>Even if you believe that the FreeBSD system was properly configured -when it was installed you should at least verify each of these bits of -information to prevent trouble in subsequent steps. - -<sect1> -<heading>Verifying the FreeBSD Host Name</heading> - -<p>It's possible that the FreeBSD host name was specified and saved -when the system was initially installed. To verify that it was, enter -the following command at a prompt:<p> -<tscreen><verb> -# hostname -</verb></tscreen> - -<p>The name of the host FreeBSD system will be displayed on a single -line. If the name looks correct (this is very subjective :-) skip -ahead to Section 3.2, "Verifying the Ethernet Interface -Configuration". - -<p>For example, in our sample network, we would see 'curly.my.domain' -as a result of the `hostname` command if the name had been set -correctly during, or after, installation. (At this point, don't worry -too much about the ".my.domain" part, we'll sort this out later. The -important part is the name up to the first dot.) - -<p>If a host name wasn't specified when FreeBSD was installed you'll -probably see 'myname.my.domain` as a response. You'll need to edit -<tt>/etc/sysconfig</tt> to set the name of the machine. - -<sect2><heading>Configuring the FreeBSD Host Name</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies the FreeBSD system's host -name when the system boots is in <tt>/etc/sysconfig</tt>. Use the -default text editor ('<tt/ee/') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</verb></tscreen> - -<p>Using the arrow keys, scroll down until you find the line that -specifies the host name of the FreeBSD system. By default, this -section says: -<tscreen><verb> ---- -# Set to the name of your host - this is pretty important! -hostname=myname.my.domain ---- -</verb></tscreen> -Change this section to say (in our example): -<tscreen><verb> ---- -# Set to the name of your host - this is pretty important! -hostname=curly.my.domain ---- -</verb></tscreen> - -Once the change to the host name has been made, press the 'Esc' key to -access the command menu. Select "leave editor" and make sure to -specify "save changes" when prompted. - -<sect1> -<heading>Verifying the Ethernet Interface Configuration</heading> - -<p>To reiterate our basic assumption, this guide assumes that the -Ethernet Interface in the FreeBSD system is named '<tt/ed0/'. This is -the default for NE-1000, NE-2000, WD/SMC models 8003, 8013 and Elite -Ultra (8216) network adapters. - -<p>Other models of network adapters may have different device names in -FreeBSD. Check the FAQ for specifics about your network adapter. If -you're not sure of the device name of your adapter, check the FreeBSD -FAQ to determine the device name for the card you have and substitute -that name (i.e.: '<tt/de0/', '<tt/zp0/', or similar) in the following -steps. - -<p>As was the case with the host name, the configuration for the -FreeBSD system's Ethernet Interface may have been specified when the -system was installed. - -To display the configuration for the interfaces in your -FreeBSD system (Ethernet and others), enter the following command: -<tscreen><verb> -# ifconfig -a -</verb></tscreen> -(In layman's terms: "Show me the <BF/I/nter<BF/F/ace <BF/CONFIG/uration -for my network devices.") - -<p>An example: -<tscreen><verb> -# ifconfig -a - ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu -1500 - inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255 - ether 01:02:03:04:05:06 - lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 - tun0: flags=8050<POINTOPOINT,RUNNING, MULTICAST> mtu 1500 - sl0: flags=c010<POINTOPOINT,LINK2,MULTICAST> mtu 552 - ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 - lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 - inet 127.0.0.1 netmask 0xff000000 -# _ -</verb></tscreen> - -<p>In this example, the following devices were displayed:<p> -<tt/ed0:/ The Ethernet Interface<p> -<tt/lp0:/ The Parallel Port Interface (ignored in this guide)<p> -<tt/tun0:/ The "tunnel" device; <em/This is the one user-mode ppp uses!/<p> -<tt/sl0:/ The SL/IP device (ignored in this guide)<p> -<tt/ppp0:/ Another PPP device (for kernel ppp; ignored in this guide)<p> -<tt/lo0:/ The "Loopback" device (ignored in this guide)<p> - -In this example, the 'ed0' device is up and running. The key -indicators are: -<enum> -<item>Its status is "<tt/UP/", -<item>It has an Internet ("<tt/inet/") address, (in this case, 192.168.1.1) -<item>It has a valid Subnet Mask ("netmask"; 0xffffff00 is the same as -255.255.255.0), and -<item>It has a valid broadcast address (in this case, 192.168.1.255). -</enum> - -<p>If the line for the Ethernet card had shown something similar to: -<tscreen><verb> -ed0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 - ether 01:02:03:04:05:06 -</verb></tscreen> -then the Ethernet card hasn't been configured yet. - -<p>If the configuration for the Ethernet interface is correct you can -skip forward to Section 3.4, "Creating the list of other LAN hosts". -Otherwise, proceed with the next section. -<sect2> -<heading>Configuring your Ethernet Interface</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies settings for the network -interfaces when the system boots is in <tt>/etc/sysconfig</tt>. Use -the default text editor ('ee') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<p> -<tt> # ee /etc/sysconfig</tt> -<p> -About 100 lines from the top of <tt>/etc/sysconfig</tt> is the section -that describes which network interfaces should be activated when the -system boots. In the default configuration file the specific line -that controls this is: - -<tscreen><verb> -network_interfaces="lo0" -</verb></tscreen> - -<p>You'll need to amend this line to tell FreeBSD that you want to add -another device, namely the '<tt/ed0/' device. Change this line to -read: - -<tscreen><verb> -network_interfaces="lo0 ed0" -</verb></tscreen> - -<p>(Note the space between the definition for the loopback device -("lo0") -and the Ethernet device ("<tt/ed0/")! - -<p><em><bf> Reminder: If your Ethernet card isn't named '<tt/ed0/', specify -the correct device name here instead.</bf></em> - -<p>If you performed the installation of FreeBSD over a network -connection then the '<tt/network_interfaces=/' line may already -include a reference to your Ethernet adapter. If it is, verify that -it is the correct device name. - -<p>Specify the Interface Settings for the Ethernet device -('<tt/ed0/'): - -<p>Beneath the line that specifies which interfaces should be -activated are the lines that specify the actual settings for each -interface. In the default <tt>/etc/sysconfig</tt> file is a single -line that says: - -<tscreen><verb> -ifconfig_lo0="inet localhost" -</verb></tscreen> - -<p>You'll need to add another line after that to specify the settings -for your '<tt/ed0/' device. - -<p>If you performed the installation of FreeBSD over a network -connection then there may already be an '<tt>ifconfig_ed0=</tt>' line -after the loopback definition. If so, verify that it has the correct -values. - -<p>For our sample configuration we'll insert a line immediately after -the loopback device definition that says: - -<tscreen><verb> -ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0" -</verb></tscreen> - -<p>When you've finished editing <tt>/etc/sysconfig</tt> to specify and -configure the network interfaces the section should look really close -to: - -<tscreen><verb> ---- -network_interfaces="lo0 ed0" -ifconfig_lo0="inet localhost" -ifconfig_ed0="inet 192.168.1.1 netmask 0xffffff00" ---- -</verb></tscreen> - -<p>Once all of the necessary changes to <tt>/etc/sysconfig</tt> have -been made, press the 'Esc' key to invoke the control menu. Select -"leave editor" and be sure to select "save changes" when prompted. - -<sect1> -<heading>Enabling Packet Forwarding</heading> - -<p>By default the FreeBSD system will not forward IP packets between -various network interfaces. In other words, routing functions (also -known as gateway functions) are disabled. - -<p>If your intent is to use a FreeBSD system as stand-alone Internet -workstation and not as a gateway between LAN nodes and your ISP you -should skip forward to Section 3.4, "Creating the List of Other -LAN Hosts". - -<p>If you intend for the PPP program to service the local FreeBSD box -as well as LAN workstations (as a router) you'll need to enable IP -forwarding. - -<p>To enable IP Packet forwarding you'll need to edit the -<tt>/etc/sysconfig</tt> file. -Load this file into your editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</verb></tscreen> - -<p>About 250 lines down from the top of the file will be the -configuration -section which controls IP forwarding, which will look like: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=NO -===== -</verb></tscreen> - -<p>Change this line to read: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=YES -===== -</verb></tscreen> - -and exit the editor (saving the changes!). - -<p><em><bf>NOTE: This line may already be set to '<tt/gateway=YES/' if IP -forwarding was enabled when the FreeBSD system was installed.</bf></em> - -<sect1> -<heading>Creating the List of other LAN Hosts(<tt>/etc/hosts</tt>)</heading> - -<p>The final step in configuring the LAN side of the FreeBSD system is -to create a list of the names and TCP/IP addresses of the various -systems that are connected to the Local Area Network. This list is -stored in the '<tt>/etc/hosts</tt>' file. - -<p>The default version of this file has only a single host name -listing in it: the name and address of the loopback device ('lo0'). -By networking convention, this device is always named "localhost" and -always has an IP address of 127.0.0.1. (See the interface -configuration example in Section 3.2.) - -<p>To edit the <tt>/etc/hosts</tt> file enter the following command: -<tscreen><verb> # ee /etc/hosts </verb></tscreen> - -<p>Scroll all the way to the bottom of the file (paying attention to -the comments along the way; there's some good information there!) and -enter (assuming our sample network) the following IP addresses and -host names: -<tscreen><verb> -192.168.1.1 curly curly.my.domain # FreeBSD System -192.168.1.2 larry larry.my.domain # Windows '95 System -192.168.1.3 moe moe.my.domain # Windows for Workgroups -System -192.168.1.4 shemp shemp.my.domain # Windows NT System -</verb></tscreen> - -<p>(No changes are needed to the line for the '<tt>127.0.0.1 -localhost</tt>' entry.) - -<p>Once you've entered these lines, press the 'Esc' key to invoke the -control menu. Select "leave editor" and be sure to select "save -changes" when prompted. - -<sect1> -<heading>Testing the FreeBSD system</heading> - -<p>Congratulations! Once you've made it to this point, the FreeBSD -system is configured as a network-connected UNIX system! If you made -any changes to the <tt>/etc/sysconfig</tt> file you should probably -re-boot your FreeBSD system. This will accomplish two important -objectives: -<itemize> -<item>Allow the changes to the interface configurations to be applied, and -<item>Verify that the system restarts without any glaring configuration errors. -</itemize> - -Once the system has been rebooted you should test the network -interfaces. -<p> -<sect2> -<heading>Verifying the operation of the loopback device</heading> - -<p>To verify that the loopback device is configured correctly, log in as -'root' and enter: -<tscreen><verb> -# ping localhost -</verb></tscreen> - -<p>You should see: -<tscreen><verb> -# ping localhost -PING localhost.my.domain. (127.0.0.1): 56 data bytes -64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms -64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m -[...] -</verb></tscreen> -messages scroll by until you hit Ctrl-C to stop the madness. - -<sect2> -<heading>Verifying the operation of the Ethernet Device</heading> - -<p>To verify that the Ethernet device is configured correctly, enter: - -<tscreen><verb> -# ping curly -</verb></tscreen> - -You should see: -<tscreen><verb> -# ping curly -PING curly.my.domain. (192.168.1.1): 56 data bytes -64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms -[...] -</verb></tscreen> -messages. - -<p>One important thing to look at in these two examples is that the -names (loopback and curly) correctly correlate to their IP addresses -(127.0.0.1 and 192.168.1.1). This verifies that the -<tt>/etc/hosts</tt> files is correct. - -<p>If the IP address for "curly" isn't 192.168.1.1 or the address for -"localhost" isn't 127.0.0.1, return to Section 3.4 and review your -entries in '<tt>/etc/hosts</tt>'. - -<p>If the names and addresses are indicated correctly in the result of -the ping command but there are errors displayed then something is -amiss with the interface configuration(s). Return to Section 3.1 and -verify everything again. - -<p>If everything here checks out, proceed with the next section. -</sect> - -<sect> -<heading>Configuring the PPP Dial-Out Connection</heading> -<p>There are two basic modes of operation of the ppp driver: -"Interactive" and "Automatic". - -In Interactive mode you:<p> -<itemize> -<item>Manually establish a connection to your ISP, -<item>Browse, surf, transfer files and mail, etc..., -<item>Manually disconnect from your ISP. -</itemize> - -<p>In Automatic mode, the PPP program silently watches what goes on -inside the FreeBSD system and automagically connects and disconnects -with your ISP as required to make the Internet a seamless element of -your network. - -<p>In this section we'll address the configuration(s) for both modes -with emphasis on configuring your `ppp` environment to operate in -"Automatic" mode. - -<sect1> -<heading>Backing up the original PPP configuration files</heading> - -<p>Before making any changes to the files which are used by PPP you -should make a copy of the default files that were created when the -FreeBSD system was installed. - -Log in as the 'root' user and perform the following steps: - -Change to the '<tt>/etc</tt> directory: -<p><tt># cd /etc</tt> - -Make a backup copy the original files in the 'ppp' directory: -<p><tt># cp -R ppp ppp.ORIGINAL</TT> - -<p>You should now be able to see both a '<tt>ppp</tt>' and a -'<tt>ppp.ORIGINAL</tt>' subdirectory -in the '<tt>/etc</tt>' directory. - -<sect1> -<heading>Create your own PPP configuration files</heading> - -<p>By default, the FreeBSD installation process creates a number of -sample configuration files in the /etc/ppp directory. Please take -some time to review these files; they were derived from working -systems and represent the features and capabilities of the PPP -program. - -<p>I <em/strongly/ encourage you to learn from these sample files and -apply them to your own configuration as necessary. - -<p>For detailed information about the `ppp` program, read the ppp -manpage: -<tscreen><verb> -# man ppp -</verb></tscreen> - -<p>For detailed information about the `chat` scripting language used by -the PPP dialer, read the chat manpage: -<tscreen><verb> -# man chat -</verb></tscreen> - -<p>The remainder of this section describes the recommended contents of -the PPP configuration files. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.conf</tt>' file</heading> - -<p>The '<tt>/etc/ppp/ppp.conf</tt>' file contains the information and -settings required to set up a dial-out PPP connection. More than one -configuration may be contained in this file. The FreeBSD handbook -(XXX URL? XXX) describes the contents and syntax of this file in -detail. - -<p>This section will describe only the minimal configuration to get a -dial-out connection working. - -<p>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a -dial-out Internet gateway for our example LAN: -<tscreen><verb> -################################################################ -# PPP Configuration File ('/etc/ppp/ppp.conf') -# -# Default settings; These are always executed always when PPP -# is invoked and apply to all system configurations. -################################################################ -default: -set device /dev/cuaa0 -set speed 57600 -disable pred1 -deny pred1 -disable lqr -deny lqr -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -set redial 3 10 -# -# -################################################################ -# -# For interactive mode use this configuration: -# -# Invoke with `ppp -alias interactive` -# -################################################################ -interactive: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -# -################################################################ -# -# For demand-dial (automatic) mode we'll use this configuration: -# -# Invoke with: 'ppp -auto -alias demand' -# -################################################################ -demand: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -add 0 0 127.2.2.2 -################################################################ -# End of /etc/ppp/ppp.conf -</verb></tscreen> -This file, taken verbatim from a working system, has three relevant -configuration sections: - -<sect3> -<heading>The "<tt>default</tt>" Section</heading> - -<p>The '<tt>default:</tt>' section contains the values and settings -used by every other section in the file. Essentially, this section is -implicitly added to the configuration lines to each other section. - -<p>This is a good place to put "global defaults" applicable to all -dial-up sessions; especially modem settings and dialing prefixes which -typically don't change based on which destination system you're -connecting to. - -<p>Following are the descriptions of each line in the "default" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: -<tscreen><verb> -set device /dev/cuaa0 -</verb></tscreen> -This statement informs the PPP program that it should use the first -serial port. -Under FreeBSD the '<tt>/dev/cuaa0</tt>' device is the same port that's -known as "<tt>COM1:</tt>" under DOS, Windows, Windows 95, etc.... - -<p>If your modem is on <tt>COM2:</tt> you should specify -'<tt>/dev/cua01</tt>; <tt>COM3:</tt> would be '<tt>/dev/cua02</tt>'. - -<tscreen><verb> -set speed 57600 -</verb></tscreen> - -This line sets the transmit and receive speed for the connection -between the serial port and the modem. While the modem used for this -configuration is only a 28.8 device, setting this value to 57600 lets -the serial link run at a higher rate to accommodate higher throughput -as a result of the data compression built into late-model modems. - -If you have trouble communicating with your modem, try setting this -value to 38400 or even as low as 19200. - -<tscreen><verb> -disable pred1 -deny pred1 -</verb></tscreen> - -These two lines disable the "CCP/Predictor type 1" compression -features of the PPP program. The current version of `ppp` supports -data compression in accordance with draft Internet standards. -Unfortunately many ISPs use equipment that does not support this -capability. Since most modems try to perform on-the-fly compression -anyway you're probably not losing much performance by disabling this -feature on the FreeBSD side and denying the remote side from forcing -it on you. - -<tscreen><verb> -disable lqr -deny lqr -</verb></tscreen> - -These two lines control the "Line Quality Reporting" functions which -are part of the complete Point-to-Point (PPP) protocol specification. -(See RFC-1989 for details.) - -The first line, "disable lqr", instructs the PPP program to not -attempt to report line quality status to the device on the remote end. - -The second line, "deny lqr", instructs the PPP program to deny any -attempts by the remote end to reports line quality. - -As most modern dial-up modems have automatic error correction and -detection and LQR reporting is not fully implemented in many vendor's -products it's generally a safe bet to include these two lines in the -default configuration. - -<tscreen><verb> -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -</verb></tscreen> - -<em>NOTE: (This statement should appear on a single line; ignore any -line wrapping that may appear in this document.)</em> - -This line instructs the PPP program how to dial the modem and -specifies some rudimentary guidelines for doing so: -<itemize> -<item>Attempts to dial should fail if the modem returns a "BUSY" result code, -<item>Attempts to dial should also fail if the modem returns a "NO CARRIER" result code, -<item>The PPP program should expect each of the following events to complete within a -5-second timeout period: -<itemize> -<item>The PPP program will initially expect nothing (specified above -by the \"\" portion of the statement) from the modem <item>The program -will send the modem initialization string "ATE1Q0M0" to the modem and -await a response of "OK". If a response is not received, the program -should send an attention command to the modem ("AT") and look again -for a response of "OK", <item>The program should delay for one second -(specified by the "\\d" part of the statement, and send the dialing -string to the modem. The "ATDT" portion of the statement is the -standard modem prefix to dial using tone-dialing; if you do not have -touch-tone service on your local phone line, replace the "ATDT" with -"ATDP". The "\\T" string is a placeholder for the actual phone number -(which will be automatically inserted as specified by the "set dial -123-4567"). -</itemize> -<item>Finally, before a (maximum) timeout of 40 seconds, the PPP -program should expect to see a "CONNECT" result code returned from the -modem. -</itemize> - -A failure at any point in this dialog will be interpreted as a dialing -failure and the PPP program will fail to connect. - -(For a detailed description of the mini-scripting language used by the -PPP dialer, refer to the "chat" manpage.) - -<tscreen><verb> -set redial 3 10 -</verb></tscreen> -This line specifies that if a dial connection cannot immediately be made -the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds -between redialing attempts. - -<sect3> -<heading>The "<tt>interactive</tt>" Section</heading> - -<p>The '<tt>interactive:</tt>' section contains the values and -settings used to set up an "interactive" PPP session with a specific -remote system. Settings in this section will have the lines included -in the "default" section included automatically. - -<p>The example cited in this section of the guide presumes that you'll -be connecting to a remote system that understands how to authenticate -a user without any fancy scripting language. That is, this sample -uses the CHAP protocol to set up the connection. - -<p>A good rule of thumb is that if the Windows '95 dialer can set up a -connection by just clicking the "Connect" button this sample -configuration should work OK. - -<p>If, on the other hand, when you connect to your ISP using Microsoft -Windows '95 Dial-Up Networking you need to resort to using the "Dial -Up Scripting Tool" from the Microsoft Plus! pack or you have to select -"Bring up a terminal windows after dialing" in the Windows '95 -connection options then you'll need to look at the sample PPP -configuration files and the ppp manpage for examples of "expect / -response" scripting to make your ISP connection. - -<p>Or even better, find an ISP who knows how to provide PAP or CHAP -authentication! - -<p>The configuration examples shown here have been successfully used to -connect to: -<itemize> -<item>Various Shiva LanRovers -<item>The IBM Network (<url url="http://www.ibm.net">) -<item>AT&T WorldNet (<url url="http://att.com/worldnet">) -<item>Erol's (<url url="http://www.erols.com">) -</itemize> - -Following are descriptions for each line in the "interactive" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. If you're inside a PBX -you can -prepend '<tt>9, </tt>' to the number here. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> -This tells the PPP program that it should automatically hang up the -phone if no data has -be exchanged for 300 seconds (5 minutes). You may wish to tailor this -number to your -specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<sect3> -<heading>The "<tt>demand</tt>" Section</heading> - -<p>The "<tt>demand</tt>" section contains the values and settings used -to set up a "Dial-on-demand" PPP session with a specific remote -system. Settings in this section will also have the lines included in -the "default" section included automatically. - -<p>Except for the last two lines in this section it is identical to -the configuration section which defines the "interactive" -configuration. - -<p>As noted in Paragraph ???, the examples cited in this section of -the guide presume that you'll be connecting to a remote system that -understands how to use the CHAP protocol to set up the connection. - -<p>Following are descriptions for each line in the "demand" section of -the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> - -This tells the PPP program that it should automatically hang up the -phone if no data has be exchanged for 300 seconds (5 minutes). You -may wish to tailor this number to your specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> - -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> - -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<tscreen><verb> -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -</verb></tscreen> - -This command sets up a pair of "fake" IP addresses for the local and -remote sides of the PPP link. It instructs the PPP program to create -an IP address of 127.1.1.1 for the local side of the '<tt/tun0/' -(tunnel) device (refer back to section ?? for a description of this -device) and 127.2.2.2 for the remote side. Appending '<tt>/0</tt>' to -each address tells the PPP program that zero of the bits that make up -these addresses are significant and can (in fact, must!) be negotiated -between the local and remote systems when the link is established. -The 255.255.255.0 string tells the PPP program what Subnet mask to -apply to these pseudo-interfaces. - -<p>Remember, we've assumed that your ISP provides the IP addresses for -both ends of the link! If your ISP assigned you a specific IP address -that you should use on your side when configuring your system, enter -that IP address here <em/instead/ of <tt>127.1.1.1</tt>. - -Conversly, if your ISP gave you a specific IP address that he uses on -his end you should enter that IP address here <em/instead/ of -<tt>127.2.2.2</tt>. - -In both cases, it's probably a good idea to leave the '<tt>/0</tt>' on -the end of each address. This gives the PPP program the opportunity -to change the address(es) of the link if it <em/has/ to. - -<tscreen><verb> -add 0 0 127.2.2.2 -</verb></tscreen> - -This last line tells the PPP program that it should add a default -route for IP traffic that points to the (fake) IP address of the ISP's -system. - -<em><bf>Note: If you used an ISP-specified address instead of -<tt>127.2.2.2</tt> on the preceeding line, use the same number here -instead of <tt>127.2.2.2</tt></bf></em>. - -<p>By adding this "fake" route for IP traffic, the PPP program can, -while idle: -<itemize> -<item>Accept packets that FreeBSD doesn't already know how to forward, -<item>Establish a connection to the ISP "<em/on-the-fly/", -<item>Reconfigure the IP addresses of the local and remote side of the link, -<item>Forward packets between your workstation and the ISP. -</itemize> -automatically! - -<p>Once the number of seconds specified by the timeout value in the -"default" section have elapsed without any TCP/IP traffic the PPP -program will automatically close the dial-up connection and the -process will begin again. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.linkup</tt>' file</heading> - -<p>The other file needed to complete the PPP configuration is found in -'<tt>/etc/ppp/ppp.linkup</tt>'. This file contains instructions for -the PPP program on what actions to take after a dial-up link is -established. - -In the case of dial-on-demand configurations the PPP program will need -to delete the default route that was created to the fake IP address of -the remote side (127.2.2.2 in our example in the previous section) and -install a new default route that points the actual IP address of the -remote end (discovered during the dial-up connection setup). - -A representative '<tt>/etc/ppp/ppp.linkup</tt>' file: -<tscreen><verb> -#########################################################################= - -# PPP Link Up File ('/etc/ppp/ppp.linkup') -# -# This file is checked after PPP establishes a network connection. -# -# This file is searched in the following order. -# -# 1) First, the IP address assigned to us is searched and -# the associated command(s) are executed. -# -# 2) If the IP Address is not found, then the label name specified at - -# PPP startup time is searched and the associated command(s) -# are executed. -# -# 3) If neither of the above are found then commands under the label -# 'MYADDR:' are executed. -# -#########################################################################= - -# -# This section is used for the "demand" configuration in -# /etc/ppp/ppp.conf: -demand: - delete ALL - add 0 0 HISADDR -# -# All other configurations in /etc/ppp/ppp.conf use this: -# -MYADDR: - add 0 0 HISADDR -######################################################################## -# End of /etc/ppp/ppp.linkup -</verb></tscreen> -Notice that there is a section in this file named "demand:", identical -to the configuration name used in the '<tt>/etc/ppp/ppp.conf</tt>' -file. This section instructs the PPP program that once a link is -established using this configuration, it must: -<enum> - <item>Remove any IP routing information that the PPP program has created - <item>Add a default route the remote end's actual address. -</enum> - -<p>It's critical that those configurations in -'<tt>/etc/ppp/ppp.conf</tt>' which include the '<tt/set ifaddr/' and -'<tt/add 0 0/' statements (i.e.: those configurations used for -Dial-on-Demand configurations) execute the "delete ALL" and "add 0 0 -HISADDR" commands in <tt>/etc/ppp/ppp.linkup</tt>. - -<p><em><bf>This is the mechanism that controls the actual on-demand -configuration of the link.</bf></em> - -<p>All configurations not explicitly named in -<tt>/etc/ppp/ppp.linkup</tt> will use whatever commands are in the -"MYADDR:" section of the file. This is where non-Demand-Dial -configurations (such as our "interactive:" sample) will fall through -to. This section simply adds a default route to the ISP's IP address -(at the remote end). - -<sect1> -<heading>IP Aliasing</heading> - -<p>All of the configuration steps described thus far are relevant to -any FreeBSD system which will be used to connect to an ISP via dial-up -connection. - -<p>If your sole objective in reading this guide is to connect your -FreeBSD box to the Internet using dial-out ppp you can proceed to -Section 6, "Testing the Network". - -One very attractive feature of the PPP program in on-demand mode is -its ability to route IP traffic between other systems on the Local -Area Network automatically. This feature is known by various names, -"<em/IP Aliasing/", "<em/Network Address Translation/", "<em/Address -Masquerading/" or "<em/Transparent Proxying/". - -<p>Regardless of the terminology used, this mode is not, however, -automatic. If the PPP program is started normally then the program -will not forward packets between LAN interface(s) and the dial-out -connection. In effect, only the FreeBSD system is connected to the -ISP; other workstations cannot "share" the same connection. - -For example, if the program is started with either of the following -command lines: -<p><tt># ppp interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto demand (Dial-on-Demand mode)</tt> -<p>then the system will function as an Internet-connected workstation -<em/only/ for the -FreeBSD box. - -To start the PPP program as a gateway between LAN resources and the -Internet, one of the following command lines would be used instead: -<p><tt># ppp -alias interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto -alias demand (Dial-on-Demand mode)</tt> -<p>Keep this in mind if you intend to proceed with Section 5, -"Configuring Windows Systems". -</sect> - -<sect> -<heading>Configuring Windows Systems</heading> - -<p>As indicated in Section 1, our example network consists of a -FreeBSD system ("Curly") which acts as a gateway (or router) between a -Local Area Network consisting of two different flavors of Windows -Workstations. In order for the LAN nodes to use Curly as a router -they need to be properly configured. Note that this section does not -explain how to configure the Windows workstations for Dial-Up -networking. If you need a good explanation of that procedure, I -recommend <url url="http://www.aladdin.co.uk/techweb">. - -<sect1> -<heading> Configuring Windows 95</heading> - -<p>Configuring Windows 95 to act as an attached resource on your LAN -is relatively simple. The Windows 95 network configuration must be -slightly modified to use the FreeBSD system as the default gateway to -the ISP. Perform the following steps: - -<p><bf>Create the Windows 95 "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it.<p> -The settings for all Network Elements are displayed. -<item>With the "Configuration" tab selected, scroll down the list of -installed components and highlight the "TCP/IP-><em/YourInterfaceType/" line -(where "<em/YourInterfaceType/" is the name or type of Ethernet adapter in your system). -<p>If TCP/IP is not listed in the list of installed network -components, click the "Add" button and install it before proceeding. -<p>(Hint: "Add | Protocol | Microsoft | TCP/IP | OK") -<item>Click on the "Properties" button to display a list of the -settings associated with the TCP component. -</itemize> - -<p><bf>Configure the IP Address Information:</bf> -<itemize> -<item>Click the "IP Address" tab -<item>Click the "Specify an IP address" radio button. - <p>(In our example LAN the Windows 95 system is the one we've called "Larry".) -<item>In the "IP Address" field enter "192.168.1.2". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> -<itemize> -<item>Click on the "Gateway" tab -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection. Enter the IP address of the FreeBSD -Ethernet interface, 192.168.1.1, in the "New gateway" field and click -the "Add" button. If any other gateways are defined in the "Installed -gateways" list you may wish to consider removing them. -</itemize> - -<p><bf>Configure the DNS Information:</bf> - -<p>This guide assumes that your Internet Service Provider has given -you a list of Domain Name Servers (or "DNS Servers") that you should -use. If you wish to run a DNS server on your local FreeBSD system, -refer to Section 6, "Exercise for the Interested Student" for tips on -setting up DNS on your FreeBSD system. - -<itemize> -<item>Click the "DNS Configuration" tab -<item>Make sure that the "Enable DNS" radio button is selected. -<p>(If this button is not selected only the entries that -we put in the host file(s) will be available and your Net-Surfing -will not work as you expect!) -<item>In the "Host" field enter the name of the Windows 95 box, in this -case: "Larry". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address -of the DNS server(s) that your ISP provided, clicking the "Add" button -after every address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows 95 TCP/IP options:</bf> - -<p>For our purposes the settings under the "Advanced", "WINS -Configuration" and "Bindings" tabs are not necessary. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties window. -<item>Click on the "OK" button to close the Network Control Panel. -<item>Reboot your computer if prompted to do so. -</itemize> - -<p> That's it! -<sect1> -<heading>Configuring Windows NT</heading> - -<p>Configuring Windows NT to act as a LAN resource is also relatively -straightforward. The procedures for configuring Windows NT are -similar to Windows 95 with minor exceptions in the user interface. - -<p>The steps shown here are appropriate for a Windows NT 4.0 -Workstation, but the principles are the same for NT 3.5x. You may -wish to refer to the "Configuring Windows for Workgroups" section if -you're configuring Windows NT 3.5<it/x/, since the user interface is -the same for NT 3.5 and WfW. - -<p>Perform the following steps: - -<p><bf>Create the Windows NT "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4 -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\SYSTEM\DRIVERS\ETC\HOSTS" (without the quotes) and click -"OK" -<item>In the editor, enter the addresses and system names from Section -3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows NT TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it. -<item>With the "Identification" tab selected, verify the "Computer Name" -and "Workgroup" fields. In this example we'll use "Shemp" for the name -and "Stooges" for the workgroup. Click the "Change" button and amend -these entries as necessary. -<item>Select the "Protocols" tab. - -<p>The installed Network Protocols will be displayed. There may be a -number of protocols listed but the one of interest to this guide is -the "TCP/IP Protocol". If "TCP/IP Protocol" is not listed, click the -"Add" button to load it. -<p>(Hint: "Add | TCP/IP Protocol | OK") <item>Highlight "TCP/IP -Protocol" and click the "Properties" button. -<p>Tabs for specifying various settings for TCP/IP will be displayed. - </itemize> - -<p><bf>Configuring the IP Address:</bf> - -<p>Make sure that the Ethernet Interface is shown in the "Adapter" -box; if not, scroll through the list of adapters until the correct -interface is shown. -<itemize> -<item>Click the "Specify an IP address" radio button to enable the three -text boxes. -<p>In our example LAN the Windows NT system is the one we've called -"Shemp" -<item>In the "IP Address" field enter "192.168.1.4". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our gateway -to the Internet (routing packets between the Ethernet LAN and the PPP dial-up -connection. -<itemize> -<item>Enter the IP address of the FreeBSD Ethernet interface, -192.168.1.1, in the "New gateway" field and click the "Add" button. -<p>If any other gateways are defined in the "Installed gateways" list -you may wish to consider removing them. -</itemize> -<p><bf>Configuring DNS:</bf> -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. - -If you wish to run a DNS server on your local FreeBSD system, refer to -Section 6, "Exercise for the Interested Student" for tips on setting -up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" tab -<item>In the "Host Name" field enter the name of the Windows NT box, in -this case: "Shemp". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address of -the DNS server that your ISP provided, clicking the "Add" button after -every address is entered. Repeat this step as many times as necessary -to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows NT TCP/IP options:</bf> - -<p>For our purposes the settings under the "WINS Address" and -"Routing" tabs are not used. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties section. - -<item>Click on the "Close" button to close the Network Control Panel. - -<item>Restart your computer if prompted to do so. -</itemize> - -<p>That's it! - -<sect1> -<heading>Configuring Windows for Workgroups</heading> - -<p>Configuring Windows for Workgroups to act as a network client -requires that the Microsoft TCP/IP-32 driver diskette has been -installed on the workstation. The TCP/IP drivers are not included -with the WfW CD or diskettes; if you need a copy they're available at -<url url="ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip">. - -<p>Once the TCP/IP drivers have been loaded, perform the following -steps: - -<p><bf>Create the Windows for Workgroups "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>In Program Manager, click the "File" button; select "Run"; and -enter: "notepad \WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf> -<itemize> -<item>In the main window of Program Manager, open the "Network" group by -double-clicking the icon. -<item>Double click on the "Network Setup" icon. -<item>In the "Network Drivers Box" double-click the "Microsoft -TCP/IP-32" entry. -</itemize> - -<p><bf>Configure the Windows for Workgroups IP Address:</bf> <p>Ensure -the correct Ethernet Interface is selected in the "Adapter" list. If -not, scroll down until it is displayed and select it by clicking on -it. -<itemize> -<item>Ensure that the "Enable Automatic DHCP Configuration" check box is -blank. If it is checked, click it to remove the "X". -<item>In our example LAN the Windows for Workgroups system is the one -we've called "Moe"; in the "IP Address" field enter "192.168.1.3". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection). -<itemize> -<item>Enter the IP address of the FreeBSD system, 192.168.1.1, in the -"Default Gateway" field. -</itemize> - -<p><bf>Configuring DNS:</bf> - -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. If you wish to run a DNS server on your local FreeBSD -system, refer to Section 6, "Exercise for the Interested Student" for -tips on setting up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" button. -<item>In the "Host Name" field enter the name of the Windows for -Workgroups box, in this case: "Moe". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "Domain Name Service (DNS) Search Order" section, enter the -IP address of the DNS server that your ISP provided, clicking the "Add" -button after each address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -<item>Click on the "OK" button to close the DNS Configuration window. - -</itemize> - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Configuration window. - -<item>Click on the "OK" button to close the Network Setup window. -<item>Reboot your computer if prompted. -</itemize> - -<p>That's it! - -<sect> -<heading>Testing the Network</heading> - -<p> Once you've completed that appropriate tasks above you should have -a functioning PPP gateway to the Internet. - -<sect1> -<heading>Testing the Dial-Up link:</heading> - -<p> The first thing to test is that the connection is being made -between your modem and the ISP. - -<sect1> -<heading>Testing the Ethernet LAN</heading> - -<p> *** TBD *** -</sect> - -<sect> -<heading>Exercises for the Interested Student</heading> - -<p> -<sect1> -<heading>Creating a mini-DNS system</heading> - -<p>While managing a Domain Name Service (DNS) hierarchy can be a black -art, it is possible to set up a Mini-DNS server on the FreeBSD system -that also acts as your gateway to your ISP. - -<p>Building on the files in <tt>/etc/namedb</tt> when the FreeBSD -system was installed it's possible to create a name server that is -both authoritative for the example network shown here as well as a -front-door to the Internet DNS architecture. - -<p>In this minimal DNS configuration, only three files are necessary: -<tscreen><verb> -/etc/namedb/named.boot -/etc/namedb/named.root -/etc/namedb/mydomain.db -</verb></tscreen> - -<p>The <tt>/etc/namedb/named.root</tt> file is automatically installed -as part of the FreeBSD base installation; the other two files must be -created manually. - -<sect2> -<heading>The <tt>/etc/namedb/named.boot</tt> file</heading> -<p>The <tt>/etc/namedb/named.boot</tt> file controls the startup -settings of the DNS server. -Esentially, it tells the Name Server: -<enum> -<item>Where to find configuration files, -<item>What "domain names" it's responsible for, and -<item>Where to find other DNS servers. -</enum> - -<p>Using the '<tt/ee/' editor, create a -<tt>/etc/namedb/named.boot</tt> with the following contents: -<tscreen><verb> -; boot file for mini-name server - -directory /etc/namedb - -; type domain source host/file backup file - -cache . named.root -primary my.domain. mydomain.db -</verb></tscreen> -<p>Lines that begin with a semi-colon are comments. The significant -lines in this file are: -<itemize> -<item><tt>directory /etc/namedb</tt> -<p>Tells the Name Server where to find the configuration files -referenced in the remaining sections of the -'<tt>/etc/namedb/named.boot</tt>' file. -<item><tt>cache . named.root</tt> -<p>Tells the Name Server that the list of "Top-Level" DNS servers for -the Internet can be found in a file called '<tt>named.root</tt>'. -(This file is included in the base installation and its -contents are not described in this document.) -<item><tt>primary my.domain. mydomain.db</tt> -<p>Tells the Name Server that it will be "authoritative" for a DNS -domain called "my.domain" and that a list of names and IP addresses -for the systems in "my.domain" (the local network) -can be found in a file named '<tt>mydomain.db</tt>'. -</itemize> -<p>Once the <tt>/etc/namedb/named.boot</tt> file has been created and -saved, proceed to the next section to create the -<tt>/etc/namedb/mydomain.db</tt> file. - -<sect2> -<heading>The <tt>/etc/namedb/mydomain.db</tt> file</heading> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file lists the names and IP -addresses of <em/every/ system in the Local Area Network. - -<p><em>For a detailed description of the statements used in this file, -refer to the <tt/named/ manpage.</em> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file for our minimal DNS -server has the following contents: -<tscreen><verb> -@ IN SOA my.domain. root.my.domain. ( - 961230 ; Serial - 3600 ; Refresh - 300 ; Retry - 3600000 ; Expire - 3600 ) ; Minimum - IN NS curly.my.domain. - -curly.my.domain. IN A 192.168.1.1 # The FreeBSD box -larry.my.domain. IN A 192.168.1.2 # The Win'95 box -moe.my.domain. IN A 192.168.1.3 # The WfW box -shemp.my.domain. IN A 192.168.1.4 # The Windows NT box - -$ORIGIN 1.168.192.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR curly.my.domain. -2 IN PTR larry.my.domain. -3 IN PTR moe.my.domain. -4 IN PTR shemp.my.domain. - -$ORIGIN 0.0.127.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR localhost.my.domain. -</verb></tscreen> -<p>In simple terms, this file declares that the local DNS server is: -<itemize> -<item>The Start of Authority for ("SOA") for a domain called -'my.domain', -<item>The Name Server ("NS") for 'my.domain', -<item>Responsible for the reverse-mapping for all IP addresses that -start with '192.168.1.' and -'127.0.0.' ("$ORIGIN ...") -</itemize> - -<p>To add workstation entries to this file you'll need to add two -lines for each system; one in the top section where the name(s) are -mapped into Internet Addresses ("IN A"), and another line that maps -the addresses back into names in the <tt>$ORIGIN -1.168.192.IN-ADDR.ARPA</tt> section. - -<sect2> -<heading>Starting the DNS Server</heading> - -<p>By default the DNS server ('<tt>/usr/sbin/named</tt>') is not -started when the system boots. You can modify this behavior by -changing a single line in '<tt>/etc/sysconfig</tt>' as follows: - -<p> Using the '<tt/ee/' editor, load <tt>/etc/sysconfig</tt>. Scroll -down approximately 200 lines until you come to the section that says: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="NO" ---- -</verb></tscreen> -Change this section to read: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="-b /etc/namedb/named.boot" ---- -</verb></tscreen> -Save the file and reboot. - -Alternatively, start the Name Server daemon by entering the following -command: -<tscreen><verb> -# named -b /etc/namedb/named.boot -</verb></tscreen> - -<p>Whenever you modify any of the files in <tt>/etc/namedb</tt> you'll -need to kick-start the Name Server process to make it pick up the -modifications. This is performed with the following system command: -<tscreen><verb> -# kill -HUP `cat /var/run/named.pid` -</verb></tscreen> - -<sect1> -<heading>Playing with PPP filters</heading> - -<p>The PPP program has the ability to apply selected filtering rules -to the traffic it routes. While this is not nearly as secure as a -formal firewall it does provide some access control as to how the link -is used. - -<p>('<tt>man ipfw</tt>' for information on setting up a more secure -FreeBSD system.) - -<p>The complete documentation for the various filters and rules under -PPP are availabe in the PPP manpage. - -<p>There are four distinct classes of rules which may be applied to -the PPP program: -<itemize> -<item><tt/afilter/ - Access Counter (or "Keep Alive") filters -<p>These control which events are ignored by the <tt/set timeout=/ -statement in the configuration file. -<item><tt/dfilter/ - Dialing filters -<p>These filtering rules control which events are ignored by the -demand-dial mode of PPP. -<item><tt/ifilter/ - Input filters -<p>Control whether incoming packets should be discarded or passed into -the system. -<item><tt/ofilter/ - Output filters -<p>Control whether outgoing packets should be discarded or passed into -the system. -</itemize> -<p> - -What follows is a snippet from an operating system which provides a -good foundation for "normal" Internet operations while preventing PPP -from pumping <em/all/ data over the dial-up connection. Comments -briefly describe the logic of each rule set: -<tscreen><verb> -# -# KeepAlive filters -# Don't keep Alive with ICMP,DNS and RIP packet -# - set afilter 0 deny icmp - set afilter 1 deny udp src eq 53 - set afilter 2 deny udp dst eq 53 - set afilter 3 deny udp src eq 520 - set afilter 4 deny udp dst eq 520 - set afilter 5 permit 0/0 0/0 -# -# Dial Filters: -# Note: ICMP will trigger a dial-out in this configuration! -# - set dfilter 0 permit 0/0 0/0 -# -# Allow ident packet pass through -# - set ifilter 0 permit tcp dst eq 113 - set ofilter 0 permit tcp src eq 113 -# -# Allow telnet connection to the Internet -# - set ifilter 1 permit tcp src eq 23 estab - set ofilter 1 permit tcp dst eq 23 -# -# Allow ftp access to the Internet -# - set ifilter 2 permit tcp src eq 21 estab - set ofilter 2 permit tcp dst eq 21 - set ifilter 3 permit tcp src eq 20 dst gt 1023 - set ofilter 3 permit tcp dst eq 20 -# -# Allow access to DNS lookups -# - set ifilter 4 permit udp src eq 53 - set ofilter 4 permit udp dst eq 53 -# -# Allow DNS Zone Transfers -# - set ifilter 5 permit tcp src eq 53 - set ofilter 5 permit tcp dst eq 53 -# -# Allow access from/to local network -# - set ifilter 6 permit 0/0 192.168.1.0/24 - set ofilter 6 permit 192.168.1.0/24 0/0 -# -# Allow ping and traceroute response -# - set ifilter 7 permit icmp - set ofilter 7 permit icmp - set ifilter 8 permit udp dst gt 33433 - set ofilter 9 permit udp dst gt 33433 -# -# Allow cvsup -# - set ifilter 9 permit tcp src eq 5998 - set ofilter 9 permit tcp dst eq 5998 - set ifilter 10 permit tcp src eq 5999 - set ofilter 10 permit tcp dst eq 5999 -# -# Allow NTP for Time Synchronization -# - set ifilter 11 permit tcp src eq 123 dst eq 123 - set ofilter 11 permit tcp src eq 123 dst eq 123 - set ifilter 12 permit udp src eq 123 dst eq 123 - set ofilter 12 permit udp src eq 123 dst eq 123 -# -# SMTP'd be a good idea! -# - set ifilter 13 permit tcp src eq 25 - set ofilter 13 permit tcp dst eq 25 -# -# -# We use a lot of `whois`, let's pass that -# - set ifilter 14 permit tcp src eq 43 - set ofilter 14 permit tcp dst eq 43 - set ifilter 15 permit udp src eq 43 - set ofilter 15 permit udp dst eq 43 -# -# If none of above rules matches, then packet is blocked. -#------- -</verb></tscreen> -<p>Up to 20 distinct filtering rules can be applied to each class of -filter. Rules in each class are number sequentially from 0 to 20 -<em/but none of the rules for a particular filter class take affect -until ruleset '0' is defined!/ - -<p>If you choose <em/not/ to use Filtering Rules in the PPP -configuration then <em/ALL/ traffic will be permitted both into and -out of your system while it's connected to your ISP. - -If you decide that you want to implement filtering rules, add the -above lines to your <tt>/etc/ppp/ppp.conf</tt> file in either the -"default:", "demand:", or "interactive:" section (or all of them - the -choice is yours). - -</sect> - -</article> - diff --git a/ja_JP.eucJP/Makefile b/ja_JP.eucJP/Makefile deleted file mode 100644 index 4708f7e403..0000000000 --- a/ja_JP.eucJP/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# From: @(#)Makefile 8.1 (Berkeley) 6/5/93 -# $Id: Makefile,v 1.3 1997-02-22 13:00:32 peter Exp $ - -SUBDIR= handbook - -.include <bsd.subdir.mk> diff --git a/ja_JP.eucJP/books/handbook/Makefile b/ja_JP.eucJP/books/handbook/Makefile deleted file mode 100644 index 4a28740c67..0000000000 --- a/ja_JP.eucJP/books/handbook/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# $Id: Makefile,v 1.14 1997-09-13 20:09:22 max Exp $ -# Original revision: 1.22 -# The FreeBSD Japanese Documentation Project - -DOC= handbook -DOCDIR=${SHAREDIR}/doc/ja_JP.EUC -FORMATS= html roff -SGMLOPTS+=-e EUC-JP -SGMLOPTS+=-links - -SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml -SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml cvsup.sgml -SRCS+= cyclades.sgml development.sgml dialup.sgml dialout.sgml -SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml -SRCS+= firewalls.sgml glossary.sgml goals.sgml -SRCS+= handbook.sgml history.sgml hw.sgml install.sgml isdn.sgml -SRCS+= kerberos.sgml kernelconfig.sgml kerneldebug.sgml kernelopts.sgml -SRCS+= lists.sgml mail.sgml memoryuse.sgml -SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml -SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml -SRCS+= quotas.sgml relnotes.sgml routing.sgml russian.sgml -SRCS+= serial.sgml scsi.sgml sections.sgml sio.sgml skey.sgml slipc.sgml -SRCS+= slips.sgml stable.sgml submitters.sgml synching.sgml -SRCS+= term.sgml userppp.sgml uart.sgml linuxemu.sgml -SRCS+= jcontrib.sgml jmembers.sgml - -.include <bsd.sgml.mk> diff --git a/ja_JP.eucJP/books/handbook/book.sgml b/ja_JP.eucJP/books/handbook/book.sgml deleted file mode 100644 index 417cb9418c..0000000000 --- a/ja_JP.eucJP/books/handbook/book.sgml +++ /dev/null @@ -1,195 +0,0 @@ -<!-- $Id: book.sgml,v 1.21 1997-10-20 05:44:54 max Exp $ --> -<!-- The FreeBSD Japanese Documentation Project --> -<!-- Original revision: 1.79 --> - -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [ - -<!-- Conditional flags for this version of the document --> -<!ENTITY % boothelp.only "IGNORE"> -<!ENTITY % handbook.only "INCLUDE"> - -<!-- Entity shorthand for authors' names and email addresses --> -<!ENTITY % authors SYSTEM "authors.sgml"> -%authors; - -<!-- Entity shorthand for translator's names and email addresses --> -<!ENTITY % jmembers SYSTEM "jmembers.sgml"> -%jmembers; - -<!-- Entity shorthand for mailing list email addresses --> -<!ENTITY % lists SYSTEM "lists.sgml"> -%lists; - -<!-- Entity definitions for all the parts --> -<!ENTITY % sections SYSTEM "sections.sgml"> -%sections; - -<!-- The currently released version of FreeBSD --> -<!ENTITY rel.current CDATA "2.2.2"> - -]> - -<linuxdoc> - <book> - - <title>FreeBSD ハンドブック - - FreeBSD ドキュメンテーションプロジェクト - - 1997年10月 - -FreeBSD へようこそ! このハンドブックはFreeBSD Release -&rel.current;のインストールおよび, 日常での使い方について記述したもので, -FreeBSD ドキュメンテーションプロジェクトによって編集されています. - -日本語版の作成は FreeBSD 日本語ドキュメンテーションプロジェクトがおこなって -います. 本書は現在進行中の作業であって, 多くの個人の手からなる -仕事です. 多くのセクションはまだ存在しませんし, いま存在するセクションの -いくつかはアップデートが必要です. この FreeBSD ドキュメンテーション -プロジェクトに協力したいと思ったら, &a.doc; まで (英語で) 電子メールを -送ってください. ハンドブックそのものに関する議論は, こちらで -おこなわれています. (もちろん英語でです.) -日本語訳および, 日本語版のみに関することは &a.doc-jp; において日本語で -議論されています. 必要に応じて日本語ドキュメンテーションプロジェクトから -本家ドキュメンテーションプロジェクトに対してフィードバックをおこないますので, -英語が得意でない方は &a.doc-jp; まで日本語でコメントをお寄せください. -このドキュメントの最新バージョンは, いつでも -や - -から入手できますし, - -や, たくさんあるからプレインテキスト, -postscript, HTML などの形式でダウンロードすることもできます. -また, も可能です. - - - - - - - 導入 - - はじめに -

FreeBSD は, Intel アーキテクチャ (x86) ベースの PC のための -4.4BSD-Lite をベースとしたオペレーティングシステムです. -FreeBSD の概要については, -をご覧ください. -このプロジェクトの歴史については, -をご覧ください. 最新のリリースについての記述は, -をご覧ください. -FreeBSD プロジェクトへの何らかの貢献 (ソースコード, 機器, 資金の提供など) -について興味があれば, -の章をご覧ください. - - &nutshell; - &history; - &goals; - &development; - &relnotes; - - &install; - &basics; - - &ports; - - - - システム管理 - - &kernelconfig; - セキュリティ - &crypt; - &skey; - &kerberos; - &firewalls; - - &printing; - - "as; - X ウィンドウシステム -

この節の完成は保留にしてあります. - - から提供されるドキュメントを参考にしてください. - - &hw; - - ローカル化 - &russian; - - - - ネットワーク通信 - - シリアル通信 - &serial; - &term; - &dialup; - &dialout; - - PPP と SLIP - -

もしあなたがモデムを使ってインターネットに接続したり, -他の人々に FreeBSD によるインターネットへのダイヤルアップ接続を -提供しようとしているのでしたら, PPP または SLIP 接続を選択することができます. -PPP 接続には, 2 種類の方法が提供されています: -ユーザPPP (iijppp とも呼ばれます) とカーネルPPP です. -両方の PPP の設定手順と, SLIP の設定方法については以下の章に書かれています. - - &userppp; - &ppp; - &slipc; - &slips; - - 高度なネットワーク - &routing; - &nfs; - &diskless; - &isdn; - - &mail; - - - - さらに進んだ話題 - 開発の最前線: FreeBSD-current と FreeBSD-stable -

あるリリースから次のリリースまでの期間にも, FreeBSD の開発は - 休みなく続けられています. この開発の最前線に興味を持っている人のために, - 手元のシステムを最新の開発ツリーに同期させておくための, - とても使いやすい仕掛けが何種類も用意されています. - 注意: 開発の最前線は, 誰でもが扱えるという性質のものではありません! - もしもあなたが, 開発途中のシステムを追いかけようか, それともリリース - バージョンのどれかを使い続けようかと迷っているのなら, - きっとこの章が参考になるでしょう.

- - ¤t; - &stable; - &synching; - - - &submitters; - &policies; - &kernelopts; - &kerneldebug; - &linuxemu; - FreeBSD の内部 - &booting; - &memoryuse; - &dma; - - - - - 付録 - - &mirrors; - &bibliography; - &eresources; - &contrib; - &pgpkeys; - &jcontrib; - - - - - -- cgit v1.2.3