About FreeBSD's availability

There are a few FreeBSD specific newsgroups, along with numerous other newsgroups on topics of interest to FreeBSD users, though the mailing lists remain the most reliable way to get in touch with the FreeBSD developers. For miscellaneous FreeBSD discussion, see comp.unix.bsd.freebsd.misc. For important announcements, see comp.unix.bsd.freebsd.announce.

WEB Resources

For information on recent FreeBSD progress and releases, see the Newsflash page.

GNATS Problem Report Database

Problem reports may also be submitted to the development team using the send-pr(1) command on a FreeBSD system or by sending an email message to bugs@freebsd.org. Please note that send-pr is preferred since messages sent to the mailing list are not tracked as official problem reports!

CVS Repository

CVS (the Concurrent Version System) is the tool we use for keeping our sources under control. Every change (with accompanying log message explaining its purpose) from FreeBSD 2.0 to the present is stored here, and can be easily viewed from here (click on the link). To obtain a - complete copy of the FreeBSD CVS respository, please use + complete copy of the FreeBSD CVS repository, please use either the sup or CTM tools or simply FTP it.

User Groups

FreeBSD's widespread popularity has spawned a number of user groups around the world. If you know of a FreeBSD user group not listed here, let us know about it.

General UNIX Information

The X Window System

Hardware

Multimedia

Related Operating System Projects

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 +<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 <it> The FreeBSD kernel is very well documented, unfortunately it's all in `C'. </it> <sect> Types of drivers. <sect1> Character <sect2> Data Structures <tt/struct cdevsw/ Structure <sect2> Entry Points <sect3> d_open() 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. 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()/ The <tt/flag/ and <tt/mode/ arguments are as described in the 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. The <tt/p/ argument contains all the information about the current process. <sect3> d_close() 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() 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 read(2) and 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() 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 stty(1). The ioctl entry point is called from ioctl() in sys/kern/sys_generic.c 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() d_strategy()'s argument list is as follows: <code> void d_strategy(struct buf *bp) </code> 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 <tt/struct bdevsw/ Structure <tt/struct buf/ Structure <sect2> Entry Points <sect3> d_open() Described in the Character device section. <sect3> d_close() Described in the Character device section. <sect3> d_strategy() Described in the Character device section. <sect3> d_ioctl() Described in the Character device section. <sect3> d_dump() <sect3> d_psize() <sect2> Header Files <sect1> Network <sect2> Data Structures <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 <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 This structure is required, but generally it is created by 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>  <sect3> <tt/struct isa_driver/ Structure 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 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() 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() 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 <tt/struct eisa_dev/ Structure <tt/struct isa_driver/ Structure <sect2> Entry Points <sect3> probe() Described in the ISA device section. <sect3> attach() Described in the ISA device section. <sect2> Header Files <sect1> PCI -- Peripheral Computer Interconnect <sect2> Data Structures <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 <tt/struct scsi_adapter/ Structure <tt/struct scsi_device/ Structure <tt/struct scsi_ctlr_config/ Structure <tt/struct scsi_device_config/ Structure <tt/struct scsi_link/ Structure <sect2> Entry Points <sect3> attach() <sect3> init() <sect2> Header Files <sect1> PCCARD (PCMCIA) <sect2> Data Structures <tt/struct slot_cont/ Structure <tt/struct pccard_drv/ Structure <tt/struct pccard_dev/ Structure <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. 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}. 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. 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 file2c(1). 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. 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. 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 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> config(8), compile, and install the kernel <item> make required nodes. <item> reboot. </itemize> <sect2> Adding to the driver list. 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 -dependant on the cpu architecture. If the device is not i386 specific +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 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 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 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. 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>config(8) the kernel. 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. 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. 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) 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, 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 funtion which + 133 * this macro maps to a function which 134 * sets the LKM up for a driver - 135 * as opposed to a filesystem, systemcall, or misc + 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 * consistant with the way + 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. 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. <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 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 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 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 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. FreeBSD Kernel Sources http://www.freebsd.org NetBSD Kernel Sources http://www.netbsd.org Writing Device Drivers: Tutorial and Reference; Tim Burke, Mark A. Parenti, Al, Wojtas; Digital Press, ISBN 1-55558-141-2. Writing A Unix Device Driver; Janet I. Egan, Thomas J. Teixeira; John Wiley & Sons, ISBN 0-471-62859-X. Writing Device Drivers for SCO Unix; Peter Kettle; </article> diff --git a/data/tutorials/disklessx/disklessx.sgml b/data/tutorials/disklessx/disklessx.sgml index 914236c41e..408ae81e91 100644 --- a/data/tutorials/disklessx/disklessx.sgml +++ b/data/tutorials/disklessx/disklessx.sgml @@ -1,266 +1,266 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ <!ENTITY base CDATA "../.."> -<!ENTITY date "$Date: 1996-10-06 20:17:12 $"> +<!ENTITY date "$Date: 1996-12-28 23:36:52 $"> <!ENTITY title "Diskless X Server: a how to guide"> <!ENTITY copyright " "> <!ENTITY % includes SYSTEM "../../includes.sgml"> %includes; ]> - + <html> &header; <H3>By Jerry Kendall</H3> <H3>(<a href="mailto:jerry@kcis.com">jerry@kcis.com</a>)</H3> 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 +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. <hr> NOTE: I am sure that there is stuff that needs to be added to this. Please send me any comments.... <hr> <h2>Creating the boot floppy (On the diskless system)</h2> 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. <pre> ---- 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 ----</pre> <h2>Getting the network boot programs (On the server)</h2> 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. <h2>Determine which program to run (On the diskless system)</h2> -If you know the chipset that your ethernet adapter uses, this is +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. <h2>Booting across the network</h2> Boot the diskless system with out any config.sys/autoexec.bat -files. try running the boot program for your ethernet adapter. +files. try running the boot program for your Ethernet adapter. <pre> - My ethernet adapter is running in WD8013 16bit mode so + 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..</pre> 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. <h2>Allowing systems to boot across the network (On the server)</h2> Make sure the /etc/inetd.conf file has entries for tftp and bootps. Mine are listed below: <pre> ---- /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 ---- </pre> 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: <pre> 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... </pre> 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: <pre> ---- /tftpboot/cfg.199.246.76.2 ---- rootfs 199.246.76.1:/DiskLess/rootfs/altair hostname altair.kcis.com ---- </pre> 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: <pre> / /bin /etc /tmp /sbin /dev /dev/fd /usr /var /var/run </pre> The actual list of files is: <pre> -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 </pre> Don't forget to 'MAKEDEV all' in the 'dev' directory. My /etc/rc for 'altair' is: <pre> #!/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 </pre> <hr> Any comments and ALL questions welcome.... <address> Jerry Kendall <a href="mailto:jerry@kcis.com">jerry@kcis.com</a> </address> &footer; </body> </html> diff --git a/data/tutorials/mh/mh.sgml b/data/tutorials/mh/mh.sgml index f9207d3b94..465787a182 100644 --- a/data/tutorials/mh/mh.sgml +++ b/data/tutorials/mh/mh.sgml @@ -1,573 +1,573 @@ - +  <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">  <article> <title>An MH Primer <author>Matt Midboe, <url url="mailto:matt@garply.com" name="matt@garply.com"> <date>v1.0, 16 January 1996 <abstract>This document contains an introduction to using MH on FreeBSD</abstract> <toc> <sect>Introduction<label id="mhintro">  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 <tt/-help/ 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: <tscreen><verb> pkg_add /cdrom/packages/mh-6.8.3.tgz </verb></tscreen> 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 <url url="ftp://ftp.ics.uci.edu/" name="ftp.ics.uci.edu"> or <url url="ftp://louie.udel.edu/" name="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 <url url="news:comp.mail.mh" name="comp.mail.mh"> newsgroup. Also you can read the <url url="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html" name="FAQ"> for MH. The best resource for MH is the O'Reilly and Associates book written by Jerry Peek. <sect>Reading Mail  This section covers how to use <tt/inc/, <tt/show/, <tt/scan/, <tt/next/, <tt/prev/, <tt/rmm/, <tt/rmf/, and <tt/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 <em/inc/ this doesn't really make any sense but with commands like <em/show/ it is useful to know. A message list can consist of something like <tt/23 20 16/ which will act on messages 23, 20 and 16. This is fairly simple but you can do more useful things like <tt/23-30/ which will act on all the messages between 23 and 30. You can also specify something like <tt/cur:10/ which will act on the current message and the next 9 messages. The <tt/cur/, <tt/last/, and <tt/first/ messages are special messages that refer to the current, last or first message in the folder. <sect1><heading>inc, msgchk - read in your new email or check it<label id="inc"></> 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: <tscreen><verb> 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 </verb></tscreen> This is the same thing you will see from a ``<ref id="scan">''. 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. <tscreen><verb> inc -host mail.pop.org -user username -norpop </verb></tscreen> That tells inc</> to go to <bf/mail.pop.org/ to download your email, and that your username on their system is <bf/username/. The <tt>-norpop</tt> 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 <em/msgchk/ command is used to get information on whether or not you have new email. <em/msgchk/ takes the same <tt/-host/ and <tt/-user/ options that <em/inc/ takes. <sect1><heading>show, next and prev - displaying and moving through emails <label id="show"></> <em/show/ is to show a letter in your current folder. Like inc, <em/show/ is a fairly straightforward command. If you just type <em/show/ and hit return then it displays the current message. You can also give specific message numbers to show: <tscreen><verb> show 32 45 56 </verb></tscreen> This would display message numbers 32, 45 and 56 right after each other. Unless you change the default behavior <em/show/ basically just does a more on the email message. <em/next/ is used to move onto the next message and <em/prev/ will go to the previous message. Both commands have an implied <em/show/ command so that when you go to the next message it automatically displays it. <sect1><heading>scan - shows you a scan of your messages<label id="scan"></> <em/scan/ will display a brief listing of the messages in your current folder. This is an example of what the <em/scan/ command will give you. <tscreen><verb> 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 </verb></tscreen> 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 <em/show/ it will display that message. One useful option for scan is the <tt/-reverse/ option. This will list your messages with the highest message number first and lowest message number last. Another useful option with <em/scan/ is to have it read from a file. If you want to scan your incoming mailbox on FreeBSD without having to <em/inc/ it you can do <tt>scan -file /var/mail/username</tt>. This can be used with any file that is in the <bf/mbox/ format. <sect1><heading>rmm and rmf - remove the current message or folder <label id="rmm"></> <em/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 <em/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. <sect1><heading>A typical session of reading with MH<label id="samplereading"></> The first thing that you will want to do is <em/inc/ your new mail. So at a shell prompt just type in <em/inc/ and hit return. <tscreen><verb> 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% </verb></tscreen> This shows you the new email that has been added to your mailbox. So the next thing to do is <em/show/ the email and move around. <tscreen><verb> 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). </verb></tscreen> The <em/rmm/ removed the current message and the <em/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: <tscreen><verb> 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% </verb></tscreen> Then if I wanted to read message number 27 I would do a <tt/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. <sect>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 <em/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 <bf/inbox/. The <bf/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 +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 <tt/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 <tt/scan +freebsd/ it will scan your freebsd folder, and your current folder will be changed to freebsd. If you do a <tt/show +freebsd 23 16 42/ <em/show/ is going to switch to your freebsd folder and display messages 23, 16 and 42. So remember that +folder syntax. You will need to make sure you use it to make commands process different folders. Remember you default folder for mail is inbox so doing a <tt/folder +inbox/ should always get you back to your mail. Of course, in MH's infinite flexibility this can be changed but most places have probably left it as inbox.  <sect1>pick - search email that matches certain criteria <em/pick/ is one of the more complex commands in the MH system. So you might want to read the pick man page for a more thorough understanding. At its simplest level you can do something like <tscreen><verb> tempest% pick -search pci 15 42 55 56 57 </verb></tscreen> This will tell <em/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 <em/show/ those messages and read them if you wish or <em/rmm/ them. You would have to specify something like <tt/show 15 42 55-57/ to display them though. A slightly more useful thing to do is this: <tscreen><verb> tempest% pick -search pci -seq pick 5 hits tempest% show pick </verb></tscreen> This will show you the same messages you just didn't have to work as hard to do it. The <tt/-seq/ option is really an abbreviation of <tt/-sequence/ and <bf/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 <tt/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 <tt/pick -search/ can be a bit more time consuming than just searching for message from someone, or to someone. So <em/pick/ allows you to use the following predefined search criteria: <itemize> <item><tt/-to/ search based upon who the message is to <item><tt/-cc/ search based on who is in the cc list <item><tt/-from/ search for who sent the message <item><tt/-subject/ search for emails with this subject <item><tt/-date/ find emails with a matching dat <item><tt>--component</tt> search for any other component in the header. (i.e. --reply-to to find all emails with a certain reply-to in the header) </itemize> This allows you to do things like <tscreen><verb> pick -to freebsd-hackers@freebsd.org -seq hackers </verb></tscreen> to get a list of all the email send to the FreeBSD hackers mailing -list. <em/pick/ also allows you to group these criteria in differents +list. <em/pick/ also allows you to group these criteria in different ways using the following options: <itemize> <item>... <tt/-and/ ... <item>... <tt/-or/ ... <item><tt/-not/ ... <item><tt/-lbrace/ ... <tt/-rbrace/ </itemize> These commands allow you to do things like <tscreen><verb> pick -to freebsd-hackers -and -cc freebsd-hackers </verb></tscreen> 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 <tscreen><verb> pick -lbrace -to freebsd-hackers -and -not -cc freebsd-questions -rbrace -and -subject pci </verb></tscreen> 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 send 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 <em/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. <sect1>folder, folders, refile - three useful programs for folder maintenance There are three programs which are primarily just for manipulating your folders. The <em/folder/ program is used to switch between folders, pack them, and list them. At its simplest level you can do a <tt/folder +newfolder/ and you will be switched into <bf/newfolder/. From there on out all your MH commands like <em/comp/, <em/repl/, <em/scan/, and <em/show/ will act on that <bf/newfolder/ folder. Sometimes when you are reading and deleting messages you will develop ``holes'' in your folders. If you do a <em/scan/ you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do a <tt/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 <em/rmm/'d messages. If you need statistics on your folders you can do a <em/folders/ or <tt/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 <tt/folder +foldername/. A <em/folders/ command looks like this: <tscreen><verb> 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. </verb></tscreen> The <em/refile/ command is what you use to move messages between folders. When you do something like <tt/refile 23 +netfuture/ message number 23 is moved into the netfuture folder. You could also do something like <tt/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 <tt/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. <sect>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 <em/whatnow/ program. When you are at the ``What now?'' prompt you can tell it to <bf/send/, <bf/list/, <bf/edit/, <bf/edit/, <bf/push/, and <bf/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 <em/whatnow/ program what to do with your email. <sect1><heading>comp, forw, reply - compose, forward or reply to a message to someone</> The <em/comp/ program has a few useful command line options. The most important one to know right now is the <tt/-editor/ option. When MH is installed the default editor is usually a program called <em/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 <tt/comp -editor /usr/bin/vi/ or <tt/comp -editor /usr/local/bin/pico/ instead. Once you have run <em/comp/ you are in your editor and you see something that looks like this: <tscreen><verb> To: cc: Subject: -------- </verb></tscreen> 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. <tscreen><verb> 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! </verb></tscreen> You can now save this message and exit your editor. You will see the <tt/What now?/ prompt and you can type in <tt/send/ or <tt/s/ and hit return. Then the freebsd core team will receive their just rewards. As I mentioned earlier you can also send other commands, for example <tt/quit/ if you don't want to send the message. The <em/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 <em/forw/ it will forward your current message. You can always tell it to forward something else by doing something like <tt/forw 23/ and then message number 23 will be put in your outgoing message instead of the current message. Beyond those small differences <em/forw/ functions exactly the same as <em/comp/. You go through the exact same message sending process. The <em/repl/ command will reply to whatever your current message is, unless you give it a different message to reply to. <em/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 <tt/-cc/ option. You can use <bf/all/, <bf/to/, <bf/cc/, <bf/me/ after the <tt/-cc/ option to have <em/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. <sect1> components, and replcomps - components files for comp and repl The <em/components/ file is usually in <tt>/usr/local/lib/mh</tt>. 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 <em/comp/ command just copies this <em/components/ file and then edits it. You can any kind of valid RFC822 header you want. For instance you could have something like this in your <em/components/ file: <tscreen><verb> To: Fcc: out Subject: X-Mailer: MH 6.8.3 X-Home-Page: http://www.freebsd.org/ ------- </verb></tscreen> MH would then copy this components file and throw you into your editor. The <em/components/ file is fairly simple. If you wanted to have a signature on those messages you would just put your signature in that <em/components/ file. The <em/replcomps/ file is a bit more complex. The default <em/replcomps/ looks like this: <tscreen><verb> %(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%>\ -------- </verb></tscreen> It's in the same basic format as the <em/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: <tscreen> %<<bf/if/ {reply-to} <bf/the original message has a reply-to/ then give that to formataddr, %? <bf/else/ {from} <bf/take the from address/, %? <bf/else/ {sender} <bf/take the sender address/, %? <bf/else/ {return-path} <bf/take the return-path from the original message/, %> <bf/endif/. </tscreen> 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 <em/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. </article> diff --git a/data/tutorials/newuser/newuser.sgml b/data/tutorials/newuser/newuser.sgml index a9ae37af76..9f63e518ca 100644 --- a/data/tutorials/newuser/newuser.sgml +++ b/data/tutorials/newuser/newuser.sgml @@ -1,538 +1,538 @@ <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> - + <article> <title>For People New to Both FreeBSD and Unix Annelise Anderson June 30, 1996 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!) 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 Ctrl-Alt-Delete. 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 Don't use the -verbose option; the defaults are what you want. 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 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, and as root you'll have the same environment as jack (this is good). You can quit adduser any time by typing Ctrl-C, 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 newuser (jill?) so that when you edit +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. 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 -F/ Lists the files in the current directory with a * after executables, a / after directories, and an @ after symbolic links. ls -l/ Lists the files in long format—size, date, permissions. ls -a/ Lists hidden (unless you're root) ``dot'' files with the others. 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, Ctrl-b to go back a page, Ctrl-f to go forward, q or Ctrl-c 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. 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 /etc/weekly /etc/monthly If you get tired waiting, press Alt-F2 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. The text editor is vi. Before you edit a file, you should probably back it up. Suppose you want to edit /etc/sysconfig. You could just use cd /etc to get to the /etc directory and do: cp sysconfig sysconfig.orig This would copy sysconfig to sysconfig.orig, and you could later copy sysconfig.orig to sysconfig to recover the original. But even better would be moving (renaming) and then copying back: mv sysconfig sysconfig.orig cp sysconfig.orig sysconfig because the mv command preserves the original date and owner of the file. You can now edit sysconfig. If you want the original back, you'd then mv sysconfig syconfig.myedit (assuming you want to preserve your edited version) and then mv sysconfig.orig sysconfig 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 Ctrl-L/ to redraw the screen Ctrl-b and Ctrl-f/ 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 > chmod.txt will 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 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 or reboot to go to DOS. Copy these files to a DOS directory, call them up with DOS EDIT, Windows Notepad, 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 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. lsdev/ lists configured devices devmenu/ a menu of devices—in color! 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 . 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 . A wide variety of packages and ports are on the 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, 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. (Create /usr/ports/distfiles if it doesn't exist using mkdir.) 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 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 . (Netscape requires the X Window System.) The version you want is the "unknown bsd" version. 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. 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. Using the live file system—the second of FreeBSD's CDROM disks—is useful if you've got limited space. You might try using emacs or 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. You can delete a user (say, jack) by using the command vipw to bring up the master.passwd file (do not use vi directly on master.passwd); delete the line for jack and save the file. Then edit /etc/group, eliminating jack wherever it appears. Finally, go to /usr/home and use rm -R jack (to get rid of user jack's home directory files). 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

Availability of FreeBSD

FreeBSD's development stream has, as of today, branched into the 2.2-RELEASE and 3.0-CURRENT development streams. The 2.1-STABLE branch is also still alive, soon to terminate (for real, this time) with the impending release of FreeBSD-2.1.6.

This branch has occurred so that 2.2 may be readied for release without impacting significant new developments, like SMP support, in the mainstream -current branch.

Modulo any of our usual two-week slips here and there, here is our release schedule for 96/97:

December 1996

January 1997

Spring 1997

This is also probably as good a time as any to announce that new XFree86 3.2 binaries, with early Matrox support, are available.

Thanks to The XFree86 project for the timely release, which will be distributed with 2.2-RELEASE and 2.1.6-RELEASE.

Lest there be any confusion about the 2.1.6 and 2.2 releases coming so close together, let me also just explain that the two branches of development had really very little to do with one another, and the fact that both branches came to release status around the same time was simply how the scheduling worked out. When engineering is allowed to do the scheduling, it rarely employs traditional marketing -strategems. :)

As always, all branches of FreeBSD development are available from a single CVS repository which may be freely replicated to your own machine (see the handbook) or browsed via the WEB.

If you are a regular FreeBSD subscription customer of Walnut Creek CDROM, you will receive both 2.1.6 and 2.2 releases. Making each release a full CD distribution was the only way of ensuring that each would meet the quality expectations of each customer base, and any customer who feels they would have preferred to receive only one release may contact the the orders department at Walnut Creek CDROM at any time for a full refund or credit towards the next subscription issue.

The power, flexibility and reliability of FreeBSD attracts users and commercial vendors alike. In addition to the gallery which showcases users of FreeBSD, we provide this listing of vendors offering software and hardware and consulting services for FreeBSD. If you know of other companies supporting FreeBSD that should be added to this page, please notify us.

Availability of FreeBSD

December 1996

January 1997

Spring 1997

Documentation and miscellaneous accessories

Commercial organizations

Non-profit organizations

Personal sites

FreeBSD was designed for the Internet

What experts have to say . . .

Questions about this WWW server...

Questions about the contents of this WWW server...

Questions about FreeBSD...

Installing Rsync

Running Rsync

Optimizing Rsync's Performance

More Information on Rsync

December 1996

November 1996

October 1996

August 1996

July 1996

June 1996

May 1996

April 1996

March 1996

November 1995

October 1995

September 1995

August 1995

July 1995

June 1995

May 1995

April 1995

March 1995

February 1995

January 1995

December 1994

GNATS Problem Report Database

User Groups

General UNIX Information

The X Window System

Hardware

Multimedia

Related Operating System Projects

Availability of FreeBSD

December 1996

January 1997

Spring 1997

Documentation and miscellaneous accessories

Commercial organizations

Non-profit organizations

Personal sites

Installing Rsync

Running Rsync

Optimizing Rsync's Performance

More Information on Rsync

FreeBSD was designed for the Internet

What experts have to say . . .

Questions about this WWW server...

Questions about the contents of this WWW server...

Questions about FreeBSD...

December 1996

November 1996

October 1996

August 1996

July 1996

June 1996

May 1996

April 1996

March 1996

November 1995

October 1995

September 1995

August 1995

July 1995

June 1995

May 1995

April 1995

March 1995