diff options
author | Ted Unangst <tedu@cvs.openbsd.org> | 2010-07-01 20:04:11 +0000 |
---|---|---|
committer | Ted Unangst <tedu@cvs.openbsd.org> | 2010-07-01 20:04:11 +0000 |
commit | 61135645c205feedcb7d51656c429a07b405ec8e (patch) | |
tree | 8a92aa56b9c2055b80bc23c4e549a21b989aed6c /share | |
parent | 7c9275d132808298c9c7fbfdd44770f4ff8a32ac (diff) |
remove old documentation
Diffstat (limited to 'share')
46 files changed, 3 insertions, 9811 deletions
diff --git a/share/doc/psd/05.sysman/0.t b/share/doc/psd/05.sysman/0.t deleted file mode 100644 index 1b9c6faf9eb..00000000000 --- a/share/doc/psd/05.sysman/0.t +++ /dev/null @@ -1,290 +0,0 @@ -.\" $OpenBSD: 0.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)0.t 8.1 (Berkeley) 6/8/93 -.\" -.if n .ND -.TL -Berkeley Software Architecture Manual -.br -4.4BSD Edition -.AU -William Joy, Robert Fabry, -.AU -Samuel Leffler, M. Kirk McKusick, -.AU -Michael Karels -.AI -Computer Systems Research Group -Computer Science Division -Department of Electrical Engineering and Computer Science -University of California, Berkeley -Berkeley, CA 94720 -.EH 'PSD:5-%''4.4BSD Architecture Manual' -.OH '4.4BSD Architecture Manual''PSD:5-%' -.AB -.FS -* UNIX is a trademark of Bell Laboratories. -.FE -This document summarizes the facilities -provided by the 4.4BSD version of the UNIX\|* operating system. -It does not attempt to act as a tutorial for use of the system -nor does it attempt to explain or justify the design of the -system facilities. -It gives neither motivation nor implementation details, -in favor of brevity. -.PP -The first section describes the basic kernel functions -provided to a UNIX process: process naming and protection, -memory management, software interrupts, -object references (descriptors), time and statistics functions, -and resource controls. -These facilities, as well as facilities for -bootstrap, shutdown and process accounting, -are provided solely by the kernel. -.PP -The second section describes the standard system -abstractions for -files and file systems, -communication, -terminal handling, -and process control and debugging. -These facilities are implemented by the operating system or by -network server processes. -.AE -.LP -.bp -.ft B -.br -.sv 2 -.ce -TABLE OF CONTENTS -.ft R -.LP -.sp 1 -.nf -.B "Introduction." -.LP -.if t .sp .5v -.nf -.B "0. Notation and types" -.LP -.if t .sp .5v -.nf -.B "1. Kernel primitives" -.LP -.if t .sp .5v -.nf -.nf -\fB1.1. Processes and protection\fP -1.1.1. Host and process identifiers -1.1.2. Process creation and termination -1.1.3. User and group ids -1.1.4. Process groups -.LP -.nf -\fB1.2. Memory management\fP -1.2.1. Text, data and stack -1.2.2. Mapping pages -1.2.3. Page protection control -1.2.4. Giving and getting advice -1.2.5. Protection primitives -.LP -.if t .sp .5v -.nf -\fB1.3. Signals\fP -1.3.1. Overview -1.3.2. Signal types -1.3.3. Signal handlers -1.3.4. Sending signals -1.3.5. Protecting critical sections -1.3.6. Signal stacks -.LP -.if t .sp .5v -.nf -\fB1.4. Timing and statistics\fP -1.4.1. Real time -1.4.2. Interval time -.LP -.if t .sp .5v -.nf -\fB1.5. Descriptors\fP -1.5.1. The reference table -1.5.2. Descriptor properties -1.5.3. Managing descriptor references -1.5.4. Multiplexing requests -1.5.5. Descriptor wrapping -.LP -.if t .sp .5v -.nf -\fB1.6. Resource controls\fP -1.6.1. Process priorities -1.6.2. Resource utilization -1.6.3. Resource limits -.LP -.if t .sp .5v -.nf -\fB1.7. System operation support\fP -1.7.1. Bootstrap operations -1.7.2. Shutdown operations -1.7.3. Accounting -.bp -.LP -.if t .sp .5v -.sp 1 -.nf -\fB2. System facilities\fP -.LP -.if t .sp .5v -.nf -\fB2.1. Generic operations\fP -2.1.1. Read and write -2.1.2. Input/output control -2.1.3. Non-blocking and asynchronous operations -.LP -.if t .sp .5v -.nf -\fB2.2. File system\fP -2.2.1 Overview -2.2.2. Naming -2.2.3. Creation and removal -2.2.3.1. Directory creation and removal -2.2.3.2. File creation -2.2.3.3. Creating references to devices -2.2.3.4. Portal creation -2.2.3.6. File, device, and portal removal -2.2.4. Reading and modifying file attributes -2.2.5. Links and renaming -2.2.6. Extension and truncation -2.2.7. Checking accessibility -2.2.8. Locking -2.2.9. Disc quotas -.LP -.if t .sp .5v -.nf -\fB2.3. Interprocess communication\fP -2.3.1. Interprocess communication primitives -2.3.1.1.\0 Communication domains -2.3.1.2.\0 Socket types and protocols -2.3.1.3.\0 Socket creation, naming and service establishment -2.3.1.4.\0 Accepting connections -2.3.1.5.\0 Making connections -2.3.1.6.\0 Sending and receiving data -2.3.1.7.\0 Scatter/gather and exchanging access rights -2.3.1.8.\0 Using read and write with sockets -2.3.1.9.\0 Shutting down halves of full-duplex connections -2.3.1.10.\0 Socket and protocol options -2.3.2. UNIX domain -2.3.2.1. Types of sockets -2.3.2.2. Naming -2.3.2.3. Access rights transmission -2.3.3. INTERNET domain -2.3.3.1. Socket types and protocols -2.3.3.2. Socket naming -2.3.3.3. Access rights transmission -2.3.3.4. Raw access -.LP -.if t .sp .5v -.nf -\fB2.4. Terminals and devices\fP -2.4.1. Terminals -2.4.1.1. Terminal input -2.4.1.1.1 Input modes -2.4.1.1.2 Interrupt characters -2.4.1.1.3 Line editing -2.4.1.2. Terminal output -2.4.1.3. Terminal control operations -2.4.1.4. Terminal hardware support -2.4.2. Structured devices -2.4.3. Unstructured devices -.LP -.if t .sp .5v -.nf -\fB2.5. Process control and debugging\fP -.LP -.if t .sp .5v -.nf -\fBI. Summary of facilities\fP -.LP -.de sh -.ds RH \\$1 -.bp -.NH \\*(ss -\s+2\\$1\s0 -.PP -.PP -.. -.bp -.ds ss 1 -.de _d -.if t .ta .6i 2.1i 2.6i -.\" 2.94 went to 2.6, 3.64 to 3.30 -.if n .ta .84i 2.6i 3.30i -.. -.de _f -.if t .ta .5i 1.25i 2.5i 3.5i -.\" 3.5i went to 3.8i -.if n .ta .7i 1.75i 3.8i 4.8i -.. -.nr H1 -1 -.sh "Notation and types -.PP -The notation used to describe system calls is a variant of a -C language call, consisting of a prototype call followed by -declaration of parameters and results. -An additional keyword \fBresult\fP, not part of the normal C language, -is used to indicate which of the declared entities receive results. -As an example, consider the \fIread\fP call, as described in -section 2.1: -.DS -cc = read(fd, buf, nbytes); -result int cc; int fd; result char *buf; int nbytes; -.DE -The first line shows how the \fIread\fP routine is called, with -three parameters. -As shown on the second line \fIcc\fP is an integer and \fIread\fP also -returns information in the parameter \fIbuf\fP. -.PP -Description of all error conditions arising from each system call -is not provided here; they appear in the programmer's manual. -In particular, when accessed from the C language, -many calls return a characteristic \-1 value -when an error occurs, returning the error code in the global variable -\fIerrno\fP. -Other languages may present errors in different ways. -.PP -A number of system standard types are defined in the include file -.I <sys/types.h> -and used in the specifications here and in many C programs. -These include \fBcaddr_t\fP giving a memory address (typically as -a character pointer), -\fBoff_t\fP giving a file offset (typically as a long integer), -and a set of unsigned types \fBu_char\fP, \fBu_short\fP, \fBu_int\fP -and \fBu_long\fP, shorthand names for \fBunsigned char\fP, \fBunsigned -short\fP, etc. diff --git a/share/doc/psd/05.sysman/1.0.t b/share/doc/psd/05.sysman/1.0.t deleted file mode 100644 index dd3ff53a7c0..00000000000 --- a/share/doc/psd/05.sysman/1.0.t +++ /dev/null @@ -1,54 +0,0 @@ -.\" $OpenBSD: 1.0.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.0.t 8.1 (Berkeley) 6/8/93 -.\" -.ds ss 1 -.sh "Kernel primitives -.PP -The facilities available to a UNIX user process are logically -divided into two parts: kernel facilities directly implemented by -UNIX code running in the operating system, and system facilities -implemented either by the system, or in cooperation with a -\fIserver process\fP. These kernel facilities are described in -this section 1. -.PP -The facilities implemented in the kernel are those which define the -\fIUNIX virtual machine\fP in which each process runs. -Like many real machines, this virtual machine has memory management hardware, -an interrupt facility, timers and counters. The UNIX -virtual machine also allows access to files and other objects through a set of -\fIdescriptors\fP. Each descriptor resembles a device controller, -and supports a set of operations. Like devices on real machines, some -of which are internal to the machine and some of which are external, -parts of the descriptor machinery are built-in to the operating system, while -other parts are often implemented in server processes on other machines. -The facilities provided through the descriptor machinery are described in -section 2. -.ds ss 2 diff --git a/share/doc/psd/05.sysman/1.1.t b/share/doc/psd/05.sysman/1.1.t deleted file mode 100644 index a00944b4612..00000000000 --- a/share/doc/psd/05.sysman/1.1.t +++ /dev/null @@ -1,213 +0,0 @@ -.\" $OpenBSD: 1.1.t,v 1.4 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.1.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Processes and protection -.NH 3 -Host and process identifiers -.PP -Each UNIX host has associated with it a 32-bit host id, and a host -name of up to 256 characters (as defined by MAXHOSTNAMELEN in -\fI<sys/param.h>\fP). -These are set (by a privileged user) -and returned by the calls: -.DS -sethostid(hostid) -long hostid; - -hostid = gethostid(); -result long hostid; - -sethostname(name, len) -char *name; int len; - -len = gethostname(buf, buflen) -result int len; result char *buf; int buflen; -.DE -On each host runs a set of \fIprocesses\fP. -Each process is largely independent of other processes, -having its own protection domain, address space, timers, and -an independent set of references to system or user implemented objects. -.PP -Each process in a host is named by an integer -called the \fIprocess id\fP. This number is -in the range 1-30000 -and is returned by -the \fIgetpid\fP routine: -.DS -pid = getpid(); -result int pid; -.DE -On each UNIX host this identifier is guaranteed to be unique; -in a multi-host environment, the (hostid, process id) pairs are -guaranteed unique. -.NH 3 -Process creation and termination -.PP -A new process is created by making a logical duplicate of an -existing process: -.DS -pid = fork(); -result int pid; -.DE -The \fIfork\fP call returns twice, once in the parent process, where -\fIpid\fP is the process identifier of the child, -and once in the child process where \fIpid\fP is 0. -The parent-child relationship induces a hierarchical structure on -the set of processes in the system. -.PP -A process may terminate by executing an \fIexit\fP call: -.DS -exit(status) -int status; -.DE -returning 8 bits of exit status to its parent. -.PP -When a child process exits or -terminates abnormally, the parent process receives -information about any -event which caused termination of the child process. A -second call provides a non-blocking interface and may also be used -to retrieve information about resources consumed by the process during its -lifetime. -.DS -#include <sys/wait.h> - -pid = wait(astatus); -result int pid; result union wait *astatus; - -pid = wait3(astatus, options, arusage); -result int pid; result union waitstatus *astatus; -int options; result struct rusage *arusage; -.DE -.PP -A process can overlay itself with the memory image of another process, -passing the newly created process a set of parameters, using the call: -.DS -execve(name, argv, envp) -char *name, **argv, **envp; -.DE -The specified \fIname\fP must be a file which is in a format recognized -by the system, either a binary executable file or a file which causes -the execution of a specified interpreter program to process its contents. -.NH 3 -User and group ids -.PP -Each process in the system has associated with it two user-id's: -a \fIreal user id\fP and a \fIeffective user id\fP, both 16 bit -unsigned integers (type \fBuid_t\fP). -Each process has an \fIreal accounting group id\fP and an \fIeffective -accounting group id\fP and a set of -\fIaccess group id's\fP. The group id's are 16 bit unsigned integers -(type \fBgid_t\fP). -Each process may be in several different access groups, with the maximum -concurrent number of access groups a system compilation parameter, -the constant NGROUPS in the file \fI<sys/param.h>\fP, -guaranteed to be at least 8. -.PP -The real and effective user ids associated with a process are returned by: -.DS -ruid = getuid(); -result uid_t ruid; - -euid = geteuid(); -result uid_t euid; -.DE -the real and effective accounting group ids by: -.DS -rgid = getgid(); -result gid_t rgid; - -egid = getegid(); -result gid_t egid; -.DE -The access group id set is returned by a \fIgetgroups\fP call*: -.DS -ngroups = getgroups(gidsetsize, gidset); -result int ngroups; int gidsetsize; result int gidset[gidsetsize]; -.DE -.FS -* The type of the gidset array in getgroups and setgroups -remains integer for compatibility with 4.2BSD. -It may change to \fBgid_t\fP in future releases. -.FE -.PP -The user and group id's -are assigned at login time using the \fIsetreuid\fP, \fIsetregid\fP, -and \fIsetgroups\fP calls: -.DS -setreuid(ruid, euid); -int ruid, euid; - -setregid(rgid, egid); -int rgid, egid; - -setgroups(gidsetsize, gidset) -int gidsetsize; int gidset[gidsetsize]; -.DE -The \fIsetreuid\fP call sets both the real and effective user-id's, -while the \fIsetregid\fP call sets both the real -and effective accounting group id's. -Unless the caller is the super-user, \fIruid\fP -must be equal to either the current real or effective user-id, -and \fIrgid\fP equal to either the current real or effective -accounting group id. The \fIsetgroups\fP call is restricted -to the super-user. -.NH 3 -Process groups -.PP -Each process in the system is also normally associated with a \fIprocess -group\fP. The group of processes in a process group is sometimes -referred to as a \fIjob\fP and manipulated by high-level system -software (such as the shell). -The current process group of a process is returned by the -\fIgetpgrp\fP call: -.DS -pgrp = getpgrp(pid); -result int pgrp; int pid; -.DE -When a process is in a specific process group it may receive -software interrupts affecting the group, causing the group to -suspend or resume execution or to be interrupted or terminated. -In particular, a system terminal has a process group and only processes -which are in the process group of the terminal may read from the -terminal, allowing arbitration of terminals among several different jobs. -.PP -The process group associated with a process may be changed by -the \fIsetpgrp\fP call: -.DS -setpgrp(pid, pgrp); -int pid, pgrp; -.DE -Newly created processes are assigned process id's distinct from all -processes and process groups, and the same process group as their -parent. A normal (unprivileged) process may set its process group equal -to its process id. A privileged process may set the process group of any -process to any value. diff --git a/share/doc/psd/05.sysman/1.2.t b/share/doc/psd/05.sysman/1.2.t deleted file mode 100644 index 1a74d8c0b40..00000000000 --- a/share/doc/psd/05.sysman/1.2.t +++ /dev/null @@ -1,270 +0,0 @@ -.\" $OpenBSD: 1.2.t,v 1.4 2003/10/30 14:53:58 jmc Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.2.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Memory management\(dg -.NH 3 -Text, data and stack -.PP -.FS -\(dg This section represents the interface planned for later -releases of the system. Of the calls described in this section, -only \fIsbrk\fP and \fIgetpagesize\fP are included in 4.3BSD. -.FE -Each process begins execution with three logical areas of memory -called text, data and stack. -The text area is read-only and shared, while the data and stack -areas are private to the process. Both the data and stack areas may -be extended and contracted on program request. The call -.DS -addr = sbrk(incr); -result caddr_t addr; int incr; -.DE -changes the size of the data area by \fIincr\fP bytes and -returns the new end of the data area, while -.DS -addr = sstk(incr); -result caddr_t addr; int incr; -.DE -changes the size of the stack area. -The stack area is also automatically extended as needed. -On the VAX the text and data areas are adjacent in the P0 region, -while the stack section is in the P1 region, and grows downward. -.NH 3 -Mapping pages -.PP -The system supports sharing of data between processes -by allowing pages to be mapped into memory. These mapped -pages may be \fIshared\fP with other processes or \fIprivate\fP -to the process. -Protection and sharing options are defined in \fI<sys/mman.h>\fP as: -.DS -.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u -/* protections are chosen from these bits, or-ed together */ -#define PROT_READ 0x04 /* pages can be read */ -#define PROT_WRITE 0x02 /* pages can be written */ -#define PROT_EXEC 0x01 /* pages can be executed */ -.DE -.DS -.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u -/* flags contain mapping type, sharing type and options */ -/* mapping type; choose one */ -#define MAP_FILE 0x0001 /* mapped from a file or device */ -#define MAP_ANON 0x0002 /* allocated from memory, swap space */ -#define MAP_TYPE 0x000f /* mask for type field */ -.DE -.DS -.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u -/* sharing types; choose one */ -#define MAP_SHARED 0x0010 /* share changes */ -#define MAP_PRIVATE 0x0000 /* changes are private */ -.DE -.DS -.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u -/* other flags */ -#define MAP_FIXED 0x0020 /* map addr must be exactly as requested */ -#define MAP_INHERIT 0x0040 /* region is retained after exec */ -#define MAP_HASSEMAPHORE 0x0080 /* region may contain semaphores */ -#define MAP_NOPREALLOC 0x0100 /* do not preallocate space */ -.DE -The cpu-dependent size of a page is returned by the -\fIgetpagesize\fP system call: -.DS -pagesize = getpagesize(); -result int pagesize; -.DE -.LP -The call: -.DS -maddr = mmap(addr, len, prot, flags, fd, pos); -result caddr_t maddr; caddr_t addr; int *len, prot, flags, fd; off_t pos; -.DE -causes the pages starting at \fIaddr\fP and continuing -for at most \fIlen\fP bytes to be mapped from the object represented by -descriptor \fIfd\fP, starting at byte offset \fIpos\fP. -The starting address of the region is returned; -for the convenience of the system, -it may differ from that supplied -unless the MAP_FIXED flag is given, -in which case the exact address will be used or the call will fail. -The actual amount mapped is returned in \fIlen\fP. -The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters -must all be multiples of the pagesize. -A successful \fImmap\fP will delete any previous mapping -in the allocated address range. -The parameter \fIprot\fP specifies the accessibility -of the mapped pages. -The parameter \fIflags\fP specifies -the type of object to be mapped, -mapping options, and -whether modifications made to -this mapped copy of the page -are to be kept \fIprivate\fP, or are to be \fIshared\fP with -other references. -Possible types include MAP_FILE, -mapping a regular file or character-special device memory, -and MAP_ANON, which maps memory not associated with any specific file. -The file descriptor used for creating MAP_ANON regions is used only -for naming, and may be given as \-1 if no name -is associated with the region.\(dd -.FS -\(dd The current design does not allow a process -to specify the location of swap space. -In the future we may define an additional mapping type, MAP_SWAP, -in which the file descriptor argument specifies a file -or device to which swapping should be done. -.FE -The MAP_INHERIT flag allows a region to be inherited after an \fIexec\fP. -The MAP_HASSEMAPHORE flag allows special handling for -regions that may contain semaphores. -The MAP_NOPREALLOC flag allows processes to allocate regions whose -virtual address space, if fully allocated, -would exceed the available memory plus swap resources. -Such regions may get a SIGSEGV signal if they page fault and resources -are not available to service their request; -typically they would free up some resources via \fIunmap\fP so that -when they return from the signal the page -fault could be successfully completed. -.PP -A facility is provided to synchronize a mapped region with the file -it maps; the call -.DS -msync(addr, len); -caddr_t addr; int len; -.DE -writes any modified pages back to the filesystem and updates -the file modification time. -If \fIlen\fP is 0, all modified pages within the region containing \fIaddr\fP -will be flushed; -if \fIlen\fP is non-zero, only the pages containing \fIaddr\fP and \fIlen\fP -succeeding locations will be examined. -Any required synchronization of memory caches -will also take place at this time. -Filesystem operations on a file that is mapped for shared modifications -are unpredictable except after an \fImsync\fP. -.PP -A mapping can be removed by the call -.DS -munmap(addr, len); -caddr_t addr; int len; -.DE -This call deletes the mappings for the specified address range, -and causes further references to addresses within the range -to generate invalid memory references. -.NH 3 -Page protection control -.PP -A process can control the protection of pages using the call -.DS -mprotect(addr, len, prot); -caddr_t addr; int len, prot; -.DE -This call changes the specified pages to have protection \fIprot\fP\|. -Not all implementations will guarantee protection on a page basis; -the granularity of protection changes may be as large as an entire region. -.NH 3 -Giving and getting advice -.PP -A process that has knowledge of its memory behavior may -use the \fImadvise\fP call: -.DS -madvise(addr, len, behav); -caddr_t addr; int len, behav; -.DE -\fIBehav\fP describes expected behavior, as given -in \fI<sys/mman.h>\fP: -.DS -.ta \w'#define\ \ 'u +\w'MADV_SEQUENTIAL\ \ 'u +\w'00\ \ \ \ 'u -#define MADV_NORMAL 0 /* no further special treatment */ -#define MADV_RANDOM 1 /* expect random page references */ -#define MADV_SEQUENTIAL 2 /* expect sequential references */ -#define MADV_WILLNEED 3 /* will need these pages */ -#define MADV_DONTNEED 4 /* don't need these pages */ -#define MADV_SPACEAVAIL 5 /* insure that resources are reserved */ -.DE -Finally, a process may obtain information about whether pages are -core resident by using the call -.DS -mincore(addr, len, vec) -caddr_t addr; int len; result char *vec; -.DE -Here the current core residency of the pages is returned -in the character array \fIvec\fP, with a value of 1 meaning -that the page is in-core. -.NH 3 -Synchronization primitives -.PP -Primitives are provided for synchronization using semaphores in shared memory. -Semaphores must lie within a MAP_SHARED region with at least modes -PROT_READ and PROT_WRITE. -The MAP_HASSEMAPHORE flag must have been specified when the region was created. -To acquire a lock a process calls: -.DS -value = mset(sem, wait) -result int value; semaphore *sem; int wait; -.DE -\fIMset\fP indivisibly tests and sets the semaphore \fIsem\fP. -If the previous value is zero, the process has acquired the lock -and \fImset\fP returns true immediately. -Otherwise, if the \fIwait\fP flag is zero, -failure is returned. -If \fIwait\fP is true and the previous value is non-zero, -\fImset\fP relinquishes the processor until notified that it should retry. -.LP -To release a lock a process calls: -.DS -mclear(sem) -semaphore *sem; -.DE -\fIMclear\fP indivisibly tests and clears the semaphore \fIsem\fP. -If the ``WANT'' flag is zero in the previous value, -\fImclear\fP returns immediately. -If the ``WANT'' flag is non-zero in the previous value, -\fImclear\fP arranges for waiting processes to retry before returning. -.PP -Two routines provide services analogous to the kernel -\fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of -shared memory. -A process may relinquish the processor by calling \fImsleep\fP -with a set semaphore: -.DS -msleep(sem) -semaphore *sem; -.DE -If the semaphore is still set when it is checked by the kernel, -the process will be put in a sleeping state -until some other process issues an \fImwakeup\fP for the same semaphore -within the region using the call: -.DS -mwakeup(sem) -semaphore *sem; -.DE -An \fImwakeup\fP may awaken all sleepers on the semaphore, -or may awaken only the next sleeper on a queue. diff --git a/share/doc/psd/05.sysman/1.3.t b/share/doc/psd/05.sysman/1.3.t deleted file mode 100644 index 30c70fff70d..00000000000 --- a/share/doc/psd/05.sysman/1.3.t +++ /dev/null @@ -1,252 +0,0 @@ -.\" $OpenBSD: 1.3.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.3.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Signals -.PP -.NH 3 -Overview -.PP -The system defines a set of \fIsignals\fP that may be delivered -to a process. Signal delivery resembles the occurrence of a hardware -interrupt: the signal is blocked from further occurrence, -the current process context is saved, and a new one -is built. A process may specify -the \fIhandler\fP to which a signal is delivered, or specify that -the signal is to be \fIblocked\fP or \fIignored\fP. A process may -also specify that a -\fIdefault\fP action is to be taken when signals occur. -.PP -Some signals -will cause a process to exit when they are not caught. This -may be accompanied by creation of a \fIcore\fP image file, containing -the current memory image of the process for use in post-mortem debugging. -A process may choose to have signals delivered on a special -stack, so that sophisticated software stack manipulations are possible. -.PP -All signals have the same \fIpriority\fP. If multiple signals -are pending simultaneously, the order in which they are delivered -to a process is implementation specific. Signal routines execute -with the signal that caused their invocation \fIblocked\fP, but other -signals may yet occur. Mechanisms are provided whereby critical sections -of code may protect themselves against the occurrence of specified signals. -.NH 3 -Signal types -.PP -The signals defined by the system fall into one of -five classes: hardware conditions, -software conditions, input/output notification, process control, or -resource control. -The set of signals is defined in the file \fI<signal.h>\fP. -.PP -Hardware signals are derived from exceptional conditions which -may occur during -execution. Such signals include SIGFPE representing floating -point and other arithmetic exceptions, SIGILL for illegal instruction -execution, SIGSEGV for addresses outside the currently assigned -area of memory, and SIGBUS for accesses that violate memory -protection constraints. -Other, more cpu-specific hardware signals exist, -such as those for the various customer-reserved instructions on -the VAX (SIGIOT, SIGEMT, and SIGTRAP). -.PP -Software signals reflect interrupts generated by user request: -SIGINT for the normal interrupt signal; SIGQUIT for the more -powerful \fIquit\fP signal, that normally causes a core image -to be generated; SIGHUP and SIGTERM that cause graceful -process termination, either because a user has ``hung up'', or -by user or program request; and SIGKILL, a more powerful termination -signal which a process cannot catch or ignore. -Programs may define their own asynchronous events using SIGUSR1 -and SIGUSR2. -Other software signals (SIGALRM, SIGVTALRM, SIGPROF) -indicate the expiration of interval timers. -.PP -A process can request notification via a SIGIO signal -when input or output is possible -on a descriptor, or when a \fInon-blocking\fP operation completes. -A process may request to receive a SIGURG signal when an -urgent condition arises. -.PP -A process may be \fIstopped\fP by a signal sent to it or the members -of its process group. The SIGSTOP signal is a powerful stop -signal, because it cannot be caught. Other stop signals -SIGTSTP, SIGTTIN, and SIGTTOU are used when a user request, input -request, or output request respectively is the reason for stopping the process. -A SIGCONT signal is sent to a process when it is -continued from a stopped state. -Processes may receive notification with a SIGCHLD signal when -a child process changes state, either by stopping or by terminating. -.PP -Exceeding resource limits may cause signals to be generated. -SIGXCPU occurs when a process nears its CPU time limit and SIGXFSZ -warns that the limit on file size creation has been reached. -.NH 3 -Signal handlers -.PP -A process has a handler associated with each signal. -The handler controls the way the signal is delivered. -The call -.DS -#include <signal.h> - -._f -struct sigvec { - int (*sv_handler)(); - int sv_mask; - int sv_flags; -}; - -sigvec(signo, sv, osv) -int signo; struct sigvec *sv; result struct sigvec *osv; -.DE -assigns interrupt handler address \fIsv_handler\fP to signal \fIsigno\fP. -Each handler address -specifies either an interrupt routine for the signal, that the -signal is to be ignored, -or that a default action (usually process termination) is to occur -if the signal occurs. -The constants -SIG_IGN and SIG_DEF used as values for \fIsv_handler\fP -cause ignoring or defaulting of a condition. -The \fIsv_mask\fP value specifies the -signal mask to be used when the handler is invoked; it implicitly includes -the signal which invoked the handler. -Signal masks include one bit for each signal; -the mask for a signal \fIsigno\fP is provided by the macro -\fIsigmask\fP(\fIsigno\fP), from \fI<signal.h>\fP. -\fISv_flags\fP specifies whether system calls should be -restarted if the signal handler returns and -whether the handler should operate on the normal run-time -stack or a special signal stack (see below). If \fIosv\fP -is non-zero, the previous signal vector is returned. -.PP -When a signal condition arises for a process, the signal -is added to a set of signals pending for the process. -If the signal is not currently \fIblocked\fP by the process -then it will be delivered. The process of signal delivery -adds the signal to be delivered and those signals -specified in the associated signal -handler's \fIsv_mask\fP to a set of those \fImasked\fP -for the process, saves the current process context, -and places the process in the context of the signal -handling routine. The call is arranged so that if the signal -handling routine exits normally the signal mask will be restored -and the process will resume execution in the original context. -If the process wishes to resume in a different context, then -it must arrange to restore the signal mask itself. -.PP -The mask of \fIblocked\fP signals is independent of handlers for -signals. It delays signals from being delivered much as a -raised hardware interrupt priority level delays hardware interrupts. -Preventing an interrupt from occurring by changing the handler is analogous to -disabling a device from further interrupts. -.PP -The signal handling routine \fIsv_handler\fP is called by a C call -of the form -.DS -(*sv_handler)(signo, code, scp); -int signo; long code; struct sigcontext *scp; -.DE -The \fIsigno\fP gives the number of the signal that occurred, and -the \fIcode\fP, a word of information supplied by the hardware. -The \fIscp\fP parameter is a pointer to a machine-dependent -structure containing the information for restoring the -context before the signal. -.NH 3 -Sending signals -.PP -A process can send a signal to another process or group of processes -with the calls: -.DS -kill(pid, signo) -int pid, signo; - -killpgrp(pgrp, signo) -int pgrp, signo; -.DE -Unless the process sending the signal is privileged, -it must have the same effective user id as the process receiving the signal. -.PP -Signals are also sent implicitly from a terminal device to the -process group associated with the terminal when certain input characters -are typed. -.NH 3 -Protecting critical sections -.PP -To block a section of code against one or more signals, a \fIsigblock\fP -call may be used to add a set of signals to the existing mask, returning -the old mask: -.DS -oldmask = sigblock(mask); -result long oldmask; long mask; -.DE -The old mask can then be restored later with \fIsigsetmask\fP\|, -.DS -oldmask = sigsetmask(mask); -result long oldmask; long mask; -.DE -The \fIsigblock\fP call can be used to read the current mask -by specifying an empty \fImask\fP\|. -.PP -It is possible to check conditions with some signals blocked, -and then to pause waiting for a signal and restoring the mask, by using: -.DS -sigpause(mask); -long mask; -.DE -.NH 3 -Signal stacks -.PP -Applications that maintain complex or fixed size stacks can use -the call -.DS -._f -struct sigstack { - caddr_t ss_sp; - int ss_onstack; -}; - -sigstack(ss, oss) -struct sigstack *ss; result struct sigstack *oss; -.DE -to provide the system with a stack based at \fIss_sp\fP for delivery -of signals. The value \fIss_onstack\fP indicates whether the -process is currently on the signal stack, -a notion maintained in software by the system. -.PP -When a signal is to be delivered, the system checks whether -the process is on a signal stack. If not, then the process is switched -to the signal stack for delivery, with the return from the signal -arranged to restore the previous stack. -.PP -If the process wishes to take a non-local exit from the signal routine, -or run code from the signal stack that uses a different stack, -a \fIsigstack\fP call should be used to reset the signal stack. diff --git a/share/doc/psd/05.sysman/1.4.t b/share/doc/psd/05.sysman/1.4.t deleted file mode 100644 index 97ca282c077..00000000000 --- a/share/doc/psd/05.sysman/1.4.t +++ /dev/null @@ -1,135 +0,0 @@ -.\" $OpenBSD: 1.4.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.4.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Timers -.NH 3 -Real time -.PP -The system's notion of the current Greenwich time and the current time -zone is set and returned by the call by the calls: -.DS -#include <sys/time.h> - -settimeofday(tvp, tzp); -struct timeval *tp; -struct timezone *tzp; - -gettimeofday(tp, tzp); -result struct timeval *tp; -result struct timezone *tzp; -.DE -where the structures are defined in \fI<sys/time.h>\fP as: -.DS -._f -struct timeval { - long tv_sec; /* seconds since Jan 1, 1970 */ - long tv_usec; /* and microseconds */ -}; - -struct timezone { - int tz_minuteswest; /* of Greenwich */ - int tz_dsttime; /* type of dst correction to apply */ -}; -.DE -The precision of the system clock is hardware dependent. -Earlier versions of UNIX contained only a 1-second resolution version -of this call, which remains as a library routine: -.DS -time(tvsec) -result long *tvsec; -.DE -returning only the tv_sec field from the \fIgettimeofday\fP call. -.NH 3 -Interval time -.PP -The system provides each process with three interval timers, -defined in \fI<sys/time.h>\fP: -.DS -._d -#define ITIMER_REAL 0 /* real time intervals */ -#define ITIMER_VIRTUAL 1 /* virtual time intervals */ -#define ITIMER_PROF 2 /* user and system virtual time */ -.DE -The ITIMER_REAL timer decrements -in real time. It could be used by a library routine to -maintain a wakeup service queue. A SIGALRM signal is delivered -when this timer expires. -.PP -The ITIMER_VIRTUAL timer decrements in process virtual time. -It runs only when the process is executing. A SIGVTALRM signal -is delivered when it expires. -.PP -The ITIMER_PROF timer decrements both in process virtual time and when -the system is running on behalf of the process. -It is designed to be used by processes to statistically profile -their execution. -A SIGPROF signal is delivered when it expires. -.PP -A timer value is defined by the \fIitimerval\fP structure: -.DS -._f -struct itimerval { - struct timeval it_interval; /* timer interval */ - struct timeval it_value; /* current value */ -}; -.DE -and a timer is set or read by the call: -.DS -getitimer(which, value); -int which; result struct itimerval *value; - -setitimer(which, value, ovalue); -int which; struct itimerval *value; result struct itimerval *ovalue; -.DE -The third argument to \fIsetitimer\fP specifies an optional structure -to receive the previous contents of the interval timer. -A timer can be disabled by specifying a timer value of 0. -.PP -The system rounds argument timer intervals to be not less than the -resolution of its clock. This clock resolution can be determined -by loading a very small value into a timer and reading the timer back to -see what value resulted. -.PP -The \fIalarm\fP system call of earlier versions of UNIX is provided -as a library routine using the ITIMER_REAL timer. The process -profiling facilities of earlier versions of UNIX -remain because -it is not always possible to guarantee -the automatic restart of system calls after -receipt of a signal. -The \fIprofil\fP call arranges for the kernel to begin gathering -execution statistics for a process: -.DS -profil(buf, bufsize, offset, scale); -result char *buf; int bufsize, offset, scale; -.DE -This begins sampling of the program counter, with statistics maintained -in the user-provided buffer. diff --git a/share/doc/psd/05.sysman/1.5.t b/share/doc/psd/05.sysman/1.5.t deleted file mode 100644 index 9371b7d8fb9..00000000000 --- a/share/doc/psd/05.sysman/1.5.t +++ /dev/null @@ -1,223 +0,0 @@ -.\" $OpenBSD: 1.5.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.5.t 8.1 (Berkeley) 6/8/93 -.\" -.sh Descriptors -.PP -.NH 3 -The reference table -.PP -Each process has access to resources through -\fIdescriptors\fP. Each descriptor is a handle allowing -the process to reference objects such as files, devices -and communications links. -.PP -Rather than allowing processes direct access to descriptors, the system -introduces a level of indirection, so that descriptors may be shared -between processes. Each process has a \fIdescriptor reference table\fP, -containing pointers to the actual descriptors. The descriptors -themselves thus have multiple references, and are reference counted by the -system. -.PP -Each process has a fixed size descriptor reference table, where -the size is returned by the \fIgetdtablesize\fP call: -.DS -nds = getdtablesize(); -result int nds; -.DE -and guaranteed to be at least 20. The entries in the descriptor reference -table are referred to by small integers; for example if there -are 20 slots they are numbered 0 to 19. -.NH 3 -Descriptor properties -.PP -Each descriptor has a logical set of properties maintained -by the system and defined by its \fItype\fP. -Each type supports a set of operations; -some operations, such as reading and writing, are common to several -abstractions, while others are unique. -The generic operations applying to many of these types are described -in section 2.1. Naming contexts, files and directories are described in -section 2.2. Section 2.3 describes communications domains and sockets. -Terminals and (structured and unstructured) devices are described -in section 2.4. -.NH 3 -Managing descriptor references -.PP -A duplicate of a descriptor reference may be made by doing -.DS -new = dup(old); -result int new; int old; -.DE -returning a copy of descriptor reference \fIold\fP indistinguishable from -the original. The \fInew\fP chosen by the system will be the -smallest unused descriptor reference slot. -A copy of a descriptor reference may be made in a specific slot -by doing -.DS -dup2(old, new); -int old, new; -.DE -The \fIdup2\fP call causes the system to deallocate the descriptor reference -current occupying slot \fInew\fP, if any, replacing it with a reference -to the same descriptor as old. -This deallocation is also performed by: -.DS -close(old); -int old; -.DE -.NH 3 -Multiplexing requests -.PP -The system provides a -standard way to do -synchronous and asynchronous multiplexing of operations. -.PP -Synchronous multiplexing is performed by using the \fIselect\fP call -to examine the state of multiple descriptors simultaneously, -and to wait for state changes on those descriptors. -Sets of descriptors of interest are specified as bit masks, -as follows: -.DS -#include <sys/types.h> - -nds = select(nd, in, out, except, tvp); -result int nds; int nd; result fd_set *in, *out, *except; -struct timeval *tvp; - -FD_ZERO(&fdset); -FD_SET(fd, &fdset); -FD_CLR(fd, &fdset); -FD_ISSET(fd, &fdset); -int fs; fs_set fdset; -.DE -The \fIselect\fP call examines the descriptors -specified by the -sets \fIin\fP, \fIout\fP and \fIexcept\fP, replacing -the specified bit masks by the subsets that select true for input, -output, and exceptional conditions respectively (\fInd\fP -indicates the number of file descriptors specified by the bit masks). -If any descriptors meet the following criteria, -then the number of such descriptors is returned in \fInds\fP and the -bit masks are updated. -.if n .ds bu * -.if t .ds bu \(bu -.IP \*(bu -A descriptor selects for input if an input oriented operation -such as \fIread\fP or \fIreceive\fP is possible, or if a -connection request may be accepted (see section 2.3.1.4). -.IP \*(bu -A descriptor selects for output if an output oriented operation -such as \fIwrite\fP or \fIsend\fP is possible, or if an operation -that was ``in progress'', such as connection establishment, -has completed (see section 2.1.3). -.IP \*(bu -A descriptor selects for an exceptional condition if a condition -that would cause a SIGURG signal to be generated exists (see section 1.3.2), -or other device-specific events have occurred. -.LP -If none of the specified conditions is true, the operation -waits for one of the conditions to arise, -blocking at most the amount of time specified by \fItvp\fP. -If \fItvp\fP is given as 0, the \fIselect\fP waits indefinitely. -.PP -Options affecting I/O on a descriptor -may be read and set by the call: -.DS -._d -dopt = fcntl(d, cmd, arg) -result int dopt; int d, cmd, arg; - -/* interesting values for cmd */ -#define F_SETFL 3 /* set descriptor options */ -#define F_GETFL 4 /* get descriptor options */ -#define F_SETOWN 5 /* set descriptor owner (pid/pgrp) */ -#define F_GETOWN 6 /* get descriptor owner (pid/pgrp) */ -.DE -The F_SETFL \fIcmd\fP may be used to set a descriptor in -non-blocking I/O mode and/or enable signaling when I/O is -possible. F_SETOWN may be used to specify a process or process -group to be signaled when using the latter mode of operation -or when urgent indications arise. -.PP -Operations on non-blocking descriptors will -either complete immediately, -note an error EWOULDBLOCK, -partially complete an input or output operation returning a partial count, -or return an error EINPROGRESS noting that the requested operation is -in progress. -A descriptor which has signalling enabled will cause the specified process -and/or process group -be signaled, with a SIGIO for input, output, or in-progress -operation complete, or -a SIGURG for exceptional conditions. -.PP -For example, when writing to a terminal -using non-blocking output, -the system will accept only as much data as there is buffer space for -and return; when making a connection on a \fIsocket\fP, the operation may -return indicating that the connection establishment is ``in progress''. -The \fIselect\fP facility can be used to determine when further -output is possible on the terminal, or when the connection establishment -attempt is complete. -.NH 3 -Descriptor wrapping.\(dg -.PP -.FS -\(dg The facilities described in this section are not included -in 4.3BSD. -.FE -A user process may build descriptors of a specified type by -\fIwrapping\fP a communications channel with a system supplied protocol -translator: -.DS -new = wrap(old, proto) -result int new; int old; struct dprop *proto; -.DE -Operations on the descriptor \fIold\fP are then translated by the -system provided protocol translator into requests on the underlying -object \fIold\fP in a way defined by the protocol. -The protocols supported by the kernel may vary from system to system -and are described in the programmers manual. -.PP -Protocols may be based on communications multiplexing or a rights-passing -style of handling multiple requests made on the same object. For instance, -a protocol for implementing a file abstraction may or may not include -locally generated ``read-ahead'' requests. A protocol that provides for -read-ahead may provide higher performance but have a more difficult -implementation. -.PP -Another example is the terminal driving facilities. Normally a terminal -is associated with a communications line, and the terminal type -and standard terminal access protocol are wrapped around a synchronous -communications line and given to the user. If a virtual terminal -is required, the terminal driver can be wrapped around a communications -link, the other end of which is held by a virtual terminal protocol -interpreter. diff --git a/share/doc/psd/05.sysman/1.6.t b/share/doc/psd/05.sysman/1.6.t deleted file mode 100644 index ad5bc980d15..00000000000 --- a/share/doc/psd/05.sysman/1.6.t +++ /dev/null @@ -1,133 +0,0 @@ -.\" $OpenBSD: 1.6.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.6.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Resource controls -.NH 3 -Process priorities -.PP -The system gives CPU scheduling priority to processes that have not used -CPU time recently. This tends to favor interactive processes and -processes that execute only for short periods. -It is possible to determine the priority currently -assigned to a process, process group, or the processes of a specified user, -or to alter this priority using the calls: -.DS -._d -#define PRIO_PROCESS 0 /* process */ -#define PRIO_PGRP 1 /* process group */ -#define PRIO_USER 2 /* user id */ - -prio = getpriority(which, who); -result int prio; int which, who; - -setpriority(which, who, prio); -int which, who, prio; -.DE -The value \fIprio\fP is in the range \-20 to 20. -The default priority is 0; lower priorities cause more -favorable execution. -The \fIgetpriority\fP call returns the highest priority (lowest numerical value) -enjoyed by any of the specified processes. -The \fIsetpriority\fP call sets the priorities of all of the -specified processes to the specified value. -Only the super-user may lower priorities. -.NH 3 -Resource utilization -.PP -The resources used by a process are returned by a \fIgetrusage\fP call, -returning information in a structure defined in \fI<sys/resource.h>\fP: -.DS -._d -#define RUSAGE_SELF 0 /* usage by this process */ -#define RUSAGE_CHILDREN -1 /* usage by all children */ - -getrusage(who, rusage) -int who; result struct rusage *rusage; - -._f -struct rusage { - struct timeval ru_utime; /* user time used */ - struct timeval ru_stime; /* system time used */ - int ru_maxrss; /* maximum core resident set size: kbytes */ - int ru_ixrss; /* integral shared memory size (kbytes*sec) */ - int ru_idrss; /* unshared data memory size */ - int ru_isrss; /* unshared stack memory size */ - int ru_minflt; /* page-reclaims */ - int ru_majflt; /* page faults */ - int ru_nswap; /* swaps */ - int ru_inblock; /* block input operations */ - int ru_oublock; /* block output operations */ - int ru_msgsnd; /* messages sent */ - int ru_msgrcv; /* messages received */ - int ru_nsignals; /* signals received */ - int ru_nvcsw; /* voluntary context switches */ - int ru_nivcsw; /* involuntary context switches */ -}; -.DE -The \fIwho\fP parameter specifies whose resource usage is to be returned. -The resources used by the current process, or by all -the terminated children of the current process may be requested. -.NH 3 -Resource limits -.PP -The resources of a process for which limits are controlled by the -kernel are defined in \fI<sys/resource.h>\fP, and controlled by the -\fIgetrlimit\fP and \fIsetrlimit\fP calls: -.DS -._d -#define RLIMIT_CPU 0 /* cpu time in milliseconds */ -#define RLIMIT_FSIZE 1 /* maximum file size */ -#define RLIMIT_DATA 2 /* maximum data segment size */ -#define RLIMIT_STACK 3 /* maximum stack segment size */ -#define RLIMIT_CORE 4 /* maximum core file size */ -#define RLIMIT_RSS 5 /* maximum resident set size */ - -#define RLIM_NLIMITS 6 - -#define RLIM_INFINITY 0x7f\&f\&f\&f\&f\&f\&f - -._f -struct rlimit { - int rlim_cur; /* current (soft) limit */ - int rlim_max; /* hard limit */ -}; - -getrlimit(resource, rlp) -int resource; result struct rlimit *rlp; - -setrlimit(resource, rlp) -int resource; struct rlimit *rlp; -.DE -.PP -Only the super-user can raise the maximum limits. -Other users may only -alter \fIrlim_cur\fP within the range from 0 to \fIrlim_max\fP -or (irreversibly) lower \fIrlim_max\fP. diff --git a/share/doc/psd/05.sysman/1.7.t b/share/doc/psd/05.sysman/1.7.t deleted file mode 100644 index 2a37599ec52..00000000000 --- a/share/doc/psd/05.sysman/1.7.t +++ /dev/null @@ -1,98 +0,0 @@ -.\" $OpenBSD: 1.7.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.7.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "System operation support -.PP -Unless noted otherwise, -the calls in this section are permitted only to a privileged user. -.NH 3 -Bootstrap operations -.PP -The call -.DS -mount(blkdev, dir, ronly); -char *blkdev, *dir; int ronly; -.DE -extends the UNIX name space. The \fImount\fP call specifies -a block device \fIblkdev\fP containing a UNIX file system -to be made available starting at \fIdir\fP. If \fIronly\fP is -set then the file system is read-only; writes to the file system -will not be permitted and access times will not be updated -when files are referenced. -\fIDir\fP is normally a name in the root directory. -.PP -The call -.DS -swapon(blkdev, size); -char *blkdev; int size; -.DE -specifies a device to be made available for paging and swapping. -.PP -.NH 3 -Shutdown operations -.PP -The call -.DS -unmount(dir); -char *dir; -.DE -unmounts the file system mounted on \fIdir\fP. -This call will succeed only if the file system is -not currently being used. -.PP -The call -.DS -sync(); -.DE -schedules input/output to clean all system buffer caches. -(This call does not require privileged status.) -.PP -The call -.DS -reboot(how) -int how; -.DE -causes a machine halt or reboot. The call may request a reboot -by specifying \fIhow\fP as RB_AUTOBOOT, or that the machine be halted -with RB_HALT. These constants are defined in \fI<sys/reboot.h>\fP. -.NH 3 -Accounting -.PP -The system optionally keeps an accounting record in a file -for each process that exits on the system. -The format of this record is beyond the scope of this document. -The accounting may be enabled to a file \fIname\fP by doing -.DS -acct(path); -char *path; -.DE -If \fIpath\fP is null, then accounting is disabled. Otherwise, -the named file becomes the accounting file. diff --git a/share/doc/psd/05.sysman/2.0.t b/share/doc/psd/05.sysman/2.0.t deleted file mode 100644 index 1707608ede5..00000000000 --- a/share/doc/psd/05.sysman/2.0.t +++ /dev/null @@ -1,81 +0,0 @@ -.\" $OpenBSD: 2.0.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.0.t 8.1 (Berkeley) 6/8/93 -.\" -.ds ss 1 -.sh "System facilities -This section discusses the system facilities that -are not considered part of the kernel. -.PP -The system abstractions described are: -.IP "Directory contexts -.br -A directory context is a position in the UNIX file system name -space. Operations on files and other named objects in a file system are -always specified relative to such a context. -.IP "Files -.br -Files are used to store uninterpreted sequence of bytes on which -random access \fIreads\fP and \fIwrites\fP may occur. -Pages from files may also be mapped into process address space.\(dg -A directory may be read as a file. -.FS -\(dg Support for mapping files is not included in the 4.3 release. -.FE -.IP "Communications domains -.br -A communications domain represents -an interprocess communications environment, such as the communications -facilities of the UNIX system, -communications in the INTERNET, or the resource sharing protocols -and access rights of a resource sharing system on a local network. -.IP "Sockets -.br -A socket is an endpoint of communication and the focal -point for IPC in a communications domain. Sockets may be created in pairs, -or given names and used to rendezvous with other sockets -in a communications domain, accepting connections from these -sockets or exchanging messages with them. These operations model -a labeled or unlabeled communications graph, and can be used in a -wide variety of communications domains. Sockets can have different -\fItypes\fP\| to provide different semantics of communication, -increasing the flexibility of the model. -.IP "Terminals and other devices -.br -Devices include -terminals, providing input editing and interrupt generation -and output flow control and editing, magnetic tapes, -disks and other peripherals. They often support the generic -\fIread\fP and \fIwrite\fP operations as well as a number of \fIioctl\fP\|s. -.IP "Processes -.br -Process descriptors provide facilities for control and debugging of -other processes. -.ds ss 2 diff --git a/share/doc/psd/05.sysman/2.1.t b/share/doc/psd/05.sysman/2.1.t deleted file mode 100644 index 1b6342ce5e3..00000000000 --- a/share/doc/psd/05.sysman/2.1.t +++ /dev/null @@ -1,136 +0,0 @@ -.\" $OpenBSD: 2.1.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.1.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Generic operations -.PP -.PP -Many system abstractions support the -operations \fIread\fP, \fIwrite\fP and \fIioctl\fP. We describe -the basics of these common primitives here. -Similarly, the mechanisms whereby normally synchronous operations -may occur in a non-blocking or asynchronous fashion are -common to all system-defined abstractions and are described here. -.NH 3 -Read and write -.PP -The \fIread\fP and \fIwrite\fP system calls can be applied -to communications channels, files, terminals and devices. -They have the form: -.DS -cc = read(fd, buf, nbytes); -result int cc; int fd; result caddr_t buf; int nbytes; - -cc = write(fd, buf, nbytes); -result int cc; int fd; caddr_t buf; int nbytes; -.DE -The \fIread\fP call transfers as much data as possible from the -object defined by \fIfd\fP to the buffer at address \fIbuf\fP of -size \fInbytes\fP. The number of bytes transferred is -returned in \fIcc\fP, which is \-1 if a return occurred before -any data was transferred because of an error or use of non-blocking -operations. -.PP -The \fIwrite\fP call transfers data from the buffer to the -object defined by \fIfd\fP. Depending on the type of \fIfd\fP, -it is possible that the \fIwrite\fP call will accept some portion -of the provided bytes; the user should resubmit the other bytes -in a later request in this case. -Error returns because of interrupted or otherwise incomplete operations -are possible. -.PP -Scattering of data on input or gathering of data for output -is also possible using an array of input/output vector descriptors. -The type for the descriptors is defined in \fI<sys/uio.h>\fP as: -.DS -._f -struct iovec { - caddr_t iov_msg; /* base of a component */ - int iov_len; /* length of a component */ -}; -.DE -The calls using an array of descriptors are: -.DS -cc = readv(fd, iov, iovlen); -result int cc; int fd; struct iovec *iov; int iovlen; - -cc = writev(fd, iov, iovlen); -result int cc; int fd; struct iovec *iov; int iovlen; -.DE -Here \fIiovlen\fP is the count of elements in the \fIiov\fP array. -.NH 3 -Input/output control -.PP -Control operations on an object are performed by the \fIioctl\fP -operation: -.DS -ioctl(fd, request, buffer); -int fd, request; caddr_t buffer; -.DE -This operation causes the specified \fIrequest\fP to be performed -on the object \fIfd\fP. The \fIrequest\fP parameter specifies -whether the argument buffer is to be read, written, read and written, -or is not needed, and also the size of the buffer, as well as the -request. -Different descriptor types and subtypes within descriptor types -may use distinct \fIioctl\fP requests. For example, -operations on terminals control flushing of input and output -queues and setting of terminal parameters; operations on -disks cause formatting operations to occur; operations on tapes -control tape positioning. -.PP -The names for basic control operations are defined in \fI<sys/ioctl.h>\fP. -.NH 3 -Non-blocking and asynchronous operations -.PP -A process that wishes to do non-blocking operations on one of -its descriptors sets the descriptor in non-blocking mode as -described in section 1.5.4. Thereafter the \fIread\fP call will -return a specific EWOULDBLOCK error indication if there is no data to be -\fIread\fP. The process may -\fIselect\fP the associated descriptor to determine when a read is -possible. -.PP -Output attempted when a descriptor can accept less than is requested -will either accept some of the provided data, returning a shorter than normal -length, or return an error indicating that the operation would block. -More output can be performed as soon as a \fIselect\fP call indicates -the object is writeable. -.PP -Operations other than data input or output -may be performed on a descriptor in a non-blocking fashion. -These operations will return with a characteristic error indicating -that they are in progress -if they cannot complete immediately. The descriptor -may then be \fIselect\fPed for \fIwrite\fP to find out -when the operation has been completed. When \fIselect\fP indicates -the descriptor is writeable, the operation has completed. -Depending on the nature of the descriptor and the operation, -additional activity may be started or the new state may be tested. diff --git a/share/doc/psd/05.sysman/2.2.t b/share/doc/psd/05.sysman/2.2.t deleted file mode 100644 index 6b63fe82889..00000000000 --- a/share/doc/psd/05.sysman/2.2.t +++ /dev/null @@ -1,468 +0,0 @@ -.\" $OpenBSD: 2.2.t,v 1.4 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.2.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "File system -.NH 3 -Overview -.PP -The file system abstraction provides access to a hierarchical -file system structure. -The file system contains directories (each of which may contain -other sub-directories) as well as files and references to other -objects such as devices and inter-process communications sockets. -.PP -Each file is organized as a linear array of bytes. No record -boundaries or system related information is present in -a file. -Files may be read and written in a random-access fashion. -The user may read the data in a directory as though -it were an ordinary file to determine the names of the contained files, -but only the system may write into the directories. -The file system stores only a small amount of ownership, protection and usage -information with a file. -.NH 3 -Naming -.PP -The file system calls take \fIpath name\fP arguments. -These consist of a zero or more component \fIfile names\fP -separated by ``/\^'' characters, where each file name -is up to 255 ASCII characters excluding null and ``/\^''. -.PP -Each process always has two naming contexts: one for the -root directory of the file system and one for the -current working directory. These are used -by the system in the filename translation process. -If a path name begins with a ``/\^'', it is called -a full path name and interpreted relative to the root directory context. -If the path name does not begin with a ``/\^'' it is called -a relative path name and interpreted relative to the current directory -context. -.PP -The system limits -the total length of a path name to 1024 characters. -.PP -The file name ``..'' in each directory refers to -the parent directory of that directory. -The parent directory of the root of the file system is always that directory. -.PP -The calls -.DS -chdir(path); -char *path; - -chroot(path) -char *path; -.DE -change the current working directory and root directory context of a process. -Only the super-user can change the root directory context of a process. -.NH 3 -Creation and removal -.PP -The file system allows directories, files, special devices, -and ``portals'' to be created and removed from the file system. -.NH 4 -Directory creation and removal -.PP -A directory is created with the \fImkdir\fP system call: -.DS -mkdir(path, mode); -char *path; int mode; -.DE -where the mode is defined as for files (see below). -Directories are removed with the \fIrmdir\fP system call: -.DS -rmdir(path); -char *path; -.DE -A directory must be empty if it is to be deleted. -.NH 4 -File creation -.PP -Files are created with the \fIopen\fP system call, -.DS -fd = open(path, oflag, mode); -result int fd; char *path; int oflag, mode; -.DE -The \fIpath\fP parameter specifies the name of the -file to be created. The \fIoflag\fP parameter must -include O_CREAT from below to cause the file to be created. -Bits for \fIoflag\fP are -defined in \fI<sys/file.h>\fP: -.DS -._d -#define O_RDONLY 000 /* open for reading */ -#define O_WRONLY 001 /* open for writing */ -#define O_RDWR 002 /* open for read & write */ -#define O_NDELAY 004 /* non-blocking open */ -#define O_APPEND 010 /* append on each write */ -#define O_CREAT 01000 /* open with file create */ -#define O_TRUNC 02000 /* open with truncation */ -#define O_EXCL 04000 /* error on create if file exists */ -.DE -.PP -One of O_RDONLY, O_WRONLY and O_RDWR should be specified, -indicating what types of operations are desired to be performed -on the open file. The operations will be checked against the user's -access rights to the file before allowing the \fIopen\fP to succeed. -Specifying O_APPEND causes writes to automatically append to the -file. -The flag O_CREAT causes the file to be created if it does not -exist, owned by the current user -and the group of the containing directory. -The protection for the new file is specified in \fImode\fP. -The file mode is used as a three digit octal number. -Each digit encodes read access as 4, write access as 2 and execute -access as 1, or'ed together. The 0700 bits describe owner -access, the 070 bits describe the access rights for processes in the same -group as the file, and the 07 bits describe the access rights -for other processes. -.PP -If the open specifies to create the file with O_EXCL -and the file already exists, then the \fIopen\fP will fail -without affecting the file in any way. This provides a -simple exclusive access facility. -If the file exists but is a symbolic link, the open will fail -regardless of the existence of the file specified by the link. -.NH 4 -Creating references to devices -.PP -The file system allows entries which reference peripheral devices. -Peripherals are distinguished as \fIblock\fP or \fIcharacter\fP -devices according by their ability to support block-oriented -operations. -Devices are identified by their ``major'' and ``minor'' -device numbers. The major device number determines the kind -of peripheral it is, while the minor device number indicates -one of possibly many peripherals of that kind. -Structured devices have all operations performed internally -in ``block'' quantities while -unstructured devices often have a number of -special \fIioctl\fP operations, and may have input and output -performed in varying units. -The \fImknod\fP call creates special entries: -.DS -mknod(path, mode, dev); -char *path; int mode, dev; -.DE -where \fImode\fP is formed from the object type -and access permissions. The parameter \fIdev\fP is a configuration -dependent parameter used to identify specific character or -block I/O devices. -.NH 4 -Portal creation\(dg -.PP -.FS -\(dg The \fIportal\fP call is not implemented in 4.3BSD. -.FE -The call -.DS -fd = portal(name, server, param, dtype, protocol, domain, socktype) -result int fd; char *name, *server, *param; int dtype, protocol; -int domain, socktype; -.DE -places a \fIname\fP in the file system name space that causes connection to a -server process when the name is used. -The portal call returns an active portal in \fIfd\fP as though an -access had occurred to activate an inactive portal, as now described. -.PP -When an inactive portal is accessed, the system sets up a socket -of the specified \fIsocktype\fP in the specified communications -\fIdomain\fP (see section 2.3), and creates the \fIserver\fP process, -giving it the specified \fIparam\fP as argument to help it identify -the portal, and also giving it the newly created socket as descriptor -number 0. The accessor of the portal will create a socket in the same -\fIdomain\fP and \fIconnect\fP to the server. The user will then -\fIwrap\fP the socket in the specified \fIprotocol\fP to create an object of -the required descriptor type \fIdtype\fP and proceed with the -operation which was in progress before the portal was encountered. -.PP -While the server process holds the socket (which it received as \fIfd\fP -from the \fIportal\fP call on descriptor 0 at activation) further references -will result in connections being made to the same socket. -.NH 4 -File, device, and portal removal -.PP -A reference to a file, special device or portal may be removed with the -\fIunlink\fP call, -.DS -unlink(path); -char *path; -.DE -The caller must have write access to the directory in which -the file is located for this call to be successful. -.NH 3 -Reading and modifying file attributes -.PP -Detailed information about the attributes of a file -may be obtained with the calls: -.DS -#include <sys/stat.h> - -stat(path, stb); -char *path; result struct stat *stb; - -fstat(fd, stb); -int fd; result struct stat *stb; -.DE -The \fIstat\fP structure includes the file -type, protection, ownership, access times, -size, and a count of hard links. -If the file is a symbolic link, then the status of the link -itself (rather than the file the link references) -may be found using the \fIlstat\fP call: -.DS -lstat(path, stb); -char *path; result struct stat *stb; -.DE -.PP -Newly created files are assigned the user id of the -process that created it and the group id of the directory -in which it was created. The ownership of a file may -be changed by either of the calls -.DS -chown(path, owner, group); -char *path; int owner, group; - -fchown(fd, owner, group); -int fd, owner, group; -.DE -.PP -In addition to ownership, each file has three levels of access -protection associated with it. These levels are owner relative, -group relative, and global (all users and groups). Each level -of access has separate indicators for read permission, write -permission, and execute permission. -The protection bits associated with a file may be set by either -of the calls: -.DS -chmod(path, mode); -char *path; int mode; - -fchmod(fd, mode); -int fd, mode; -.DE -where \fImode\fP is a value indicating the new protection -of the file, as listed in section 2.2.3.2. -.PP -Finally, the access and modify times on a file may be set by the call: -.DS -utimes(path, tvp) -char *path; struct timeval *tvp[2]; -.DE -This is particularly useful when moving files between media, to -preserve relationships between the times the file was modified. -.NH 3 -Links and renaming -.PP -Links allow multiple names for a file -to exist. Links exist independently of the file linked to. -.PP -Two types of links exist, \fIhard\fP links and \fIsymbolic\fP -links. A hard link is a reference counting mechanism that -allows a file to have multiple names within the same file -system. Symbolic links cause string substitution -during the pathname interpretation process. -.PP -Hard links and symbolic links have different -properties. A hard link insures the target -file will always be accessible, even after its original -directory entry is removed; no such guarantee exists for a symbolic link. -Symbolic links can span file systems boundaries. -.PP -The following calls create a new link, named \fIpath2\fP, -to \fIpath1\fP: -.DS -link(path1, path2); -char *path1, *path2; - -symlink(path1, path2); -char *path1, *path2; -.DE -The \fIunlink\fP primitive may be used to remove -either type of link. -.PP -If a file is a symbolic link, the ``value'' of the -link may be read with the \fIreadlink\fP call, -.DS -len = readlink(path, buf, bufsize); -result int len; result char *path, *buf; int bufsize; -.DE -This call returns, in \fIbuf\fP, the null-terminated string -substituted into pathnames passing through \fIpath\fP\|. -.PP -Atomic renaming of file system resident objects is possible -with the \fIrename\fP call: -.DS -rename(oldname, newname); -char *oldname, *newname; -.DE -where both \fIoldname\fP and \fInewname\fP must be -in the same file system. -If \fInewname\fP exists and is a directory, then it must be empty. -.NH 3 -Extension and truncation -.PP -Files are created with zero length and may be extended -simply by writing or appending to them. While a file is -open the system maintains a pointer into the file -indicating the current location in the file associated with -the descriptor. This pointer may be moved about in the -file in a random access fashion. -To set the current offset into a file, the \fIlseek\fP -call may be used, -.DS -oldoffset = lseek(fd, offset, type); -result off_t oldoffset; int fd; off_t offset; int type; -.DE -where \fItype\fP is given in \fI<sys/file.h>\fP as one of: -.DS -._d -#define SEEK_SET 0 /* set file offset to offset */ -#define SEEK_CUR 1 /* set file offset to current plus offset */ -#define SEEK_CUR 2 /* set file offset to EOF plus offset */ -.DE -The call ``lseek(fd, 0, SEEK_CUR)'' -returns the current offset into the file. -.PP -Files may have ``holes'' in them. Holes are void areas in the -linear extent of the file where data has never been -written. These may be created by seeking to -a location in a file past the current end-of-file and writing. -Holes are treated by the system as zero valued bytes. -.PP -A file may be truncated with either of the calls: -.DS -truncate(path, length); -char *path; int length; - -ftruncate(fd, length); -int fd, length; -.DE -reducing the size of the specified file to \fIlength\fP bytes. -.NH 3 -Checking accessibility -.PP -A process running with -different real and effective user ids -may interrogate the accessibility of a file to the -real user by using -the \fIaccess\fP call: -.DS -accessible = access(path, how); -result int accessible; char *path; int how; -.DE -Here \fIhow\fP is constructed by or'ing the following bits, defined -in \fI<sys/file.h>\fP: -.DS -._d -#define F_OK 0 /* file exists */ -#define X_OK 1 /* file is executable */ -#define W_OK 2 /* file is writable */ -#define R_OK 4 /* file is readable */ -.DE -The presence or absence of advisory locks does not affect the -result of \fIaccess\fP\|. -.NH 3 -Locking -.PP -The file system provides basic facilities that allow cooperating processes -to synchronize their access to shared files. A process may -place an advisory \fIread\fP or \fIwrite\fP lock on a file, -so that other cooperating processes may avoid interfering -with the process' access. This simple mechanism -provides locking with file granularity. More granular -locking can be built using the IPC facilities to provide a lock -manager. -The system does not force processes to obey the locks; -they are of an advisory nature only. -.PP -Locking is performed after an \fIopen\fP call by applying the -\fIflock\fP primitive, -.DS -flock(fd, how); -int fd, how; -.DE -where the \fIhow\fP parameter is formed from bits defined in \fI<sys/file.h>\fP: -.DS -._d -#define LOCK_SH 1 /* shared lock */ -#define LOCK_EX 2 /* exclusive lock */ -#define LOCK_NB 4 /* don't block when locking */ -#define LOCK_UN 8 /* unlock */ -.DE -Successive lock calls may be used to increase or -decrease the level of locking. If an object is currently -locked by another process when a \fIflock\fP call is made, -the caller will be blocked until the current lock owner -releases the lock; this may be avoided by including LOCK_NB -in the \fIhow\fP parameter. -Specifying LOCK_UN removes all locks associated with the descriptor. -Advisory locks held by a process are automatically deleted when -the process terminates. -.NH 3 -Disk quotas -.PP -As an optional facility, each file system may be requested to -impose limits on a user's disk usage. -Two quantities are limited: the total amount of disk space which -a user may allocate in a file system and the total number of files -a user may create in a file system. Quotas are expressed as -\fIhard\fP limits and \fIsoft\fP limits. A hard limit is -always imposed; if a user would exceed a hard limit, the operation -which caused the resource request will fail. A soft limit results -in the user receiving a warning message, but with allocation succeeding. -Facilities are provided to turn soft limits into hard limits if a -user has exceeded a soft limit for an unreasonable period of time. -.PP -To enable disk quotas on a file system the \fIsetquota\fP call -is used: -.DS -setquota(special, file) -char *special, *file; -.DE -where \fIspecial\fP refers to a structured device file where -a mounted file system exists, and -\fIfile\fP refers to a disk quota file (residing on the file -system associated with \fIspecial\fP) from which user quotas -should be obtained. The format of the disk quota file is -implementation dependent. -.PP -To manipulate disk quotas the \fIquota\fP call is provided: -.DS -#include <sys/quota.h> - -quota(cmd, uid, arg, addr) -int cmd, uid, arg; caddr_t addr; -.DE -The indicated \fIcmd\fP is applied to the user ID \fIuid\fP. -The parameters \fIarg\fP and \fIaddr\fP are command specific. -The file \fI<sys/quota.h>\fP contains definitions pertinent to the -use of this call. diff --git a/share/doc/psd/05.sysman/2.3.t b/share/doc/psd/05.sysman/2.3.t deleted file mode 100644 index f733f81d9b1..00000000000 --- a/share/doc/psd/05.sysman/2.3.t +++ /dev/null @@ -1,410 +0,0 @@ -.\" $OpenBSD: 2.3.t,v 1.4 2007/06/25 15:57:28 jmc Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.3.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Interprocess communications -.NH 3 -Interprocess communication primitives -.NH 4 -Communication domains -.PP -The system provides access to an extensible set of -communication \fIdomains\fP. A communication domain -is identified by a manifest constant defined in the -file \fI<sys/socket.h>\fP. -Important standard domains supported by the system are the ``unix'' -domain, AF_UNIX, for communication within the system, the ``Internet'' -domain for communication in the DARPA Internet, AF_INET, -and the ``NS'' domain, AF_NS, for communication -using the Xerox Network Systems protocols. -Other domains can be added to the system. -.NH 4 -Socket types and protocols -.PP -Within a domain, communication takes place between communication endpoints -known as \fIsockets\fP. Each socket has the potential to exchange -information with other sockets of an appropriate type within the domain. -.PP -Each socket has an associated -abstract type, which describes the semantics of communication using that -socket. Properties such as reliability, ordering, and prevention -of duplication of messages are determined by the type. -The basic set of socket types is defined in \fI<sys/socket.h>\fP: -.DS -/* Standard socket types */ -._d -#define SOCK_DGRAM 1 /* datagram */ -#define SOCK_STREAM 2 /* virtual circuit */ -#define SOCK_RAW 3 /* raw socket */ -#define SOCK_RDM 4 /* reliably-delivered message */ -#define SOCK_SEQPACKET 5 /* sequenced packets */ -.DE -The SOCK_DGRAM type models the semantics of datagrams in network communication: -messages may be lost or duplicated and may arrive out-of-order. -A datagram socket may send messages to and receive messages from multiple -peers. -The SOCK_RDM type models the semantics of reliable datagrams: messages -arrive unduplicated and in-order, the sender is notified if -messages are lost. -The \fIsend\fP and \fIreceive\fP operations (described below) -generate reliable/unreliable datagrams. -The SOCK_STREAM type models connection-based virtual circuits: two-way -byte streams with no record boundaries. -Connection setup is required before data communication may begin. -The SOCK_SEQPACKET type models a connection-based, -full-duplex, reliable, sequenced packet exchange; -the sender is notified if messages are lost, and messages are never -duplicated or presented out-of-order. -Users of the last two abstractions may use the facilities for -out-of-band transmission to send out-of-band data. -.PP -SOCK_RAW is used for unprocessed access to internal network layers -and interfaces; it has no specific semantics. -.PP -Other socket types can be defined. -.PP -Each socket may have a specific \fIprotocol\fP associated with it. -This protocol is used within the domain to provide the semantics -required by the socket type. -Not all socket types are supported by each domain; -support depends on the existence and the implementation -of a suitable protocol within the domain. -For example, within the ``Internet'' domain, the SOCK_DGRAM type may be -implemented by the UDP user datagram protocol, and the SOCK_STREAM -type may be implemented by the TCP transmission control protocol, while -no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets exist. -.NH 4 -Socket creation, naming and service establishment -.PP -Sockets may be \fIconnected\fP or \fIunconnected\fP. An unconnected -socket descriptor is obtained by the \fIsocket\fP call: -.DS -s = socket(domain, type, protocol); -result int s; int domain, type, protocol; -.DE -The socket domain and type are as described above, -and are specified using the definitions from \fI<sys/socket.h>\fP. -The protocol may be given as 0, meaning any suitable protocol. -One of several possible protocols may be selected using identifiers -obtained from a library routine, \fIgetprotobyname\fP. -.PP -An unconnected socket descriptor of a connection-oriented type -may yield a connected socket descriptor -in one of two ways: either by actively connecting to another socket, -or by becoming associated with a name in the communications domain and -\fIaccepting\fP a connection from another socket. -Datagram sockets need not establish connections before use. -.PP -To accept connections or to receive datagrams, -a socket must first have a binding -to a name (or address) within the communications domain. -Such a binding may be established by a \fIbind\fP call: -.DS -bind(s, name, namelen); -int s; struct sockaddr *name; int namelen; -.DE -Datagram sockets may have default bindings established when first -sending data if not explicitly bound earlier. -In either case, -a socket's bound name may be retrieved with a \fIgetsockname\fP call: -.DS -getsockname(s, name, namelen); -int s; result struct sockaddr *name; result int *namelen; -.DE -while the peer's name can be retrieved with \fIgetpeername\fP: -.DS -getpeername(s, name, namelen); -int s; result struct sockaddr *name; result int *namelen; -.DE -Domains may support sockets with several names. -.NH 4 -Accepting connections -.PP -Once a binding is made to a connection-oriented socket, -it is possible to \fIlisten\fP for connections: -.DS -listen(s, backlog); -int s, backlog; -.DE -The \fIbacklog\fP specifies the maximum count of connections -that can be simultaneously queued awaiting acceptance. -.PP -An \fIaccept\fP call: -.DS -t = accept(s, name, anamelen); -result int t; int s; result struct sockaddr *name; result int *anamelen; -.DE -returns a descriptor for a new, connected, socket -from the queue of pending connections on \fIs\fP. -If no new connections are queued for acceptance, -the call will wait for a connection unless non-blocking I/O has been enabled. -.NH 4 -Making connections -.PP -An active connection to a named socket is made by the \fIconnect\fP call: -.DS -connect(s, name, namelen); -int s; struct sockaddr *name; int namelen; -.DE -Although datagram sockets do not establish connections, -the \fIconnect\fP call may be used with such sockets -to create an \fIassociation\fP with the foreign address. -The address is recorded for use in future \fIsend\fP calls, -which then need not supply destination addresses. -Datagrams will be received only from that peer, -and asynchronous error reports may be received. -.PP -It is also possible to create connected pairs of sockets without -using the domain's name space to rendezvous; this is done with the -\fIsocketpair\fP call\(dg: -.FS -\(dg 4.3BSD supports \fIsocketpair\fP creation only in the ``unix'' -communication domain. -.FE -.DS -socketpair(domain, type, protocol, sv); -int domain, type, protocol; result int sv[2]; -.DE -Here the returned \fIsv\fP descriptors correspond to those obtained with -\fIaccept\fP and \fIconnect\fP. -.PP -The call -.DS -pipe(pv) -result int pv[2]; -.DE -creates a pair of SOCK_STREAM sockets in the UNIX domain, -with pv[0] only writable and pv[1] only readable. -.NH 4 -Sending and receiving data -.PP -Messages may be sent from a socket by: -.DS -cc = sendto(s, buf, len, flags, to, tolen); -result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen; -.DE -if the socket is not connected or: -.DS -cc = send(s, buf, len, flags); -result int cc; int s; caddr_t buf; int len, flags; -.DE -if the socket is connected. -The corresponding receive primitives are: -.DS -msglen = recvfrom(s, buf, len, flags, from, fromlenaddr); -result int msglen; int s; result caddr_t buf; int len, flags; -result caddr_t from; result int *fromlenaddr; -.DE -and -.DS -msglen = recv(s, buf, len, flags); -result int msglen; int s; result caddr_t buf; int len, flags; -.DE -.PP -In the unconnected case, -the parameters \fIto\fP and \fItolen\fP -specify the destination or source of the message, while -the \fIfrom\fP parameter stores the source of the message, -and \fI*fromlenaddr\fP initially gives the size of the \fIfrom\fP -buffer and is updated to reflect the true length of the \fIfrom\fP -address. -.PP -All calls cause the message to be received in or sent from -the message buffer of length \fIlen\fP bytes, starting at address \fIbuf\fP. -The \fIflags\fP specify -peeking at a message without reading it or sending or receiving -high-priority out-of-band messages, as follows: -.DS -._d -#define MSG_PEEK 0x1 /* peek at incoming message */ -#define MSG_OOB 0x2 /* process out-of-band data */ -.DE -.NH 4 -Scatter/gather and exchanging access rights -.PP -It is possible scatter and gather data and to exchange access rights -with messages. When either of these operations is involved, -the number of parameters to the call becomes large. -Thus the system defines a message header structure, in \fI<sys/socket.h>\fP, -which can be -used to conveniently contain the parameters to the calls: -.DS -.if t .ta .5i 1.25i 2i 2.7i -.if n ._f -struct msghdr { - caddr_t msg_name; /* optional address */ - int msg_namelen; /* size of address */ - struct iov *msg_iov; /* scatter/gather array */ - int msg_iovlen; /* # elements in msg_iov */ - caddr_t msg_accrights; /* access rights sent/received */ - int msg_accrightslen; /* size of msg_accrights */ -}; -.DE -Here \fImsg_name\fP and \fImsg_namelen\fP specify the source or destination -address if the socket is unconnected; \fImsg_name\fP may be given as -a null pointer if no names are desired or required. -The \fImsg_iov\fP and \fImsg_iovlen\fP describe the scatter/gather -locations, as described in section 2.1.3. -Access rights to be sent along with the message are specified -in \fImsg_accrights\fP, which has length \fImsg_accrightslen\fP. -In the ``unix'' domain these are an array of integer descriptors, -taken from the sending process and duplicated in the receiver. -.PP -This structure is used in the operations \fIsendmsg\fP and \fIrecvmsg\fP: -.DS -sendmsg(s, msg, flags); -int s; struct msghdr *msg; int flags; - -msglen = recvmsg(s, msg, flags); -result int msglen; int s; result struct msghdr *msg; int flags; -.DE -.NH 4 -Using read and write with sockets -.PP -The normal UNIX \fIread\fP and \fIwrite\fP calls may be -applied to connected sockets and translated into \fIsend\fP and \fIreceive\fP -calls from or to a single area of memory and discarding any rights -received. A process may operate on a virtual circuit socket, a terminal -or a file with blocking or non-blocking input/output -operations without distinguishing the descriptor type. -.NH 4 -Shutting down halves of full-duplex connections -.PP -A process that has a full-duplex socket such as a virtual circuit -and no longer wishes to read from or write to this socket can -give the call: -.DS -shutdown(s, direction); -int s, direction; -.DE -where \fIdirection\fP is 0 to not read further, 1 to not -write further, or 2 to completely shut the connection down. -If the underlying protocol supports unidirectional or bidirectional shutdown, -this indication will be passed to the peer. -For example, a shutdown for writing might produce an end-of-file -condition at the remote end. -.NH 4 -Socket and protocol options -.PP -Sockets, and their underlying communication protocols, may -support \fIoptions\fP. These options may be used to manipulate -implementation- or protocol-specific facilities. -The \fIgetsockopt\fP -and \fIsetsockopt\fP calls are used to control options: -.DS -getsockopt(s, level, optname, optval, optlen) -int s, level, optname; result caddr_t optval; result int *optlen; - -setsockopt(s, level, optname, optval, optlen) -int s, level, optname; caddr_t optval; int optlen; -.DE -The option \fIoptname\fP is interpreted at the indicated -protocol \fIlevel\fP for socket \fIs\fP. If a value is specified -with \fIoptval\fP and \fIoptlen\fP, it is interpreted by -the software operating at the specified \fIlevel\fP. The \fIlevel\fP -SOL_SOCKET is reserved to indicate options maintained -by the socket facilities. Other \fIlevel\fP values indicate -a particular protocol which is to act on the option request; -these values are normally interpreted as a ``protocol number''. -.NH 3 -UNIX domain -.PP -This section describes briefly the properties of the UNIX communications -domain. -.NH 4 -Types of sockets -.PP -In the UNIX domain, -the SOCK_STREAM abstraction provides pipe-like -facilities, while SOCK_DGRAM provides (usually) -reliable message-style communications. -.NH 4 -Naming -.PP -Socket names are strings and may appear in the UNIX file -system name space through portals\(dg. -.FS -\(dg The 4.3BSD implementation of the UNIX domain embeds -bound sockets in the UNIX file system name space; -this may change in future releases. -.FE -.NH 4 -Access rights transmission -.PP -The ability to pass UNIX descriptors with messages in this domain -allows migration of service within the system and allows -user processes to be used in building system facilities. -.NH 3 -INTERNET domain -.PP -This section describes briefly how the Internet domain is -mapped to the model described in this section. More -information will be found in the document describing the -network implementation in 4.3BSD. -.NH 4 -Socket types and protocols -.PP -SOCK_STREAM is supported by the Internet TCP protocol; -SOCK_DGRAM by the UDP protocol. -Each is layered atop the transport-level Internet Protocol (IP). -The Internet Control Message Protocol is implemented atop/beside IP -and is accessible via a raw socket. -The SOCK_SEQPACKET -has no direct Internet family analogue; a protocol -based on one from the XEROX NS family and layered on -top of IP could be implemented to fill this gap. -.NH 4 -Socket naming -.PP -Sockets in the Internet domain have names composed of the 32 bit -Internet address, and a 16 bit port number. -Options may be used to -provide IP source routing or security options. -The 32-bit address is composed of network and host parts; -the network part is variable in size and is frequency encoded. -The host part may optionally be interpreted as a subnet field -plus the host on subnet; this is enabled by setting a network address -mask at boot time. -.NH 4 -Access rights transmission -.PP -No access rights transmission facilities are provided in the Internet domain. -.NH 4 -Raw access -.PP -The Internet domain allows the super-user access to the raw facilities -of IP. -These interfaces are modeled as SOCK_RAW sockets. -Each raw socket is associated with one IP protocol number, -and receives all traffic received for that protocol. -This allows administrative and debugging -functions to occur, -and enables user-level implementations of special-purpose protocols -such as inter-gateway routing protocols. diff --git a/share/doc/psd/05.sysman/2.4.t b/share/doc/psd/05.sysman/2.4.t deleted file mode 100644 index 3a7ccedcdca..00000000000 --- a/share/doc/psd/05.sysman/2.4.t +++ /dev/null @@ -1,172 +0,0 @@ -.\" $OpenBSD: 2.4.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.4.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Terminals and Devices -.NH 3 -Terminals -.PP -Terminals support \fIread\fP and \fIwrite\fP I/O operations, -as well as a collection of terminal specific \fIioctl\fP operations, -to control input character interpretation and editing, -and output format and delays. -.NH 4 -Terminal input -.PP -Terminals are handled according to the underlying communication -characteristics such as baud rate and required delays, -and a set of software parameters. -.NH 5 -Input modes -.PP -A terminal is in one of three possible modes: \fIraw\fP, \fIcbreak\fP, -or \fIcooked\fP. -In raw mode all input is passed through to the -reading process immediately and without interpretation. -In cbreak mode, the handler interprets input only by looking -for characters that cause interrupts or output flow control; -all other characters are made available as in raw mode. -In cooked mode, input -is processed to provide standard line-oriented local editing functions, -and input is presented on a line-by-line basis. -.NH 5 -Interrupt characters -.PP -Interrupt characters are interpreted by the terminal handler only in -cbreak and cooked modes, and -cause a software interrupt to be sent to all processes in the process -group associated with the terminal. Interrupt characters exist -to send SIGINT -and SIGQUIT signals, -and to stop a process group -with the SIGTSTP signal either immediately, or when -all input up to the stop character has been read. -.NH 5 -Line editing -.PP -When the terminal is in cooked mode, editing of an input line -is performed. Editing facilities allow deletion of the previous -character or word, or deletion of the current input line. -In addition, a special character may be used to reprint the current -input line after some number of editing operations have been applied. -.PP -Certain other characters are interpreted specially when a process is -in cooked mode. The \fIend of line\fP character determines -the end of an input record. The \fIend of file\fP character simulates -an end of file occurrence on terminal input. Flow control is provided -by \fIstop output\fP and \fIstart output\fP control characters. Output -may be flushed with the \fIflush output\fP character; and a \fIliteral -character\fP may be used to force literal input of the immediately -following character in the input line. -.PP -Input characters may be echoed to the terminal as they are received. -Non-graphic ASCII input characters may be echoed as a two-character -printable representation, ``^character.'' -.NH 4 -Terminal output -.PP -On output, the terminal handler provides some simple formatting services. -These include converting the carriage return character to the -two character return-linefeed sequence, -inserting delays after certain standard control characters, -expanding tabs, and providing translations -for upper-case only terminals. -.NH 4 -Terminal control operations -.PP -When a terminal is first opened it is initialized to a standard -state and configured with a set of standard control, editing, -and interrupt characters. A process -may alter this configuration with certain -control operations, specifying parameters in a standard structure:\(dg -.FS -\(dg The control interface described here is an internal interface only -in 4.3BSD. Future releases will probably use a modified interface -based on currently-proposed standards. -.FE -.DS -._f -struct ttymode { - short tt_ispeed; /* input speed */ - int tt_iflags; /* input flags */ - short tt_ospeed; /* output speed */ - int tt_oflags; /* output flags */ -}; -.DE -and ``special characters'' are specified with the -\fIttychars\fP structure, -.DS -._f -struct ttychars { - char tc_erasec; /* erase char */ - char tc_killc; /* erase line */ - char tc_intrc; /* interrupt */ - char tc_quitc; /* quit */ - char tc_startc; /* start output */ - char tc_stopc; /* stop output */ - char tc_eofc; /* end-of-file */ - char tc_brkc; /* input delimiter (like nl) */ - char tc_suspc; /* stop process signal */ - char tc_dsuspc; /* delayed stop process signal */ - char tc_rprntc; /* reprint line */ - char tc_flushc; /* flush output (toggles) */ - char tc_werasc; /* word erase */ - char tc_lnextc; /* literal next character */ -}; -.DE -.NH 4 -Terminal hardware support -.PP -The terminal handler allows a user to access basic -hardware related functions; e.g. line speed, -modem control, parity, and stop bits. A special signal, -SIGHUP, is automatically -sent to processes in a terminal's process -group when a carrier transition is detected. This is -normally associated with a user hanging up on a modem -controlled terminal line. -.NH 3 -Structured devices -.PP -Structures devices are typified by disks and magnetic -tapes, but may represent any random-access device. -The system performs read-modify-write type buffering actions on block -devices to allow them to be read and written in a totally random -access fashion like ordinary files. -File systems are normally created in block devices. -.NH 3 -Unstructured devices -.PP -Unstructured devices are those devices which -do not support block structure. Familiar unstructured devices -are raw communications lines (with -no terminal handler), raster plotters, magnetic tape and disks unfettered -by buffering and permitting large block input/output and positioning -and formatting commands. diff --git a/share/doc/psd/05.sysman/2.5.t b/share/doc/psd/05.sysman/2.5.t deleted file mode 100644 index b2dda7a1bbc..00000000000 --- a/share/doc/psd/05.sysman/2.5.t +++ /dev/null @@ -1,37 +0,0 @@ -.\" $OpenBSD: 2.5.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.5.t 8.1 (Berkeley) 6/8/93 -.\" -.sh "Process and kernel descriptors -.PP -The status of the facilities in this section is still under discussion. -The \fIptrace\fP facility of earlier UNIX systems -remains in 4.3BSD. -Planned enhancements would allow a descriptor-based process control facility. diff --git a/share/doc/psd/05.sysman/Makefile b/share/doc/psd/05.sysman/Makefile deleted file mode 100644 index e6ad009e7ab..00000000000 --- a/share/doc/psd/05.sysman/Makefile +++ /dev/null @@ -1,12 +0,0 @@ -# $OpenBSD: Makefile,v 1.2 2001/02/03 08:15:04 niklas Exp $ - - -DIR= psd/05.sysman -SRCS= 0.t 1.0.t 1.1.t 1.2.t 1.3.t 1.4.t 1.5.t 1.6.t 1.7.t \ - 2.0.t 2.1.t 2.2.t 2.3.t 2.4.t 2.5.t a.t -MACROS= -ms - -paper.ps: ${SRCS} - ${TBL} ${SRCS} | ${ROFF} > ${.TARGET} - -.include <bsd.doc.mk> diff --git a/share/doc/psd/05.sysman/a.t b/share/doc/psd/05.sysman/a.t deleted file mode 100644 index 00e08d0cce0..00000000000 --- a/share/doc/psd/05.sysman/a.t +++ /dev/null @@ -1,233 +0,0 @@ -.\" $OpenBSD: a.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1983, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)a.t 8.1 (Berkeley) 6/8/93 -.\" -.ds RH Summary of facilities -.bp -.SH -\s+2I. Summary of facilities\s0 -.PP -.de h -.br -.if n .ne 8 -\fB\\$1 \\$2\fP -.br -.. -.nr H1 0 -.NH -Kernel primitives -.LP -.h 1.1. "Process naming and protection -.in +5 -.TS -lw(1.6i) aw(3i). -sethostid set UNIX host id -gethostid get UNIX host id -sethostname set UNIX host name -gethostname get UNIX host name -getpid get process id -fork create new process -exit terminate a process -execve execute a different process -getuid get user id -geteuid get effective user id -setreuid set real and effective user id's -getgid get accounting group id -getegid get effective accounting group id -getgroups get access group set -setregid set real and effective group id's -setgroups set access group set -getpgrp get process group -setpgrp set process group -.TE -.in -5 -.h 1.2 "Memory management -.in +5 -.TS -lw(1.6i) aw(3i). -<sys/mman.h> memory management definitions -sbrk change data section size -sstk\(dg change stack section size -.FS -\(dg Not supported in 4.3BSD. -.FE -getpagesize get memory page size -mmap\(dg map pages of memory -msync\(dg flush modified mapped pages to filesystem -munmap\(dg unmap memory -mprotect\(dg change protection of pages -madvise\(dg give memory management advice -mincore\(dg determine core residency of pages -msleep\(dg sleep on a lock -mwakeup\(dg wakeup process sleeping on a lock -.TE -.in -5 -.h 1.3 "Signals -.in +5 -.TS -lw(1.6i) aw(3i). -<signal.h> signal definitions -sigvec set handler for signal -kill send signal to process -killpgrp send signal to process group -sigblock block set of signals -sigsetmask restore set of blocked signals -sigpause wait for signals -sigstack set software stack for signals -.TE -.in -5 -.h 1.4 "Timing and statistics -.in +5 -.TS -lw(1.6i) aw(3i). -<sys/time.h> time-related definitions -gettimeofday get current time and timezone -settimeofday set current time and timezone -getitimer read an interval timer -setitimer get and set an interval timer -profil profile process -.TE -.in -5 -.h 1.5 "Descriptors -.in +5 -.TS -lw(1.6i) aw(3i). -getdtablesize descriptor reference table size -dup duplicate descriptor -dup2 duplicate to specified index -close close descriptor -select multiplex input/output -fcntl control descriptor options -wrap\(dg wrap descriptor with protocol -.FS -\(dg Not supported in 4.3BSD. -.FE -.TE -.in -5 -.h 1.6 "Resource controls -.in +5 -.TS -lw(1.6i) aw(3i). -<sys/resource.h> resource-related definitions -getpriority get process priority -setpriority set process priority -getrusage get resource usage -getrlimit get resource limitations -setrlimit set resource limitations -.TE -.in -5 -.h 1.7 "System operation support -.in +5 -.TS -lw(1.6i) aw(3i). -mount mount a device file system -swapon add a swap device -umount umount a file system -sync flush system caches -reboot reboot a machine -acct specify accounting file -.TE -.in -5 -.NH -System facilities -.LP -.h 2.1 "Generic operations -.in +5 -.TS -lw(1.6i) aw(3i). -read read data -write write data -<sys/uio.h> scatter-gather related definitions -readv scattered data input -writev gathered data output -<sys/ioctl.h> standard control operations -ioctl device control operation -.TE -.in -5 -.h 2.2 "File system -.PP -Operations marked with a * exist in two forms: as shown, -operating on a file name, and operating on a file descriptor, -when the name is preceded with a ``f''. -.in +5 -.TS -lw(1.6i) aw(3i). -<sys/file.h> file system definitions -chdir change directory -chroot change root directory -mkdir make a directory -rmdir remove a directory -open open a new or existing file -mknod make a special file -portal\(dg make a portal entry -unlink remove a link -stat* return status for a file -lstat returned status of link -chown* change owner -chmod* change mode -utimes change access/modify times -link make a hard link -symlink make a symbolic link -readlink read contents of symbolic link -rename change name of file -lseek reposition within file -truncate* truncate file -access determine accessibility -flock lock a file -.TE -.in -5 -.h 2.3 "Communications -.in +5 -.TS -lw(1.6i) aw(3i). -<sys/socket.h> standard definitions -socket create socket -bind bind socket to name -getsockname get socket name -listen allow queuing of connections -accept accept a connection -connect connect to peer socket -socketpair create pair of connected sockets -sendto send data to named socket -send send data to connected socket -recvfrom receive data on unconnected socket -recv receive data on connected socket -sendmsg send gathered data and/or rights -recvmsg receive scattered data and/or rights -shutdown partially close full-duplex connection -getsockopt get socket option -setsockopt set socket option -.TE -.in -5 -.h 2.4 "Terminals, block and character devices -.in +5 -.in -5 -.h 2.5 "Processes and kernel hooks -.in -5 diff --git a/share/doc/psd/05.sysman/spell.ok b/share/doc/psd/05.sysman/spell.ok deleted file mode 100644 index b0cbd9ce9cf..00000000000 --- a/share/doc/psd/05.sysman/spell.ok +++ /dev/null @@ -1,332 +0,0 @@ -AF -ANON -AUTOBOOT -Behav -CLR -DEF -DGRAM -DONTNEED -Datagram -Datagrams -EINPROGRESS -EWOULDBLOCK -EXCL -FD -FSIZE -Fabry -GETFL -GETOWN -HASSEMAPHORE -HASSEMPHORE -IGN -INCR -INET -IP -IPC -ISSET -ITIMER -Karels -Leffler -MADV -MAXHOSTNAMELEN -MSG -Manual''PS1:6 -McKusick -Mclear -Mset -NB -NDELAY -NGROUPS -NLIMITS -NOEXTEND -NS -OOB -PGRP -PRIO -PROT -PS1:6 -RB -RDM -RDONLY -RDWR -RH -RLIM -RLIMIT -RSS -RUSAGE -SEQPACKET -SETFL -SETOWN -SIG -SIGALRM -SIGBUS -SIGCHLD -SIGCONT -SIGEMT -SIGFPE -SIGHUP -SIGILL -SIGINT -SIGIO -SIGIOT -SIGKILL -SIGPROF -SIGQUIT -SIGSEGV -SIGSTOP -SIGTERM -SIGTRAP -SIGTSTP -SIGTTIN -SIGTTOU -SIGURG -SIGUSR1 -SIGUSR2 -SIGVTALRM -SIGXCPU -SIGXFSZ -Sem -Sv -TCP -TRUNC -UDP -VAX -WILLNEED -WRONLY -XTND -accessor -accrights -accrightslen -addr -anamelen -arg -argv -arusage -astatus -behav -blkdev -brkc -bu -buf -buflen -bufsize -caddr -cbreak -chroot -cmd -datagram -datagrams -dev -dopt -dprop -ds -dst -dsttime -dsuspc -dtype -dup2 -egid -envp -eofc -erasec -errno -euid -fchmod -fchown -fcntl -fd -fdset -file.h -filename -filesystem -flushc -fromlenaddr -fs -fstat -ftruncate -getdtablesize -getegid -geteuid -getgid -getgroups -gethostid -gethostname -getitimer -getpagesize -getpeername -getpriority -getprotobyname -getrlimit -getrusage -getsockname -getsockopt -gettimeofday -gid -gidset -gidsetsize -hostid -idrss -iflags -inblock -incr -intrc -ioctl.h -iov -iovec -iovlen -ispeed -isrss -itimerval -ixrss -kbytes -killc -killpgrp -len -linefeed -lnextc -lstat -maddr -madvise -majflt -maxrss -mclear -mincore -minflt -minuteswest -mman.h -mmap -mprotect -mremap -mset -msg -msghdr -msglen -msgrcv -msgsnd -msleep -msync -munmap -mwakeup -namelen -nbytes -nd -nds -newname -ngroups -nivcsw -nl -nsignals -nswap -nvcsw -oflag -oflags -oldmask -oldname -oldoffset -onstack -optlen -optname -optval -or'ed -or'ing -ospeed -oss -osv -oublock -ovalue -pagesize -param -param.h -path1 -path2 -pathname -pathnames -pgrp -pid -pos -prio -prot -proto -pv -quitc -quota.h -readlink -readv -reboot.h -recv -recvfrom -recvmsg -resource.h -rgid -rlim -rlimit -rlp -ronly -rprntc -ru -ruid -rusage -sbrk -scp -sem -sendmsg -sendto -setgroups -sethostid -sethostname -setitimer -setpriority -setquota -setregid -setreuid -setrlimit -setsockopt -settimeofday -sigblock -sigcontext -sigmask -signal.h -signo -sigpause -sigsetmask -sigstack -sigvec -sockaddr -socket.h -socketpair -socktype -sp -ss -sstk -startc -stat.h -stb -stopc -suspc -sv -sw -symlink -ta -time.h -timeval -timezone -tolen -tt -ttychars -ttymode -tv -tvp -tvsec -types.h -tz -tzp -uid -uio.h -umount -usec -vec -wait.h -waitstatus -werasc -writeable -writev diff --git a/share/doc/psd/20.ipctut/Makefile b/share/doc/psd/20.ipctut/Makefile deleted file mode 100644 index 9efbe0d1773..00000000000 --- a/share/doc/psd/20.ipctut/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# $OpenBSD: Makefile,v 1.3 2004/02/01 14:22:45 jmc Exp $ - - -DIR= psd/20.ipctut -SRCS= tutor.me -MACROS= -me -EXTRA= dgramread.c dgramsend.c fig2.pic fig3.pic fig8.pic pipe.c \ - socketpair.c strchkread.c streamread.c streamwrite.c \ - udgramread.c udgramsend.c ustreamread.c ustreamwrite.c - -paper.ps: ${SRCS} ${EXTRA} - ${SOELIM} ${SRCS} | ${PIC} | ${TBL} | ${ROFF} > ${.TARGET} - -paper.txt: ${SRCS} ${EXTRA} - ${SOELIM} ${SRCS} | ${PIC} | ${TBL} | ${ROFF} -Tascii > ${.TARGET} - -.include <bsd.doc.mk> diff --git a/share/doc/psd/20.ipctut/dgramread.c b/share/doc/psd/20.ipctut/dgramread.c deleted file mode 100644 index b4994a408f0..00000000000 --- a/share/doc/psd/20.ipctut/dgramread.c +++ /dev/null @@ -1,81 +0,0 @@ -.\" $OpenBSD: dgramread.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)dgramread.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <stdio.h> - -/* - * In the included file <netinet/in.h> a sockaddr_in is defined as follows: - * struct sockaddr_in { - * short sin_family; - * u_short sin_port; - * struct in_addr sin_addr; - * char sin_zero[8]; - * }; - * - * This program creates a datagram socket, binds a name to it, then reads - * from the socket. - */ -main() -{ - int sock, length; - struct sockaddr_in name; - char buf[1024]; - - /* Create socket from which to read. */ - sock = socket(AF_INET, SOCK_DGRAM, 0); - if (sock < 0) { - perror("opening datagram socket"); - exit(1); - } - /* Create name with wildcards. */ - name.sin_family = AF_INET; - name.sin_addr.s_addr = INADDR_ANY; - name.sin_port = 0; - if (bind(sock, &name, sizeof(name))) { - perror("binding datagram socket"); - exit(1); - } - /* Find assigned port value and print it out. */ - length = sizeof(name); - if (getsockname(sock, &name, &length)) { - perror("getting socket name"); - exit(1); - } - printf("Socket has port #%d\en", ntohs(name.sin_port)); - /* Read from the socket */ - if (read(sock, buf, 1024) < 0) - perror("receiving datagram packet"); - printf("-->%s\en", buf); - close(sock); -} diff --git a/share/doc/psd/20.ipctut/dgramsend.c b/share/doc/psd/20.ipctut/dgramsend.c deleted file mode 100644 index b24b26b1388..00000000000 --- a/share/doc/psd/20.ipctut/dgramsend.c +++ /dev/null @@ -1,78 +0,0 @@ -.\" $OpenBSD: dgramsend.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)dgramsend.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <netdb.h> -#include <stdio.h> - -#define DATA "The sea is calm tonight, the tide is full . . ." - -/* - * Here I send a datagram to a receiver whose name I get from the command - * line arguments. The form of the command line is dgramsend hostname - * portnumber - */ - -main(argc, argv) - int argc; - char *argv[]; -{ - int sock; - struct sockaddr_in name; - struct hostent *hp, *gethostbyname(); - - /* Create socket on which to send. */ - sock = socket(AF_INET, SOCK_DGRAM, 0); - if (sock < 0) { - perror("opening datagram socket"); - exit(1); - } - /* - * Construct name, with no wildcards, of the socket to send to. - * Getnostbyname() returns a structure including the network address - * of the specified host. The port number is taken from the command - * line. - */ - hp = gethostbyname(argv[1]); - if (hp == 0) { - fprintf(stderr, "%s: unknown host\n", argv[1]); - exit(2); - } - bcopy(hp->h_addr, &name.sin_addr, hp->h_length); - name.sin_family = AF_INET; - name.sin_port = htons(atoi(argv[2])); - /* Send message. */ - if (sendto(sock, DATA, sizeof(DATA), 0, &name, sizeof(name)) < 0) - perror("sending datagram message"); - close(sock); -} diff --git a/share/doc/psd/20.ipctut/fig2.pic b/share/doc/psd/20.ipctut/fig2.pic deleted file mode 100644 index b4ce7ea619b..00000000000 --- a/share/doc/psd/20.ipctut/fig2.pic +++ /dev/null @@ -1,79 +0,0 @@ -.\" $OpenBSD: fig2.pic,v 1.2 2001/02/03 08:15:05 niklas Exp $ -.\" -.\" Copyright (c) 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" @(#)fig2.pic 8.1 (Berkeley) 8/14/93 -.PS -.ps -.ps 10 -arc at 5.407,4.723 from 5.375,4.838 to 5.362,4.612 cw -arc at 5.907,7.973 from 5.875,8.088 to 5.862,7.862 cw -line from 5.963,5.513 to 6.925,5.513 -line from 5.963,5.650 to 6.925,5.650 -line from 5.963,5.787 to 6.925,5.787 -line from 5.963,5.912 to 6.925,5.912 -line from 5.963,6.050 to 6.925,6.050 -line from 5.963,6.200 to 6.925,6.200 to 6.925,5.375 to 5.963,5.375 to 5.963,6.200 -ellipse at 6.388,6.713 wid 0.475 ht 0.475 -line from 6.388,6.463 to 6.388,6.200 -line from 3.150,6.200 to 4.112,6.200 to 4.112,5.375 to 3.150,5.375 to 3.150,6.200 -line from 3.150,6.050 to 4.112,6.050 -line from 3.150,5.912 to 4.112,5.912 -line from 3.150,5.787 to 4.112,5.787 -line from 3.150,5.650 to 4.112,5.650 -line from 3.150,5.513 to 4.112,5.513 -ellipse at 3.575,6.713 wid 0.475 ht 0.475 -line from 3.575,6.463 to 3.575,6.200 -line from 3.650,8.762 to 4.612,8.762 -line from 3.650,8.900 to 4.612,8.900 -line from 3.650,9.037 to 4.612,9.037 -line from 3.650,9.162 to 4.612,9.162 -line from 3.650,9.300 to 4.612,9.300 -line from 3.650,9.450 to 4.612,9.450 to 4.612,8.625 to 3.650,8.625 to 3.650,9.450 -ellipse at 4.075,9.963 wid 0.475 ht 0.475 -ellipse at 3.950,4.725 wid 0.225 ht 0.225 -ellipse at 4.450,7.975 wid 0.225 ht 0.225 -dashwid = 0.037i -line dotted from 1.925,7.513 to 8.238,7.513 -line from 6.050,6.138 to 5.737,6.138 to 5.737,4.700 to 5.550,4.700 -line from 5.650,4.725 to 5.550,4.700 to 5.650,4.675 -line from 6.050,6.013 to 4.050,4.888 -line from 4.125,4.958 to 4.050,4.888 to 4.149,4.915 -line from 3.975,6.000 to 4.525,5.987 to 3.925,4.875 -line from 3.950,4.975 to 3.925,4.875 to 3.994,4.951 -line from 3.975,6.112 to 5.650,6.112 to 5.650,4.750 to 5.550,4.763 -line from 5.652,4.775 to 5.550,4.763 to 5.646,4.725 -line from 4.075,9.713 to 4.075,9.450 -line from 4.475,9.363 to 6.150,9.363 to 6.150,8.000 to 6.050,8.012 -line from 6.152,8.025 to 6.050,8.012 to 6.146,7.975 -line from 4.475,9.250 to 5.025,9.238 to 4.425,8.125 -line from 4.450,8.225 to 4.425,8.125 to 4.494,8.201 -.ps -.ps 20 -line from 4.362,4.775 to 4.162,4.725 to 4.362,4.675 -line from 4.162,4.725 to 4.838,4.725 -.ps -.ps 10 -line from 3.962,4.600 to 5.375,4.600 -line from 3.950,4.838 to 5.375,4.838 -line from 4.450,8.088 to 5.875,8.088 -line from 4.463,7.850 to 5.875,7.850 -.ps -.ps 20 -line from 4.862,8.025 to 4.662,7.975 to 4.862,7.925 -line from 4.662,7.975 to 5.338,7.975 -.ps -.ps 11 -.ft -.ft R -"Child" at 6.362,7.106 -.ps -.ps 12 -"Parent" at 3.362,7.096 ljust -"Parent" at 3.862,10.346 ljust -"PIPE" at 4.987,4.671 ljust -"PIPE" at 5.425,7.921 ljust -.ps -.ft -.PE diff --git a/share/doc/psd/20.ipctut/fig2.xfig b/share/doc/psd/20.ipctut/fig2.xfig deleted file mode 100644 index 59b46be37b8..00000000000 --- a/share/doc/psd/20.ipctut/fig2.xfig +++ /dev/null @@ -1,100 +0,0 @@ -#FIG 2.0 -80 2 -5 1 0 1 0 0 0 0 0.000 0 0 0 432.554 462.170 430 453 442 461 429 471 -5 1 0 1 0 0 0 0 0.000 0 0 0 472.554 202.170 470 193 482 201 469 211 -6 414 279 589 424 -6 473 340 557 414 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 399 554 399 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 388 554 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 377 554 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 367 554 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 356 554 356 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 477 344 554 344 554 410 477 410 477 344 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 511 303 19 19 511 303 525 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 511 323 511 344 9999 9999 --6 -6 189 279 364 424 -6 248 340 332 414 -2 2 0 1 0 0 0 0 0.000 0 0 - 252 344 329 344 329 410 252 410 252 344 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 356 329 356 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 367 329 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 377 329 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 388 329 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 399 329 399 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 286 303 19 19 286 303 300 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 286 323 286 344 9999 9999 --6 -6 288 80 372 154 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 139 369 139 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 128 369 128 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 117 369 117 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 107 369 107 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 96 369 96 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 292 84 369 84 369 150 292 150 292 84 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 326 43 19 19 326 43 340 57 -1 3 0 1 0 0 0 0 0.000 1 0.000 316 462 9 9 316 462 322 469 -1 3 0 1 0 0 0 0 0.000 1 0.000 356 202 9 9 356 202 362 209 -2 1 2 1 0 0 0 0 3.000 0 0 - 154 239 659 239 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 349 459 349 459 464 444 464 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 359 324 449 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 318 360 362 361 314 450 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 318 351 452 351 452 460 444 459 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 326 63 326 84 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 358 91 492 91 492 200 484 199 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 358 100 402 101 354 190 9999 9999 -2 1 0 2 0 0 0 0 0.000 0 1 - 0 0 2.000 8.000 16.000 - 333 462 387 462 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 317 472 430 472 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 316 453 430 453 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 356 193 470 193 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 357 212 470 212 9999 9999 -2 1 0 2 0 0 0 0 0.000 0 1 - 0 0 2.000 8.000 16.000 - 373 202 427 202 9999 9999 -4 1 0 11 0 0 0 0.000 1 7 24 509 274 Child -4 0 0 12 0 0 0 0.000 1 9 33 269 275 Parent -4 0 0 12 0 0 0 0.000 1 9 33 309 15 Parent -4 0 0 12 0 0 0 0.000 1 9 26 399 469 PIPE -4 0 0 12 0 0 0 0.000 1 9 26 434 209 PIPE diff --git a/share/doc/psd/20.ipctut/fig3.pic b/share/doc/psd/20.ipctut/fig3.pic deleted file mode 100644 index 6f2adcdf8f2..00000000000 --- a/share/doc/psd/20.ipctut/fig3.pic +++ /dev/null @@ -1,71 +0,0 @@ -.\" $OpenBSD: fig3.pic,v 1.2 2001/02/03 08:15:05 niklas Exp $ -.\" -.\" Copyright (c) 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" @(#)fig3.pic 8.1 (Berkeley) 8/14/93 -.PS -.ps -.ps 10 -ellipse at 5.787,8.012 wid 0.275 ht 0.275 -ellipse at 4.175,8.012 wid 0.275 ht 0.275 -dashwid = 0.037i -line dotted from 5.550,8.012 to 4.362,8.012 -line from 4.462,8.037 to 4.362,8.012 to 4.462,7.987 -line dotted from 4.362,7.950 to 5.550,7.950 -line from 5.450,7.925 to 5.550,7.950 to 5.450,7.975 -ellipse at 3.737,4.763 wid 0.275 ht 0.275 -ellipse at 5.350,4.763 wid 0.275 ht 0.275 -line dotted from 3.925,4.700 to 5.112,4.700 -line from 5.013,4.675 to 5.112,4.700 to 5.013,4.725 -line dotted from 5.112,4.763 to 3.925,4.763 -line from 4.025,4.788 to 3.925,4.763 to 4.025,4.737 -line from 5.963,5.513 to 6.925,5.513 -line from 5.963,5.650 to 6.925,5.650 -line from 5.963,5.787 to 6.925,5.787 -line from 5.963,5.912 to 6.925,5.912 -line from 5.963,6.050 to 6.925,6.050 -line from 5.963,6.200 to 6.925,6.200 to 6.925,5.375 to 5.963,5.375 to 5.963,6.200 -ellipse at 6.388,6.713 wid 0.475 ht 0.475 -line from 6.388,6.463 to 6.388,6.200 -line from 3.150,6.200 to 4.112,6.200 to 4.112,5.375 to 3.150,5.375 to 3.150,6.200 -line from 3.150,6.050 to 4.112,6.050 -line from 3.150,5.912 to 4.112,5.912 -line from 3.150,5.787 to 4.112,5.787 -line from 3.150,5.650 to 4.112,5.650 -line from 3.150,5.513 to 4.112,5.513 -ellipse at 3.575,6.713 wid 0.475 ht 0.475 -line from 3.575,6.463 to 3.575,6.200 -line from 3.650,8.762 to 4.612,8.762 -line from 3.650,8.900 to 4.612,8.900 -line from 3.650,9.037 to 4.612,9.037 -line from 3.650,9.162 to 4.612,9.162 -line from 3.650,9.300 to 4.612,9.300 -line from 3.650,9.450 to 4.612,9.450 to 4.612,8.625 to 3.650,8.625 to 3.650,9.450 -ellipse at 4.075,9.963 wid 0.475 ht 0.475 -line from 3.975,6.112 to 5.650,6.112 to 5.650,4.750 to 5.550,4.763 -line from 5.652,4.775 to 5.550,4.763 to 5.646,4.725 -line from 6.050,6.138 to 5.737,6.138 to 5.737,4.700 to 5.550,4.700 -line from 5.650,4.725 to 5.550,4.700 to 5.650,4.675 -line dotted from 1.925,7.513 to 8.238,7.513 -line from 6.050,6.013 to 4.050,4.888 -line from 4.125,4.958 to 4.050,4.888 to 4.149,4.915 -line from 3.975,6.000 to 4.525,5.987 to 3.925,4.875 -line from 3.950,4.975 to 3.925,4.875 to 3.994,4.951 -line from 4.075,9.713 to 4.075,9.450 -line from 4.475,9.363 to 6.150,9.363 to 6.150,8.000 to 6.050,8.012 -line from 6.152,8.025 to 6.050,8.012 to 6.146,7.975 -line from 4.475,9.250 to 5.025,9.238 to 4.425,8.125 -line from 4.450,8.225 to 4.425,8.125 to 4.494,8.201 -.ps -.ps 11 -.ft -.ft R -"Child" at 6.362,7.106 -.ps -.ps 12 -"Parent" at 3.362,7.096 ljust -"Parent" at 3.862,10.346 ljust -.ps -.ft -.PE diff --git a/share/doc/psd/20.ipctut/fig3.xfig b/share/doc/psd/20.ipctut/fig3.xfig deleted file mode 100644 index ed65b70bd18..00000000000 --- a/share/doc/psd/20.ipctut/fig3.xfig +++ /dev/null @@ -1,100 +0,0 @@ -#FIG 2.0 -80 2 -6 309 184 479 214 -1 3 0 1 0 0 0 0 0.000 1 0.000 463 199 11 11 463 199 468 209 -1 3 0 1 0 0 0 0 0.000 1 0.000 334 199 11 11 334 199 339 209 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 444 199 349 199 9999 9999 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 349 204 444 204 9999 9999 --6 -6 274 444 444 474 -1 3 0 1 0 0 0 0 0.000 1 0.000 299 459 11 11 299 459 304 469 -1 3 0 1 0 0 0 0 0.000 1 0.000 428 459 11 11 428 459 433 469 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 314 464 409 464 9999 9999 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 409 459 314 459 9999 9999 --6 -6 414 279 589 424 -6 473 340 557 414 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 399 554 399 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 388 554 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 377 554 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 367 554 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 356 554 356 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 477 344 554 344 554 410 477 410 477 344 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 511 303 19 19 511 303 525 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 511 323 511 344 9999 9999 --6 -6 189 279 364 424 -6 248 340 332 414 -2 2 0 1 0 0 0 0 0.000 0 0 - 252 344 329 344 329 410 252 410 252 344 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 356 329 356 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 367 329 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 377 329 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 388 329 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 399 329 399 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 286 303 19 19 286 303 300 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 286 323 286 344 9999 9999 --6 -6 288 80 372 154 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 139 369 139 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 128 369 128 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 117 369 117 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 107 369 107 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 292 96 369 96 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 292 84 369 84 369 150 292 150 292 84 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 326 43 19 19 326 43 340 57 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 318 351 452 351 452 460 444 459 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 349 459 349 459 464 444 464 9999 9999 -2 1 2 1 0 0 0 0 3.000 0 0 - 154 239 659 239 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 359 324 449 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 318 360 362 361 314 450 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 326 63 326 84 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 358 91 492 91 492 200 484 199 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 358 100 402 101 354 190 9999 9999 -4 1 0 11 0 0 0 0.000 1 7 24 509 274 Child -4 0 0 12 0 0 0 0.000 1 9 33 269 275 Parent -4 0 0 12 0 0 0 0.000 1 9 33 309 15 Parent diff --git a/share/doc/psd/20.ipctut/fig8.pic b/share/doc/psd/20.ipctut/fig8.pic deleted file mode 100644 index 4b1b37675fa..00000000000 --- a/share/doc/psd/20.ipctut/fig8.pic +++ /dev/null @@ -1,81 +0,0 @@ -.\" $OpenBSD: fig8.pic,v 1.2 2001/02/03 08:15:05 niklas Exp $ -.\" -.\" Copyright (c) 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" @(#)fig8.pic 8.1 (Berkeley) 8/14/93 -.PS -.ps -.ps 11 -.ft -.ft R -"Process 1" at 3.800,7.106 rjust -"Process 2" at 6.612,7.106 rjust -.ps -.ps 10 -line from 3.150,6.200 to 4.112,6.200 to 4.112,5.375 to 3.150,5.375 to 3.150,6.200 -line from 3.150,6.050 to 4.112,6.050 -line from 3.150,5.912 to 4.112,5.912 -line from 3.150,5.787 to 4.112,5.787 -line from 3.150,5.650 to 4.112,5.650 -line from 3.150,5.513 to 4.112,5.513 -ellipse at 3.575,6.713 wid 0.475 ht 0.475 -line from 3.575,6.463 to 3.575,6.200 -line from 5.963,5.513 to 6.925,5.513 -line from 5.963,5.650 to 6.925,5.650 -line from 5.963,5.787 to 6.925,5.787 -line from 5.963,5.912 to 6.925,5.912 -line from 5.963,6.050 to 6.925,6.050 -line from 5.963,6.200 to 6.925,6.200 to 6.925,5.375 to 5.963,5.375 to 5.963,6.200 -ellipse at 6.388,6.713 wid 0.475 ht 0.475 -line from 6.388,6.463 to 6.388,6.200 -line from 3.087,8.637 to 4.050,8.637 -line from 3.087,8.775 to 4.050,8.775 -line from 3.087,8.912 to 4.050,8.912 -line from 3.087,9.037 to 4.050,9.037 -line from 3.087,9.175 to 4.050,9.175 -line from 3.087,9.325 to 4.050,9.325 to 4.050,8.500 to 3.087,8.500 to 3.087,9.325 -ellipse at 3.513,9.838 wid 0.475 ht 0.475 -line from 3.513,9.588 to 3.513,9.325 -line from 5.900,9.325 to 6.862,9.325 to 6.862,8.500 to 5.900,8.500 to 5.900,9.325 -line from 5.900,9.175 to 6.862,9.175 -line from 5.900,9.037 to 6.862,9.037 -line from 5.900,8.912 to 6.862,8.912 -line from 5.900,8.775 to 6.862,8.775 -line from 5.900,8.637 to 6.862,8.637 -ellipse at 6.325,9.838 wid 0.475 ht 0.475 -line from 6.325,9.588 to 6.325,9.325 -.ps -.ps 11 -"Process 2" at 6.550,10.231 rjust -"Process 1" at 3.737,10.231 rjust -.ps -.ps 10 -ellipse at 6.112,4.888 wid 0.275 ht 0.275 -ellipse at 5.350,4.763 wid 0.275 ht 0.275 -ellipse at 3.737,4.763 wid 0.275 ht 0.275 -ellipse at 4.550,7.950 wid 0.275 ht 0.275 -ellipse at 5.487,7.950 wid 0.275 ht 0.275 -line from 6.050,6.013 to 5.175,6.013 to 5.987,5.013 -line from 5.905,5.074 to 5.987,5.013 to 5.944,5.106 -line from 6.050,6.138 to 5.737,6.138 to 5.737,4.700 to 5.550,4.700 -line from 5.650,4.725 to 5.550,4.700 to 5.650,4.675 -dashwid = 0.037i -line dotted from 1.925,7.513 to 8.238,7.513 -line from 3.975,6.000 to 4.525,5.987 to 3.925,4.875 -line from 3.950,4.975 to 3.925,4.875 to 3.994,4.951 -line dotted from 5.112,4.763 to 3.925,4.763 -line from 4.025,4.788 to 3.925,4.763 to 4.025,4.737 -line dotted from 3.925,4.700 to 5.112,4.700 -line from 5.013,4.675 to 5.112,4.700 to 5.013,4.725 -line from 6.050,9.012 to 5.487,9.012 to 5.487,8.137 -line from 5.462,8.237 to 5.487,8.137 to 5.513,8.237 -line from 3.737,9.137 to 4.550,9.137 to 4.550,8.137 -line from 4.525,8.237 to 4.550,8.137 to 4.575,8.237 -.ps -.ps 11 -"NAME" at 6.737,4.918 rjust -"NAME" at 6.112,8.043 rjust -.ps -.ft -.PE diff --git a/share/doc/psd/20.ipctut/fig8.xfig b/share/doc/psd/20.ipctut/fig8.xfig deleted file mode 100644 index f1a52576857..00000000000 --- a/share/doc/psd/20.ipctut/fig8.xfig +++ /dev/null @@ -1,116 +0,0 @@ -#FIG 2.0 -80 2 -6 224 254 589 279 -4 2 0 11 0 0 0 0.000 1 7 38 304 274 Process 1 -4 2 0 11 0 0 0 0.000 1 7 38 529 274 Process 2 --6 -6 189 279 364 424 -6 248 340 332 414 -2 2 0 1 0 0 0 0 0.000 0 0 - 252 344 329 344 329 410 252 410 252 344 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 356 329 356 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 367 329 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 377 329 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 388 329 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 252 399 329 399 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 286 303 19 19 286 303 300 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 286 323 286 344 9999 9999 --6 -6 414 279 589 424 -6 473 340 557 414 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 399 554 399 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 388 554 388 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 377 554 377 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 367 554 367 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 477 356 554 356 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 477 344 554 344 554 410 477 410 477 344 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 511 303 19 19 511 303 525 317 -2 1 0 1 0 0 0 0 0.000 0 0 - 511 323 511 344 9999 9999 --6 -6 184 29 359 174 -6 243 90 327 164 -2 1 0 1 0 0 0 0 0.000 0 0 - 247 149 324 149 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 247 138 324 138 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 247 127 324 127 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 247 117 324 117 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 247 106 324 106 9999 9999 -2 2 0 1 0 0 0 0 0.000 0 0 - 247 94 324 94 324 160 247 160 247 94 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 281 53 19 19 281 53 295 67 -2 1 0 1 0 0 0 0 0.000 0 0 - 281 73 281 94 9999 9999 --6 -6 409 29 584 174 -6 468 90 552 164 -2 2 0 1 0 0 0 0 0.000 0 0 - 472 94 549 94 549 160 472 160 472 94 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 472 106 549 106 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 472 117 549 117 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 472 127 549 127 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 472 138 549 138 9999 9999 -2 1 0 1 0 0 0 0 0.000 0 0 - 472 149 549 149 9999 9999 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 506 53 19 19 506 53 520 67 -2 1 0 1 0 0 0 0 0.000 0 0 - 506 73 506 94 9999 9999 --6 -6 219 4 584 29 -4 2 0 11 0 0 0 0.000 1 7 38 524 24 Process 2 -4 2 0 11 0 0 0 0.000 1 7 38 299 24 Process 1 --6 -1 3 0 1 0 0 0 0 0.000 1 0.000 489 449 11 11 489 449 494 459 -1 3 0 1 0 0 0 0 0.000 1 0.000 428 459 11 11 428 459 433 469 -1 3 0 1 0 0 0 0 0.000 1 0.000 299 459 11 11 299 459 304 469 -1 3 0 1 0 0 0 0 0.000 1 0.000 364 204 11 11 364 204 369 214 -1 3 0 1 0 0 0 0 0.000 1 0.000 439 204 11 11 439 204 444 214 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 359 414 359 479 439 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 349 459 349 459 464 444 464 9999 9999 -2 1 2 1 0 0 0 0 3.000 0 0 - 154 239 659 239 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 318 360 362 361 314 450 9999 9999 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 409 459 314 459 9999 9999 -2 1 2 1 0 0 0 0 3.000 1 0 - 0 0 1.000 4.000 8.000 - 314 464 409 464 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 484 119 439 119 439 189 9999 9999 -2 1 0 1 0 0 0 0 0.000 1 0 - 0 0 1.000 4.000 8.000 - 299 109 364 109 364 189 9999 9999 -4 2 0 11 0 0 0 0.000 1 7 32 539 449 NAME -4 2 0 11 0 0 0 0.000 1 7 32 489 199 NAME diff --git a/share/doc/psd/20.ipctut/pipe.c b/share/doc/psd/20.ipctut/pipe.c deleted file mode 100644 index cfdb0b6a0ff..00000000000 --- a/share/doc/psd/20.ipctut/pipe.c +++ /dev/null @@ -1,72 +0,0 @@ -.\" $OpenBSD: pipe.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)pipe.c 8.1 (Berkeley) 6/8/93 -.\" -#include <stdio.h> - -#define DATA "Bright star, would I were steadfast as thou art . . ." - -/* - * This program creates a pipe, then forks. The child communicates to the - * parent over the pipe. Notice that a pipe is a one-way communications - * device. I can write to the output socket (sockets[1], the second socket - * of the array returned by pipe()) and read from the input socket - * (sockets[0]), but not vice versa. - */ - -main() -{ - int sockets[2], child; - - /* Create a pipe */ - if (pipe(sockets) < 0) { - perror("opening stream socket pair"); - exit(10); - } - - if ((child = fork()) == -1) - perror("fork"); - else if (child) { - char buf[1024]; - - /* This is still the parent. It reads the child's message. */ - close(sockets[1]); - if (read(sockets[0], buf, 1024) < 0) - perror("reading message"); - printf("-->%s\en", buf); - close(sockets[0]); - } else { - /* This is the child. It writes a message to its parent. */ - close(sockets[0]); - if (write(sockets[1], DATA, sizeof(DATA)) < 0) - perror("writing message"); - close(sockets[1]); - } -} diff --git a/share/doc/psd/20.ipctut/socketpair.c b/share/doc/psd/20.ipctut/socketpair.c deleted file mode 100644 index 6222e5935d8..00000000000 --- a/share/doc/psd/20.ipctut/socketpair.c +++ /dev/null @@ -1,75 +0,0 @@ -.\" $OpenBSD: socketpair.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)socketpair.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <stdio.h> - -#define DATA1 "In Xanadu, did Kublai Khan . . ." -#define DATA2 "A stately pleasure dome decree . . ." - -/* - * This program creates a pair of connected sockets then forks and - * communicates over them. This is very similar to communication with pipes, - * however, socketpairs are two-way communications objects. Therefore I can - * send messages in both directions. - */ - -main() -{ - int sockets[2], child; - char buf[1024]; - - if (socketpair(AF_UNIX, SOCK_STREAM, 0, sockets) < 0) { - perror("opening stream socket pair"); - exit(1); - } - - if ((child = fork()) == -1) - perror("fork"); - else if (child) { /* This is the parent. */ - close(sockets[0]); - if (read(sockets[1], buf, 1024, 0) < 0) - perror("reading stream message"); - printf("-->%s\en", buf); - if (write(sockets[1], DATA2, sizeof(DATA2)) < 0) - perror("writing stream message"); - close(sockets[1]); - } else { /* This is the child. */ - close(sockets[1]); - if (write(sockets[0], DATA1, sizeof(DATA1)) < 0) - perror("writing stream message"); - if (read(sockets[0], buf, 1024, 0) < 0) - perror("reading stream message"); - printf("-->%s\en", buf); - close(sockets[0]); - } -} diff --git a/share/doc/psd/20.ipctut/strchkread.c b/share/doc/psd/20.ipctut/strchkread.c deleted file mode 100644 index cc045debab2..00000000000 --- a/share/doc/psd/20.ipctut/strchkread.c +++ /dev/null @@ -1,104 +0,0 @@ -.\" $OpenBSD: strchkread.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)strchkread.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <sys/time.h> -#include <netinet/in.h> -#include <netdb.h> -#include <stdio.h> -#define TRUE 1 - -/* - * This program uses select() to check that someone is trying to connect - * before calling accept(). - */ - -main() -{ - int sock, length; - struct sockaddr_in server; - int msgsock; - char buf[1024]; - int rval; - fd_set ready; - struct timeval to; - - /* Create socket */ - sock = socket(AF_INET, SOCK_STREAM, 0); - if (sock < 0) { - perror("opening stream socket"); - exit(1); - } - /* Name socket using wildcards */ - server.sin_family = AF_INET; - server.sin_addr.s_addr = INADDR_ANY; - server.sin_port = 0; - if (bind(sock, &server, sizeof(server))) { - perror("binding stream socket"); - exit(1); - } - /* Find out assigned port number and print it out */ - length = sizeof(server); - if (getsockname(sock, &server, &length)) { - perror("getting socket name"); - exit(1); - } - printf("Socket has port #%d\en", ntohs(server.sin_port)); - - /* Start accepting connections */ - listen(sock, 5); - do { - FD_ZERO(&ready); - FD_SET(sock, &ready); - to.tv_sec = 5; - if (select(sock + 1, &ready, 0, 0, &to) < 0) { - perror("select"); - continue; - } - if (FD_ISSET(sock, &ready)) { - msgsock = accept(sock, (struct sockaddr *)0, (int *)0); - if (msgsock == -1) - perror("accept"); - else do { - bzero(buf, sizeof(buf)); - if ((rval = read(msgsock, buf, 1024)) < 0) - perror("reading stream message"); - else if (rval == 0) - printf("Ending connection\en"); - else - printf("-->%s\en", buf); - } while (rval > 0); - close(msgsock); - } else - printf("Do something else\en"); - } while (TRUE); -} diff --git a/share/doc/psd/20.ipctut/streamread.c b/share/doc/psd/20.ipctut/streamread.c deleted file mode 100644 index 2d339e29a71..00000000000 --- a/share/doc/psd/20.ipctut/streamread.c +++ /dev/null @@ -1,100 +0,0 @@ -.\" $OpenBSD: streamread.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)streamread.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <netdb.h> -#include <stdio.h> -#define TRUE 1 - -/* - * This program creates a socket and then begins an infinite loop. Each time - * through the loop it accepts a connection and prints out messages from it. - * When the connection breaks, or a termination message comes through, the - * program accepts a new connection. - */ - -main() -{ - int sock, length; - struct sockaddr_in server; - int msgsock; - char buf[1024]; - int rval; - int i; - - /* Create socket */ - sock = socket(AF_INET, SOCK_STREAM, 0); - if (sock < 0) { - perror("opening stream socket"); - exit(1); - } - /* Name socket using wildcards */ - server.sin_family = AF_INET; - server.sin_addr.s_addr = INADDR_ANY; - server.sin_port = 0; - if (bind(sock, &server, sizeof(server))) { - perror("binding stream socket"); - exit(1); - } - /* Find out assigned port number and print it out */ - length = sizeof(server); - if (getsockname(sock, &server, &length)) { - perror("getting socket name"); - exit(1); - } - printf("Socket has port #%d\en", ntohs(server.sin_port)); - - /* Start accepting connections */ - listen(sock, 5); - do { - msgsock = accept(sock, 0, 0); - if (msgsock == -1) - perror("accept"); - else do { - bzero(buf, sizeof(buf)); - if ((rval = read(msgsock, buf, 1024)) < 0) - perror("reading stream message"); - i = 0; - if (rval == 0) - printf("Ending connection\en"); - else - printf("-->%s\en", buf); - } while (rval != 0); - close(msgsock); - } while (TRUE); - /* - * Since this program has an infinite loop, the socket "sock" is - * never explicitly closed. However, all sockets will be closed - * automatically when a process is killed or terminates normally. - */ -} diff --git a/share/doc/psd/20.ipctut/streamwrite.c b/share/doc/psd/20.ipctut/streamwrite.c deleted file mode 100644 index 22282cdb24f..00000000000 --- a/share/doc/psd/20.ipctut/streamwrite.c +++ /dev/null @@ -1,79 +0,0 @@ -.\" $OpenBSD: streamwrite.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)streamwrite.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <netdb.h> -#include <stdio.h> - -#define DATA "Half a league, half a league . . ." - -/* - * This program creates a socket and initiates a connection with the socket - * given in the command line. One message is sent over the connection and - * then the socket is closed, ending the connection. The form of the command - * line is streamwrite hostname portnumber - */ - -main(argc, argv) - int argc; - char *argv[]; -{ - int sock; - struct sockaddr_in server; - struct hostent *hp, *gethostbyname(); - char buf[1024]; - - /* Create socket */ - sock = socket(AF_INET, SOCK_STREAM, 0); - if (sock < 0) { - perror("opening stream socket"); - exit(1); - } - /* Connect socket using name specified by command line. */ - server.sin_family = AF_INET; - hp = gethostbyname(argv[1]); - if (hp == 0) { - fprintf(stderr, "%s: unknown host\n", argv[1]); - exit(2); - } - bcopy(hp->h_addr, &server.sin_addr, hp->h_length); - server.sin_port = htons(atoi(argv[2])); - - if (connect(sock, &server, sizeof(server)) < 0) { - perror("connecting stream socket"); - exit(1); - } - if (write(sock, DATA, sizeof(DATA)) < 0) - perror("writing on stream socket"); - close(sock); -} diff --git a/share/doc/psd/20.ipctut/tutor.me b/share/doc/psd/20.ipctut/tutor.me deleted file mode 100644 index 6afafec92ac..00000000000 --- a/share/doc/psd/20.ipctut/tutor.me +++ /dev/null @@ -1,937 +0,0 @@ -.\" $OpenBSD: tutor.me,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)tutor.me 8.1 (Berkeley) 8/14/93 -.\" -.oh 'Introductory 4.4BSD IPC''PSD:20-%' -.eh 'PSD:20-%''Introductory 4.4BSD IPC' -.rs -.sp 2 -.sz 14 -.ft B -.ce 2 -An Introductory 4.4BSD -Interprocess Communication Tutorial -.sz 10 -.sp 2 -.ce -.i "Stuart Sechrest" -.ft -.sp -.ce 4 -Computer Science Research Group -Computer Science Division -Department of Electrical Engineering and Computer Science -University of California, Berkeley -.sp 2 -.ce -.i ABSTRACT -.sp -.(c -.pp -Berkeley UNIX\(dg 4.4BSD offers several choices for interprocess communication. -To aid the programmer in developing programs which are comprised of -cooperating -processes, the different choices are discussed and a series of example -programs are presented. These programs -demonstrate in a simple way the use of pipes, socketpairs, sockets -and the use of datagram and stream communication. The intent of this -document is to present a few simple example programs, not to describe the -networking system in full. -.)c -.sp 2 -.(f -\(dg\|UNIX is a trademark of AT&T Bell Laboratories. -.)f -.b -.sh 1 "Goals" -.r -.pp -Facilities for interprocess communication (IPC) and networking -were a major addition to UNIX in the Berkeley UNIX 4.2BSD release. -These facilities required major additions and some changes -to the system interface. -The basic idea of this interface is to make IPC similar to file I/O. -In UNIX a process has a set of I/O descriptors, from which one reads -and to which one writes. -Descriptors may refer to normal files, to devices (including terminals), -or to communication channels. -The use of a descriptor has three phases: its creation, -its use for reading and writing, and its destruction. By using descriptors -to write files, rather than simply naming the target file in the write -call, one gains a surprising amount of flexibility. Often, the program that -creates a descriptor will be different from the program that uses the -descriptor. For example the shell can create a descriptor for the output -of the `ls' -command that will cause the listing to appear in a file rather than -on a terminal. -Pipes are another form of descriptor that have been used in UNIX -for some time. -Pipes allow one-way data transmission from one process -to another; the two processes and the pipe must be set up by a common -ancestor. -.pp -The use of descriptors is not the only communication interface -provided by UNIX. -The signal mechanism sends a tiny amount of information from one -process to another. -The signaled process receives only the signal type, -not the identity of the sender, -and the number of possible signals is small. -The signal semantics limit the flexibility of the signaling mechanism -as a means of interprocess communication. -.pp -The identification of IPC with I/O is quite longstanding in UNIX and -has proved quite successful. At first, however, IPC was limited to -processes communicating within a single machine. With Berkeley UNIX -4.2BSD this expanded to include IPC between machines. This expansion -has necessitated some change in the way that descriptors are created. -Additionally, new possibilities for the meaning of read and write have -been admitted. Originally the meanings, or semantics, of these terms -were fairly simple. When you wrote something it was delivered. When -you read something, you were blocked until the data arrived. -Other possibilities exist, -however. One can write without full assurance of delivery if one can -check later to catch occasional failures. Messages can be kept as -discrete units or merged into a stream. -One can ask to read, but insist on not waiting if nothing is immediately -available. These new possibilities are allowed in the Berkeley UNIX IPC -interface. -.pp -Thus Berkeley UNIX 4.4BSD offers several choices for IPC. -This paper presents simple examples that illustrate some of -the choices. -The reader is presumed to be familiar with the C programming language -[Kernighan & Ritchie 1978], -but not necessarily with the system calls of the UNIX system or with -processes and interprocess communication. -The paper reviews the notion of a process and the types of -communication that are supported by Berkeley UNIX 4.4BSD. -A series of examples are presented that create processes that communicate -with one another. The programs show different ways of establishing -channels of communication. -Finally, the calls that actually transfer data are reviewed. -To clearly present how communication can take place, -the example programs have been cleared of anything that -might be construed as useful work. -They can, therefore, serve as models -for the programmer trying to construct programs which are comprised of -cooperating processes. -.b -.sh 1 "Processes" -.pp -A \fIprogram\fP is both a sequence of statements and a rough way of referring -to the computation that occurs when the compiled statements are run. -A \fIprocess\fP can be thought of as a single line of control in a program. -Most programs execute some statements, go through a few loops, branch in -various directions and then end. These are single process programs. -Programs can also have a point where control splits into two independent lines, -an action called \fIforking.\fP -In UNIX these lines can never join again. A call to the system routine -\fIfork()\fP, causes a process to split in this way. -The result of this call is that two independent processes will be -running, executing exactly the same code. -Memory values will be the same for all values set before the fork, but, -subsequently, each version will be able to change only the -value of its own copy of each variable. -Initially, the only difference between the two will be the value returned by -\fIfork().\fP The parent will receive a process id for the child, -the child will receive a zero. -Calls to \fIfork(),\fP -therefore, typically precede, or are included in, an if-statement. -.pp -A process views the rest of the system through a private table of descriptors. -The descriptors can represent open files or sockets (sockets are communication -objects that will be discussed below). Descriptors are referred to -by their index numbers in the table. The first three descriptors are often -known by special names, \fI stdin, stdout\fP and \fIstderr\fP. -These are the standard input, output and error. -When a process forks, its descriptor table is copied to the child. -Thus, if the parent's standard input is being taken from a terminal -(devices are also treated as files in UNIX), the child's input will -be taken from the -same terminal. Whoever reads first will get the input. If, before forking, -the parent changes its standard input so that it is reading from a -new file, the child will take its input from the new file. It is -also possible to take input from a socket, rather than from a file. -.b -.sh 1 "Pipes" -.r -.pp -Most users of UNIX know that they can pipe the output of a -program ``prog1'' to the input of another, ``prog2,'' by typing the command -\fI``prog1 | prog2.''\fP -This is called ``piping'' the output of one program -to another because the mechanism used to transfer the output is called a -pipe. -When the user types a command, the command is read by the shell, which -decides how to execute it. If the command is simple, for example, -.i "``prog1,''" -the shell forks a process, which executes the program, prog1, and then dies. -The shell waits for this termination and then prompts for the next -command. -If the command is a compound command, -.i "``prog1 | prog2,''" -the shell creates two processes connected by a pipe. One process -runs the program, prog1, the other runs prog2. The pipe is an I/O -mechanism with two ends, or sockets. Data that is written into one socket -can be read from the other. -.(z -.ft CW -.so pipe.c -.ft -.ce 1 -Figure 1\ \ Use of a pipe -.)z -.pp -Since a program specifies its input and output only by the descriptor table -indices, which appear as variables or constants, -the input source and output destination can be changed without -changing the text of the program. -It is in this way that the shell is able to set up pipes. Before executing -prog1, the process can close whatever is at \fIstdout\fP -and replace it with one -end of a pipe. Similarly, the process that will execute prog2 can substitute -the opposite end of the pipe for -\fIstdin.\fP -.pp -Let us now examine a program that creates a pipe for communication between -its child and itself (Figure 1). -A pipe is created by a parent process, which then forks. -When a process forks, the parent's descriptor table is copied into -the child's. -.pp -In Figure 1, the parent process makes a call to the system routine -\fIpipe().\fP -This routine creates a pipe and places descriptors for the sockets -for the two ends of the pipe in the process's descriptor table. -\fIPipe()\fP -is passed an array into which it places the index numbers of the -sockets it created. -The two ends are not equivalent. The socket whose index is -returned in the low word of the array is opened for reading only, -while the socket in the high end is opened only for writing. -This corresponds to the fact that the standard input is the first -descriptor of a process's descriptor table and the standard output -is the second. After creating the pipe, the parent creates the child -with which it will share the pipe by calling \fIfork().\fP -Figure 2 illustrates the effect of a fork. -The parent process's descriptor table points to both ends of the pipe. -After the fork, both parent's and child's descriptor tables point to -the pipe. -The child can then use the pipe to send a message to the parent. -.(z -.so fig2.pic -.ce 2 -Figure 2\ \ Sharing a pipe between parent and child -.ce 0 -.)z -.pp -Just what is a pipe? -It is a one-way communication mechanism, with one end opened -for reading and the other end for writing. -Therefore, parent and child need to agree on which way to turn -the pipe, from parent to child or the other way around. -Using the same pipe for communication both from parent to child and -from child to parent would be possible (since both processes have -references to both ends), but very complicated. -If the parent and child are to have a two-way conversation, -the parent creates two pipes, one for use in each direction. -(In accordance with their plans, both parent and child in the example above -close the socket that they will not use. It is not required that unused -descriptors be closed, but it is good practice.) -A pipe is also a \fIstream\fP communication mechanism; that -is, all messages sent through the pipe are placed in order -and reliably delivered. When the reader asks for a certain -number of bytes from this -stream, he is given as many bytes as are available, up -to the amount of the request. Note that these bytes may have come from -the same call to \fIwrite()\fR or from several calls to \fIwrite()\fR -which were concatenated. -.b -.sh 1 "Socketpairs" -.r -.pp -Berkeley UNIX 4.4BSD provides a slight generalization of pipes. A pipe is a -pair of connected sockets for one-way stream communication. One may -obtain a pair of connected sockets for two-way stream communication -by calling the routine \fIsocketpair().\fP -The program in Figure 3 calls \fIsocketpair()\fP -to create such a connection. The program uses the link for -communication in both directions. Since socketpairs are -an extension of pipes, their use resembles that of pipes. -Figure 4 illustrates the result of a fork following a call to -\fIsocketpair().\fP -.pp -\fISocketpair()\fP -takes as -arguments a specification of a domain, a style of communication, and a -protocol. -These are the parameters shown in the example. -Domains and protocols will be discussed in the next section. -Briefly, -a domain is a space of names that may be bound -to sockets and implies certain other conventions. -Currently, socketpairs have only been implemented for one -domain, called the UNIX domain. -The UNIX domain uses UNIX path names for naming sockets. -It only allows communication -between sockets on the same machine. -.pp -Note that the header files -.i "<sys/socket.h>" -and -.i "<sys/types.h>." -are required in this program. -The constants AF_UNIX and SOCK_STREAM are defined in -.i "<sys/socket.h>," -which in turn requires the file -.i "<sys/types.h>" -for some of its definitions. -.(z -.ft CW -.so socketpair.c -.ft -.ce 1 -Figure 3\ \ Use of a socketpair -.)z -.(z -.so fig3.pic -.ce 1 -Figure 4\ \ Sharing a socketpair between parent and child -.)z -.b -.sh 1 "Domains and Protocols" -.r -.pp -Pipes and socketpairs are a simple solution for communicating between -a parent and child or between child processes. -What if we wanted to have processes that have no common ancestor -with whom to set up communication? -Neither standard UNIX pipes nor socketpairs are -the answer here, since both mechanisms require a common ancestor to -set up the communication. -We would like to have two processes separately create sockets -and then have messages sent between them. This is often the -case when providing or using a service in the system. This is -also the case when the communicating processes are on separate machines. -In Berkeley UNIX 4.4BSD one can create individual sockets, give them names and -send messages between them. -.pp -Sockets created by different programs use names to refer to one another; -names generally must be translated into addresses for use. -The space from which an address is drawn is referred to as a -.i domain. -There are several domains for sockets. -Two that will be used in the examples here are the UNIX domain (or AF_UNIX, -for Address Format UNIX) and the Internet domain (or AF_INET). -UNIX domain IPC is an experimental facility in 4.2BSD and 4.3BSD. -In the UNIX domain, a socket is given a path name within the file system -name space. -A file system node is created for the socket and other processes may -then refer to the socket by giving the proper pathname. -UNIX domain names, therefore, allow communication between any two processes -that work in the same file system. -The Internet domain is the UNIX implementation of the DARPA Internet -standard protocols IP/TCP/UDP. -Addresses in the Internet domain consist of a machine network address -and an identifying number, called a port. -Internet domain names allow communication between machines. -.pp -Communication follows some particular ``style.'' -Currently, communication is either through a \fIstream\fP -or by \fIdatagram.\fP -Stream communication implies several things. Communication takes -place across a connection between two sockets. The communication -is reliable, error-free, and, as in pipes, no message boundaries are -kept. Reading from a stream may result in reading the data sent from -one or several calls to \fIwrite()\fP -or only part of the data from a single call, if there is not enough room -for the entire message, or if not all the data from a large message -has been transferred. -The protocol implementing such a style will retransmit messages -received with errors. It will also return error messages if one tries to -send a message after the connection has been broken. -Datagram communication does not use connections. Each message is -addressed individually. If the address is correct, it will generally -be received, although this is not guaranteed. Often datagrams are -used for requests that require a response from the -recipient. If no response -arrives in a reasonable amount of time, the request is repeated. -The individual datagrams will be kept separate when they are read, that -is, message boundaries are preserved. -.pp -The difference in performance between the two styles of communication is -generally less important than the difference in semantics. The -performance gain that one might find in using datagrams must be weighed -against the increased complexity of the program, which must now concern -itself with lost or out of order messages. If lost messages may simply be -ignored, the quantity of traffic may be a consideration. The expense -of setting up a connection is best justified by frequent use of the connection. -Since the performance of a protocol changes as it is tuned for different -situations, it is best to seek the most up-to-date information when -making choices for a program in which performance is crucial. -.pp -A protocol is a set of rules, data formats and conventions that regulate the -transfer of data between participants in the communication. -In general, there is one protocol for each socket type (stream, -datagram, etc.) within each domain. -The code that implements a protocol -keeps track of the names that are bound to sockets, -sets up connections and transfers data between sockets, -perhaps sending the data across a network. -This code also keeps track of the names that are bound to sockets. -It is possible for several protocols, differing only in low level -details, to implement the same style of communication within -a particular domain. Although it is possible to select -which protocol should be used, for nearly all uses it is sufficient to -request the default protocol. This has been done in all of the example -programs. -.pp -One specifies the domain, style and protocol of a socket when -it is created. For example, in Figure 5a the call to \fIsocket()\fP -causes the creation of a datagram socket with the default protocol -in the UNIX domain. -.b -.sh 1 "Datagrams in the UNIX Domain" -.r -.(z -.ft CW -.so udgramread.c -.ft -.ce 1 -Figure 5a\ \ Reading UNIX domain datagrams -.)z -.pp -Let us now look at two programs that create sockets separately. -The programs in Figures 5a and 5b use datagram communication -rather than a stream. -The structure used to name UNIX domain sockets is defined -in the file \fI<sys/un.h>.\fP -The definition has also been included in the example for clarity. -.pp -Each program creates a socket with a call to \fIsocket().\fP -These sockets are in the UNIX domain. -Once a name has been decided upon it is attached to a socket by the -system call \fIbind().\fP -The program in Figure 5a uses the name ``socket'', -which it binds to its socket. -This name will appear in the working directory of the program. -The routines in Figure 5b use its -socket only for sending messages. It does not create a name for -the socket because no other process has to refer to it. -.(z -.ft CW -.so udgramsend.c -.ft -.ce 1 -Figure 5b\ \ Sending a UNIX domain datagrams -.)z -.pp -Names in the UNIX domain are path names. Like file path names they may -be either absolute (e.g. ``/dev/imaginary'') or relative (e.g. ``socket''). -Because these names are used to allow processes to rendezvous, relative -path names can pose difficulties and should be used with care. -When a name is bound into the name space, a file (inode) is allocated in the -file system. If -the inode is not deallocated, the name will continue to exist even after -the bound socket is closed. This can cause subsequent runs of a program -to find that a name is unavailable, and can cause -directories to fill up with these -objects. The names are removed by calling \fIunlink()\fP or using -the \fIrm\fP\|(1) command. -Names in the UNIX domain are only used for rendezvous. They are not used -for message delivery once a connection is established. Therefore, in -contrast with the Internet domain, unbound sockets need not be (and are -not) automatically given addresses when they are connected. -.pp -There is no established means of communicating names to interested -parties. In the example, the program in Figure 5b gets the -name of the socket to which it will send its message through its -command line arguments. Once a line of communication has been created, -one can send the names of additional, perhaps new, sockets over the link. -Facilities will have to be built that will make the distribution of -names less of a problem than it now is. -.b -.sh 1 "Datagrams in the Internet Domain" -.r -.(z -.ft CW -.so dgramread.c -.ft -.ce 1 -Figure 6a\ \ Reading Internet domain datagrams -.)z -.pp -The examples in Figure 6a and 6b are very close to the previous example -except that the socket is in the Internet domain. -The structure of Internet domain addresses is defined in the file -\fI<netinet/in.h>\fP. -Internet addresses specify a host address (a 32-bit number) -and a delivery slot, or port, on that -machine. These ports are managed by the system routines that implement -a particular protocol. -Unlike UNIX domain names, Internet socket names are not entered into -the file system and, therefore, -they do not have to be unlinked after the socket has been closed. -When a message must be sent between machines it is sent to -the protocol routine on the destination machine, which interprets the -address to determine to which socket the message should be delivered. -Several different protocols may be active on -the same machine, but, in general, they will not communicate with one another. -As a result, different protocols are allowed to use the same port numbers. -Thus, implicitly, an Internet address is a triple including a protocol as -well as the port and machine address. -An \fIassociation\fP is a temporary or permanent specification -of a pair of communicating sockets. -An association is thus identified by the tuple -<\fIprotocol, local machine address, local port, -remote machine address, remote port\fP>. -An association may be transient when using datagram sockets; -the association actually exists during a \fIsend\fP operation. -.(z -.ft CW -.so dgramsend.c -.ft -.ce 1 -Figure 6b\ \ Sending an Internet domain datagram -.)z -.pp -The protocol for a socket is chosen when the socket is created. The -local machine address for a socket can be any valid network address of the -machine, if it has more than one, or it can be the wildcard value -INADDR_ANY. -The wildcard value is used in the program in Figure 6a. -If a machine has several network addresses, it is likely -that messages sent to any of the addresses should be deliverable to -a socket. This will be the case if the wildcard value has been chosen. -Note that even if the wildcard value is chosen, a program sending messages -to the named socket must specify a valid network address. One can be willing -to receive from ``anywhere,'' but one cannot send a message ``anywhere.'' -The program in Figure 6b is given the destination host name as a command -line argument. -To determine a network address to which it can send the message, it looks -up -the host address by the call to \fIgethostbyname()\fP. -The returned structure includes the host's network address, -which is copied into the structure specifying the -destination of the message. -.pp -The port number can be thought of as the number of a mailbox, into -which the protocol places one's messages. Certain daemons, offering -certain advertised services, have reserved -or ``well-known'' port numbers. These fall in the range -from 1 to 1023. Higher numbers are available to general users. -Only servers need to ask for a particular number. -The system will assign an unused port number when an address -is bound to a socket. -This may happen when an explicit \fIbind\fP -call is made with a port number of 0, or -when a \fIconnect\fP or \fIsend\fP -is performed on an unbound socket. -Note that port numbers are not automatically reported back to the user. -After calling \fIbind(),\fP asking for port 0, one may call -\fIgetsockname()\fP to discover what port was actually assigned. -The routine \fIgetsockname()\fP -will not work for names in the UNIX domain. -.pp -The format of the socket address is specified in part by standards within the -Internet domain. The specification includes the order of the bytes in -the address. Because machines differ in the internal representation -they ordinarily use -to represent integers, printing out the port number as returned by -\fIgetsockname()\fP may result in a misinterpretation. To -print out the number, it is necessary to use the routine \fIntohs()\fP -(for \fInetwork to host: short\fP) to convert the number from the -network representation to the host's representation. On some machines, -such as 68000-based machines, this is a null operation. On others, -such as VAXes, this results in a swapping of bytes. Another routine -exists to convert a short integer from the host format to the network format, -called \fIhtons()\fP; similar routines exist for long integers. -For further information, refer to the -entry for \fIbyteorder\fP in section 3 of the manual. -.b -.sh 1 "Connections" -.r -.pp -To send data between stream sockets (having communication style SOCK_STREAM), -the sockets must be connected. -Figures 7a and 7b show two programs that create such a connection. -The program in 7a is relatively simple. -To initiate a connection, this program simply creates -a stream socket, then calls \fIconnect()\fP, -specifying the address of the socket to which -it wishes its socket connected. Provided that the target socket exists and -is prepared to handle a connection, connection will be complete, -and the program can begin to send -messages. Messages will be delivered in order without message -boundaries, as with pipes. The connection is destroyed when either -socket is closed (or soon thereafter). If a process persists -in sending messages after the connection is closed, a SIGPIPE signal -is sent to the process by the operating system. Unless explicit action -is taken to handle the signal (see the manual page for \fIsignal\fP -or \fIsigvec\fP), -the process will terminate and the shell -will print the message ``broken pipe.'' -.(z -.ft CW -.so streamwrite.c -.ft -.ce 1 -Figure 7a\ \ Initiating an Internet domain stream connection -.)z -.(z -.ft CW -.so streamread.c -.ft -.ce 1 -Figure 7b\ \ Accepting an Internet domain stream connection -.sp 2 -.ft CW -.so strchkread.c -.ft -.ce 1 -Figure 7c\ \ Using select() to check for pending connections -.)z -.(z -.so fig8.pic -.sp -.ce 1 -Figure 8\ \ Establishing a stream connection -.)z -.pp -Forming a connection is asymmetrical; one process, such as the -program in Figure 7a, requests a connection with a particular socket, -the other process accepts connection requests. -Before a connection can be accepted a socket must be created and an address -bound to it. This -situation is illustrated in the top half of Figure 8. Process 2 -has created a socket and bound a port number to it. Process 1 has created an -unnamed socket. -The address bound to process 2's socket is then made known to process 1 and, -perhaps to several other potential communicants as well. -If there are several possible communicants, -this one socket might receive several requests for connections. -As a result, a new socket is created for each connection. This new socket -is the endpoint for communication within this process for this connection. -A connection may be destroyed by closing the corresponding socket. -.pp -The program in Figure 7b is a rather trivial example of a server. It -creates a socket to which it binds a name, which it then advertises. -(In this case it prints out the socket number.) The program then calls -\fIlisten()\fP for this socket. -Since several clients may attempt to connect more or less -simultaneously, a queue of pending connections is maintained in the system -address space. \fIListen()\fP -marks the socket as willing to accept connections and initializes the queue. -When a connection is requested, it is listed in the queue. If the -queue is full, an error status may be returned to the requester. -The maximum length of this queue is specified by the second argument of -\fIlisten()\fP; the maximum length is limited by the system. -Once the listen call has been completed, the program enters -an infinite loop. On each pass through the loop, a new connection is -accepted and removed from the queue, and, hence, a new socket for the -connection is created. The bottom half of Figure 8 shows the result of -Process 1 connecting with the named socket of Process 2, and Process 2 -accepting the connection. After the connection is created, the -service, in this case printing out the messages, is performed and the -connection socket closed. The \fIaccept()\fP -call will take a pending connection -request from the queue if one is available, or block waiting for a request. -Messages are read from the connection socket. -Reads from an active connection will normally block until data is available. -The number of bytes read is returned. When a connection is destroyed, -the read call returns immediately. The number of bytes returned will -be zero. -.pp -The program in Figure 7c is a slight variation on the server in Figure 7b. -It avoids blocking when there are no pending connection requests by -calling \fIselect()\fP -to check for pending requests before calling \fIaccept().\fP -This strategy is useful when connections may be received -on more than one socket, or when data may arrive on other connected -sockets before another connection request. -.pp -The programs in Figures 9a and 9b show a program using stream communication -in the UNIX domain. Streams in the UNIX domain can be used for this sort -of program in exactly the same way as Internet domain streams, except for -the form of the names and the restriction of the connections to a single -file system. There are some differences, however, in the functionality of -streams in the two domains, notably in the handling of -\fIout-of-band\fP data (discussed briefly below). These differences -are beyond the scope of this paper. -.(z -.ft CW -.so ustreamwrite.c -.ft -.ce 1 -Figure 9a\ \ Initiating a UNIX domain stream connection -.sp 2 -.ft CW -.so ustreamread.c -.ft -.ce 1 -Figure 9b\ \ Accepting a UNIX domain stream connection -.)z -.b -.sh 1 "Reads, Writes, Recvs, etc." -.r -.pp -UNIX 4.4BSD has several system calls for reading and writing information. -The simplest calls are \fIread() \fP and \fIwrite().\fP \fIWrite()\fP -takes as arguments the index of a descriptor, a pointer to a buffer -containing the data and the size of the data. -The descriptor may indicate either a file or a connected socket. -``Connected'' can mean either a connected stream socket (as described -in Section 8) or a datagram socket for which a \fIconnect()\fP -call has provided a default destination (see the \fIconnect()\fP manual page). -\fIRead()\fP also takes a descriptor that indicates either a file or a socket. -\fIWrite()\fP requires a connected socket since no destination is -specified in the parameters of the system call. -\fIRead()\fP can be used for either a connected or an unconnected socket. -These calls are, therefore, quite flexible and may be used to -write applications that require no assumptions about the source of -their input or the destination of their output. -There are variations on \fIread() \fP and \fIwrite()\fP -that allow the source and destination of the input and output to use -several separate buffers, while retaining the flexibility to handle -both files and sockets. These are \fIreadv()\fP and \fI writev(),\fP -for read and write \fIvector.\fP -.pp -It is sometimes necessary to send high priority data over a -connection that may have unread low priority data at the -other end. For example, a user interface process may be interpreting -commands and sending them on to another process through a stream connection. -The user interface may have filled the stream with as yet unprocessed -requests when the user types -a command to cancel all outstanding requests. -Rather than have the high priority data wait -to be processed after the low priority data, it is possible to -send it as \fIout-of-band\fP -(OOB) data. The notification of pending OOB data results in the generation of -a SIGURG signal, if this signal has been enabled (see the manual -page for \fIsignal\fP or \fIsigvec\fP). -See [Leffler 1986] for a more complete description of the OOB mechanism. -There are a pair of calls similar to \fIread\fP and \fIwrite\fP -that allow options, including sending -and receiving OOB information; these are \fI send()\fP -and \fIrecv().\fP -These calls are used only with sockets; specifying a descriptor for a file will -result in the return of an error status. These calls also allow -\fIpeeking\fP at data in a stream. -That is, they allow a process to read data without removing the data from -the stream. One use of this facility is to read ahead in a stream -to determine the size of the next item to be read. -When not using these options, these calls have the same functions as -\fIread()\fP and \fIwrite().\fP -.pp -To send datagrams, one must be allowed to specify the destination. -The call \fIsendto()\fP -takes a destination address as an argument and is therefore used for -sending datagrams. The call \fIrecvfrom()\fP -is often used to read datagrams, since this call returns the address -of the sender, if it is available, along with the data. -If the identity of the sender does not matter, one may use \fIread()\fP -or \fIrecv().\fP -.pp -Finally, there are a pair of calls that allow the sending and -receiving of messages from multiple buffers, when the address of the -recipient must be specified. These are \fIsendmsg()\fP and -\fIrecvmsg().\fP -These calls are actually quite general and have other uses, -including, in the UNIX domain, the transmission of a file descriptor from one -process to another. -.pp -The various options for reading and writing are shown in Figure 10, -together with their parameters. The parameters for each system call -reflect the differences in function of the different calls. -In the examples given in this paper, the calls \fIread()\fP and -\fIwrite()\fP have been used whenever possible. -.(z -.ft CW - /* - * The variable descriptor may be the descriptor of either a file - * or of a socket. - */ - cc = read(descriptor, buf, nbytes) - int cc, descriptor; char *buf; int nbytes; - - /* - * An iovec can include several source buffers. - */ - cc = readv(descriptor, iov, iovcnt) - int cc, descriptor; struct iovec *iov; int iovcnt; - - cc = write(descriptor, buf, nbytes) - int cc, descriptor; char *buf; int nbytes; - - cc = writev(descriptor, iovec, ioveclen) - int cc, descriptor; struct iovec *iovec; int ioveclen; - - /* - * The variable ``sock'' must be the descriptor of a socket. - * Flags may include MSG_OOB and MSG_PEEK. - */ - cc = send(sock, msg, len, flags) - int cc, sock; char *msg; int len, flags; - - cc = sendto(sock, msg, len, flags, to, tolen) - int cc, sock; char *msg; int len, flags; - struct sockaddr *to; int tolen; - - cc = sendmsg(sock, msg, flags) - int cc, sock; struct msghdr msg[]; int flags; - - cc = recv(sock, buf, len, flags) - int cc, sock; char *buf; int len, flags; - - cc = recvfrom(sock, buf, len, flags, from, fromlen) - int cc, sock; char *buf; int len, flags; - struct sockaddr *from; int *fromlen; - - cc = recvmsg(sock, msg, flags) - int cc, socket; struct msghdr msg[]; int flags; -.ft -.sp 1 -.ce 1 -Figure 10\ \ Varieties of read and write commands -.)z -.b -.sh 1 "Choices" -.r -.pp -This paper has presented examples of some of the forms -of communication supported by -Berkeley UNIX 4.4BSD. These have been presented in an order chosen for -ease of presentation. It is useful to review these options emphasizing the -factors that make each attractive. -.pp -Pipes have the advantage of portability, in that they are supported in all -UNIX systems. They also are relatively -simple to use. Socketpairs share this simplicity and have the additional -advantage of allowing bidirectional communication. The major shortcoming -of these mechanisms is that they require communicating processes to be -descendants of a common process. They do not allow intermachine communication. -.pp -The two communication domains, UNIX and Internet, allow processes with no common -ancestor to communicate. -Of the two, only the Internet domain allows -communication between machines. -This makes the Internet domain a necessary -choice for processes running on separate machines. -.pp -The choice between datagrams and stream communication is best made by -carefully considering the semantic and performance -requirements of the application. -Streams can be both advantageous and disadvantageous. One disadvantage -is that a process is only allowed a limited number of open streams, -as there are usually only 64 entries available in the open descriptor -table. This can cause problems if a single server must talk with a large -number of clients. -Another is that for delivering a short message the stream setup and -teardown time can be unnecessarily long. Weighed against this are -the reliability built into the streams. This will often be the -deciding factor in favor of streams. -.b -.sh 1 "What to do Next" -.r -.pp -Many of the examples presented here can serve as models for multiprocess -programs and for programs distributed across several machines. -In developing a new multiprocess program, it is often easiest to -first write the code to create the processes and communication paths. -After this code is debugged, the code specific to the application can -be added. -.pp -An introduction to the UNIX system and programming using UNIX system calls -can be found in [Kernighan and Pike 1984]. -Further documentation of the Berkeley UNIX 4.4BSD IPC mechanisms can be -found in [Leffler et al. 1986]. -More detailed information about particular calls and protocols -is provided in sections -2, 3 and 4 of the -UNIX Programmer's Manual [CSRG 1986]. -In particular the following manual pages are relevant: -.(b -.TS -l l. -creating and naming sockets socket(2), bind(2) -establishing connections listen(2), accept(2), connect(2) -transferring data read(2), write(2), send(2), recv(2) -addresses inet(4F) -protocols tcp(4P), udp(4P). -.TE -.)b -.(b -.sp -.b -Acknowledgements -.pp -I would like to thank Sam Leffler and Mike Karels for their help in -understanding the IPC mechanisms and all the people whose comments -have helped in writing and improving this report. -.pp -This work was sponsored by the Defense Advanced Research Projects Agency -(DoD), ARPA Order No. 4031, monitored by the Naval Electronics Systems -Command under contract No. N00039-C-0235. -The views and conclusions contained in this document are those of the -author and should not be interpreted as representing official policies, -either expressed or implied, of the Defense Research Projects Agency -or of the US Government. -.)b -.(b -.sp -.b -References -.r -.sp -.ls 1 -B.W. Kernighan & R. Pike, 1984, -.i "The UNIX Programming Environment." -Englewood Cliffs, N.J.: Prentice-Hall. -.sp -.ls 1 -B.W. Kernighan & D.M. Ritchie, 1978, -.i "The C Programming Language," -Englewood Cliffs, N.J.: Prentice-Hall. -.sp -.ls 1 -S.J. Leffler, R.S. Fabry, W.N. Joy, P. Lapsley, S. Miller & C. Torek, 1986, -.i "An Advanced 4.4BSD Interprocess Communication Tutorial." -Computer Systems Research Group, -Department of Electrical Engineering and Computer Science, -University of California, Berkeley. -.sp -.ls 1 -Computer Systems Research Group, 1986, -.i "UNIX Programmer's Manual, 4.4 Berkeley Software Distribution." -Computer Systems Research Group, -Department of Electrical Engineering and Computer Science, -University of California, Berkeley. -.)b diff --git a/share/doc/psd/20.ipctut/udgramread.c b/share/doc/psd/20.ipctut/udgramread.c deleted file mode 100644 index c55fdce8a1b..00000000000 --- a/share/doc/psd/20.ipctut/udgramread.c +++ /dev/null @@ -1,78 +0,0 @@ -.\" $OpenBSD: udgramread.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)udgramread.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <sys/un.h> - -/* - * In the included file <sys/un.h> a sockaddr_un is defined as follows - * struct sockaddr_un { - * short sun_family; - * char sun_path[108]; - * }; - */ - -#include <stdio.h> - -#define NAME "socket" - -/* - * This program creates a UNIX domain datagram socket, binds a name to it, - * then reads from the socket. - */ -main() -{ - int sock, length; - struct sockaddr_un name; - char buf[1024]; - - /* Create socket from which to read. */ - sock = socket(AF_UNIX, SOCK_DGRAM, 0); - if (sock < 0) { - perror("opening datagram socket"); - exit(1); - } - /* Create name. */ - name.sun_family = AF_UNIX; - strcpy(name.sun_path, NAME); - if (bind(sock, &name, sizeof(struct sockaddr_un))) { - perror("binding name to datagram socket"); - exit(1); - } - printf("socket -->%s\en", NAME); - /* Read from the socket */ - if (read(sock, buf, 1024) < 0) - perror("receiving datagram packet"); - printf("-->%s\en", buf); - close(sock); - unlink(NAME); -} diff --git a/share/doc/psd/20.ipctut/udgramsend.c b/share/doc/psd/20.ipctut/udgramsend.c deleted file mode 100644 index aa1b1160aa3..00000000000 --- a/share/doc/psd/20.ipctut/udgramsend.c +++ /dev/null @@ -1,66 +0,0 @@ -.\" $OpenBSD: udgramsend.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)udgramsend.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <sys/un.h> -#include <stdio.h> - -#define DATA "The sea is calm tonight, the tide is full . . ." - -/* - * Here I send a datagram to a receiver whose name I get from the command - * line arguments. The form of the command line is udgramsend pathname - */ - -main(argc, argv) - int argc; - char *argv[]; -{ - int sock; - struct sockaddr_un name; - - /* Create socket on which to send. */ - sock = socket(AF_UNIX, SOCK_DGRAM, 0); - if (sock < 0) { - perror("opening datagram socket"); - exit(1); - } - /* Construct name of socket to send to. */ - name.sun_family = AF_UNIX; - strcpy(name.sun_path, argv[1]); - /* Send message. */ - if (sendto(sock, DATA, sizeof(DATA), 0, - &name, sizeof(struct sockaddr_un)) < 0) { - perror("sending datagram message"); - } - close(sock); -} diff --git a/share/doc/psd/20.ipctut/ustreamread.c b/share/doc/psd/20.ipctut/ustreamread.c deleted file mode 100644 index 423a6644e48..00000000000 --- a/share/doc/psd/20.ipctut/ustreamread.c +++ /dev/null @@ -1,94 +0,0 @@ -.\" $OpenBSD: ustreamread.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)ustreamread.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <sys/un.h> -#include <stdio.h> - -#define NAME "socket" - -/* - * This program creates a socket in the UNIX domain and binds a name to it. - * After printing the socket's name it begins a loop. Each time through the - * loop it accepts a connection and prints out messages from it. When the - * connection breaks, or a termination message comes through, the program - * accepts a new connection. - */ -main() -{ - int sock, msgsock, rval; - struct sockaddr_un server; - char buf[1024]; - - /* Create socket */ - sock = socket(AF_UNIX, SOCK_STREAM, 0); - if (sock < 0) { - perror("opening stream socket"); - exit(1); - } - /* Name socket using file system name */ - server.sun_family = AF_UNIX; - strcpy(server.sun_path, NAME); - if (bind(sock, &server, sizeof(struct sockaddr_un))) { - perror("binding stream socket"); - exit(1); - } - printf("Socket has name %s\en", server.sun_path); - /* Start accepting connections */ - listen(sock, 5); - for (;;) { - msgsock = accept(sock, 0, 0); - if (msgsock == -1) - perror("accept"); - else do { - bzero(buf, sizeof(buf)); - if ((rval = read(msgsock, buf, 1024)) < 0) - perror("reading stream message"); - else if (rval == 0) - printf("Ending connection\en"); - else - printf("-->%s\en", buf); - } while (rval > 0); - close(msgsock); - } - /* - * The following statements are not executed, because they follow an - * infinite loop. However, most ordinary programs will not run - * forever. In the UNIX domain it is necessary to tell the file - * system that one is through using NAME. In most programs one uses - * the call unlink() as below. Since the user will have to kill this - * program, it will be necessary to remove the name by a command from - * the shell. - */ - close(sock); - unlink(NAME); -} diff --git a/share/doc/psd/20.ipctut/ustreamwrite.c b/share/doc/psd/20.ipctut/ustreamwrite.c deleted file mode 100644 index 0edf9e3f880..00000000000 --- a/share/doc/psd/20.ipctut/ustreamwrite.c +++ /dev/null @@ -1,69 +0,0 @@ -.\" $OpenBSD: ustreamwrite.c,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)ustreamwrite.c 8.1 (Berkeley) 6/8/93 -.\" -#include <sys/types.h> -#include <sys/socket.h> -#include <sys/un.h> -#include <stdio.h> - -#define DATA "Half a league, half a league . . ." - -/* - * This program connects to the socket named in the command line and sends a - * one line message to that socket. The form of the command line is - * ustreamwrite pathname - */ -main(argc, argv) - int argc; - char *argv[]; -{ - int sock; - struct sockaddr_un server; - char buf[1024]; - - /* Create socket */ - sock = socket(AF_UNIX, SOCK_STREAM, 0); - if (sock < 0) { - perror("opening stream socket"); - exit(1); - } - /* Connect socket using name specified by command line. */ - server.sun_family = AF_UNIX; - strcpy(server.sun_path, argv[1]); - - if (connect(sock, &server, sizeof(struct sockaddr_un)) < 0) { - close(sock); - perror("connecting stream socket"); - exit(1); - } - if (write(sock, DATA, sizeof(DATA)) < 0) - perror("writing on stream socket"); -} diff --git a/share/doc/psd/21.ipc/0.t b/share/doc/psd/21.ipc/0.t deleted file mode 100644 index 04739794e10..00000000000 --- a/share/doc/psd/21.ipc/0.t +++ /dev/null @@ -1,91 +0,0 @@ -.\" $OpenBSD: 0.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)0.t 8.1 (Berkeley) 6/8/93 -.\" -.EH 'PSD:21-%''Advanced 4.4BSD IPC Tutorial' -.OH 'Advanced 4.4BSD IPC Tutorial''PSD:21-%' -.ds lq `` -.ds rq '' -.de DT -.if t .ta .5i 1.25i 2.5i 3.75i -.\" 3.5i went to 3.8i -.if n .ta .7i 1.75i 3.8i -.. -.bd S B 3 -.TL -An Advanced 4.4BSD Interprocess Communication Tutorial -.AU -Samuel J. Leffler -.AU -Robert S. Fabry -.AU -William N. Joy -.AU -Phil Lapsley -.AI -Computer Systems Research Group -Department of Electrical Engineering and Computer Science -University of California, Berkeley -Berkeley, California 94720 -.sp 2 -.AU -Steve Miller -.AU -Chris Torek -.AI -Heterogeneous Systems Laboratory -Department of Computer Science -University of Maryland, College Park -College Park, Maryland 20742 -.de IR -\fI\\$1\fP\\$2 -.. -.de UX -UNIX\\$1 -.. -.AB -.PP -.FS -* \s-2UNIX\s0 is a trademark of UNIX System Laboratories, Inc. -in the US and some other countries. -.FE -This document provides an introduction to the interprocess -communication facilities included in the -4.4BSD release of the -.UX * -system. -.PP -It discusses the overall model for interprocess communication -and introduces the interprocess communication primitives -which have been added to the system. The majority of the -document considers the use of these primitives in developing -applications. The reader is expected to be familiar with -the C programming language as all examples are written in C. -.AE diff --git a/share/doc/psd/21.ipc/1.t b/share/doc/psd/21.ipc/1.t deleted file mode 100644 index 653d94dde11..00000000000 --- a/share/doc/psd/21.ipc/1.t +++ /dev/null @@ -1,104 +0,0 @@ -.\" $OpenBSD: 1.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)1.t 8.1 (Berkeley) 8/14/93 -.\" -.\".ds LH "4.4BSD IPC Primer -.\".ds RH Introduction -.\".ds RF "Leffler/Fabry/Joy -.\".ds LF "\*(DY -.\".ds CF " -.nr H1 1 -.LP -.bp -.LG -.B -.ce -1. INTRODUCTION -.sp 2 -.R -.NL -One of the most important additions to UNIX in 4.2BSD was interprocess -communication. -These facilities were the result of -more than two years of discussion and research. The facilities -provided in 4.2BSD incorporated many of the ideas from current -research, while trying to maintain the UNIX philosophy of -simplicity and conciseness. -The 4.3BSD release of Berkeley UNIX -improved upon some of the IPC facilities -while providing an upward-compatible interface. -4.4BSD adds support for ISO protocols and IP multicasting. -The BSD interprocess communication -facilities have become a defacto standard for UNIX. -.PP -UNIX has previously been very weak in the area of interprocess -communication. Prior to the 4BSD facilities, the only -standard mechanism which allowed two processes to communicate were -pipes (the mpx files which were part of Version 7 were -experimental). Unfortunately, pipes are very restrictive -in that -the two communicating processes must be related through a -common ancestor. -Further, the semantics of pipes makes them almost impossible -to maintain in a distributed environment. -.PP -Earlier attempts at extending the IPC facilities of UNIX have -met with mixed reaction. The majority of the problems have -been related to the fact that these facilities have been tied to -the UNIX file system, either through naming or implementation. -Consequently, the IPC facilities provided in 4.2BSD were -designed as a totally independent subsystem. The BSD IPC -allows processes to rendezvous in many ways. -Processes may rendezvous through a UNIX file system-like -name space (a space where all names are path names) -as well as through a -network name space. In fact, new name spaces may -be added at a future time with only minor changes visible -to users. Further, the communication facilities -have been extended to include more than the simple byte stream -provided by a pipe. These extensions have resulted -in a completely new part of the system which users will need -time to familiarize themselves with. It is likely that as -more use is made of these facilities they will be refined; -only time will tell. -.PP -This document provides a high-level description -of the IPC facilities in 4.4BSD and their use. -It is designed to complement the manual pages for the IPC primitives -by examples of their use. -The remainder of this document is organized in four sections. -Section 2 introduces the IPC-related system calls and the basic model -of communication. Section 3 describes some of the supporting -library routines users may find useful in constructing distributed -applications. Section 4 is concerned with the client/server model -used in developing applications and includes examples of the -two major types of servers. Section 5 delves into advanced topics -which sophisticated users are likely to encounter when using -the IPC facilities. diff --git a/share/doc/psd/21.ipc/2.t b/share/doc/psd/21.ipc/2.t deleted file mode 100644 index 082def348a8..00000000000 --- a/share/doc/psd/21.ipc/2.t +++ /dev/null @@ -1,712 +0,0 @@ -.\" $OpenBSD: 2.t,v 1.5 2003/08/12 20:44:57 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)2.t 8.1 (Berkeley) 8/14/93 -.\" -.\".ds RH "Basics -.bp -.nr H1 2 -.nr H2 0 -.\" The next line is a major hack to get around internal changes in the groff -.\" implementation of .NH. -.nr nh*hl 1 -.bp -.LG -.B -.ce -2. BASICS -.sp 2 -.R -.NL -.PP -The basic building block for communication is the \fIsocket\fP. -A socket is an endpoint of communication to which a name may -be \fIbound\fP. Each socket in use has a \fItype\fP -and one or more associated processes. Sockets exist within -\fIcommunication domains\fP. -A communication domain is an -abstraction introduced to bundle common properties of -processes communicating through sockets. -One such property is the scheme used to name sockets. For -example, in the UNIX communication domain sockets are -named with UNIX path names; e.g. a -socket may be named \*(lq/dev/foo\*(rq. Sockets normally -exchange data only with -sockets in the same domain (it may be possible to cross domain -boundaries, but only if some translation process is -performed). The -4.4BSD IPC facilities support four separate communication domains: -the UNIX domain, for on-system communication; -the Internet domain, which is used by -processes which communicate -using the Internet standard communication protocols; -the NS domain, which is used by processes which -communicate using the Xerox standard communication -protocols*; -.FS -* See \fIInternet Transport Protocols\fP, Xerox System Integration -Standard (XSIS)028112 for more information. This document is -almost a necessity for one trying to write NS applications. -.FE -and the ISO OSI protocols, which are not documented in this tutorial. -The underlying communication -facilities provided by these domains have a significant influence -on the internal system implementation as well as the interface to -socket facilities available to a user. An example of the -latter is that a socket \*(lqoperating\*(rq in the UNIX domain -sees a subset of the error conditions which are possible -when operating in the Internet (or NS) domain. -.NH 2 -Socket types -.PP -Sockets are -typed according to the communication properties visible to a -user. -Processes are presumed to communicate only between sockets of -the same type, although there is -nothing that prevents communication between sockets of different -types should the underlying communication -protocols support this. -.PP -Four types of sockets currently are available to a user. -A \fIstream\fP socket provides for the bidirectional, reliable, -sequenced, and unduplicated flow of data without record boundaries. -Aside from the bidirectionality of data flow, a pair of connected -stream sockets provides an interface nearly identical to that of pipes\(dg. -.FS -\(dg In the UNIX domain, in fact, the semantics are identical and, -as one might expect, pipes have been implemented internally -as simply a pair of connected stream sockets. -.FE -.PP -A \fIdatagram\fP socket supports bidirectional flow of data which -is not promised to be sequenced, reliable, or unduplicated. -That is, a process -receiving messages on a datagram socket may find messages duplicated, -and, possibly, -in an order different from the order in which it was sent. -An important characteristic of a datagram -socket is that record boundaries in data are preserved. Datagram -sockets closely model the facilities found in many contemporary -packet switched networks such as the Ethernet. -.PP -A \fIraw\fP socket provides users access to -the underlying communication -protocols which support socket abstractions. -These sockets are normally datagram oriented, though their -exact characteristics are dependent on the interface provided by -the protocol. Raw sockets are not intended for the general user; they -have been provided mainly for those interested in developing new -communication protocols, or for gaining access to some of the more -esoteric facilities of an existing protocol. The use of raw sockets -is considered in section 5. -.PP -A \fIsequenced packet\fP socket is similar to a stream socket, -with the exception that record boundaries are preserved. This -interface is provided only as part of the NS socket abstraction, -and is very important in most serious NS applications. -Sequenced-packet sockets allow the user to manipulate the -SPP or IDP headers on a packet or a group of packets either -by writing a prototype header along with whatever data is -to be sent, or by specifying a default header to be used with -all outgoing data, and allows the user to receive the headers -on incoming packets. The use of these options is considered in -section 5. -.PP -Another potential socket type which has interesting properties is -the \fIreliably delivered -message\fP socket. -The reliably delivered message socket has -similar properties to a datagram socket, but with -reliable delivery. There is currently no support for this -type of socket, but a reliably delivered message protocol -similar to Xerox's Packet Exchange Protocol (PEX) may be -simulated at the user level. More information on this topic -can be found in section 5. -.NH 2 -Socket creation -.PP -To create a socket the \fIsocket\fP system call is used: -.DS -s = socket(domain, type, protocol); -.DE -This call requests that the system create a socket in the specified -\fIdomain\fP and of the specified \fItype\fP. A particular protocol may -also be requested. If the protocol is left unspecified (a value -of 0), the system will select an appropriate protocol from those -protocols which comprise the communication domain and which -may be used to support the requested socket type. The user is -returned a descriptor (a small integer number) which may be used -in later system calls which operate on sockets. The domain is specified as -one of the manifest constants defined in the file <\fIsys/socket.h\fP>. -For the UNIX domain the constant is AF_UNIX*; for the Internet -.FS -* The manifest constants are named AF_whatever as they indicate -the ``address format'' to use in interpreting names. -.FE -domain AF_INET; and for the NS domain, AF_NS. -The socket types are also defined in this file -and one of SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, or SOCK_SEQPACKET -must be specified. -To create a stream socket in the Internet domain the following -call might be used: -.DS -s = socket(AF_INET, SOCK_STREAM, 0); -.DE -This call would result in a stream socket being created with the TCP -protocol providing the underlying communication support. To -create a datagram socket for on-machine use the call might -be: -.DS -s = socket(AF_UNIX, SOCK_DGRAM, 0); -.DE -.PP -The default protocol (used when the \fIprotocol\fP argument to the -\fIsocket\fP call is 0) should be correct for most every -situation. However, it is possible to specify a protocol -other than the default; this will be covered in -section 5. -.PP -There are several reasons a socket call may fail. Aside from -the rare occurrence of lack of memory (ENOBUFS), a socket -request may fail due to a request for an unknown protocol -(EPROTONOSUPPORT), or a request for a type of socket for -which there is no supporting protocol (EPROTOTYPE). -.NH 2 -Binding local names -.PP -A socket is created without a name. Until a name is bound -to a socket, processes have no way to reference it and, consequently, -no messages may be received on it. -Communicating processes are bound -by an \fIassociation\fP. In the Internet and NS domains, -an association -is composed of local and foreign -addresses, and local and foreign ports, -while in the UNIX domain, an association is composed of -local and foreign path names (the phrase ``foreign pathname'' -means a pathname created by a foreign process, not a pathname -on a foreign system). -In most domains, associations must be unique. -In the Internet domain there -may never be duplicate <protocol, local address, local port, foreign -address, foreign port> tuples. UNIX domain sockets need not always -be bound to a name, but when bound -there may never be duplicate <protocol, local pathname, foreign -pathname> tuples. -The pathnames may not refer to files -already existing on the system -in 4.3; the situation may change in future releases. -.PP -The \fIbind\fP system call allows a process to specify half of -an association, <local address, local port> -(or <local pathname>), while the \fIconnect\fP -and \fIaccept\fP primitives are used to complete a socket's association. -.PP -In the Internet domain, -binding names to sockets can be fairly complex. -Fortunately, it is usually not necessary to specifically bind an -address and port number to a socket, because the -\fIconnect\fP and \fIsend\fP calls will automatically -bind an appropriate address if they are used with an -unbound socket. The process of binding names to NS -sockets is similar in most ways to that of -binding names to Internet sockets. -.PP -The \fIbind\fP system call is used as follows: -.DS -bind(s, name, namelen); -.DE -The bound name is a variable length byte string which is interpreted -by the supporting protocol(s). Its interpretation may vary from -communication domain to communication domain (this is one of -the properties which comprise the \*(lqdomain\*(rq). -As mentioned, in the -Internet domain names contain an Internet address and port -number. NS domain names contain an NS address and -port number. In the UNIX domain, names contain a path name and -a family, which is always AF_UNIX. If one wanted to bind -the name \*(lq/tmp/foo\*(rq to a UNIX domain socket, the -following code would be used*: -.FS -* Note that, although the tendency here is to call the \*(lqaddr\*(rq -structure \*(lqsun\*(rq, doing so would cause problems if the code -were ever ported to a Sun workstation. -.FE -.DS -#include <sys/un.h> - ... -struct sockaddr_un addr; - ... -strcpy(addr.sun_path, "/tmp/foo"); -addr.sun_family = AF_UNIX; -bind(s, (struct sockaddr *) &addr, strlen(addr.sun_path) + - sizeof (addr.sun_len) + sizeof (addr.sun_family)); -.DE -Note that in determining the size of a UNIX domain address null -bytes are not counted, which is why \fIstrlen\fP is used. In -the current implementation of UNIX domain IPC, -the file name -referred to in \fIaddr.sun_path\fP is created as a socket -in the system file space. -The caller must, therefore, have -write permission in the directory where -\fIaddr.sun_path\fP is to reside, and this file should be deleted by the -caller when it is no longer needed. Future versions of 4BSD -may not create this file. -.PP -In binding an Internet address things become more -complicated. The actual call is similar, -.DS -#include <sys/types.h> -#include <netinet/in.h> - ... -struct sockaddr_in sin; - ... -bind(s, (struct sockaddr *) &sin, sizeof (sin)); -.DE -but the selection of what to place in the address \fIsin\fP -requires some discussion. We will come back to the problem -of formulating Internet addresses in section 3 when -the library routines used in name resolution are discussed. -.PP -Binding an NS address to a socket is even more -difficult, -especially since the Internet library routines do not -work with NS hostnames. The actual call is again similar: -.DS -#include <sys/types.h> -#include <netns/ns.h> - ... -struct sockaddr_ns sns; - ... -bind(s, (struct sockaddr *) &sns, sizeof (sns)); -.DE -Again, discussion of what to place in a \*(lqstruct sockaddr_ns\*(rq -will be deferred to section 3. -.NH 2 -Connection establishment -.PP -Connection establishment is usually asymmetric, -with one process a \*(lqclient\*(rq and the other a \*(lqserver\*(rq. -The server, when willing to offer its advertised services, -binds a socket to a well-known address associated with the service -and then passively \*(lqlistens\*(rq on its socket. -It is then possible for an unrelated process to rendezvous -with the server. -The client requests services from the server by initiating a -\*(lqconnection\*(rq to the server's socket. -On the client side the \fIconnect\fP call is -used to initiate a connection. Using the UNIX domain, this -might appear as, -.DS -struct sockaddr_un server; - ... -connect(s, (struct sockaddr *)&server, strlen(server.sun_path) + - sizeof (server.sun_family)); -.DE -while in the Internet domain, -.DS -struct sockaddr_in server; - ... -connect(s, (struct sockaddr *)&server, sizeof (server)); -.DE -and in the NS domain, -.DS -struct sockaddr_ns server; - ... -connect(s, (struct sockaddr *)&server, sizeof (server)); -.DE -where \fIserver\fP in the example above would contain either the UNIX -pathname, Internet address and port number, or NS address and -port number of the server to which the -client process wishes to speak. -If the client process's socket is unbound at the time of -the connect call, -the system will automatically select and bind a name to -the socket if necessary; c.f. section 5.4. -This is the usual way that local addresses are bound -to a socket. -.PP -An error is returned if the connection was unsuccessful -(any name automatically bound by the system, however, remains). -Otherwise, the socket is associated with the server and -data transfer may begin. Some of the more common errors returned -when a connection attempt fails are: -.IP ETIMEDOUT -.br -After failing to establish a connection for a period of time, -the system decided there was no point in retrying the -connection attempt any more. This usually occurs because -the destination host is down, or because problems in -the network resulted in transmissions being lost. -.IP ECONNREFUSED -.br -The host refused service for some reason. -This is usually -due to a server process -not being present at the requested name. -.IP "ENETDOWN or EHOSTDOWN" -.br -These operational errors are -returned based on status information delivered to -the client host by the underlying communication services. -.IP "ENETUNREACH or EHOSTUNREACH" -.br -These operational errors can occur either because the network -or host is unknown (no route to the network or host is present), -or because of status information returned by intermediate -gateways or switching nodes. Many times the status returned -is not sufficient to distinguish a network being down from a -host being down, in which case the system -indicates the entire network is unreachable. -.PP -For the server to receive a client's connection it must perform -two steps after binding its socket. -The first is to indicate a willingness to listen for -incoming connection requests: -.DS -listen(s, 5); -.DE -The second parameter to the \fIlisten\fP call specifies the maximum -number of outstanding connections which may be queued awaiting -acceptance by the server process; this number -may be limited by the system. Should a connection be -requested while the queue is full, the connection will not be -refused, but rather the individual messages which comprise the -request will be ignored. This gives a harried server time to -make room in its pending connection queue while the client -retries the connection request. Had the connection been returned -with the ECONNREFUSED error, the client would be unable to tell -if the server was up or not. As it is now it is still possible -to get the ETIMEDOUT error back, though this is unlikely. The -backlog figure supplied with the listen call is currently limited -by the system to a maximum of 5 pending connections on any -one queue. This avoids the problem of processes hogging system -resources by setting an infinite backlog, then ignoring -all connection requests. -.PP -With a socket marked as listening, a server may \fIaccept\fP -a connection: -.DS -struct sockaddr_in from; - ... -fromlen = sizeof (from); -newsock = accept(s, (struct sockaddr *)&from, &fromlen); -.DE -(For the UNIX domain, \fIfrom\fP would be declared as a -\fIstruct sockaddr_un\fP, and for the NS domain, \fIfrom\fP -would be declared as a \fIstruct sockaddr_ns\fP, -but nothing different would need -to be done as far as \fIfromlen\fP is concerned. In the examples -which follow, only Internet routines will be discussed.) A new -descriptor is returned on receipt of a connection (along with -a new socket). If the server wishes to find out who its client is, -it may supply a buffer for the client socket's name. The value-result -parameter \fIfromlen\fP is initialized by the server to indicate how -much space is associated with \fIfrom\fP, then modified on return -to reflect the true size of the name. If the client's name is not -of interest, the second parameter may be a null pointer. -.PP -\fIAccept\fP normally blocks. That is, \fIaccept\fP -will not return until a connection is available or the system call -is interrupted by a signal to the process. Further, there is no -way for a process to indicate it will accept connections from only -a specific individual, or individuals. It is up to the user process -to consider who the connection is from and close down the connection -if it does not wish to speak to the process. If the server process -wants to accept connections on more than one socket, or wants to avoid blocking -on the accept call, there are alternatives; they will be considered -in section 5. -.NH 2 -Data transfer -.PP -With a connection established, data may begin to flow. To send -and receive data there are a number of possible calls. -With the peer entity at each end of a connection -anchored, a user can send or receive a message without specifying -the peer. As one might expect, in this case, then -the normal \fIread\fP and \fIwrite\fP system calls are usable, -.DS -write(s, buf, sizeof (buf)); -read(s, buf, sizeof (buf)); -.DE -In addition to \fIread\fP and \fIwrite\fP, -the new calls \fIsend\fP and \fIrecv\fP -may be used: -.DS -send(s, buf, sizeof (buf), flags); -recv(s, buf, sizeof (buf), flags); -.DE -While \fIsend\fP and \fIrecv\fP are virtually identical to -\fIread\fP and \fIwrite\fP, -the extra \fIflags\fP argument is important. The flags, -defined in \fI<sys/socket.h>\fP, may be -specified as a non-zero value if one or more -of the following is required: -.DS -.TS -l l. -MSG_OOB send/receive out of band data -MSG_PEEK look at data without reading -MSG_DONTROUTE send data without routing packets -.TE -.DE -Out of band data is a notion specific to stream sockets, and one -which we will not immediately consider. The option to have data -sent without routing applied to the outgoing packets is currently -used only by the routing table management process, and is -unlikely to be of interest to the casual user. The ability -to preview data is, however, of interest. When MSG_PEEK -is specified with a \fIrecv\fP call, any data present is returned -to the user, but treated as still \*(lqunread\*(rq. That -is, the next \fIread\fP or \fIrecv\fP call applied to the socket will -return the data previously previewed. -.NH 2 -Discarding sockets -.PP -Once a socket is no longer of interest, it may be discarded -by applying a \fIclose\fP to the descriptor, -.DS -close(s); -.DE -If data is associated with a socket which promises reliable delivery -(e.g. a stream socket) when a close takes place, the system will -continue to attempt to transfer the data. -However, after a fairly long period of -time, if the data is still undelivered, it will be discarded. -Should a user have no use for any pending data, it may -perform a \fIshutdown\fP on the socket prior to closing it. -This call is of the form: -.DS -shutdown(s, how); -.DE -where \fIhow\fP is 0 if the user is no longer interested in reading -data, 1 if no more data will be sent, or 2 if no data is to -be sent or received. -.NH 2 -Connectionless sockets -.PP -To this point we have been concerned mostly with sockets which -follow a connection oriented model. However, there is also -support for connectionless interactions typical of the datagram -facilities found in contemporary packet switched networks. -A datagram socket provides a symmetric interface to data -exchange. While processes are still likely to be client -and server, there is no requirement for connection establishment. -Instead, each message includes the destination address. -.PP -Datagram sockets are created as before. -If a particular local address is needed, -the \fIbind\fP operation must precede the first data transmission. -Otherwise, the system will set the local address and/or port -when data is first sent. -To send data, the \fIsendto\fP primitive is used, -.DS -sendto(s, buf, buflen, flags, (struct sockaddr *)&to, tolen); -.DE -The \fIs\fP, \fIbuf\fP, \fIbuflen\fP, and \fIflags\fP -parameters are used as before. -The \fIto\fP and \fItolen\fP -values are used to indicate the address of the intended recipient of the -message. When -using an unreliable datagram interface, it is -unlikely that any errors will be reported to the sender. When -information is present locally to recognize a message that can -not be delivered (for instance when a network is unreachable), -the call will return \-1 and the global value \fIerrno\fP will -contain an error number. -.PP -To receive messages on an unconnected datagram socket, the -\fIrecvfrom\fP primitive is provided: -.DS -recvfrom(s, buf, buflen, flags, (struct sockaddr *)&from, &fromlen); -.DE -Once again, the \fIfromlen\fP parameter is handled in -a value-result fashion, initially containing the size of -the \fIfrom\fP buffer, and modified on return to indicate -the actual size of the address from which the datagram was received. -.PP -In addition to the two calls mentioned above, datagram -sockets may also use the \fIconnect\fP call to associate -a socket with a specific destination address. In this case, any -data sent on the socket will automatically be addressed -to the connected peer, and only data received from that -peer will be delivered to the user. Only one connected -address is permitted for each socket at one time; -a second connect will change the destination address, -and a connect to a null address (family AF_UNSPEC) -will disconnect. -Connect requests on datagram sockets return immediately, -as this simply results in the system recording -the peer's address (as compared to a stream socket, where a -connect request initiates establishment of an end to end -connection). \fIAccept\fP and \fIlisten\fP are not -used with datagram sockets. -.PP -While a datagram socket is connected, -errors from recent \fIsend\fP calls may be returned -asynchronously. -These errors may be reported on subsequent operations -on the socket, -or a special socket option used with \fIgetsockopt\fP, SO_ERROR, -may be used to interrogate the error status. -A \fIselect\fP for reading or writing will return true -when an error indication has been received. -The next operation will return the error, and the error status is cleared. -Other of the less -important details of datagram sockets are described -in section 5. -.NH 2 -Input/Output multiplexing -.PP -One last facility often used in developing applications -is the ability to multiplex i/o requests among multiple -sockets and/or files. This is done using the \fIselect\fP -call: -.DS -#include <sys/time.h> -#include <sys/types.h> - ... - -fd_set readmask, writemask, exceptmask; -struct timeval timeout; - ... -select(nfds, &readmask, &writemask, &exceptmask, &timeout); -.DE -\fISelect\fP takes as arguments pointers to three sets, one for -the set of file descriptors for which the caller wishes to -be able to read data on, one for those descriptors to which -data is to be written, and one for which exceptional conditions -are pending; out-of-band data is the only -exceptional condition currently implemented by the socket -If the user is not interested -in certain conditions (i.e., read, write, or exceptions), -the corresponding argument to the \fIselect\fP should -be a null pointer. -.PP -Each set is actually a structure containing an array of -long integer bit masks; the size of the array is set -by the definition FD_SETSIZE. -The array is be -long enough to hold one bit for each of FD_SETSIZE file descriptors. -.PP -The macros FD_SET(\fIfd, &mask\fP) and -FD_CLR(\fIfd, &mask\fP) -have been provided for adding and removing file descriptor -\fIfd\fP in the set \fImask\fP. The -set should be zeroed before use, and -the macro FD_ZERO(\fI&mask\fP) has been provided -to clear the set \fImask\fP. -The parameter \fInfds\fP in the \fIselect\fP call specifies the range -of file descriptors (i.e. one plus the value of the largest -descriptor) to be examined in a set. -.PP -A timeout value may be specified if the selection -is not to last more than a predetermined period of time. If -the fields in \fItimeout\fP are set to 0, the selection takes -the form of a -\fIpoll\fP, returning immediately. If the last parameter is -a null pointer, the selection will block indefinitely*. -.FS -* To be more specific, a return takes place only when a -descriptor is selectable, or when a signal is received by -the caller, interrupting the system call. -.FE -\fISelect\fP normally returns the number of file descriptors selected; -if the \fIselect\fP call returns due to the timeout expiring, then -the value 0 is returned. -If the \fIselect\fP terminates because of an error or interruption, -a \-1 is returned with the error number in \fIerrno\fP, -and with the file descriptor masks unchanged. -.PP -Assuming a successful return, the three sets will -indicate which -file descriptors are ready to be read from, written to, or -have exceptional conditions pending. -The status of a file descriptor in a select mask may be -tested with the \fIFD_ISSET(fd, &mask)\fP macro, which -returns a non-zero value if \fIfd\fP is a member of the set -\fImask\fP, and 0 if it is not. -.PP -To determine if there are connections waiting -on a socket to be used with an \fIaccept\fP call, -\fIselect\fP can be used, followed by -a \fIFD_ISSET(fd, &mask)\fP macro to check for read -readiness on the appropriate socket. If \fIFD_ISSET\fP -returns a non-zero value, indicating permission to read, then a -connection is pending on the socket. -.PP -As an example, to read data from two sockets, \fIs1\fP and -\fIs2\fP as it is available from each and with a one-second -timeout, the following code -might be used: -.DS -#include <sys/time.h> -#include <sys/types.h> - ... -fd_set read_template; -struct timeval wait; - ... -for (;;) { - wait.tv_sec = 1; /* one second */ - wait.tv_usec = 0; - - FD_ZERO(&read_template); - - FD_SET(s1, &read_template); - FD_SET(s2, &read_template); - - nb = select(MAX(s1, s2) + 1, &read_template, NULL, NULL, &wait); - if (nb <= 0) { - \fIAn error occurred during the \fPselect\fI, or - the \fPselect\fI timed out.\fP - } - - if (FD_ISSET(s1, &read_template)) { - \fISocket #1 is ready to be read from.\fP - } - - if (FD_ISSET(s2, &read_template)) { - \fISocket #2 is ready to be read from.\fP - } -} -.DE -.PP -In 4.2, the arguments to \fIselect\fP were pointers to integers -instead of pointers to \fIfd_set\fPs. This type of call -will still work as long as the number of file descriptors -being examined is less than the number of bits in an -integer; however, the methods illustrated above should -be used in all current programs. -.PP -\fISelect\fP provides a synchronous multiplexing scheme. -Asynchronous notification of output completion, input availability, -and exceptional conditions is possible through use of the -SIGIO and SIGURG signals described in section 5. diff --git a/share/doc/psd/21.ipc/3.t b/share/doc/psd/21.ipc/3.t deleted file mode 100644 index 42ba6799e26..00000000000 --- a/share/doc/psd/21.ipc/3.t +++ /dev/null @@ -1,407 +0,0 @@ -.\" $OpenBSD: 3.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)3.t 8.1 (Berkeley) 6/8/93 -.\" -.\".ds RH "Network Library Routines -.bp -.nr H1 3 -.nr H2 0 -.bp -.LG -.B -.ce -3. NETWORK LIBRARY ROUTINES -.sp 2 -.R -.NL -.PP -The discussion in section 2 indicated the possible need to -locate and construct network addresses when using the -interprocess communication facilities in a distributed -environment. To aid in this task a number of routines -have been added to the standard C run-time library. -In this section we will consider the new routines provided -to manipulate network addresses. While the 4.4BSD networking -facilities support the Internet protocols -and the Xerox NS protocols, -most of the routines presented -in this section do not apply to the NS domain. Unless otherwise -stated, it should be assumed that the routines presented in this -section do not apply to the NS domain. -.PP -Locating a service on a remote host requires many levels of -mapping before client and server may -communicate. A service is assigned a name which is intended -for human consumption; e.g. \*(lqthe \fIlogin server\fP on host -monet\*(rq. -This name, and the name of the peer host, must then be translated -into network \fIaddresses\fP which are not necessarily suitable -for human consumption. Finally, the address must then used in locating -a physical \fIlocation\fP and \fIroute\fP to the service. The -specifics of these three mappings are likely to vary between -network architectures. For instance, it is desirable for a network -to not require hosts to -be named in such a way that their physical location is known by -the client host. Instead, underlying services in the network -may discover the actual location of the host at the time a client -host wishes to communicate. This ability to have hosts named in -a location independent manner may induce overhead in connection -establishment, as a discovery process must take place, -but allows a host to be physically mobile without requiring it to -notify its clientele of its current location. -.PP -Standard routines are provided for: mapping host names -to network addresses, network names to network numbers, -protocol names to protocol numbers, and service names -to port numbers and the appropriate protocol to -use in communicating with the server process. The -file <\fInetdb.h\fP> must be included when using any of these -routines. -.NH 2 -Host names -.PP -An Internet host name to address mapping is represented by -the \fIhostent\fP structure: -.DS -.if t .ta 0.6i 1.1i 2.6i -struct hostent { - char *h_name; /* official name of host */ - char **h_aliases; /* alias list */ - int h_addrtype; /* host address type (e.g., AF_INET) */ - int h_length; /* length of address */ - char **h_addr_list; /* list of addresses, null terminated */ -}; - -#define h_addr h_addr_list[0] /* first address, network byte order */ -.DE -The routine \fIgethostbyname\fP(3N) takes an Internet host name -and returns a \fIhostent\fP structure, -while the routine \fIgethostbyaddr\fP(3N) -maps Internet host addresses into a \fIhostent\fP structure. -.PP -The official name of the host and its public aliases are -returned by these routines, -along with the address type (family) and a null terminated list of -variable length address. This list of addresses is -required because it is possible -for a host to have many addresses, all having the same name. -The \fIh_addr\fP definition is provided for backward compatibility, -and is defined to be the first address in the list of addresses -in the \fIhostent\fP structure. -.PP -The database for these calls is provided either by the -file \fI/etc/hosts\fP (\fIhosts\fP\|(5)), -or by use of a nameserver, \fInamed\fP\|(8). -Because of the differences in these databases and their access protocols, -the information returned may differ. -When using the host table version of \fIgethostbyname\fP, -only one address will be returned, but all listed aliases will be included. -The nameserver version may return alternate addresses, -but will not provide any aliases other than one given as argument. -.PP -Unlike Internet names, NS names are always mapped into host -addresses by the use of a standard NS \fIClearinghouse service\fP, -a distributed name and authentication server. The algorithms -for mapping NS names to addresses via a Clearinghouse are -rather complicated, and the routines are not part of the -standard libraries. The user-contributed Courier (Xerox -remote procedure call protocol) compiler contains routines -to accomplish this mapping; see the documentation and -examples provided therein for more information. It is -expected that almost all software that has to communicate -using NS will need to use the facilities of -the Courier compiler. -.PP -An NS host address is represented by the following: -.DS -union ns_host { - u_char c_host[6]; - u_short s_host[3]; -}; - -union ns_net { - u_char c_net[4]; - u_short s_net[2]; -}; - -struct ns_addr { - union ns_net x_net; - union ns_host x_host; - u_short x_port; -}; -.DE -The following code fragment inserts a known NS address into -a \fIns_addr\fP: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> - ... -u_long netnum; -struct sockaddr_ns dst; - ... -bzero((char *)&dst, sizeof(dst)); - -/* - * There is no convenient way to assign a long - * integer to a ``union ns_net'' at present; in - * the future, something will hopefully be provided, - * but this is the portable way to go for now. - * The network number below is the one for the NS net - * that the desired host (gyre) is on. - */ -netnum = htonl(2266); -dst.sns_addr.x_net = *(union ns_net *) &netnum; -dst.sns_family = AF_NS; - -/* - * host 2.7.1.0.2a.18 == "gyre:Computer Science:UofMaryland" - */ -dst.sns_addr.x_host.c_host[0] = 0x02; -dst.sns_addr.x_host.c_host[1] = 0x07; -dst.sns_addr.x_host.c_host[2] = 0x01; -dst.sns_addr.x_host.c_host[3] = 0x00; -dst.sns_addr.x_host.c_host[4] = 0x2a; -dst.sns_addr.x_host.c_host[5] = 0x18; -dst.sns_addr.x_port = htons(75); -.DE -.NH 2 -Network names -.PP -As for host names, routines for mapping network names to numbers, -and back, are provided. These routines return a \fInetent\fP -structure: -.DS -.DT -/* - * Assumption here is that a network number - * fits in 32 bits -- probably a poor one. - */ -struct netent { - char *n_name; /* official name of net */ - char **n_aliases; /* alias list */ - int n_addrtype; /* net address type */ - int n_net; /* network number, host byte order */ -}; -.DE -The routines \fIgetnetbyname\fP(3N), \fIgetnetbynumber\fP(3N), -and \fIgetnetent\fP(3N) are the network counterparts to the -host routines described above. The routines extract their -information from \fI/etc/networks\fP. -.PP -NS network numbers are determined either by asking your local -Xerox Network Administrator (and hardcoding the information -into your code), or by querying the Clearinghouse for addresses. -The internetwork router is the only process -that needs to manipulate network numbers on a regular basis; if -a process wishes to communicate with a machine, it should ask the -Clearinghouse for that machine's address (which will include -the net number). -.NH 2 -Protocol names -.PP -For protocols, which are defined in \fI/etc/protocols\fP, -the \fIprotoent\fP structure defines the -protocol-name mapping -used with the routines \fIgetprotobyname\fP(3N), -\fIgetprotobynumber\fP(3N), -and \fIgetprotoent\fP(3N): -.DS -.DT -struct protoent { - char *p_name; /* official protocol name */ - char **p_aliases; /* alias list */ - int p_proto; /* protocol number */ -}; -.DE -.PP -In the NS domain, protocols are indicated by the "client type" -field of a IDP header. No protocol database exists; see section -5 for more information. -.NH 2 -Service names -.PP -Information regarding services is a bit more complicated. A service -is expected to reside at a specific \*(lqport\*(rq and employ -a particular communication protocol. This view is consistent with -the Internet domain, but inconsistent with other network architectures. -Further, a service may reside on multiple ports. -If this occurs, the higher level library routines -will have to be bypassed or extended. -Services available are contained in the file \fI/etc/services\fP. -A service mapping is described by the \fIservent\fP structure, -.DS -.DT -struct servent { - char *s_name; /* official service name */ - char **s_aliases; /* alias list */ - int s_port; /* port number, network byte order */ - char *s_proto; /* protocol to use */ -}; -.DE -The routine \fIgetservbyname\fP(3N) maps service -names to a servent structure by specifying a service name and, -optionally, a qualifying protocol. Thus the call -.DS -sp = getservbyname("telnet", (char *) 0); -.DE -returns the service specification for a telnet server using -any protocol, while the call -.DS -sp = getservbyname("telnet", "tcp"); -.DE -returns only that telnet server which uses the TCP protocol. -The routines \fIgetservbyport\fP(3N) and \fIgetservent\fP(3N) are -also provided. The \fIgetservbyport\fP routine has an interface similar -to that provided by \fIgetservbyname\fP; an optional protocol name may -be specified to qualify lookups. -.PP -In the NS domain, services are handled by a central dispatcher -provided as part of the Courier remote procedure call facilities. -Again, the reader is referred to the Courier compiler documentation -and to the Xerox standard* -.FS -* \fICourier: The Remote Procedure Call Protocol\fP, XSIS 038112. -.FE -for further details. -.NH 2 -Miscellaneous -.PP -With the support routines described above, an Internet application program -should rarely have to deal directly -with addresses. This allows -services to be developed as much as possible in a network independent -fashion. It is clear, however, that purging all network dependencies -is very difficult. So long as the user is required to supply network -addresses when naming services and sockets there will always some -network dependency in a program. For example, the normal -code included in client programs, such as the remote login program, -is of the form shown in Figure 1. -(This example will be considered in more detail in section 4.) -.PP -If we wanted to make the remote login program independent of the -Internet protocols and addressing scheme we would be forced to add -a layer of routines which masked the network dependent aspects from -the mainstream login code. For the current facilities available in -the system this does not appear to be worthwhile. -.PP -Aside from the address-related data base routines, there are several -other routines available in the run-time library which are of interest -to users. These are intended mostly to simplify manipulation of -names and addresses. Table 1 summarizes the routines -for manipulating variable length byte strings and handling byte -swapping of network addresses and values. -.KF -.DS B -.TS -box; -l | l -l | l. -Call Synopsis -_ -bcmp(s1, s2, n) compare byte-strings; 0 if same, not 0 otherwise -bcopy(s1, s2, n) copy n bytes from s1 to s2 -bzero(base, n) zero-fill n bytes starting at base -htonl(val) convert 32-bit quantity from host to network byte order -htons(val) convert 16-bit quantity from host to network byte order -ntohl(val) convert 32-bit quantity from network to host byte order -ntohs(val) convert 16-bit quantity from network to host byte order -.TE -.DE -.ce -Table 1. C run-time routines. -.KE -.PP -The byte swapping routines are provided because the operating -system expects addresses to be supplied in network order (aka ``big-endian'' order). On -``little-endian'' architectures, such as Intel x86 and VAX, -host byte ordering is different than -network byte ordering. Consequently, -programs are sometimes required to byte swap quantities. The -library routines which return network addresses provide them -in network order so that they may simply be copied into the structures -provided to the system. This implies users should encounter the -byte swapping problem only when \fIinterpreting\fP network addresses. -For example, if an Internet port is to be printed out the following -code would be required: -.DS -printf("port number %d\en", ntohs(sp->s_port)); -.DE -On machines where unneeded these routines are defined as null -macros. -.DS -.if t .ta .5i 1.0i 1.5i 2.0i -.if n .ta .7i 1.4i 2.1i 2.8i -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <stdio.h> -#include <netdb.h> - ... -main(argc, argv) - int argc; - char *argv[]; -{ - struct sockaddr_in server; - struct servent *sp; - struct hostent *hp; - int s; - ... - sp = getservbyname("login", "tcp"); - if (sp == NULL) { - fprintf(stderr, "rlogin: tcp/login: unknown service\en"); - exit(1); - } - hp = gethostbyname(argv[1]); - if (hp == NULL) { - fprintf(stderr, "rlogin: %s: unknown host\en", argv[1]); - exit(2); - } - bzero((char *)&server, sizeof (server)); - bcopy(hp->h_addr, (char *)&server.sin_addr, hp->h_length); - server.sin_family = hp->h_addrtype; - server.sin_port = sp->s_port; - s = socket(AF_INET, SOCK_STREAM, 0); - if (s < 0) { - perror("rlogin: socket"); - exit(3); - } - ... - /* Connect does the bind() for us */ - - if (connect(s, (char *)&server, sizeof (server)) < 0) { - perror("rlogin: connect"); - exit(5); - } - ... -} -.DE -.ce -Figure 1. Remote login client code. diff --git a/share/doc/psd/21.ipc/4.t b/share/doc/psd/21.ipc/4.t deleted file mode 100644 index f770b8faa0f..00000000000 --- a/share/doc/psd/21.ipc/4.t +++ /dev/null @@ -1,512 +0,0 @@ -.\" $OpenBSD: 4.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)4.t 8.1 (Berkeley) 6/8/93 -.\" -.\".ds RH "Client/Server Model -.bp -.nr H1 4 -.nr H2 0 -.sp 8i -.bp -.LG -.B -.ce -4. CLIENT/SERVER MODEL -.sp 2 -.R -.NL -.PP -The most commonly used paradigm in constructing distributed applications -is the client/server model. In this scheme client applications request -services from a server process. This implies an asymmetry in establishing -communication between the client and server which has been examined -in section 2. In this section we will look more closely at the interactions -between client and server, and consider some of the problems in developing -client and server applications. -.PP -The client and server require a well known set of conventions before -service may be rendered (and accepted). This set of conventions -comprises a protocol which must be implemented at both ends of a -connection. Depending on the situation, the protocol may be symmetric -or asymmetric. In a symmetric protocol, either side may play the -master or slave roles. In an asymmetric protocol, one side is -immutably recognized as the master, with the other as the slave. -An example of a symmetric protocol is the TELNET protocol used in -the Internet for remote terminal emulation. An example -of an asymmetric protocol is the Internet file transfer protocol, -FTP. No matter whether the specific protocol used in obtaining -a service is symmetric or asymmetric, when accessing a service there -is a \*(lqclient process\*(rq and a \*(lqserver process\*(rq. We -will first consider the properties of server processes, then -client processes. -.PP -A server process normally listens at a well known address for -service requests. That is, the server process remains dormant -until a connection is requested by a client's connection -to the server's address. At such a time -the server process ``wakes up'' and services the client, -performing whatever appropriate actions the client requests of it. -.PP -Alternative schemes which use a service server -may be used to eliminate a flock of server processes clogging the -system while remaining dormant most of the time. For Internet -servers in 4.4BSD, -this scheme has been implemented via \fIinetd\fP, the so called -``internet super-server.'' \fIInetd\fP listens at a variety -of ports, determined at start-up by reading a configuration file. -When a connection is requested to a port on which \fIinetd\fP is -listening, \fIinetd\fP executes the appropriate server program to handle the -client. With this method, clients are unaware that an -intermediary such as \fIinetd\fP has played any part in the -connection. \fIInetd\fP will be described in more detail in -section 5. -.PP -A similar alternative scheme is used by most Xerox services. In general, -the Courier dispatch process (if used) accepts connections from -processes requesting services of some sort or another. The client -processes request a particular <program number, version number, procedure -number> triple. If the dispatcher knows of such a program, it is -started to handle the request; if not, an error is reported to the -client. In this way, only one port is required to service a large -variety of different requests. Again, the Courier facilities are -not available without the use and installation of the Courier -compiler. The information presented in this section applies only -to NS clients and services that do not use Courier. -.NH 2 -Servers -.PP -In 4.4BSD most servers are accessed at well known Internet addresses -or UNIX domain names. For -example, the remote login server's main loop is of the form shown -in Figure 2. -.KF -.if t .ta .5i 1.0i 1.5i 2.0i 2.5i 3.0i 3.5i -.if n .ta .7i 1.4i 2.1i 2.8i 3.5i 4.2i 4.9i -.sp 0.5i -.DS -main(argc, argv) - int argc; - char *argv[]; -{ - int f; - struct sockaddr_in from; - struct servent *sp; - - sp = getservbyname("login", "tcp"); - if (sp == NULL) { - fprintf(stderr, "rlogind: tcp/login: unknown service\en"); - exit(1); - } - ... -#ifndef DEBUG - /* Disassociate server from controlling terminal */ - ... -#endif - - sin.sin_port = sp->s_port; /* Restricted port -- see section 5 */ - ... - f = socket(AF_INET, SOCK_STREAM, 0); - ... - if (bind(f, (struct sockaddr *) &sin, sizeof (sin)) < 0) { - ... - } - ... - listen(f, 5); - for (;;) { - int g, len = sizeof (from); - - g = accept(f, (struct sockaddr *) &from, &len); - if (g < 0) { - if (errno != EINTR) - syslog(LOG_ERR, "rlogind: accept: %m"); - continue; - } - if (fork() == 0) { - close(f); - doit(g, &from); - } - close(g); - } -} -.DE -.ce -Figure 2. Remote login server. -.sp 0.5i -.KE -.PP -The first step taken by the server is look up its service -definition: -.sp 1 -.nf -.in +5 -.if t .ta .5i 1.0i 1.5i 2.0i -.if n .ta .7i 1.4i 2.1i 2.8i -sp = getservbyname("login", "tcp"); -if (sp == NULL) { - fprintf(stderr, "rlogind: tcp/login: unknown service\en"); - exit(1); -} -.sp 1 -.in -5 -.fi -The result of the \fIgetservbyname\fP call -is used in later portions of the code to -define the Internet port at which it listens for service -requests (indicated by a connection). -.KS -.PP -Step two is to disassociate the server from the controlling -terminal of its invoker: -.DS - for (i = 0; i < 3; ++i) - close(i); - - open("/", O_RDONLY); - dup2(0, 1); - dup2(0, 2); - - i = open("/dev/tty", O_RDWR); - if (i >= 0) { - ioctl(i, TIOCNOTTY, 0); - close(i); - } -.DE -.KE -This step is important as the server will -likely not want to receive signals delivered to the process -group of the controlling terminal. Note, however, that -once a server has disassociated itself it can no longer -send reports of errors to a terminal, and must log errors -via \fIsyslog\fP. -.PP -Once a server has established a pristine environment, it -creates a socket and begins accepting service requests. -The \fIbind\fP call is required to insure the server listens -at its expected location. It should be noted that the -remote login server listens at a restricted port number, and must -therefore be run -with a user-id of root. -This concept of a ``restricted port number'' is 4BSD -specific, and is covered in section 5. -.PP -The main body of the loop is fairly simple: -.DS -.if t .ta .5i 1.0i 1.5i 2.0i -.if n .ta .7i 1.4i 2.1i 2.8i -for (;;) { - int g, len = sizeof (from); - - g = accept(f, (struct sockaddr *)&from, &len); - if (g < 0) { - if (errno != EINTR) - syslog(LOG_ERR, "rlogind: accept: %m"); - continue; - } - if (fork() == 0) { /* Child */ - close(f); - doit(g, &from); - } - close(g); /* Parent */ -} -.DE -An \fIaccept\fP call blocks the server until -a client requests service. This call could return a -failure status if the call is interrupted by a signal -such as SIGCHLD (to be discussed in section 5). Therefore, -the return value from \fIaccept\fP is checked to insure -a connection has actually been established, and -an error report is logged via \fIsyslog\fP if an error -has occurred. -.PP -With a connection -in hand, the server then forks a child process and invokes -the main body of the remote login protocol processing. Note -how the socket used by the parent for queuing connection -requests is closed in the child, while the socket created as -a result of the \fIaccept\fP is closed in the parent. The -address of the client is also handed the \fIdoit\fP routine -because it requires it in authenticating clients. -.NH 2 -Clients -.PP -The client side of the remote login service was shown -earlier in Figure 1. -One can see the separate, asymmetric roles of the client -and server clearly in the code. The server is a passive entity, -listening for client connections, while the client process is -an active entity, initiating a connection when invoked. -.PP -Let us consider more closely the steps taken -by the client remote login process. As in the server process, -the first step is to locate the service definition for a remote -login: -.DS -sp = getservbyname("login", "tcp"); -if (sp == NULL) { - fprintf(stderr, "rlogin: tcp/login: unknown service\en"); - exit(1); -} -.DE -Next the destination host is looked up with a -\fIgethostbyname\fP call: -.DS -hp = gethostbyname(argv[1]); -if (hp == NULL) { - fprintf(stderr, "rlogin: %s: unknown host\en", argv[1]); - exit(2); -} -.DE -With this accomplished, all that is required is to establish a -connection to the server at the requested host and start up the -remote login protocol. The address buffer is cleared, then filled -in with the Internet address of the foreign host and the port -number at which the login process resides on the foreign host: -.DS -bzero((char *)&server, sizeof (server)); -bcopy(hp->h_addr, (char *) &server.sin_addr, hp->h_length); -server.sin_family = hp->h_addrtype; -server.sin_port = sp->s_port; -.DE -A socket is created, and a connection initiated. Note -that \fIconnect\fP implicitly performs a \fIbind\fP -call, since \fIs\fP is unbound. -.DS -s = socket(hp->h_addrtype, SOCK_STREAM, 0); -if (s < 0) { - perror("rlogin: socket"); - exit(3); -} - ... -if (connect(s, (struct sockaddr *) &server, sizeof (server)) < 0) { - perror("rlogin: connect"); - exit(4); -} -.DE -The details of the remote login protocol will not be considered here. -.NH 2 -Connectionless servers -.PP -While connection-based services are the norm, some services -are based on the use of datagram sockets. One, in particular, -is the \*(lqrwho\*(rq service which provides users with status -information for hosts connected to a local area -network. This service, while predicated on the ability to -\fIbroadcast\fP information to all hosts connected to a particular -network, is of interest as an example usage of datagram sockets. -.PP -A user on any machine running the rwho server may find out -the current status of a machine with the \fIruptime\fP(1) program. -The output generated is illustrated in Figure 3. -.KF -.DS B -.TS -l r l l l l l. -arpa up 9:45, 5 users, load 1.15, 1.39, 1.31 -cad up 2+12:04, 8 users, load 4.67, 5.13, 4.59 -calder up 10:10, 0 users, load 0.27, 0.15, 0.14 -dali up 2+06:28, 9 users, load 1.04, 1.20, 1.65 -degas up 25+09:48, 0 users, load 1.49, 1.43, 1.41 -ear up 5+00:05, 0 users, load 1.51, 1.54, 1.56 -ernie down 0:24 -esvax down 17:04 -ingres down 0:26 -kim up 3+09:16, 8 users, load 2.03, 2.46, 3.11 -matisse up 3+06:18, 0 users, load 0.03, 0.03, 0.05 -medea up 3+09:39, 2 users, load 0.35, 0.37, 0.50 -merlin down 19+15:37 -miro up 1+07:20, 7 users, load 4.59, 3.28, 2.12 -monet up 1+00:43, 2 users, load 0.22, 0.09, 0.07 -oz down 16:09 -statvax up 2+15:57, 3 users, load 1.52, 1.81, 1.86 -ucbvax up 9:34, 2 users, load 6.08, 5.16, 3.28 -.TE -.DE -.ce -Figure 3. ruptime output. -.sp -.KE -.PP -Status information for each host is periodically broadcast -by rwho server processes on each machine. The same server -process also receives the status information and uses it -to update a database. This database is then interpreted -to generate the status information for each host. Servers -operate autonomously, coupled only by the local network and -its broadcast capabilities. -.PP -Note that the use of broadcast for such a task is fairly inefficient, -as all hosts must process each message, whether or not using an rwho server. -Unless such a service is sufficiently universal and is frequently used, -the expense of periodic broadcasts outweighs the simplicity. -.PP -Multicasting is an alternative to broadcasting. -Setting up multicast sockets is described in Section 5.10. -.PP -The rwho server, in a simplified form, is pictured in Figure -4. There are two separate tasks performed by the server. The -first task is to act as a receiver of status information broadcast -by other hosts on the network. This job is carried out in the -main loop of the program. Packets received at the rwho port -are interrogated to insure they've been sent by another rwho -server process, then are time stamped with their arrival time -and used to update a file indicating the status of the host. -When a host has not been heard from for an extended period of -time, the database interpretation routines assume the host is -down and indicate such on the status reports. This algorithm -is prone to error as a server may be down while a host is actually -up, but serves our current needs. -.KF -.DS -.if t .ta .5i 1.0i 1.5i 2.0i -.if n .ta .7i 1.4i 2.1i 2.8i -main() -{ - ... - sp = getservbyname("who", "udp"); - net = getnetbyname("localnet"); - sin.sin_addr = inet_makeaddr(INADDR_ANY, net); - sin.sin_port = sp->s_port; - ... - s = socket(AF_INET, SOCK_DGRAM, 0); - ... - on = 1; - if (setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on)) < 0) { - syslog(LOG_ERR, "setsockopt SO_BROADCAST: %m"); - exit(1); - } - bind(s, (struct sockaddr *) &sin, sizeof (sin)); - ... - signal(SIGALRM, onalrm); - onalrm(); - for (;;) { - struct whod wd; - int cc, whod, len = sizeof (from); - - cc = recvfrom(s, (char *)&wd, sizeof (struct whod), 0, - (struct sockaddr *)&from, &len); - if (cc <= 0) { - if (cc < 0 && errno != EINTR) - syslog(LOG_ERR, "rwhod: recv: %m"); - continue; - } - if (from.sin_port != sp->s_port) { - syslog(LOG_ERR, "rwhod: %d: bad from port", - ntohs(from.sin_port)); - continue; - } - ... - if (!verify(wd.wd_hostname)) { - syslog(LOG_ERR, "rwhod: malformed host name from %x", - ntohl(from.sin_addr.s_addr)); - continue; - } - (void) sprintf(path, "%s/whod.%s", RWHODIR, wd.wd_hostname); - whod = open(path, O_WRONLY | O_CREAT | O_TRUNC, 0666); - ... - (void) time(&wd.wd_recvtime); - (void) write(whod, (char *)&wd, cc); - (void) close(whod); - } -} -.DE -.ce -Figure 4. rwho server. -.sp -.KE -.PP -The second task performed by the server is to supply information -regarding the status of its host. This involves periodically -acquiring system status information, packaging it up in a message -and broadcasting it on the local network for other rwho servers -to hear. The supply function is triggered by a timer and -runs off a signal. Locating the system status -information is somewhat involved, but uninteresting. Deciding -where to transmit the resultant packet -is somewhat problematical, however. -.PP -Status information must be broadcast on the local network. -For networks which do not support the notion of broadcast another -scheme must be used to simulate or -replace broadcasting. One possibility is to enumerate the -known neighbors (based on the status messages received -from other rwho servers). This, unfortunately, -requires some bootstrapping information, -for a server will have no idea what machines are its -neighbors until it receives status messages from them. -Therefore, if all machines on a net are freshly booted, -no machine will have any -known neighbors and thus never receive, or send, any status information. -This is the identical problem faced by the routing table management -process in propagating routing status information. The standard -solution, unsatisfactory as it may be, is to inform one or more servers -of known neighbors and request that they always communicate with -these neighbors. If each server has at least one neighbor supplied -to it, status information may then propagate through -a neighbor to hosts which -are not (possibly) directly neighbors. If the server is able to -support networks which provide a broadcast capability, as well as -those which do not, then networks with an -arbitrary topology may share status information*. -.FS -* One must, however, be concerned about \*(lqloops\*(rq. -That is, if a host is connected to multiple networks, it -will receive status information from itself. This can lead -to an endless, wasteful, exchange of information. -.FE -.PP -It is important that software operating in a distributed -environment not have any site-dependent information compiled into it. -This would require a separate copy of the server at each host and -make maintenance a severe headache. 4.4BSD attempts to isolate -host-specific information from applications by providing system -calls which return the necessary information*. -.FS -* An example of such a system call is the \fIgethostname\fP(2) -call which returns the host's \*(lqofficial\*(rq name. -.FE -A mechanism exists, in the form of an \fIioctl\fP call, -for finding the collection -of networks to which a host is directly connected. -Further, a local network broadcasting mechanism -has been implemented at the socket level. -Combining these two features allows a process -to broadcast on any directly connected local -network which supports the notion of broadcasting -in a site independent manner. This allows 4.4BSD -to solve the problem of deciding how to propagate -status information in the case of \fIrwho\fP, or -more generally in broadcasting: -Such status information is broadcast to connected -networks at the socket level, where the connected networks -have been obtained via the appropriate \fIioctl\fP -calls. -The specifics of -such broadcastings are complex, however, and will -be covered in section 5. diff --git a/share/doc/psd/21.ipc/5.t b/share/doc/psd/21.ipc/5.t deleted file mode 100644 index e72f94aa08f..00000000000 --- a/share/doc/psd/21.ipc/5.t +++ /dev/null @@ -1,1665 +0,0 @@ -.\" $OpenBSD: 5.t,v 1.4 2005/09/20 20:36:09 krw Exp $ -.\" -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)5.t 8.1 (Berkeley) 8/14/93 -.\" -.\".ds RH "Advanced Topics -.bp -.nr H1 5 -.nr H2 0 -.LG -.B -.ce -5. ADVANCED TOPICS -.sp 2 -.R -.NL -.PP -A number of facilities have yet to be discussed. For most users -of the IPC the mechanisms already -described will suffice in constructing distributed -applications. However, others will find the need to utilize some -of the features which we consider in this section. -.NH 2 -Out of band data -.PP -The stream socket abstraction includes the notion of \*(lqout -of band\*(rq data. Out of band data is a logically independent -transmission channel associated with each pair of connected -stream sockets. Out of band data is delivered to the user -independently of normal data. -The abstraction defines that the out of band data facilities -must support the reliable delivery of at least one -out of band message at a time. This message may contain at least one -byte of data, and at least one message may be pending delivery -to the user at any one time. For communications protocols which -support only in-band signaling (i.e. the urgent data is -delivered in sequence with the normal data), the system normally extracts -the data from the normal data stream and stores it separately. -This allows users to choose between receiving the urgent data -in order and receiving it out of sequence without having to -buffer all the intervening data. It is possible -to ``peek'' (via MSG_PEEK) at out of band data. -If the socket has a process group, a SIGURG signal is generated -when the protocol is notified of its existence. -A process can set the process group -or process id to be informed by the SIGURG signal via the -appropriate \fIfcntl\fP call, as described below for -SIGIO. -If multiple sockets may have out of band data awaiting -delivery, a \fIselect\fP call for exceptional conditions -may be used to determine those sockets with such data pending. -Neither the signal nor the select indicate the actual arrival -of the out-of-band data, but only notification that it is pending. -.PP -In addition to the information passed, a logical mark is placed in -the data stream to indicate the point at which the out -of band data was sent. The remote login and remote shell -applications use this facility to propagate signals between -client and server processes. When a signal -flushs any pending output from the remote process(es), all -data up to the mark in the data stream is discarded. -.PP -To send an out of band message the MSG_OOB flag is supplied to -a \fIsend\fP or \fIsendto\fP calls, -while to receive out of band data MSG_OOB should be indicated -when performing a \fIrecvfrom\fP or \fIrecv\fP call. -To find out if the read pointer is currently pointing at -the mark in the data stream, the SIOCATMARK ioctl is provided: -.DS -ioctl(s, SIOCATMARK, &yes); -.DE -If \fIyes\fP is a 1 on return, the next read will return data -after the mark. Otherwise (assuming out of band data has arrived), -the next read will provide data sent by the client prior -to transmission of the out of band signal. The routine used -in the remote login process to flush output on receipt of an -interrupt or quit signal is shown in Figure 5. -It reads the normal data up to the mark (to discard it), -then reads the out-of-band byte. -.KF -.DS -#include <sys/ioctl.h> -#include <sys/file.h> - ... -oob() -{ - int out = FWRITE, mark; - char waste[BUFSIZ]; - - /* flush local terminal output */ - ioctl(1, TIOCFLUSH, (char *)&out); - for (;;) { - if (ioctl(rem, SIOCATMARK, &mark) < 0) { - perror("ioctl"); - break; - } - if (mark) - break; - (void) read(rem, waste, sizeof (waste)); - } - if (recv(rem, &mark, 1, MSG_OOB) < 0) { - perror("recv"); - ... - } - ... -} -.DE -.ce -Figure 5. Flushing terminal I/O on receipt of out of band data. -.sp -.KE -.PP -A process may also read or peek at the out-of-band data -without first reading up to the mark. -This is more difficult when the underlying protocol delivers -the urgent data in-band with the normal data, and only sends -notification of its presence ahead of time (e.g., the TCP protocol -used to implement streams in the Internet domain). -With such protocols, the out-of-band byte may not yet have arrived -when a \fIrecv\fP is done with the MSG_OOB flag. -In that case, the call will return an error of EWOULDBLOCK. -Worse, there may be enough in-band data in the input buffer -that normal flow control prevents the peer from sending the urgent data -until the buffer is cleared. -The process must then read enough of the queued data -that the urgent data may be delivered. -.PP -Certain programs that use multiple bytes of urgent data and must -handle multiple urgent signals (e.g., \fItelnet\fP\|(1C)) -need to retain the position of urgent data within the stream. -This treatment is available as a socket-level option, SO_OOBINLINE; -see \fIsetsockopt\fP\|(2) for usage. -With this option, the position of urgent data (the \*(lqmark\*(rq) -is retained, but the urgent data immediately follows the mark -within the normal data stream returned without the MSG_OOB flag. -Reception of multiple urgent indications causes the mark to move, -but no out-of-band data are lost. -.NH 2 -Non-Blocking Sockets -.PP -It is occasionally convenient to make use of sockets -which do not block; that is, I/O requests which -cannot complete immediately and -would therefore cause the process to be suspended awaiting completion are -not executed, and an error code is returned. -Once a socket has been created via -the \fIsocket\fP call, it may be marked as non-blocking -by \fIfcntl\fP as follows: -.DS -#include <fcntl.h> - ... -int s; - ... -s = socket(AF_INET, SOCK_STREAM, 0); - ... -if (fcntl(s, F_SETFL, FNDELAY) < 0) - perror("fcntl F_SETFL, FNDELAY"); - exit(1); -} - ... -.DE -.PP -When performing non-blocking I/O on sockets, one must be -careful to check for the error EWOULDBLOCK (stored in the -global variable \fIerrno\fP), which occurs when -an operation would normally block, but the socket it -was performed on is marked as non-blocking. -In particular, \fIaccept\fP, \fIconnect\fP, \fIsend\fP, \fIrecv\fP, -\fIread\fP, and \fIwrite\fP can -all return EWOULDBLOCK, and processes should be prepared -to deal with such return codes. -If an operation such as a \fIsend\fP cannot be done in its entirety, -but partial writes are sensible (for example, when using a stream socket), -the data that can be sent immediately will be processed, -and the return value will indicate the amount actually sent. -.NH 2 -Interrupt driven socket I/O -.PP -The SIGIO signal allows a process to be notified -via a signal when a socket (or more generally, a file -descriptor) has data waiting to be read. Use of -the SIGIO facility requires three steps: First, -the process must set up a SIGIO signal handler -by use of the \fIsignal\fP or \fIsigvec\fP calls. Second, -it must set the process id or process group id which is to receive -notification of pending input to its own process id, -or the process group id of its process group (note that -the default process group of a socket is group zero). -This is accomplished by use of an \fIfcntl\fP call. -Third, it must enable asynchronous notification of pending I/O requests -with another \fIfcntl\fP call. Sample code to -allow a given process to receive information on -pending I/O requests as they occur for a socket \fIs\fP -is given in Figure 6. With the addition of a handler for SIGURG, -this code can also be used to prepare for receipt of SIGURG signals. -.KF -.DS -#include <fcntl.h> - ... -int io_handler(); - ... -signal(SIGIO, io_handler); - -/* Set the process receiving SIGIO/SIGURG signals to us */ - -if (fcntl(s, F_SETOWN, getpid()) < 0) { - perror("fcntl F_SETOWN"); - exit(1); -} - -/* Allow receipt of asynchronous I/O signals */ - -if (fcntl(s, F_SETFL, FASYNC) < 0) { - perror("fcntl F_SETFL, FASYNC"); - exit(1); -} -.DE -.ce -Figure 6. Use of asynchronous notification of I/O requests. -.sp -.KE -.NH 2 -Signals and process groups -.PP -Due to the existence of the SIGURG and SIGIO signals each socket has an -associated process number, just as is done for terminals. -This value is initialized to zero, -but may be redefined at a later time with the F_SETOWN -\fIfcntl\fP, such as was done in the code above for SIGIO. -To set the socket's process id for signals, positive arguments -should be given to the \fIfcntl\fP call. To set the socket's -process group for signals, negative arguments should be -passed to \fIfcntl\fP. Note that the process number indicates -either the associated process id or the associated process -group; it is impossible to specify both at the same time. -A similar \fIfcntl\fP, F_GETOWN, is available for determining the -current process number of a socket. -.PP -Another signal which is useful when constructing server processes -is SIGCHLD. This signal is delivered to a process when any -child processes have changed state. Normally servers use -the signal to \*(lqreap\*(rq child processes that have exited -without explicitly awaiting their termination -or periodic polling for exit status. -For example, the remote login server loop shown in Figure 2 -may be augmented as shown in Figure 7. -.KF -.DS -int reaper(); - ... -signal(SIGCHLD, reaper); -listen(f, 5); -for (;;) { - int g, len = sizeof (from); - - g = accept(f, (struct sockaddr *)&from, &len,); - if (g < 0) { - if (errno != EINTR) - syslog(LOG_ERR, "rlogind: accept: %m"); - continue; - } - ... -} - ... -#include <wait.h> -reaper() -{ - union wait status; - - while (wait3(&status, WNOHANG, 0) > 0) - ; -} -.DE -.sp -.ce -Figure 7. Use of the SIGCHLD signal. -.sp -.KE -.PP -If the parent server process fails to reap its children, -a large number of \*(lqzombie\*(rq processes may be created. -.NH 2 -Pseudo terminals -.PP -Many programs will not function properly without a terminal -for standard input and output. Since sockets do not provide -the semantics of terminals, -it is often necessary to have a process communicating over -the network do so through a \fIpseudo-terminal\fP. A pseudo- -terminal is actually a pair of devices, master and slave, -which allow a process to serve as an active agent in communication -between processes and users. Data written on the slave side -of a pseudo-terminal is supplied as input to a process reading -from the master side, while data written on the master side are -processed as terminal input for the slave. -In this way, the process manipulating -the master side of the pseudo-terminal has control over the -information read and written on the slave side -as if it were manipulating the keyboard and reading the screen -on a real terminal. -The purpose of this abstraction is to -preserve terminal semantics over a network connection\(em -that is, the slave side appears as a normal terminal to -any process reading from or writing to it. -.PP -For example, the remote -login server uses pseudo-terminals for remote login sessions. -A user logging in to a machine across the network is provided -a shell with a slave pseudo-terminal as standard input, output, -and error. The server process then handles the communication -between the programs invoked by the remote shell and the user's -local client process. -When a user sends a character that generates an interrupt -on the remote machine that flushes terminal output, -the pseudo-terminal generates a control message for the server process. -The server then sends an out of band message -to the client process to signal a flush of data at the real terminal -and on the intervening data buffered in the network. -.PP -Under 4.4BSD, the name of the slave side of a pseudo-terminal is of the form -\fI/dev/ttyxy\fP, where \fIx\fP is a single letter -starting at `p' and continuing to `t'. -\fIy\fP is a hexadecimal digit (i.e., a single -character in the range 0 through 9 or `a' through `f'). -The master side of a pseudo-terminal is \fI/dev/ptyxy\fP, -where \fIx\fP and \fIy\fP correspond to the -slave side of the pseudo-terminal. -.PP -In general, the method of obtaining a pair of master and -slave pseudo-terminals is to -find a pseudo-terminal which -is not currently in use. -The master half of a pseudo-terminal is a single-open device; -thus, each master may be opened in turn until an open succeeds. -The slave side of the pseudo-terminal is then opened, -and is set to the proper terminal modes if necessary. -The process then \fIfork\fPs; the child closes -the master side of the pseudo-terminal, and \fIexec\fPs the -appropriate program. Meanwhile, the parent closes the -slave side of the pseudo-terminal and begins reading and -writing from the master side. Sample code making use of -pseudo-terminals is given in Figure 8; this code assumes -that a connection on a socket \fIs\fP exists, connected -to a peer who wants a service of some kind, and that the -process has disassociated itself from any previous controlling terminal. -.KF -.DS -gotpty = 0; -for (c = 'p'; !gotpty && c <= 's'; c++) { - line = "/dev/ptyXX"; - line[sizeof("/dev/pty")-1] = c; - line[sizeof("/dev/ptyp")-1] = '0'; - if (stat(line, &statbuf) < 0) - break; - for (i = 0; i < 16; i++) { - line[sizeof("/dev/ptyp")-1] = "0123456789abcdef"[i]; - master = open(line, O_RDWR); - if (master > 0) { - gotpty = 1; - break; - } - } -} -if (!gotpty) { - syslog(LOG_ERR, "All network ports in use"); - exit(1); -} - -line[sizeof("/dev/")-1] = 't'; -slave = open(line, O_RDWR); /* \fIslave\fP is now slave side */ -if (slave < 0) { - syslog(LOG_ERR, "Cannot open slave pty %s", line); - exit(1); -} - -ioctl(slave, TIOCGETP, &b); /* Set slave tty modes */ -b.sg_flags = CRMOD|XTABS|ANYP; -ioctl(slave, TIOCSETP, &b); - -i = fork(); -if (i < 0) { - syslog(LOG_ERR, "fork: %m"); - exit(1); -} else if (i) { /* Parent */ - close(slave); - ... -} else { /* Child */ - (void) close(s); - (void) close(master); - dup2(slave, 0); - dup2(slave, 1); - dup2(slave, 2); - if (slave > 2) - (void) close(slave); - ... -} -.DE -.ce -Figure 8. Creation and use of a pseudo terminal -.sp -.KE -.NH 2 -Selecting specific protocols -.PP -If the third argument to the \fIsocket\fP call is 0, -\fIsocket\fP will select a default protocol to use with -the returned socket of the type requested. -The default protocol is usually correct, and alternate choices are not -usually available. -However, when using ``raw'' sockets to communicate directly with -lower-level protocols or hardware interfaces, -the protocol argument may be important for setting up demultiplexing. -For example, raw sockets in the Internet family may be used to implement -a new protocol above IP, and the socket will receive packets -only for the protocol specified. -To obtain a particular protocol one determines the protocol number -as defined within the communication domain. For the Internet -domain one may use one of the library routines -discussed in section 3, such as \fIgetprotobyname\fP: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <netdb.h> - ... -pp = getprotobyname("newtcp"); -s = socket(AF_INET, SOCK_STREAM, pp->p_proto); -.DE -This would result in a socket \fIs\fP using a stream -based connection, but with protocol type of ``newtcp'' -instead of the default ``tcp.'' -.PP -In the NS domain, the available socket protocols are defined in -<\fInetns/ns.h\fP>. To create a raw socket for Xerox Error Protocol -messages, one might use: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> - ... -s = socket(AF_NS, SOCK_RAW, NSPROTO_ERROR); -.DE -.NH 2 -Address binding -.PP -As was mentioned in section 2, -binding addresses to sockets in the Internet and NS domains can be -fairly complex. As a brief reminder, these associations -are composed of local and foreign -addresses, and local and foreign ports. Port numbers are -allocated out of separate spaces, one for each system and one -for each domain on that system. -Through the \fIbind\fP system call, a -process may specify half of an association, the -<local address, local port> part, while the -\fIconnect\fP -and \fIaccept\fP -primitives are used to complete a socket's association by -specifying the <foreign address, foreign port> part. -Since the association is created in two steps the association -uniqueness requirement indicated previously could be violated unless -care is taken. Further, it is unrealistic to expect user -programs to always know proper values to use for the local address -and local port since a host may reside on multiple networks and -the set of allocated port numbers is not directly accessible -to a user. -.PP -To simplify local address binding in the Internet domain the notion of a -\*(lqwildcard\*(rq address has been provided. When an address -is specified as INADDR_ANY (a manifest constant defined in -<netinet/in.h>), the system interprets the address as -\*(lqany valid address\*(rq. For example, to bind a specific -port number to a socket, but leave the local address unspecified, -the following code might be used: -.DS -#include <sys/types.h> -#include <netinet/in.h> - ... -struct sockaddr_in sin; - ... -s = socket(AF_INET, SOCK_STREAM, 0); -sin.sin_family = AF_INET; -sin.sin_addr.s_addr = htonl(INADDR_ANY); -sin.sin_port = htons(MYPORT); -bind(s, (struct sockaddr *) &sin, sizeof (sin)); -.DE -Sockets with wildcarded local addresses may receive messages -directed to the specified port number, and sent to any -of the possible addresses assigned to a host. For example, -if a host has addresses 128.32.0.4 and 10.0.0.78, and a socket is bound as -above, the process will be -able to accept connection requests which are addressed to -128.32.0.4 or 10.0.0.78. -If a server process wished to only allow hosts on a -given network connect to it, it would bind -the address of the host on the appropriate network. -.PP -In a similar fashion, a local port may be left unspecified -(specified as zero), in which case the system will select an -appropriate port number for it. This shortcut will work -both in the Internet and NS domains. For example, to -bind a specific local address to a socket, but to leave the -local port number unspecified: -.DS -hp = gethostbyname(hostname); -if (hp == NULL) { - ... -} -bcopy(hp->h_addr, (char *) sin.sin_addr, hp->h_length); -sin.sin_port = htons(0); -bind(s, (struct sockaddr *) &sin, sizeof (sin)); -.DE -The system selects the local port number based on two criteria. -The first is that on 4BSD systems, -Internet ports below IPPORT_RESERVED (1024) (for the Xerox domain, -0 through 3000) are reserved -for privileged users (i.e., the super user); -Internet ports above IPPORT_USERRESERVED (50000) are reserved -for non-privileged servers. The second is -that the port number is not currently bound to some other -socket. In order to find a free Internet port number in the privileged -range the \fIrresvport\fP library routine may be used as follows -to return a stream socket in with a privileged port number: -.DS -int lport = IPPORT_RESERVED \- 1; -int s; -\&... -s = rresvport(&lport); -if (s < 0) { - if (errno == EAGAIN) - fprintf(stderr, "socket: all ports in use\en"); - else - perror("rresvport: socket"); - ... -} -.DE -The restriction on allocating ports was done to allow processes -executing in a \*(lqsecure\*(rq environment to perform authentication -based on the originating address and port number. For example, -the \fIrlogin\fP(1) command allows users to log in across a network -without being asked for a password, if two conditions hold: -First, the name of the system the user -is logging in from is in the file -\fI/etc/hosts.equiv\fP on the system he is logging -in to (or the system name and the user name are in -the user's \fI.rhosts\fP file in the user's home -directory), and second, that the user's rlogin -process is coming from a privileged port on the machine from which he is -logging. The port number and network address of the -machine from which the user is logging in can be determined either -by the \fIfrom\fP result of the \fIaccept\fP call, or -from the \fIgetpeername\fP call. -.PP -In certain cases the algorithm used by the system in selecting -port numbers is unsuitable for an application. This is because -associations are created in a two step process. For example, -the Internet file transfer protocol, FTP, specifies that data -connections must always originate from the same local port. However, -duplicate associations are avoided by connecting to different foreign -ports. In this situation the system would disallow binding the -same local address and port number to a socket if a previous data -connection's socket still existed. To override the default port -selection algorithm, an option call must be performed prior -to address binding: -.DS - ... -int on = 1; - ... -setsockopt(s, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on)); -bind(s, (struct sockaddr *) &sin, sizeof (sin)); -.DE -With the above call, local addresses may be bound which -are already in use. This does not violate the uniqueness -requirement as the system still checks at connect time to -be sure any other sockets with the same local address and -port do not have the same foreign address and port. -If the association already exists, the error EADDRINUSE is returned. -A related socket option, SO_REUSEPORT, which allows completely -duplicate bindings, is described in the IP multicasting section. -.NH 2 -Socket Options -.PP -It is possible to set and get a number of options on sockets -via the \fIsetsockopt\fP and \fIgetsockopt\fP system calls. -These options include such things as marking a socket for -broadcasting, not to route, to linger on close, etc. -In addition, there are protocol-specific options for IP and TCP, -as described in -.IR ip (4), -.IR tcp (4), -and in the section on multicasting below. -.PP -The general forms of the calls are: -.DS -setsockopt(s, level, optname, optval, optlen); -.DE -and -.DS -getsockopt(s, level, optname, optval, optlen); -.DE -.PP -The parameters to the calls are as follows: \fIs\fP -is the socket on which the option is to be applied. -\fILevel\fP specifies the protocol layer on which the -option is to be applied; in most cases this is -the ``socket level'', indicated by the symbolic constant -SOL_SOCKET, defined in \fI<sys/socket.h>.\fP -The actual option is specified in \fIoptname\fP, and is -a symbolic constant also defined in \fI<sys/socket.h>\fP. -\fIOptval\fP and \fIOptlen\fP point to the value of the -option (in most cases, whether the option is to be turned -on or off), and the length of the value of the option, -respectively. -For \fIgetsockopt\fP, \fIoptlen\fP is -a value-result parameter, initially set to the size of -the storage area pointed to by \fIoptval\fP, and modified -upon return to indicate the actual amount of storage used. -.PP -An example should help clarify things. It is sometimes -useful to determine the type (e.g., stream, datagram, etc.) -of an existing socket; programs -under \fIinetd\fP (described below) may need to perform this -task. This can be accomplished as follows via the -SO_TYPE socket option and the \fIgetsockopt\fP call: -.DS -#include <sys/types.h> -#include <sys/socket.h> - -int type, size; - -size = sizeof (int); - -if (getsockopt(s, SOL_SOCKET, SO_TYPE, (char *) &type, &size) < 0) { - ... -} -.DE -After the \fIgetsockopt\fP call, \fItype\fP will be set -to the value of the socket type, as defined in -\fI<sys/socket.h>\fP. If, for example, the socket were -a datagram socket, \fItype\fP would have the value -corresponding to SOCK_DGRAM. -.NH 2 -Broadcasting and determining network configuration -.PP -By using a datagram socket, it is possible to send broadcast -packets on many networks supported by the system. -The network itself must support broadcast; the system -provides no simulation of broadcast in software. -Broadcast messages can place a high load on a network since they force -every host on the network to service them. Consequently, -the ability to send broadcast packets has been limited -to sockets which are explicitly marked as allowing broadcasting. -Broadcast is typically used for one of two reasons: -it is desired to find a resource on a local network without prior -knowledge of its address, -or important functions such as routing require that information -be sent to all accessible neighbors. -.PP -Multicasting is an alternative to broadcasting. -Setting up IP multicast sockets is described in the next section. -.PP -To send a broadcast message, a datagram socket -should be created: -.DS -s = socket(AF_INET, SOCK_DGRAM, 0); -.DE -or -.DS -s = socket(AF_NS, SOCK_DGRAM, 0); -.DE -The socket is marked as allowing broadcasting, -.DS -int on = 1; - -setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof (on)); -.DE -and at least a port number should be bound to the socket: -.DS -sin.sin_family = AF_INET; -sin.sin_addr.s_addr = htonl(INADDR_ANY); -sin.sin_port = htons(MYPORT); -bind(s, (struct sockaddr *) &sin, sizeof (sin)); -.DE -or, for the NS domain, -.DS -sns.sns_family = AF_NS; -netnum = htonl(net); -sns.sns_addr.x_net = *(union ns_net *) &netnum; /* insert net number */ -sns.sns_addr.x_port = htons(MYPORT); -bind(s, (struct sockaddr *) &sns, sizeof (sns)); -.DE -The destination address of the message to be broadcast -depends on the network(s) on which the message is to be broadcast. -The Internet domain supports a shorthand notation for broadcast -on the local network, the address INADDR_BROADCAST (defined in -<\fInetinet/in.h\fP>. -To determine the list of addresses for all reachable neighbors -requires knowledge of the networks to which the host is connected. -Since this information should -be obtained in a host-independent fashion and may be impossible -to derive, 4.4BSD provides a method of -retrieving this information from the system data structures. -The SIOCGIFCONF \fIioctl\fP call returns the interface -configuration of a host in the form of a -single \fIifconf\fP structure; this structure contains -a ``data area'' which is made up of an array of -of \fIifreq\fP structures, one for each network interface -to which the host is connected. -These structures are defined in -\fI<net/if.h>\fP as follows: -.DS -.if t .ta .5i 1.0i 1.5i 3.5i -.if n .ta .7i 1.4i 2.1i 3.4i -struct ifconf { - int ifc_len; /* size of associated buffer */ - union { - caddr_t ifcu_buf; - struct ifreq *ifcu_req; - } ifc_ifcu; -}; - -#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ -#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ - -#define IFNAMSIZ 16 - -struct ifreq { - char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ - union { - struct sockaddr ifru_addr; - struct sockaddr ifru_dstaddr; - struct sockaddr ifru_broadaddr; - short ifru_flags; - caddr_t ifru_data; - } ifr_ifru; -}; - -.if t .ta \w' #define'u +\w' ifr_broadaddr'u +\w' ifr_ifru.ifru_broadaddr'u -#define ifr_addr ifr_ifru.ifru_addr /* address */ -#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ -#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ -#define ifr_flags ifr_ifru.ifru_flags /* flags */ -#define ifr_data ifr_ifru.ifru_data /* for use by interface */ -.DE -The actual call which obtains the -interface configuration is -.DS -struct ifconf ifc; -char buf[BUFSIZ]; - -ifc.ifc_len = sizeof (buf); -ifc.ifc_buf = buf; -if (ioctl(s, SIOCGIFCONF, (char *) &ifc) < 0) { - ... -} -.DE -After this call \fIbuf\fP will contain one \fIifreq\fP structure for -each network to which the host is connected, and -\fIifc.ifc_len\fP will have been modified to reflect the number -of bytes used by the \fIifreq\fP structures. -.PP -For each structure -there exists a set of ``interface flags'' which tell -whether the network corresponding to that interface is -up or down, point to point or broadcast, etc. The -SIOCGIFFLAGS \fIioctl\fP retrieves these -flags for an interface specified by an \fIifreq\fP -structure as follows: -.DS -struct ifreq *ifr; - -ifr = ifc.ifc_req; - -for (n = ifc.ifc_len / sizeof (struct ifreq); --n >= 0; ifr++) { - /* - * We must be careful that we don't use an interface - * devoted to an address family other than those intended; - * if we were interested in NS interfaces, the - * AF_INET would be AF_NS. - */ - if (ifr->ifr_addr.sa_family != AF_INET) - continue; - if (ioctl(s, SIOCGIFFLAGS, (char *) ifr) < 0) { - ... - } - /* - * Skip boring cases. - */ - if ((ifr->ifr_flags & IFF_UP) == 0 || - (ifr->ifr_flags & IFF_LOOPBACK) || - (ifr->ifr_flags & (IFF_BROADCAST | IFF_POINTTOPOINT)) == 0) - continue; -.DE -.PP -Once the flags have been obtained, the broadcast address -must be obtained. In the case of broadcast networks this is -done via the SIOCGIFBRDADDR \fIioctl\fP, while for point-to-point networks -the address of the destination host is obtained with SIOCGIFDSTADDR. -.DS -struct sockaddr dst; - -if (ifr->ifr_flags & IFF_POINTTOPOINT) { - if (ioctl(s, SIOCGIFDSTADDR, (char *) ifr) < 0) { - ... - } - bcopy((char *) ifr->ifr_dstaddr, (char *) &dst, sizeof (ifr->ifr_dstaddr)); -} else if (ifr->ifr_flags & IFF_BROADCAST) { - if (ioctl(s, SIOCGIFBRDADDR, (char *) ifr) < 0) { - ... - } - bcopy((char *) ifr->ifr_broadaddr, (char *) &dst, sizeof (ifr->ifr_broadaddr)); -} -.DE -.PP -After the appropriate \fIioctl\fP's have obtained the broadcast -or destination address (now in \fIdst\fP), the \fIsendto\fP call may be -used: -.DS - sendto(s, buf, buflen, 0, (struct sockaddr *)&dst, sizeof (dst)); -} -.DE -In the above loop one \fIsendto\fP occurs for every -interface to which the host is connected that supports the notion of -broadcast or point-to-point addressing. -If a process only wished to send broadcast -messages on a given network, code similar to that outlined above -would be used, but the loop would need to find the -correct destination address. -.PP -Received broadcast messages contain the senders address -and port, as datagram sockets are bound before -a message is allowed to go out. -.NH 2 -IP Multicasting -.PP -IP multicasting is the transmission of an IP datagram to a "host -group", a set of zero or more hosts identified by a single IP -destination address. A multicast datagram is delivered to all -members of its destination host group with the same "best-efforts" -reliability as regular unicast IP datagrams, i.e., the datagram is -not guaranteed to arrive intact at all members of the destination -group or in the same order relative to other datagrams. -.PP -The membership of a host group is dynamic; that is, hosts may join -and leave groups at any time. There is no restriction on the -location or number of members in a host group. A host may be a -member of more than one group at a time. A host need not be a member -of a group to send datagrams to it. -.PP -A host group may be permanent or transient. A permanent group has a -well-known, administratively assigned IP address. It is the address, -not the membership of the group, that is permanent; at any time a -permanent group may have any number of members, even zero. Those IP -multicast addresses that are not reserved for permanent groups are -available for dynamic assignment to transient groups which exist only -as long as they have members. -.PP -In general, a host cannot assume that datagrams sent to any host -group address will reach only the intended hosts, or that datagrams -received as a member of a transient host group are intended for the -recipient. Misdelivery must be detected at a level above IP, using -higher-level identifiers or authentication tokens. Information -transmitted to a host group address should be encrypted or governed -by administrative routing controls if the sender is concerned about -unwanted listeners. -.PP -IP multicasting is currently supported only on AF_INET sockets of type -SOCK_DGRAM and SOCK_RAW, and only on subnetworks for which the interface -driver has been modified to support multicasting. -.PP -The next subsections describe how to send and receive multicast datagrams. -.NH 3 -Sending IP Multicast Datagrams -.PP -To send a multicast datagram, specify an IP multicast address in the range -224.0.0.0 to 239.255.255.255 as the destination address -in a -.IR sendto (2) -call. -.PP -The definitions required for the multicast-related socket options are -found in \fI<netinet/in.h>\fP. -All IP addresses are passed in network byte-order. -.PP -By default, IP multicast datagrams are sent with a time-to-live (TTL) of 1, -which prevents them from being forwarded beyond a single subnetwork. A new -socket option allows the TTL for subsequent multicast datagrams to be set to -any value from 0 to 255, in order to control the scope of the multicasts: -.DS -u_char ttl; -setsockopt(sock, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); -.DE -Multicast datagrams with a TTL of 0 will not be transmitted on any subnet, -but may be delivered locally if the sending host belongs to the destination -group and if multicast loopback has not been disabled on the sending socket -(see below). Multicast datagrams with TTL greater than one may be delivered -to more than one subnet if there are one or more multicast routers attached -to the first-hop subnet. To provide meaningful scope control, the multicast -routers support the notion of TTL "thresholds", which prevent datagrams with -less than a certain TTL from traversing certain subnets. The thresholds -enforce the following convention: -.TS -center; -l | l -l | n. -_ -Scope Initial TTL -= -restricted to the same host 0 -restricted to the same subnet 1 -restricted to the same site 32 -restricted to the same region 64 -restricted to the same continent 128 -unrestricted 255 -_ -.TE -"Sites" and "regions" are not strictly defined, and sites may be further -subdivided into smaller administrative units, as a local matter. -.PP -An application may choose an initial TTL other than the ones listed above. -For example, an application might perform an "expanding-ring search" for a -network resource by sending a multicast query, first with a TTL of 0, and -then with larger and larger TTLs, until a reply is received, perhaps using -the TTL sequence 0, 1, 2, 4, 8, 16, 32. -.PP -The multicast router -.IR mrouted (8), -refuses to forward any -multicast datagram with a destination address between 224.0.0.0 and -224.0.0.255, inclusive, regardless of its TTL. This range of addresses is -reserved for the use of routing protocols and other low-level topology -discovery or maintenance protocols, such as gateway discovery and group -membership reporting. -.PP -The address 224.0.0.0 is -guaranteed not to be assigned to any group, and 224.0.0.1 is assigned -to the permanent group of all IP hosts (including gateways). This is -used to address all multicast hosts on the directly connected -network. There is no multicast address (or any other IP address) for -all hosts on the total Internet. The addresses of other well-known, -permanent groups are published in the "Assigned Numbers" RFC, -which is available from the InterNIC. -.PP -Each multicast transmission is sent from a single network interface, even if -the host has more than one multicast-capable interface. (If the host is -also serving as a multicast router, -a multicast may be \fIforwarded\fP to interfaces -other than originating interface, provided that the TTL is greater than 1.) -The default interface to be used for multicasting is the primary network -interface on the system. -A socket option -is available to override the default for subsequent transmissions from a -given socket: -.DS -struct in_addr addr; -setsockopt(sock, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); -.DE -where "addr" is the local IP address of the desired outgoing interface. -An address of INADDR_ANY may be used to revert to the default interface. -The local IP address of an interface can be obtained via the SIOCGIFCONF -ioctl. To determine if an interface supports multicasting, fetch the -interface flags via the SIOCGIFFLAGS ioctl and see if the IFF_MULTICAST -flag is set. (Normal applications should not need to use this option; it -is intended primarily for multicast routers and other system services -specifically concerned with internet topology.) -The SIOCGIFCONF and SIOCGIFFLAGS ioctls are described in the previous section. -.PP -If a multicast datagram is sent to a group to which the sending host itself -belongs (on the outgoing interface), a copy of the datagram is, by default, -looped back by the IP layer for local delivery. Another socket option gives -the sender explicit control over whether or not subsequent datagrams are -looped back: -.DS -u_char loop; -setsockopt(sock, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); -.DE -where \f2loop\f1 is set to 0 to disable loopback, -and set to 1 to enable loopback. -This option -improves performance for applications that may have no more than one -instance on a single host (such as a router daemon), by eliminating -the overhead of receiving their own transmissions. It should generally not -be used by applications for which there may be more than one instance on a -single host (such as a conferencing program) or for which the sender does -not belong to the destination group (such as a time querying program). -.PP -A multicast datagram sent with an initial TTL greater than 1 may be delivered -to the sending host on a different interface from that on which it was sent, -if the host belongs to the destination group on that other interface. The -loopback control option has no effect on such delivery. -.NH 3 -Receiving IP Multicast Datagrams -.PP -Before a host can receive IP multicast datagrams, it must become a member -of one or more IP multicast groups. A process can ask the host to join -a multicast group by using the following socket option: -.DS -struct ip_mreq mreq; -setsockopt(sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)) -.DE -where "mreq" is the following structure: -.DS -struct ip_mreq { - struct in_addr imr_multiaddr; /* \fImulticast group to join\fP */ - struct in_addr imr_interface; /* \fIinterface to join on\fP */ -} -.DE -Every membership is associated with a single interface, and it is possible -to join the same group on more than one interface. "imr_interface" should -be INADDR_ANY to choose the default multicast interface, or one of the -host's local addresses to choose a particular (multicast-capable) interface. -Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a -single socket. -.PP -To drop a membership, use: -.DS -struct ip_mreq mreq; -setsockopt(sock, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); -.DE -where "mreq" contains the same values as used to add the membership. The -memberships associated with a socket are also dropped when the socket is -closed or the process holding the socket is killed. However, more than -one socket may claim a membership in a particular group, and the host -will remain a member of that group until the last claim is dropped. -.PP -The memberships associated with a socket do not necessarily determine which -datagrams are received on that socket. Incoming multicast packets are -accepted by the kernel IP layer if any socket has claimed a membership in the -destination group of the datagram; however, delivery of a multicast datagram -to a particular socket is based on the destination port (or protocol type, for -raw sockets), just as with unicast datagrams. -To receive multicast datagrams -sent to a particular port, it is necessary to bind to that local port, -leaving the local address unspecified (i.e., INADDR_ANY). -To receive multicast datagrams -sent to a particular group and port, bind to the local port, with -the local address set to the multicast group address. -Once bound to a multicast address, the socket cannot be used for sending data. -.PP -More than one process may bind to the same SOCK_DGRAM UDP port -or the same multicast group and port if the -.I bind -call is preceded by: -.DS -int on = 1; -setsockopt(sock, SOL_SOCKET, SO_REUSEPORT, &on, sizeof(on)); -.DE -All processes sharing the port must enable this option. -Every incoming multicast or broadcast UDP datagram destined to -the shared port is delivered to all sockets bound to the port. -For backwards compatibility reasons, this does not apply to incoming -unicast datagrams. Unicast -datagrams are never delivered to more than one socket, regardless of -how many sockets are bound to the datagram's destination port. -.PP -A final multicast-related extension is independent of IP: two new ioctls, -SIOCADDMULTI and SIOCDELMULTI, are available to add or delete link-level -(e.g., Ethernet) multicast addresses accepted by a particular interface. -The address to be added or deleted is passed as a sockaddr structure of -family AF_UNSPEC, within the standard ifreq structure. -.PP -These ioctls are -for the use of protocols other than IP, and require superuser privileges. -A link-level multicast address added via SIOCADDMULTI is not automatically -deleted when the socket used to add it goes away; it must be explicitly -deleted. It is inadvisable to delete a link-level address that may be -in use by IP. -.NH 3 -Sample Multicast Program -.PP -The following program sends or receives multicast packets. -If invoked with one argument, it sends a packet containing the current -time to an arbitrarily-chosen multicast group and UDP port. -If invoked with no arguments, it receives and prints these packets. -Start it as a sender on just one host and as a receiver on all the other hosts. -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netinet/in.h> -#include <arpa/inet.h> -#include <time.h> -#include <stdio.h> - -#define EXAMPLE_PORT 60123 -#define EXAMPLE_GROUP "224.0.0.250" - -main(argc) - int argc; -{ - struct sockaddr_in addr; - int addrlen, fd, cnt; - struct ip_mreq mreq; - char message[50]; - - fd = socket(AF_INET, SOCK_DGRAM, 0); - if (fd < 0) { - perror("socket"); - exit(1); - } - - bzero(&addr, sizeof(addr)); - addr.sin_family = AF_INET; - addr.sin_addr.s_addr = htonl(INADDR_ANY); - addr.sin_port = htons(EXAMPLE_PORT); - addrlen = sizeof(addr); - - if (argc > 1) { /* Send */ - addr.sin_addr.s_addr = inet_addr(EXAMPLE_GROUP); - while (1) { - time_t t = time(0); - sprintf(message, "time is %-24.24s", ctime(&t)); - cnt = sendto(fd, message, sizeof(message), 0, - (struct sockaddr *)&addr, addrlen); - if (cnt < 0) { - perror("sendto"); - exit(1); - } - sleep(5); - } - } else { /* Receive */ - if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) { - perror("bind"); - exit(1); - } - - mreq.imr_multiaddr.s_addr = inet_addr(EXAMPLE_GROUP); - mreq.imr_interface.s_addr = htonl(INADDR_ANY); - if (setsockopt(fd, IPPROTO_IP, IP_ADD_MEMBERSHIP, - &mreq, sizeof(mreq)) < 0) { - perror("setsockopt mreq"); - exit(1); - } - - while (1) { - cnt = recvfrom(fd, message, sizeof(message), 0, - (struct sockaddr *)&addr, &addrlen); - if (cnt <= 0) { - if (cnt == 0) { - break; - } - perror("recvfrom"); - exit(1); - } - printf("%s: message = \e"%s\e"\en", - inet_ntoa(addr.sin_addr), message); - } - } -} -.DE -.\"---------------------------------------------------------------------- -.NH 2 -NS Packet Sequences -.PP -The semantics of NS connections demand that -the user both be able to look inside the network header associated -with any incoming packet and be able to specify what should go -in certain fields of an outgoing packet. -Using different calls to \fIsetsockopt\fP, it is possible -to indicate whether prototype headers will be associated by -the user with each outgoing packet (SO_HEADERS_ON_OUTPUT), -to indicate whether the headers received by the system should be -delivered to the user (SO_HEADERS_ON_INPUT), or to indicate -default information that should be associated with all -outgoing packets on a given socket (SO_DEFAULT_HEADERS). -.PP -The contents of a SPP header (minus the IDP header) are: -.DS -.if t .ta \w" #define"u +\w" u_short"u +2.0i -struct sphdr { - u_char sp_cc; /* connection control */ -#define SP_SP 0x80 /* system packet */ -#define SP_SA 0x40 /* send acknowledgement */ -#define SP_OB 0x20 /* attention (out of band data) */ -#define SP_EM 0x10 /* end of message */ - u_char sp_dt; /* datastream type */ - u_short sp_sid; /* source connection identifier */ - u_short sp_did; /* destination connection identifier */ - u_short sp_seq; /* sequence number */ - u_short sp_ack; /* acknowledge number */ - u_short sp_alo; /* allocation number */ -}; -.DE -Here, the items of interest are the \fIdatastream type\fP and -the \fIconnection control\fP fields. The semantics of the -datastream type are defined by the application(s) in question; -the value of this field is, by default, zero, but it can be -used to indicate things such as Xerox's Bulk Data Transfer -Protocol (in which case it is set to one). The connection control -field is a mask of the flags defined just below it. The user may -set or clear the end-of-message bit to indicate -that a given message is the last of a given substream type, -or may set/clear the attention bit as an alternate way to -indicate that a packet should be sent out-of-band. -As an example, to associate prototype headers with outgoing -SPP packets, consider: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> -#include <netns/sp.h> - ... -struct sockaddr_ns sns, to; -int s, on = 1; -struct databuf { - struct sphdr proto_spp; /* prototype header */ - char buf[534]; /* max. possible data by Xerox std. */ -} buf; - ... -s = socket(AF_NS, SOCK_SEQPACKET, 0); - ... -bind(s, (struct sockaddr *) &sns, sizeof (sns)); -setsockopt(s, NSPROTO_SPP, SO_HEADERS_ON_OUTPUT, &on, sizeof(on)); - ... -buf.proto_spp.sp_dt = 1; /* bulk data */ -buf.proto_spp.sp_cc = SP_EM; /* end-of-message */ -strcpy(buf.buf, "hello world\en"); -sendto(s, (char *) &buf, sizeof(struct sphdr) + strlen("hello world\en"), - (struct sockaddr *) &to, sizeof(to)); - ... -.DE -Note that one must be careful when writing headers; if the prototype -header is not written with the data with which it is to be associated, -the kernel will treat the first few bytes of the data as the -header, with unpredictable results. -To turn off the above association, and to indicate that packet -headers received by the system should be passed up to the user, -one might use: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> -#include <netns/sp.h> - ... -struct sockaddr sns; -int s, on = 1, off = 0; - ... -s = socket(AF_NS, SOCK_SEQPACKET, 0); - ... -bind(s, (struct sockaddr *) &sns, sizeof (sns)); -setsockopt(s, NSPROTO_SPP, SO_HEADERS_ON_OUTPUT, &off, sizeof(off)); -setsockopt(s, NSPROTO_SPP, SO_HEADERS_ON_INPUT, &on, sizeof(on)); - ... -.DE -.PP -Output is handled somewhat differently in the IDP world. -The header of an IDP-level packet looks like: -.DS -.if t .ta \w'struct 'u +\w" struct ns_addr"u +2.0i -struct idp { - u_short idp_sum; /* Checksum */ - u_short idp_len; /* Length, in bytes, including header */ - u_char idp_tc; /* Transport Control (i.e., hop count) */ - u_char idp_pt; /* Packet Type (i.e., level 2 protocol) */ - struct ns_addr idp_dna; /* Destination Network Address */ - struct ns_addr idp_sna; /* Source Network Address */ -}; -.DE -The primary field of interest in an IDP header is the \fIpacket type\fP -field. The standard values for this field are (as defined -in <\fInetns/ns.h\fP>): -.DS -.if t .ta \w" #define"u +\w" NSPROTO_ERROR"u +1.0i -#define NSPROTO_RI 1 /* Routing Information */ -#define NSPROTO_ECHO 2 /* Echo Protocol */ -#define NSPROTO_ERROR 3 /* Error Protocol */ -#define NSPROTO_PE 4 /* Packet Exchange */ -#define NSPROTO_SPP 5 /* Sequenced Packet */ -.DE -For SPP connections, the contents of this field are -automatically set to NSPROTO_SPP; for IDP packets, -this value defaults to zero, which means ``unknown''. -.PP -Setting the value of that field with SO_DEFAULT_HEADERS is -easy: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> -#include <netns/idp.h> - ... -struct sockaddr sns; -struct idp proto_idp; /* prototype header */ -int s, on = 1; - ... -s = socket(AF_NS, SOCK_DGRAM, 0); - ... -bind(s, (struct sockaddr *) &sns, sizeof (sns)); -proto_idp.idp_pt = NSPROTO_PE; /* packet exchange */ -setsockopt(s, NSPROTO_IDP, SO_DEFAULT_HEADERS, (char *) &proto_idp, - sizeof(proto_idp)); - ... -.DE -.PP -Using SO_HEADERS_ON_OUTPUT is somewhat more difficult. When -SO_HEADERS_ON_OUTPUT is turned on for an IDP socket, the socket -becomes (for all intents and purposes) a raw socket. In this -case, all the fields of the prototype header (except the -length and checksum fields, which are computed by the kernel) -must be filled in correctly in order for the socket to send and -receive data in a sensible manner. To be more specific, the -source address must be set to that of the host sending the -data; the destination address must be set to that of the -host for whom the data is intended; the packet type must be -set to whatever value is desired; and the hopcount must be -set to some reasonable value (almost always zero). It should -also be noted that simply sending data using \fIwrite\fP -will not work unless a \fIconnect\fP or \fIsendto\fP call -is used, in spite of the fact that it is the destination -address in the prototype header that is used, not the one -given in either of those calls. For almost -all IDP applications , using SO_DEFAULT_HEADERS is easier and -more desirable than writing headers. -.NH 2 -Three-way Handshake -.PP -The semantics of SPP connections indicates that a three-way -handshake, involving changes in the datastream type, should \(em -but is not absolutely required to \(em take place before a SPP -connection is closed. Almost all SPP connections are -``well-behaved'' in this manner; when communicating with -any process, it is best to assume that the three-way handshake -is required unless it is known for certain that it is not -required. In a three-way close, the closing process -indicates that it wishes to close the connection by sending -a zero-length packet with end-of-message set and with -datastream type 254. The other side of the connection -indicates that it is OK to close by sending a zero-length -packet with end-of-message set and datastream type 255. Finally, -the closing process replies with a zero-length packet with -substream type 255; at this point, the connection is considered -closed. The following code fragments are simplified examples -of how one might handle this three-way handshake at the user -level; in the future, support for this type of close will -probably be provided as part of the C library or as part of -the kernel. The first code fragment below illustrates how a process -might handle three-way handshake if it sees that the process it -is communicating with wants to close the connection: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> -#include <netns/sp.h> - ... -#ifndef SPPSST_END -#define SPPSST_END 254 -#define SPPSST_ENDREPLY 255 -#endif -struct sphdr proto_sp; -int s; - ... -read(s, buf, BUFSIZE); -if (((struct sphdr *)buf)->sp_dt == SPPSST_END) { - /* - * SPPSST_END indicates that the other side wants to - * close. - */ - proto_sp.sp_dt = SPPSST_ENDREPLY; - proto_sp.sp_cc = SP_EM; - setsockopt(s, NSPROTO_SPP, SO_DEFAULT_HEADERS, (char *)&proto_sp, - sizeof(proto_sp)); - write(s, buf, 0); - /* - * Write a zero-length packet with datastream type = SPPSST_ENDREPLY - * to indicate that the close is OK with us. The packet that we - * don't see (because we don't look for it) is another packet - * from the other side of the connection, with SPPSST_ENDREPLY - * on it it, too. Once that packet is sent, the connection is - * considered closed; note that we really ought to retransmit - * the close for some time if we do not get a reply. - */ - close(s); -} - ... -.DE -To indicate to another process that we would like to close the -connection, the following code would suffice: -.DS -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> -#include <netns/sp.h> - ... -#ifndef SPPSST_END -#define SPPSST_END 254 -#define SPPSST_ENDREPLY 255 -#endif -struct sphdr proto_sp; -int s; - ... -proto_sp.sp_dt = SPPSST_END; -proto_sp.sp_cc = SP_EM; -setsockopt(s, NSPROTO_SPP, SO_DEFAULT_HEADERS, (char *)&proto_sp, - sizeof(proto_sp)); -write(s, buf, 0); /* send the end request */ -proto_sp.sp_dt = SPPSST_ENDREPLY; -setsockopt(s, NSPROTO_SPP, SO_DEFAULT_HEADERS, (char *)&proto_sp, - sizeof(proto_sp)); -/* - * We assume (perhaps unwisely) - * that the other side will send the - * ENDREPLY, so we'll just send our final ENDREPLY - * as if we'd seen theirs already. - */ -write(s, buf, 0); -close(s); - ... -.DE -.NH 2 -Packet Exchange -.PP -The Xerox standard protocols include a protocol that is both -reliable and datagram-oriented. This protocol is known as -Packet Exchange (PEX or PE) and, like SPP, is layered on top -of IDP. PEX is important for a number of things: Courier -remote procedure calls may be expedited through the use -of PEX, and many Xerox servers are located by doing a PEX -``BroadcastForServers'' operation. Although there is no -implementation of PEX in the kernel, -it may be simulated at the user level with some clever coding -and the use of one peculiar \fIgetsockopt\fP. A PEX packet -looks like: -.DS -.if t .ta \w'struct 'u +\w" struct idp"u +2.0i -/* - * The packet-exchange header shown here is not defined - * as part of any of the system include files. - */ -struct pex { - struct idp p_idp; /* idp header */ - u_short ph_id[2]; /* unique transaction ID for pex */ - u_short ph_client; /* client type field for pex */ -}; -.DE -The \fIph_id\fP field is used to hold a ``unique id'' that -is used in duplicate suppression; the \fIph_client\fP -field indicates the PEX client type (similar to the packet -type field in the IDP header). PEX reliability stems from the -fact that it is an idempotent (``I send a packet to you, you -send a packet to me'') protocol. Processes on each side of -the connection may use the unique id to determine if they have -seen a given packet before (the unique id field differs on each -packet sent) so that duplicates may be detected, and to indicate -which message a given packet is in response to. If a packet with -a given unique id is sent and no response is received in a given -amount of time, the packet is retransmitted until it is decided -that no response will ever be received. To simulate PEX, one -must be able to generate unique ids -- something that is hard to -do at the user level with any real guarantee that the id is really -unique. Therefore, a means (via \fIgetsockopt\fP) has been provided -for getting unique ids from the kernel. The following code fragment -indicates how to get a unique id: -.DS -long uniqueid; -int s, idsize = sizeof(uniqueid); - ... -s = socket(AF_NS, SOCK_DGRAM, 0); - ... -/* get id from the kernel -- only on IDP sockets */ -getsockopt(s, NSPROTO_PE, SO_SEQNO, (char *)&uniqueid, &idsize); - ... -.DE -The retransmission and duplicate suppression code required to -simulate PEX fully is left as an exercise for the reader. -.NH 2 -Inetd -.PP -One of the daemons provided with 4.4BSD is \fIinetd\fP, the -so called ``internet super-server.'' -Having one daemon listen for requests for many daemons -instead of having each daemon listen for its own requests -reduces the number of idle daemons and simplies their implementation. -.I Inetd -handles -two types of services: standard and TCPMUX. -A standard service has a well-known port assigned to it and -is listed in -.I /etc/services -(see \f2services\f1(5)); -it may be a service that implements an official Internet standard or is a -BSD-specific service. -TCPMUX services are nonstandard and do not have a -well-known port assigned to them. -They are invoked from -.I inetd -when a program connects to the "tcpmux" well-known port and specifies -the service name. -This is useful for adding locally-developed servers. -.PP -\fIInetd\fP is invoked at boot -time, and determines from the file \fI/etc/inetd.conf\fP the -servers for which it is to listen. Once this information has been -read and a pristine environment created, \fIinetd\fP proceeds -to create one socket for each service it is to listen for, -binding the appropriate port number to each socket. -.PP -\fIInetd\fP then performs a \fIselect\fP on all these -sockets for read availability, waiting for somebody wishing -a connection to the service corresponding to -that socket. \fIInetd\fP then performs an \fIaccept\fP on -the socket in question, \fIfork\fPs, \fIdup\fPs the new -socket to file descriptors 0 and 1 (stdin and -stdout), closes other open file -descriptors, and \fIexec\fPs the appropriate server. -.PP -Servers making use of \fIinetd\fP are considerably simplified, -as \fIinetd\fP takes care of the majority of the IPC work -required in establishing a connection. The server invoked -by \fIinetd\fP expects the socket connected to its client -on file descriptors 0 and 1, and may immediately perform -any operations such as \fIread\fP, \fIwrite\fP, \fIsend\fP, -or \fIrecv\fP. Indeed, servers may use -buffered I/O as provided by the ``stdio'' conventions, as -long as as they remember to use \fIfflush\fP when appropriate. -.PP -One call which may be of interest to individuals writing -servers under \fIinetd\fP is the \fIgetpeername\fP call, -which returns the address of the peer (process) connected -on the other end of the socket. For example, to log the -Internet address in ``dot notation'' (e.g., ``128.32.0.4'') -of a client connected to a server under -\fIinetd\fP, the following code might be used: -.DS -struct sockaddr_in name; -int namelen = sizeof (name); - ... -if (getpeername(0, (struct sockaddr *)&name, &namelen) < 0) { - syslog(LOG_ERR, "getpeername: %m"); - exit(1); -} else - syslog(LOG_INFO, "Connection from %s", inet_ntoa(name.sin_addr)); - ... -.DE -While the \fIgetpeername\fP call is especially useful when -writing programs to run with \fIinetd\fP, it can be used -under other circumstances. Be warned, however, that \fIgetpeername\fP will -fail on UNIX domain sockets. -.PP -Standard TCP -services are assigned unique well-known port numbers in the range of -0 to 1023 by the -Internet Assigned Numbers Authority (IANA@ISI.EDU). -The limited number of ports in this range are -assigned to official Internet protocols. -The TCPMUX service allows you to add -locally-developed protocols without needing an official TCP port assignment. -The TCPMUX protocol described in RFC-1078 is simple: -.QP -``A TCP client connects to a foreign host on TCP port 1. It sends the -service name followed by a carriage-return line-feed <CRLF>. -The service name is never case sensitive. -The server replies with a -single character indicating positive ("+") or negative ("\-") -acknowledgment, immediately followed by an optional message of -explanation, terminated with a <CRLF>. If the reply was positive, -the selected protocol begins; otherwise the connection is closed.'' -.LP -In 4.4BSD, the TCPMUX service is built into -.IR inetd , -that is, -.IR inetd -listens on TCP port 1 for requests for TCPMUX services listed -in \f2inetd.conf\f1. -.IR inetd (8) -describes the format of TCPMUX entries for \f2inetd.conf\f1. -.PP -The following is an example TCPMUX server and its \f2inetd.conf\f1 entry. -More sophisticated servers may want to do additional processing -before returning the positive or negative acknowledgement. -.DS -#include <sys/types.h> -#include <stdio.h> - -main() -{ - time_t t; - - printf("+Go\er\en"); - fflush(stdout); - time(&t); - printf("%d = %s", t, ctime(&t)); - fflush(stdout); -} -.DE -The \f2inetd.conf\f1 entry is: -.DS -tcpmux/current_time stream tcp nowait nobody /d/curtime curtime -.DE -Here's the portion of the client code that handles the TCPMUX handshake: -.DS -char line[BUFSIZ]; -FILE *fp; - ... - -/* Use stdio for reading data from the server */ -fp = fdopen(sock, "r"); -if (fp == NULL) { - fprintf(stderr, "Can't create file pointer\en"); - exit(1); -} - -/* Send service request */ -sprintf(line, "%s\er\en", "current_time"); -if (write(sock, line, strlen(line)) < 0) { - perror("write"); - exit(1); -} - -/* Get ACK/NAK response from the server */ -if (fgets(line, sizeof(line), fp) == NULL) { - if (feof(fp)) { - die(); - } else { - fprintf(stderr, "Error reading response\en"); - exit(1); - } -} - -/* Delete <CR> */ -if ((lp = index(line, '\r')) != NULL) { - *lp = '\0'; -} - -switch (line[0]) { - case '+': - printf("Got ACK: %s\en", &line[1]); - break; - case '-': - printf("Got NAK: %s\en", &line[1]); - exit(0); - default: - printf("Got unknown response: %s\en", line); - exit(1); -} - -/* Get rest of data from the server */ -while ((fgets(line, sizeof(line), fp)) != NULL) { - fputs(line, stdout); -} -.DE diff --git a/share/doc/psd/21.ipc/Makefile b/share/doc/psd/21.ipc/Makefile deleted file mode 100644 index 3e32259391a..00000000000 --- a/share/doc/psd/21.ipc/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $OpenBSD: Makefile,v 1.3 2004/02/01 14:22:45 jmc Exp $ - - -DIR= psd/21.ipc -SRCS= 0.t 1.t 2.t 3.t 4.t 5.t -MACROS= -ms - -paper.ps: ${SRCS} - ${TBL} ${SRCS} | ${ROFF} > ${.TARGET} - -paper.txt: ${SRCS} - ${TBL} ${SRCS} | ${ROFF} -Tascii > ${.TARGET} - -.include <bsd.doc.mk> diff --git a/share/doc/psd/21.ipc/spell.ok b/share/doc/psd/21.ipc/spell.ok deleted file mode 100644 index 02b45d4d26d..00000000000 --- a/share/doc/psd/21.ipc/spell.ok +++ /dev/null @@ -1,347 +0,0 @@ -4.2bsd -AF -ANYP -BUFSIZ -BUFSIZE -BroadcastForServers -CF -CLR -CRMOD -Clearinghouse -DARPA -DESTPORT -DGRAM -DONTROUTE -Datagram -EADDRINUSE -EADDRNOTAVAIL -EAGAIN -ECONNREFUSED -EHOSTDOWN -EHOSTUNREACH -EINTR -ENDREPLY -ENETDOWN -ENETUNREACH -ENOBUFS -EPROTONOSUPPORT -EPROTOTYPE -ETIMEDOUT -EWOULDBLOCK -Ethernet -FASYNC -FCREATE -FD -FNDELAY -FTP -FTRUNCATE -FWRITE -FWRONLY -Fabry -GETOWN -Gethostybyname -IDP -IFF -IFNAMSIZ -INADDR -INET -INFO -IP -IPC -IPPORT -ISSET -Inetd -LF -LH -LOOPBACK -Lapsley -Leffler -MSG -MYADDRESS -MYPORT -NS -NSPROTO -OB -OOB -OOBINLINE -Optlen -Optval -PE -PEX -POINTTOPOINT -PS1:8 -RDONLY -RDWR -REUSEADDR -RF -RH -RWHODIR -SEQNO -SEQPACKET -SETFL -SETOWN -SETSIZE -SIGALRM -SIGCHLD -SIGIO -SIGURG -SIOCATMARK -SIOCGIFBRDADDR -SIOCGIFCONF -SIOCGIFDSTADDR -SIOCGIFFLAGS -SIOCGPGRP -SIOCSPGRP -SOF -SP -SPP -SPPSST -Science:UofMaryland -TCP -TELNET -TIOCFLUSH -TIOCGETP -TIOCNOTTY -TIOCSETP -TRUNC -Torek -Tutorial''PS1:8 -USERRESERVED -VAX -WNOHANG -WRONLY -XSIS -XTABS -ack -addr -addr.s -addr.sa -addr.sun -addr.x -addrtype -alo -argc -argv -arpa -b.sg -bcmp -bcopy -broadaddr -buf -buf.buf -buf.proto -buflen -bzero -c.f -cad -caddr -calder -daemons -dali -databuf -datagram -datastream -dev -dna -doit -dst -dst.sin -dst.sns -dstaddr -dt -dup2 -en0 -endhostent -endif -ernie -errno -es -esvax -exceptmask -execptfds -fcntl -fcntl.h -fd -fflush -file.h -foo -fprintf -from.sin -fromlen -gethostbyaddr -gethostbyname -gethostbynameandnet -gethostent -gethostname -getnetbyname -getnetbynumber -getnetent -getpeername -getprotobyname -getprotobynumber -getprotoent -getservbyname -getservbyport -getservent -getsockopt -goto -gotpty -gyre -gyre:Computer -hardcoding -hopcount -host.c -hostent -hostname -hostnames -hosts.equiv -htonl -htons -idp -idp.h -idp.idp -idsize -if.h -ifc -ifc.ifc -ifconf -ifcu -ifcu.ifcu -ifndef -ifr -ifreq -ifru -ifru.ifru -in.h -inet -inetd -inetd.conf -ing -ingres -io -ioctl.h -ipc -kim -len -localnet -lport -lq -makeaddr -matisse -medea -miro -monet -name.sin -namelen -nameserver -nb -netdb.h -netent -netinet -netns -netnum -netof -newsock -newtcp -nfds -ns -ns.h -ntoa -ntohl -ntohs -onalrm -oob -optlen -optname -optval -oz -pathname -pathnames -pex -pgrp -ph -pp -proto -protoent -pt -pty -ptyXX -ptyp -ptyxy -queueing -readfds -readmask -recv -recvfrom -recvtime -rem -req -rhosts -rlogin -rlogind -rq -rresvport -ruptime -rwho -rwhod -sendto -servent -server.sin -server.sun -sethostent -setsockopt -sid -sigvec -sin.sin -sizeof -sna -snew -sns -sns.sns -sockaddr -socket.h -sp -sp.h -sp.sp -sphdr -spp -spp.sp -sprintf -statbuf -statvax -std -stderr -stdin -stdio.h -stdout -strcmp -strcpy -strlen -syslog -ta -tcp -telnet -time.h -timeval -tmp -tolen -ttyxy -tuples -types.h -ucbvax -udp -un -un.h -uniqueid -useable -usec -val -wait.h -wait.tv -wd -wd.wd -whod -wildcard -wildcarded -writefds -writemask diff --git a/share/doc/psd/Makefile b/share/doc/psd/Makefile index 767d13bdd58..33643dd0b4d 100644 --- a/share/doc/psd/Makefile +++ b/share/doc/psd/Makefile @@ -1,8 +1,8 @@ -# $OpenBSD: Makefile,v 1.7 2010/01/04 17:50:39 deraadt Exp $ +# $OpenBSD: Makefile,v 1.8 2010/07/01 20:04:10 tedu Exp $ DOCDIR= /usr/share/doc/psd -FILES= 00.contents Makefile Title -SUBDIR= 05.sysman 20.ipctut 21.ipc +FILES= Makefile +SUBDIR= .if exists(12.make) SUBDIR+= 12.make .endif @@ -13,16 +13,6 @@ SUBDIR+= 18.gprof SUBDIR+= 19.curses .endif -Title.ps: ${FILES} - groff Title > ${.TARGET} -Title.txt: ${FILES} - groff -Tascii Title > ${.TARGET} - -contents.ps: ${FILES} - groff -ms 00.contents > ${.TARGET} -contents.txt: ${FILES} - groff -Tascii -ms 00.contents > ${.TARGET} - beforeinstall: install -c -o ${DOCOWN} -g ${DOCGRP} -m ${DOCMODE} ${FILES} \ ${DESTDIR}${DOCDIR} |