.nh .ls 2 .bl 10 .bl 10 .ce \fBIPC Specification\fR .pn 1 .he 1 ''%'' .bp .bl 5 .ce \fBCAPACITY\fR .bl 3 .pg The \fBcapac\fR system call enables a process to ascertain the buffering status of its various I/O channels. The usage is: .bl 3 .ls 1 .nf .kp \fBcapac(fd,bp,bl) int fd; /* file descriptor */ int bp[2]; /* result area */ int bl; /* length of result area */\fR .ke .fi .ls 2 .bl 3 .pg The call returns a value of -1 if an error occurs, as with other Unix system calls. Otherwise, the current input and output counts for the specified file are returned in the first and second words of the result area. .pg For the capacity call, the result area must be at least four bytes in length. An enhanced version of the capacity call is planned which will allow a process with many inputs to avoid the overhead of doing multiple system calls for checking the capacity of the various inputs. This version of the capacity call will accept a table in the result area, which contains all the file descriptors of interest to the caller. The table consists of consecutive three word elements, one per file descriptor. The fact that the result area length is greater than two words will identify the usage of the enhanced version. An element will contain the file descriptor itself, followed by two words for the input and output capacities. The call handler will simply scan through the table filling in the elements in turn. .pg The counts which are returned to the process should be treated as bounds on the amount of data available to read, or buffer space available for writing. The actual values at any instant may be larger than those obtained from a capacity call, due to activities of other processes or devices in the interim. The system does guarantee however that the amounts indicated are minimum values, so that read or write calls of no more than those values will not block waiting for data or buffer space. .pg The special value of -1 indicates that the associated read or write operation may be performed without blocking, but the actual data counts are unavailable. Generally this occurs when a channel has a pending error which will cause the next I/O operation to return an error code. It may also occur for devices which cannot determine the size of incoming data, but can determine that such data exists so that a read will not block. .pg For ports and pipes, the capacity call returns the number of bytes which may be read or written without blocking. Note that, in the case of ports, the system-generated header must be considered as part of the data stream. Write operations require that space be available for the sum of the header and data lengths in order to guarantee non-blocking. Similarly, the header size(s) are included in the count of bytes available for reading. .pg The teletype handlers provide counts for the number of bytes of data which may be read. Currently no distinction is made between normal and raw modes of teletype operation, but this should be changed. .pg For output on the teletype, the count specifies the number of characters which the system will permit to be added to the device output buffer queue. Note that this amount may not actually be available if other I/O operations are in progress, so that it is not really a guaranteed amount. However, the specified resources will become available as soon as possible within the system, in contrast to the case where a write operation is blocked because it exceeds the maximum permitted queue length, which will continue until the physical terminal accepts the characters. .pg The IMP interface currently performs I/O operations directly from user memory. Consequently, write operations never block in the sense of waiting for buffers, but rather always are handled immediately at the interface speed. For write counts, the capacity call always returns -1, indicating that a write operation will succeed. Note that this precludes permitting several related processes to simultaneously write to the same IMP interface, unless they use some other mechanism for coordinating their usage. For reading, the device driver knows only that the interface has a message available. Hence, it returns -1 when this is the case. A subsequent read operation will always complete to the point where the supplied data buffer fills or the interface indicates the end of the message. .bp .bl 5 .ce \fBAWAIT\fR .bl 3 .pg The \fBawait\fR facility uses three system calls; \fBawtenb\fR, \fBawtdis\fR, and \fBawt\fR. .bl 2 \fBAWTENB\fR .bl .pg The \fBawtenb\fR call is used by a process to indicate that it is interested in activity on a specified I/O channel. The channel is identified by a file descriptor, which is mapped within the kernel to an inode. .bl 3 .ls 1 .nf .kp \fBawtenb(fd) int fd; /* file descriptor */\fR .ke .fi .ls 2 .bl 3 .pg A -1 return value indicates an error. The implementation limits the number of processes which may simultaneously have any particular inode enabled to some value set at system generation time. Our current value is 2, reflecting the common usage of the mechanism for controlling interprocess communication between two processes. Attempts to enable an already-enabled inode are ignored. .pg Note that several file descriptors may refer to the same inode. Also note that inodes have no inherent direction of transfer, so that, for example, enabling a teletype input file descriptor effectively enables the output file descriptor as well, since it references the same inode. .bl 2 \fBAWTDIS\fR .bl .pg The \fBawtdis\fR call disables the specified file descriptor. The special case file descriptor of -1 causes all file descriptors for the process to be disabled. .bl 3 .ls 1 .nf .kp \fBawtdis(fd) int fd; /* file descriptor */\fR .ke .fi .ls 2 .bl 3 \fBAWT\fR .bl .pg The \fBawt\fR call enables a process to sleep awaiting activity on any of its enabled I/O channels. The call also specifies a time in seconds, after which the process is awakened regardless of the activity on the various channels. .bl 3 .ls 1 .nf .kp \fBawt(tim) int tim; /* time in seconds */\fR .ke .fi .ls 2 .bl 3 .pg As always, a -1 return indicates an error. No special errors are associated with await other than the normal Unix error codes. .pg The operation of the await mechanism can be modelled as a single bit associated with the process which indicates that something of interest has happened. The currently enabled file descriptors define what is of interest at any time. Whenever any activity occurs within Unix associated with an inode which would normally awake a process blocked waiting for that event, the activity bit is set. The awt call will return immediately if the activity bit is set when it is entered. Any activity which sets the bit will cause the process executing an awt call to be scheduled for running. When a process leaves the awt call, the bit is cleared. .pg Operationally, a process should enable all file descriptors which are of interest for its current task, perform capacity checks on each file descriptor until nothing remains to be processed, and call awt. If any activity has occurred on those channels since the last time the processed exited from awaiting, it will immediately exit. Otherwise, the process will be suspended until some such activity does occur, or the supplied time has elapsed. When a process returns from an awt call, it should use capacity to check the status of the various enabled channels, to determine the cause of the wakeup.