ref: 2b99422480d596ebc26921c87c6bb81a07949f3e
dir: /ch5.ms/
.so tmacs
.BC 5 "Talking Processes
.BS 2 "Input/Output redirection
.LP
.ix "I/O redirection
.ix "file descriptor redirection
Most commands we have executed so far write their output to the
console, because their standard output file descriptor is usually
leading to the console.
.PP
In some cases, it may be useful to \fBredirect\fP
the output for a command to store the data produced in a file.
For example, to record the date for an important moment, we can
execute
.CW date
.ix [date]
and store its output in a file, for posterity.
The shell knows how to do this:
.P1
; !!date > rememberthis
;
.P2
.LP
This command line means: Execute the command
.CW date
as usual, but send its output to
.CW rememberthis .
The obedient Plan 9 shell makes the arrangements
to get the output for the command sent to file, and not
to the console. As a result,
.CW date
did now write anything in the console. But it did write.
Its output is here instead.
.ix "output redirection
.P1
; cat rememberthis
Thu Jul 13 12:10:38 MDT 2006
.P2
.LP
This can be done to any command, as you may expect. When the shell finds a
“\f(CW>\fP” in a command line, it takes the next word as the name of a file
where to send the output for the command.
.ix "command line
This is a poor's man editor. We use
.CW cat
to read what we write in the terminal, and write it into a file.
.P1
; cat >/tmp/note
must leave at 8
\fBcontrol-d\fP
; cat /tmp/note
must leave at 8
.P2
.LP
The “\f(CW>\fP” character is an operator, and has a special meaning. To
use it just as a character, it must be quoted. We already knew, but
just as a reminder:
.P1
; echo '>' > file
; cat file
>
;
.P2
.LP
Another example. If our machine seems
to be heavily loaded, we may want
to conserve the list of running processes, to inspect it later. That is simple:
.P1
; ps > processlist
;
.P2
.ix [ps]
.ix "machine load
.ix "process list
.LP
Now that we have the list of processes stored in a file, we can take our time
to inspect what is happening to the machine. For example, we may use
.CW cat
to print the list. It reads the file and prints all the bytes read to the standard output.
.P1
.ps -1
; cat processlist
nemo 1 0:00 0:00 2308K Await bns
nemo 2 5:03 0:00 0K Wakeme genrand
nemo 3 0:00 0:00 0K Wakeme alarm
nemo 4 0:00 0:00 0K Wakeme rxmit
.I "... other lines omitted ...
.ps +2
.P2
.LP
We can count how many processes there were in the system by
the time we stored the list. To do so, we can count the lines in the file
.CW processlist ,
because we know there is one line in that file per process. The program
.CW wc
(word count)
.ix [wc]
.ix "word count
counts lines, words, and characters in a file, and prints what it finds.
.P1
; wc processlist
147 1029 8795 processlist
;
.P2
.LP
The file
.CW processlist
has 147 lines, 1929 words, and 8795 characters in it. This means that
we had 147 processes in the machine at that time. Because we are
only interested in the number of lines, we might have used the option
.CW -l
to
.CW wc ,
as said in
.I wc (1),
to ask just for the number of lines:
.P1
; wc -l processlist
147 processlist
;
.P2
.LP
As we said before,
most commands that accept a file name as an argument,
work with their standard input when no file name is given. And
.ix "standard input
.CW wc
is not an exception. For example,
.P1
; wc
when I see it, I believe it
\fBcontrol-d\fP
1 7 28
;
.P2
.LP
counts the lines, words, and characters that we type until
pressing a
.I control-d .
.ix "control-d
.PP
The shell is able to redirect the standard input for a command, and not
just its output. The syntax is similar to a redirection for output, but using
“\f(CW<\fP” instead of “\f(CW>\fP”. To remember, imagine the bytes entering through the
wide part of the symbol, going out through the little hole in the other end. We can now
do this
.P1
; cat < rememberthis
Thu Jul 13 12:10:38 MDT 2006
.P2
.LP
and it would have the same effect that doing this
.P1
; cat rememberthis
Thu Jul 13 12:10:38 MDT 2006
.P2
.LP
Both commands produce the same output, but they are very different. In the
first case, the shell makes the arrangements so that the standard input for
.CW cat
comes from
.I rememberthis
and not from the console. The
.CW cat
program has no arguments (other than
.CW argv[0] )
and therefore starts reading from its standard input. But
.CW cat
does not even know the name of the file it is reading!
In the second case, the shell is not doing anything to the standard input for
.CW cat .
The program itself has to open the file, and read from it.
.PP
For those rare cases when there is a command that requires a file name as
its input, and you still want to run the command to work on its standard input,
Plan 9
provides files named
.CW /fd/0 ,
.CW /fd/1 ,
.ix "[/fd] file system
.ix "file descriptor
etc. These are not real files, but other interface to use your file descriptors. For
example, this is another way of running
.CW cat
to copy its standard input:
.P1
; cat /fd/0
.I "...and cat reads what you type.
.P2
.LP
and this is achieves the same effect:
.P1
; cp /fd/0 /fd/1
.I "...and cp copies what you type back to the console
.P2
.LP
In the last chapter, we did see that a command line executed in the background,
i.e., terminated with “\f(CW&\fP”, is not allowed to read from the console. What
happens is that the shell redirects the command's standard input to
.ix "background command
.CW /dev/null ,
the file that seems to be always empty. You can achieve a similar effect doing
this.
.P1
; cat </dev/null
;
.P2
.LP
Therefore, the input redirection here is redundant:
.ix "input redirection
.P1
; cat </dev/null &
;
.P2
.LP
How can the shell redirect the standard input/output for a command? Think about
it. The program
.CW cat
reads from file descriptor 0, when given no arguments. That is the convention for
standard input. For output,
.CW cat
writes at file descriptor 1. If the shell manages to get the file descriptor 1 for
.CW cat
open for writing into
.CW rememberthis ,
the bytes written by cat will go into
.CW rememberthis .
And of course
.CW cat
would know nothing about where does its standard output go. They are written
into an open file descriptor that must lead to some file. Also, if the shell manages
to get the file descriptor 0 for
.CW cat
open for reading from
.CW /dev/null ,
cat would be reading from
.CW /dev/null .
.PP
Input/output redirection must be done in the process that is going to
execute the command. Otherwise, the shell would loose its own
standard input or output. It must be done before doing the
.CW exec
for the new command. It would not make sense to do it after,
because there would be no I/O redirection, and because when
.CW exec
works, your program is gone!
.PP
Consider this program
.so progs/iredir.c.ms
.ix [iredir.c]
.LP
and its output.
.P1
; 8.iredir
Copyright © 2002 Lucent Technologies Inc.
All Rights Reserved
.P2
.LP
We supplied no argument to
.CW cat
in the call to
.CW execl .
.ix [execl]
Therefore,
.CW cat
was reading from standard input. However, because of the two previous
.ix "standard input
calls, file descriptor 0 was open to read
.CW /NOTICE .
The program
.CW cat
reads from there, and writes a copy to its output.
.PP
This is a real kludge. We do
.I not
know that
.CW open
is going to return 0 as the newly open file descriptor for
.CW /NOTICE .
At the very least, the program should check that this is
the case, and abort its execution otherwise:
.ix [assert]
.P1
fd = open("/NOTICE", OREAD);
assert(fd == 0);
.P2
.LP
At least, if
.CW fd
is not zero,
.CW assert
receives
.I false
(i.e., 0) as a parameter and prints the file and line number
before calling
.CW abort .
.PP
The system call
.CW dup
.ix [dup]
.ix "duplicate file descriptor
receives a file descriptor and duplicates it into another.
This is what we need. The code
.P1
fd = open("/NOTICE", OREAD);
dup(fd, 0);
close(fd);
.P2
opens
.CW /NOTICE
for reading, then
.I duplicates
the descriptor just open into file descriptor 0. After the call,
file descriptor 0 leads to the same place
.CW fd
was leading to. It refers to the same file and shares the same offset. This is shown
in figure [[!duplicating descriptor!]], which assumes that
.CW fd
was 3 (As you can see, both descriptors refer now to the same Chan). At this point,
the descriptor
whose number is in
.CW fd
is no longer necessary, and can be closed. The program in
.CW cat
is only going to read from
.CW 0 .
It does not even know that we have other file descriptors open.
.LS
.PS 5i
.ps -2
right
boxht=.2
boxwid=1
B: [
down
circle rad .4 "Child" "process"
line -> down " File descriptor" ljust " table" ljust
D: [ down
[ right
box invis wid .2 "0" ; F: box ]
D0: last [].F
[ right
box invis wid .2 "1" ; F: box ]
D1: last [].F
[ right
box invis wid .2 "2" ; F: box ]
D2: last [].F
[ right
box invis wid .2 "3" ; F: box ]
D3: last [].F
[ right
box invis wid .2 ; box invis "..."]
[ right
box invis wid .2 "n" ; F: box ]
]
arrow -> from D.D3 down .5 right 1
C: box wid 1.5 ht 2*boxht "\f(CW/NOTICE OREAD\fP" "\f(CWoffset: 0\fP"
arrow -> from D.D1 right 1
T: box wid 1.5 ht 2*boxht "\f(CW/dev/cons ORDWR\fP" "\f(CWoffset: 3245\fP"
spline -> from D.D0 right then to T.w + 0,.1
spline -> from D.D2 right then to T.w+0,-.1
]
move
A: [
down
circle rad .4 "Child" "process"
line -> down " File descriptor" ljust " table" ljust
D: [ down
[ right
box invis wid .2 "0" ; F: box ]
D0: last [].F
[ right
box invis wid .2 "1" ; F: box ]
D1: last [].F
[ right
box invis wid .2 "2" ; F: box ]
D2: last [].F
[ right
box invis wid .2 "3" ; F: box ]
D3: last [].F
[ right
box invis wid .2 ; box invis "..."]
[ right
box invis wid .2 "n" ; F: box ]
]
arrow from D.D3 down .5 right 1
C: box wid 1.5 ht 2*boxht "\f(CW/NOTICE OREAD\fP" "\f(CWoffset: 0\fP"
arrow -> from D.D1 right 1
T: box wid 1.5 ht 2*boxht "\f(CW/dev/cons ORDWR\fP" "\f(CWoffset: 3245\fP"
spline -> from D.D0 right .7 then down .8 then to C.w + 0,.1
spline -> from D.D2 right then to T.w+0,-.1
]
box invis "Before \f(CWdup(3, 0)\fP" at B.s - 0,.5
box invis "After \f(CWdup(3, 0)\fP" at A.s - 0,.5
reset
.ps +2
.PE
.LE F File descriptors before and after duplicating descriptor 3 into descriptor 0.
.PP
This is the correct implementation for the program shown before.
Its output remains the same, but the previous program could fail (Note
that in this section we are not checking for errors, to keep the programs' purposes
clearer to see).
.P1
void
main(int, char*[])
{
int fd;
switch(fork()){
case -1:
sysfatal("fork failed");
case 0:
fd = open("/NOTICE", OREAD);
dup(fd, 0);
close(fd);
execl("/bin/cat", "cat", nil);
sysfatal("exec: %r");
default:
waitpid();
}
exits(nil);
}
.P2
.LP
There are some pitfalls that you are likely to experience by accident in the future.
One of them is redirecting standard input to a file descriptor open for writing.
That is a violation of the convention that file descriptor 0 is open for reading. For
.ix [create]
.ix [dup]
example, this code makes such mistake:
.P1
fd = create("outfile", OWRITE, 0664); // WRONG!
dup(fd, 0);
close(fd);
.P2
.LP
Using this code in the previous program puts
.CW cat
in trouble. A
.CW write
call for a descriptor open just for reading is never going
to work:
.P1
; 8.iredir
cat: error reading <stdin>: inappropriate use of fd
;
.P2
.LP
Output redirections made by the shell use
.CW create
to open the output file, because most of the times
.ix "standard output redirection
.ix "truncate
the file would not exist. When the file exists, it is
truncated by the call and nothing bad happens:
.P1
fd = create("outfile", OWRITE, 0664);
dup(fd, 1);
close(fd);
.P2
.LP
A common mistake is redirecting both input and output to the same
file in a command line, like we show here:
.P1
; cat <processlist >processlist
;
.P2
.LP
When the shell redirects the output,
.CW create
truncates the file! There is nothing there for
.CW cat
to read, and your data is gone. If you ever
want to do a similar thing, it must be done in
two steps
.P1
; cat <processlist >/tmp/temp
; cp /tmp/temp processlist
; rm /tmp/temp
.P2
.BS 2 "Conventions
.LP
Why does standard error exist? Now you can know. Consider what happens when
.ix "standard error
we redirect the output for a program and it has a problem:
.P1
; lc /usr/nemos >/tmp/list
ls: /usr/nemos: '/usr/nemos' file does not exist
; cat /tmp/list
.P2
.LP
Clearly, the diagnostic printed by
.ix diagnostic message
.CW lc
is not the output data we expect. If the program had written this message
to its standard output, the diagnostic message would be lost between the data.
Two bad things would happen: We would be unaware of the failure of the command,
and the command output would be mixed with weird diagnostic messages that
might be a problem if another program has to process such output.
.PP
In the beginning, God created the Heaven and the Earth [ ... ], and God said,
.ix God
Let there be Light, and there was Light. Yes, you are still reading the same operating
systems book. This citation seemed appropriate because of the question, How did
my process get its standard input, output, and error? and, How can it be that
the three of them go to
.CW /dev/cons ?
.ix [/dev/cons]
.PP
The answer is simple. Child processes
.I inherit
.ix inheritance
a copy of the parent's file descriptors. In the beginning, Plan 9 created the first
process that executes in the system. This process had no file descriptor open, initially.
At that point, this code was executed:
.P1
open("/dev/cons", OREAD);
open("/dev/cons", OWRITE);
open("/dev/cons", OWRITE);
.P2
.LP
Later, all the descendents had their descriptors 0, 1, and 2 open and referring to
.CW /dev/cons .
This code would do the same.
.P1
open("/dev/cons", OREAD);
open("/dev/cons", OWRITE);
dup(1, 2);
.P2
.BS 2 "Other redirections
.LP
Output can be redirected to a file appending to its contents. In this
case, the shell
seeks to the end of the file used for output before executing the command.
To redirect output appending, use “\f(CW>>\fP” instead of use “\f(CW>\fP”.
.ix "append redirection
.P1
; echo hello >/tmp/note
; echo there >>/tmp/note
; echo and there >>/tmp/note
; cat /tmp/note
hello
there
and there
; echo again >/tmp/note
; cat /tmp/note
again
.P2
.LP
The code executed by the shell to redirect the output appending
is similar to this one,
.P1
fd = open("outfile", OWRITE);
if (fd < 0)
fd = create("outfile", OWRITE, 0664);
seek(fd, 0, 2);
dup(fd, 1);
close(fd);
.P2
.LP
which creates the output file only when it does not exist. If the program
used
.CW create ,
.ix [create]
it would truncate the file to a zero-length. If it used just
.CW open ,
the output redirection would not work when file does not exist. Also,
the call to
.CW seek
is utterly important, to actually append to the file.
.PP
File descriptors other than 0 and 1 can be redirected from the shell.
You must write the descriptor number between square brackets after
the operator. For example, this discards any error message from the command
by sending its standard error to
.CW /dev/null .
.P1
; lc *.c >[2] /dev/null
open.c seek.c
;
.P2
.LP
This file is another invention of the system, like most other files in
.CW /dev .
.ix device files
When you write into it, it seems that the write was done. However, the
system did not write anything anywhere. That is why this file is used
to throw away data sent to a file.
.PP
The shell can do more things regarding I/O redirection. The “\f(CW<>\fP”
operator redirects both standard input and output to the file whose name
follows. However, it opens the file just once for both reading and writing.
For example, this leaves
.ix "input~and~output redirection
.CW file
empty:
.P1
; echo hola>file
; cat <file >file
;
.P2
.LP
But this does not:
.P1
; echo hola >file
; cat <> file
hola
;
.P2
.LP
More useful is being able to redirect one file descriptor to another one.
Errors are to be written to standard error, but
.CW echo
writes to standard output. To report an error from a shell script, this
can be done
.P1
; echo something bad happen >[1=2]
.P2
.ix "[dup] in~[rc]
.LP
which is equivalent to a
.CW dup(1,2)
in a C program.
.PP
Redirections are applied left to right, and these two commands do different
things:
.P1
; ls /blah >/dev/null >[2=1]
; ls /blah >[2=1] >/dev/null
ls: /blah: '/blah' file does not exist
;
.P2
.LP
The first one redirects its output to
.CW /dev/null ,
which throws away all the output, and then sends
.ix "output discard
its standard error to the same place. Throwing it away as well.
The second one send its standard error to where standard output
is going (the console), and then throws away the output by sending it
to
.CW /dev/null .
.BS 2 "Pipes
.LP
.ix pipe
There is a whole plethora of programs in Plan 9 that read some data,
perform some operation on it, and write some output. We already saw
some. Many tasks can be achieved by combining these programs, without
.ix "compound command
having to write an entire new program in C or other language.
.PP
For example, this book is typeset using
.I troff (1),
.ix [troff]
.ix typesetting
and the input text is kept at files named
.CW ch1.ms ,
.CW ch2.ms ,
and so on, each one with the text for one chapter.
A rough estimate of the book size would be to count
the number of words for all the files containing troff input for chapters. We can
use a program to count words. Option
.CW -w
for
.CW wc
.ix [wc]
.ix "word count
does just that:
.P1
; wc -w ch*.ms
12189 ch1.ms
9252 ch2.ms
8153 ch3.ms
6470 ch4.ms
3163 ch5.ms
61 ch6.ms
592 chXX.ms
39880 total
.P2
.LP
This gives a good break-down of the number of words in each file, and also
of the total (as of today, when we are writing this). However, to obtain just the
total we can give a single file to
.CW wc
.ix "[wc] flag~[-w]
.P1
; cat ch*.ms >/tmp/all.ms
; wc -w /tmp/all.ms
39880 /tmp/all.ms
.P2
.LP
If we suspect that we use the word
.I file
too many times in the book, and what to check that out, we can count the number
of lines that contain that word as an estimate. The program
.CW grep
.ix [grep]
.ix "word search
writes to its output only those lines that contain a given word. We can run
.P1
; grep file </tmp/all.ms >/tmp/lineswithfile
;
.P2
to generate a file
.CW lineswithfile
that contains only the lines that mention
.CW file ,
and then use
.CW wc
on that file
.P1
; wc -w /tmp/lineswithfile
7355 /tmp/lineswithfile
.P2
.LP
This is inconvenient. We have to type a lot, and require temporary files
just to use the output of one program as the input for another.
There is a better way:
.P1
; cat ch*.ms | wc -w
39880
.P2
executes both
.CW cat
and
.CW wc .
The standard output for
.CW cat
is conveyed by the “\f(CW|\fP” into the standard input for
.CW wc .
We get the output we wanted in a simple way. This is how we count
just the lines using the word file:
.ix pipe
.P1
; cat ch*.ms | grep file | wc -l
7355
;
.P2
.LP
Here, the output of
.CW cat
was conveyed to
.CW grep ,
whose output was conveyed to
.CW wc .
A small command line performed a quite complex task. By the way,
because
.CW grep
accepts as arguments the names for its input files, a more compact
command could be used:
.P1
; grep file ch*ms | wc -l
7355
;
.P2
.LP
The
.I conveyer
represented by the vertical bar is called a
.CW pipe .
Its function is the same. Think of input as bytes flowing into a
command, for processing, and output as bytes flowing out the
command. If you have a pipe, you can plumb one output to one
input. But you
.I must
use a pipe. Otherwise, bytes would pour on the floor!
.PP
Before, we have used
.CW ps
.ix [ps]
to lists processes. Usually, there are many lines printed by
the command,
but we can be interested in a particular one. There is no need to
scroll down the terminal and search through many lines just
to find the information for a broken process:
.P1
; ps | grep Broken
nemo 1633 0:00 0:00 24K Broken 8.out
;
.P2
.ix [Broken]
.LP
The output of
.CW ps
is sent into the pipe. It flows through it and becomes the input
for
.CW grep ,
which writes just those lines that contain the string
.CW Broken .
.PP
To get rid of this broken process, we can execute
.CW broke .
.ix [broke]
.ix "kill broken process
This program
.I prints
a command to kill the broken processes, but does not kill them
itself (killing is too dangerous and
.CW broke
does not want to take responsibility for your actions):
.P1
; broke
echo kill>/proc/1633/ctl # 8.out
;
.P2
.LP
But to
.I execute
this command, we must use it as input for the shell. Now we can.
.ix "[rc] in~pipes
.P1
; broke |rc
; ps | grep Broken
;
.P2
.LP
Figure [[!pipe input output connect!]] shows what happens when
you execute
.CW broke|rc
The file descriptor 1 for
.CW broke
gets sent to the input of the pipe. The output from the pipe is used
as source for
file descriptor 0 in
.CW rc
Therefore,
.CW rc
reads from its standard input what
.CW broke
writes on its output.
In the
figure, processes are represented by circles. Arrows going out from circles
are file descriptors open for writing. The descriptor number is the value or
variable printed in the arrow. Arrows pointing into circles are file descriptors
open for reading. Of course, the process represented by the circle is the one
who reads. Pipes and files do not read, they are not alive!
.LS
.PS
right
arrow right "0" above
circlerad=.4
circle "\f(CWbroke\fP"
arrow right "1" rjust above
box wid 1 ht .2 "pipe"
arrow right "0" ljust above
circle "\f(CWrc\fP"
arrow right "1" above
reset
.PE
.LE F Using a pipe to connect the output of \f(CWbroke\fP to the input of \f(CWrc\fP.
.PP
The pipe is an artifact provided by Plan 9 to let you interconnect processes.
.ix "process communication
It looks like two files connected to each other. What you write into one of them,
is what will be read from the the other. That is why in the figure, the input for
one process goes into one end of the pipe, and the output for the other process
may go to the
.I other
end of the pipe.
.PP
To create a pipe in a C program, you can use the
.CW pipe
system call. It returns
.I two
descriptors, one for each end of the pipe. Both descriptors are stored
at the integer array passed as a parameter to the function.
.P1
int fd[2];
pipe(fd);
// fd[0] has the fd for one end
// fd[1] has the fd for the other.
.P2
.ix [pipe]
.LP
This program is trivial, but it helps in understanding pipes. It writes
some text to one end of the pipe, and reads it back from the other end.
To see the outcome, it prints what it did read to its standard output.
.so progs/pipe.c.ms
.ix [pipe.c]
.LP
This is the output
.P1
; 8.pipe
Hello!
;
.P2
.LP
Because standard output is file descriptor 1, and standard input is file descriptor 0,
the tradition is to read from
.CW fd[0]
and write into
.CW fd[1] ,
as the program does. Pipes are bi-directional in Plan 9, and doing it the other
.ix "bidirectional pipe
way around works as well. It is said that Plan 9 pipes are
.B full-duplex .
.PP
Let's try now something slightly different. If we replace the single write in the
program with two ones, like
.P1
write(fd[1], "Hello!\en", 7);
write(fd[1], "there\en", 6);
.P2
.LP
this is what the program prints now.
.P1
; 8.pipe
Hello!
;
.P2
.LP
the same! Plan 9 pipes preserve
.B "write boundaries"
.ix "message delimiters"
(known also as
.I "message delimiters" ).
That is to say that for each read from a pipe, you will get data
from a single write made to the pipe. This is very convenient when
you use the pipe to speak a dialog between two programs, because
different messages in the speech do not get mixed. But beware, UNIX
does not do the same. This is the output from the same program in a
.ix UNIX
UNIX system:
.P1
$ !!pipe
Hello!
there
$
.P2
.LP
In Plan 9, we need a second read to obtain the data sent through the
pipe by the second write.
.PP
The pipe has some buffering (usually, a few Kbytes), and that is where the
.ix pipe buffering
bytes written by the program were kept until they were read from the pipe.
Plan 9 takes care of those cases when data is written to the pipe faster than
it is read from the pipe. If the buffer in the pipe gets full (the pipe is full of bytes), Plan 9
will make the writer process wait until some data is read and there is room
in the pipe for more bytes. The same happens when data is read faster than
written. If the pipe is empty, a read operation on it will wait until there is
something to read.
.PP
You can see this. This program fills a pipe. It keeps on writing into the pipe
until Plan 9 puts the process in the blocked state (because the pipe is full).
.ix [fill.c]
.so progs/fill.c.ms
.LP
This is the output. The pipe in my system can hold up to 30 Kbytes.
.P1
; 8.fill
wrote 1024 bytes
wrote 1024 bytes
wrote 1024 bytes
.I "... 29 lines including these two ones...
wrote 1024 bytes
.I "... and it blocks forever
.P2
.LP
And this is what
.CW ps
says for the process:
.P1
; ps | grep 8.fill
nemo 2473 0:00 0:00 24K Pwrite 8.fill
.P2
.LP
.ix [Pwrite]
It is trying to write, but will never do.
.PP
In the shell examples shown above, it is clear that the process reading
from the pipe gets an end of file (i.e., a read of 0 bytes) after all data
.ix "end of~file
has gone through the pipe. Otherwise, the commands on the right of
a pipe would never terminate. This is the rule: When no process can
write to one end of the pipe, and there is nothing inside the pipe,
reading from the other end yields 0 bytes. Note that when the pipe is
empty, but a process can write to one end, reading from the other end
would block.
.PP
This is easy to check using our single-process program. If we do this
.P1
close(fd[1]);
nr = read(fd[0], buf, sizeof(buf));
.P2
.LP
the value of
.CW nr
becomes zero, and
.CW read
does not block. However, removing the
.CW close
line makes the program block forever.
.ix "blocked process
.PP
Writing to a pipe when no one is going to read what we write is a
nonsense. Plan 9 kills any process doing such thing. For example
executing this program
.ix "broken pipe
.so progs/brokenpipe.c.ms
.LP
yields
.P1
; 8.brokenpipe
; echo $status
8.out 2861: sys: write on closed pipe pc=0x00002b43
.P2
.ix "closed pipe
.BS 2 "Using pipes
.LP
One useful thing would be to be able to send from a C program
an arbitrary string as the standard input for a command. This can
be used for many things. For example, the
.CW mail
.ix [mail]
program is used to send electronic mail from the command line.
The body of the message is read from standard input, and the
subject and destination address can be supplied in the command line.
This is an example using the shell.
.P1
; mail -s 'do you want a coffee?' [email protected]
!!Hi,
!!If you want a coffee, let's meet down at 5pm.
!!see u.
\fBcontrol-d\fP
.P2
.LP
To do something similar from a C program, we must create a child process
to execute
.CW mail
on it. Besides, we need a pipe to redirect to it the standard input for
.CW mail
and write what we want from the other end of the pipe.
.ix "pipe~to child~process
.PP
This seems a general tool. We are likely to want to execute many different
commands in this way. Therefore, we try to write a function as general as
possible for doing this job. It accepts a string containing a shell command line as a
parameter, and executes it in a child process. It returns a
file descriptor to write to a pipe that leads to the standard input of this process.
.ix [pipeto.c]
.so progs/pipeto.c.ms
.LP
To see a complete example, where this function is used,
the
.CW main
function uses
.CW pipeto
to send several messages to the input of a process running
.CW "grep warning" .
Messages are sent by writing the the file descriptor returned from
.CW pipeto .
When nothing more has to be sent, the file descriptor is closed. The
child process will receive an end-of-file indication as soon as it consumes
what may still be going through the pipe. This is the output for the program.
.P1
; 8.pipeto
;\ warning: the world is over
warning: it was not true
.P2
.LP
.ix "wait~for child~process
Because the parent process finishes before the child is still processing
the input that comes from the pipe, the shell prompt gets printed
almost immediately. If this is a problem, the parent must wait for the child
.I after
writing all the data to the pipe. Otherwise, the
.CW waitpid
.ix [waitpid]
call
would block waiting for the child to die, and the child would block waiting
for the end of file indication (because the parent has the pipe open for writing).
.PP
Figure [[!pipe to command!]]
shows the processes involved, all their descriptors, and the pipe. We use the
same conventions used for the last figure, which we will follow from now on.
.LS
.PS
.R
right
circlerad=.4
arrow right .5 "\f(CW0\fP" above
C: circle "Parent" "Process"
arrow right .5 "\f(CW1\fP" above
arrow from C up .5 right 1.4 "\f(CW2\fP" above chop .5
spline -> from C.se down .5 right .5 "\f(CWfd\fP" then right .5
box wid .5 ht .2 "pipe"
arrow right .5 "\f(CW0\fP" above
G: circle "\f(CWgrep\fP"
arrow right .5 "\f(CW1\fP" above
arrow from G up .5 right 1.4 "\f(CW2\fP" above chop .5
.PE
.LE F A process using a pipe to send input to a command.
.PP
.PP
All the interesting things happen in the function
.CW pipeto .
.ix [pipeto]
It executes the Plan 9 shell, supplying the command line as the argument
for option
.CW -c ,
.ix "[rc] flag~[-c]
this asks
.CW rc
to execute the argument as a command, and not to read commands from
standard input.
.PP
First,
.I before
creating the child process, the parent process makes a pipe. It is very
.ix "pipe creation
important to understand that the pipe
.I must
be created before we call
.CW fork .
.ix [fork]
Both processes must share the pipe. If the pipe is created after
forking, in the child process, the parent process does not have the descriptor
to write to the pipe. If it is created by the parent, after calling
.CW fork ,
the child will not have the descriptor to read from the pipe.
.PP
Even if both processes
create a pipe, after the child creation, there are two different pipes. Each process
can use only its own pipe, but they cannot talk. It does not matter if the numbers
returned from
.CW pipe
for the two descriptors are the same (or not) for both processes: They are different
descriptors because each process made its own call to
.CW pipe.
Therefore, pipes
are created always by a common ancestor of the processes communicating
through the pipe.
.PP
Another important detail is that all the descriptors are closed (by all processes)
.ix [close]
as soon as they are no longer useful. The child is going to call
.CW execl ,
.ix [execl]
and the new program will read from its standard input. Thus, the child must
close both pipe descriptors after redirecting its standard input to the end for
reading from the pipe. The parent process is going to write to the pipe, but
it is not going to read. It closes the end for reading from the pipe.
Not doing so risks leaving open the pipe for writing, and in this case the reader
process would never get its end of file indication.
.PP
Why does the child redirect its standard input to the pipe and not the parent?
We wrote the code for the parent. We know that it has
.CW fd[1]
open for writing, and can just use that descriptor for writing. On the other hand,
the child does
.I not
know! After the child executes
.CW grep ,
how can grep possibly know that it should use a file descriptor other than zero for
reading?
.PP
The following example is a counterpart to what we made. This function creates
a child process that is used to execute a command. However, this time, we return
the output produced by the command. For example, calling
.P1
nr = cmdoutput("wc *.c", buf, sizeof buf);
.P2
will fill in
.CW buf
a string taken from what
.CW "wc *.c"
prints to its standard output. This is not the best interface for the task, because
we do not know how much the command will print, but it is useful nevertheless.
The caller must take the precaution of supplying a buffer large enough. The number
of bytes read is the result from the function. This is its code:
.P1
.ps -2
.vs .15i
long
cmdoutput(char* cmd, char*buf, long len)
{
int fd;
long tot;
if (pipe(fd) < 0)
return -1; // failed to create a pipe
switch(fork()){
case -1:
return -1;
case 0:
close(fd[0]);
dup(fd[1], 1);
close(fd[1]);
execl("/bin/rc", "-c", cmd, nil);
sysfatal("exec");
default:
close(fd[1]);
for(tot = 0; len - tot > 1; tot += nr){
nr = read(fd[0], buf+tot, len - tot);
if (nr <= 0)
break;
}
close(fd[0]);
waitpid();
buf[tot] = 0; // terminate string
return tot;
}
}
.ps +2
.P2
.LP
In this function, we wait for the child to complete before returning, but
after having read all the data from the pipe. It is a serious mistake to
wait for the child before having read all its output. If the output does not
fit into the pipe, the child will block as soon as the pipe is full. It will be
waiting forever, because the parent is not going to read until
.CW waitpid
.ix [waitpid]
completes, and this call is not going to complete until the child dies.
.PP
This is called a
.B deadlock .
One process is waiting for another to do something, and that requires
the former to do another thing, which cannot be done because it is
waiting. You know when you have a deadlock because the processes
involved
.I freeze .
.ix "frozen process
Deadlocks must be avoided. We avoided one here simply by doing
the things in a sensible order, and waiting for the child after we have read
all its output.
.PP
What we have seen is very useful. Many programs do precisely this, or other
similar things.
The editor Acme admits commands to be applied to a portion of text
.ix "[acme] pipe command
selected by the user. For example, using the button-2 in Acme to run
the command
.CW |t+
asks Acme to execute the program
.CW t+
with the selected text as the input for
.CW t+ ,
and to replace that text with the output from the command. Of course, Acme
uses pipes to send text to the input of
.CW t+
and to read its output.
The command
.CW t+
is a shell script used to indent text by inserting a tab character at the start of each line.
.ix [t+]
.PP
The shell is also a heavy user of pipes, as you might expect. Rc includes
several interesting constructs that are implemented along the lines of what we saw before.
.PP
When Rc finds a command inside \f(CW`{\fP...\f(CW}\fP, it executes
the command, and
.ix "command substitution
.I substitutes
the whole \f(CW`{\fP...\f(CW}\fP text with the output printed by the command.
.ix "command line"
We did something alike in the C program when reading the output for a
command using a pipe. This time, Rc will do it for us, and relieve us from
typing something that can be generated using a program. This is an example.
.P1
; date
Fri Jul 21 16:36:37 MDT 2006
; today=`{date}
; echo $today
Fri Jul 21 16:36:50 MDT 2006
.P2
.LP
Another example, using a command that writes numbers in sequence, follows.
.ix [seq]
.P1
; seq 1 5
1
2
3
4
5
; echo `{seq 1 5}
1 2 3 4 5
;
.P2
.LP
As you can see, the second command was equivalent to this one:
.P1
; echo 1 2 3 4 5
.P2
.LP
The shell executed
.CW "seq 1 5" ,
and then did read the text printed by this command through its standard output
(using a pipe). Once all the
command output was read, Rc replaced the
whole \f(CW`{\fP...\f(CW}\fP construct with the text just read. The resulting line
was the one executed, instead of the one that we originally typed. Because
a newline character terminates a command, the shell replaced each
.CW \en
in the command output with a space. That is why executing
.CW seq
directly yields 5 lines of output, but using it with \f(CW`{\fP...\f(CW}\fP
produces just one line of output.
.PP
A related expression provided by the shell is \f(CW<{\fP...\f(CW}\fP.
Like before, Rc executes the command within the brackets, when it finds
.ix "here file
this construct in a command line. The output of the command is sent through
a pipe, and the whole \f(CW<{\fP...\f(CW}\fP is replaced by a file name that
represents the other end of the pipe (pipes are also files!, as we will see in a following
chapter).
.PP
There are several interesting uses for \f(CW<{\fP...\f(CW}\fP, one of them is to be able
to give a file name for the input file for a command, but still use as input another
command that writes to its standard output.
.P1
; wc <{seq 1 5} /LICENSE
5 5 10 /fd/13 \fIThis is the pipe!\fP
261 1887 13006 /LICENSE
266 1892 13016 total
;
.P2
.LP
But, perhaps, the most amazing use for this construct is to build non-linear pipelines.
That is, to use the output of
.I several
commands as input for another one. For the latter, the output of the former ones
would be just a couple of file names. An interesting example is comparing the output
of two commands. The shell command
.CW cmp
.ix [cmp]
.ix "file compare
compares two files, and informs us whether they have the same contents or not.
.P1
; cp /LICENSE /tmp/l
; cmp /LICENSE /tmp/l
; cmp /LICENSE /NOTICE
/LICENSE /NOTICE differ: char 1
.P2
.LP
Therefore, if you want to execute two commands and compare what they write to their
standard output, you can now use
.CW cmp
as well.
.ix "non-linear pipe
.P1
; cmp <{seq 1 3} <{echo 1 ; echo 2 ; echo 3}
; cmp <{seq 1 3} <{echo 1 2 3}
/fd/14 /fd/13 differ: char 2
;
.P2
.LP
You will get used to \f(CW`{\fP...\f(CW}\fP and \f(CW<{\fP...\f(CW}\fP after using them
in the couple of chapters that discuss programming in Rc.
.BS 2 "Notes and process groups
.LP
.ix "notes
.ix "process group
Pipes are a
.B "synchronous communication
mechanism. A process using a pipe must call
.CW read
or
.CW write
.ix pipe
to receive or send data through the pipe, and communication happens
only when the process makes these calls. Sometimes, the world is not
so nice and we need an
.B "asynchronous communication
mechanism. For example, if a process gets out
of control and you want to stop it, you may want to post a note
saying “interrupt” to the process. The process is not reading from
anywhere to obtain the message you want to send, but you still
can send the message at any moment. The message will interrupt
.ix "interrupt
the normal execution of the process, so this mechanism is to be
used with care.
.PP
.ix "note post
Posting notes can be dangerous, when the process is not paying
attention to the note posted it is killed by the system.
.PP
This is our first example, we are going to use the window system to
interrupt a process. When
.CW cat
is given no arguments, it reads from the console. It will be doing so
unless you type a
.I control-d
to ask the window to signal a (fake) end of file. This time, we are
not going to do so. Run this command and press
.I Delete .
.P1
; cat
\fIcat waits reading... \fP
\fBDelete\fP \fI...until you press delete,\fP
; \fIand cat is gone!\fP.
.P2
.LP
What happen to
.CW cat ?
Let's ask the shell:
.P1
; echo $status
cat 735: interrupt
;
.P2
.LP
According to the shell,
.CW cat
died because of
.I interrupt .
.PP
.ix "window system
.ix "console
.ix focus
When you type characters, the window system reads them from the
real console. Depending on which window has the
.I focus ,
i.e. on which one did you click last, it sends the characters to the
corresponding window. If the window system reads a
.I Delete
key, it understands that you want to interrupt the process in the window
that has the focus, and it posts a note with the text
.CW interrupt
.ix "[interrupt] note
for all the processes sharing the window. The shell is paying attention
(and ignoring) the note, therefore it remains unaffected. However,
.CW cat
is not paying attention to it, and gets killed in action.
.PP
Let's do it by hand. We need a victim.
.P1
; sleep 3600 &
;
.P2
.LP
And this one gives us one hour to play with it. The process is alive and well:
.P1
; ps | grep sleep
nemo 1157 0:00 0:00 8K Sleep sleep
; echo $apid
1157
.P2
.LP
.ix [apid]
We check that it is our process, looking at
.CW $apid .
No tricks here. To post a note to a process, the note text is written to a file
in
.CW /proc
.ix "[/proc] file system
that provides the interface to post notes to it. Remember that this file
is just an interface for the process, and not a real file. For this process,
the file would be
.ix "process [note] file
.CW /proc/1157/note .
To do exactly the same that the window system is doing, we want to
post the note to
.I all
processes sharing its window. Writing the note to
.CW /proc/1157/notepg
.ix "process [notepg] file
.ix "process interrupt
does this:
.P1
; echo interrupt >/proc/1157/notepg
; ps | grep 1157
;
.P2
.LP
It is gone!
.PP
The file is called
.CW notepg
because it refers to a
.B "process group" .
Processes belong to groups only for administrative reasons. For example,
.I Delete
should affect all the processes active in a window. Otherwise, you would
not be able to interrupt a command line with more than one process, like
a pipeline.
.PP
Usually, there is a process group per window, and
it is used to deal with all the programs on the window at once.
When a window is deleted using the mouse, you expect the programs
running on it to die. The window system posts a
.CW hangup
.ix "[hangup] note
note when the window is deleted. The note is posted
to all the processes in the window, i.e., to the process group of the shell
running in the window. We can also try this.
.P1
; echo hangup >/proc/$pid/notepg
\fIAnd the window is gone!\fP
.P2
This required
having an abstraction, i.e., a mechanism, to be able to group those processes
and post a note just for them. The process group is this abstraction.
.PP
By the way, notes are the mechanism used by the system to signal exceptional
.ix exception
conditions, like dividing by zero. Notes posted by the system start with
.CW suicide: ,
and put the process into the broken state, for debugging.
.PP
Processes can use
.CW atnotify
.ix [atnotify]
.ix "note handler
to register a notification handler that listens for notes. The function receives
a note handler as a parameter, and installs the handler if the second
parameter is true, or removes the handler otherwise.
.P1
; sig atnotify
int atnotify(int (*f)(void*, char*), int in)
.P2
.LP
The handler is a function that receives a pointer to the process registers
as they were when it noted the note. This is usually ignored. The second
parameter is more interesting, it is a string with the text from the note.
When the note is recognized by the handler, it must return true, to indicate that
the note was attended. Otherwise, it must return false. This is required because
there can be many handlers installed for a process, e.g., one for each type
of note. When a note is posted, each handler is called until one returns true.
If no handler does so, the note is not attended, and the process is killed.
.PP
This program may provide some insight about notes. It registers a handler
that prints the note received and pretends that it was not attended (returning
zero).
.so progs/pnote.c.ms
.LP
If we run the program, and press
.I Delete
while it is running, this is what happens:
.P1
; 8.pnote
\fIthe program runs until we press Delete. And then, ...\fP
\fBDelete\fP
note: interrupt
; echo $status
8.pnote 1543: interrupt
;
.P2
.LP
The program is killed, because it did not handle the note. When we pressed
.I Delete ,
.ix "process kill
the program was executing whatever code it had to execute. In this case,
it was blocked waiting inside
.CW sleep
for time to pass by. The note caused the system call to be interrupted, and
the process
.I jumped
to execute its handler where it printed its message. Because no handler recognized
the note, the process was killed.
.PP
Notes are asynchronous, and
.ix "asynchronous communication
this means that the handler for a note may run at any time, when it pleases
Plan 9 to instruct your process to stop what it was doing and jump into the
note handler. This is similar to the model used for
.I interrupts ,
which is quite different from the
.I process
model: One single continuous flow of control, easy to understand.
.PP
We are now going to modify the handler to return true, and not zero. This is
what the new program does.
.P1
; 8.pnote
\fIthe program runs until we press Delete. And then, ...\fP
\fBDelete\fP
note: interrupt
done (interrupted)
; echo $status
;
.P2
.LP
The program was executing the
.CW sleep
.ix [sleep]
system call, it was blocked waiting for time to pass. After hitting
.I Delete ,
.ix [Delete]
a note was posted. The natural flow of control for the process was
interrupted, and it jumped to execute the note handler. It prints the
text for the note,
.I interrupt ,
and returns true. The note was recognized and Plan 9 is happy with that. The
process is not killed. Instead, it continues where it was. Well, mostly.
.PP
The process
did not wait for one hour! Because of the note, the system call was interrupted.
It returns an error to report that. But it returns. The program is still running
at the same point it was when the note was posted. We printed the error string
reported from
.CW sleep
to see that it is
.CW interrupted .
.PP
In general, notes are not to be used in your programs. In other systems,
they are used to remove temporary files if a program is interrupted. In Plan 9,
there is a better way for doing this. Any file that you open with the
.CW ORCLOSE
.ix "[ORCLOSE] open~flag
flag, for example,
.P1
fd = open("/tmp/tempfile", ORDWR|ORCLOSE);
.P2
is automatically removed by the system when the file descriptor is closed. If
your program dies because of a note, the descriptor is closed as part of the
natural dying process. At that point, the file is removed. Using notes it could
be done by installing a note handler like this one
.P1
int cleanup(void*, char* msg)
{
if (strcmp(msg, "interrupt") == 0)
remove("/tmp/tempfile");
return 0;
}
.P2
.ix "[interrupt] note
.ix "note handler
.LP
But this is an
.I horrible
idea. Notes can happen at any time, behind your back. You are executing
your nice single flow of control, and there are functions as nasty as the
pop-ups in other window systems, that run at unexpected times and may
cause your program to fail.
.PP
When are notes posted by Plan 9? The kernel is not a magic program.
It can post a note only when it executes. Besides, for simplicity, a note
is handled from within the process that receives it. A write into the
.CW note
.ix "process [note] file
or the
.CW notepg
.ix "process [notepg] file
file records that the target process(es) has a note posted. Sooner or later,
the target process will be allowed to run (if only to process the pending note),
At that point, when returning from the kernel
back to the user's code, is when the note is processed.
.PP
If the process receiving the note was performing a system call that does not
block, the system call is allowed to complete and the note is posted while
returning from the call. On the other hand, if the process was performing a
.I slow
system call, and was blocked trying to read, or write, or any other thing,
the system call is interrupted, as we saw before.
.BS 2 "Reading, notes, and alarms
.ix "robust file read
.LP
You know how to read from a file. To read
.I n
bytes from a file the program must call
.CW read
until all the
.I n
bytes are read, because
.CW read
.ix [read]
may return less bytes than requested. This is so common, that a library
function
.CW readn
.ix [readn]
exists that keeps on calling read until all the
.I n
bytes have been read.
However, This function may return less bytes than requested, because of a note.
Of course this would happen only if the process is attending the note, because
it would be killed otherwise, and what
.CW readn
does would not matter at all.
.PP
To actually read
.I n
bytes even when receiving notes, we can use this alternate function:
.P1
.ps -2
.vs .15i
long
robustreadn(int fd, char* buf, long n)
{
long nr, tot;
char err[128];
for (tot = 0; tot < n; tot += nr){
nr = read(fd, buf+tot, n-tot);
if (nr == 0)
break;
if (nr < 0){
rerrstr(err, sizeof(err));
if (strcmp(err, "interrupted") == 0)
nr = 0; // retry
else
break;
}
}
return tot;
}
.ps +2
.P2
.ix [robustreadn]
.LP
It requires the process to install a handler for the
.CW interrupted
note, or the process will be killed.
.PP
Surprisingly enough, there are times when the problem is not that
.CW read
is interrupted, but, on the contrary, the problem is that it is not interrupted.
For example, a process may need to read a message sent from anywhere else
in the network. This is achieved by calling
.CW read
on a file that is used to
.I connect
the process with the one that is supposed to send it a message. Similar to a
pipe, but crossing the network. There is a problem in this case. If the other (remote)
process hangs, because of a bug or any other reason, it may never send its message.
The poor process that is reading will be blocked awaiting, forever, for the message
to arrive.
.PP
To recover from this circumstance, it is usual to employ a
.B timeout .
.ix "process alarm
.ix [alarm]
A timeout is an alarm timer used to be sure that there is a limit in the amount of
time that we wait for some operation to complete. In this case, it seems reasonable
to use a timeout of 30 seconds. That is an incredibly long time for a computer, even
when considering the delays involved in crossing the network to send or receive a
message.
.PP
Plan 9 provides an alarm timer for each process. The timer is started by calling
.CW alarm ,
giving as a parameter the number of milliseconds that must pass before the timer
expires.
.P1
; sig alarm
long alarm(unsigned long millisecs)
.P2
.LP
There is
.I no
guarantee that the timer will last for exactly that time. It might take a little bit
more if the system is busy doing any other thing. However, real soon after
the specified number of milliseconds, an
.CW alarm
note will be posted for the process that did call
.CW alarm .
And you know what happens, when the note is posted, any system call that
kept the process awaiting (e.g.,
.CW read )
will be interrupted. The following program reads a line from the terminal,
and prints it to the standard output. However, it will wait at most 30 seconds
for a line to be typed.
.so progs/alarm.c.ms
.ix [alarm.c]
.LP
Right before calling
.CW read ,
the program installs an alarm timer of 30 seconds. That much time later, it will
post the
.CW alarm
note. If we type something and
.CW read
completes before that time, the program calls
.CW alarm(0)
.ix "alarm cancel
to cancel the timer. Otherwise, the timer expires and
.CW read
is interrupted.
.P1
; 8.alarm
type something: !!Hi there
Hi there
; 8.alarm
type something: timed out \fIWe did not type anything for 30secs\fP
;
.P2
.LP
.ix timer
In general, timers are to be used with caution. They make programs unpredictable.
For example, it could happen that right after we typed our line the timer expires.
This could happen at
.I any
time, not necessarily while we are waiting in
.CW read ,
but perhaps when we are in our way to cancel the timer. At least,
it is wise to give plenty
of time for a timeout, to make things more predictable, and it is even better
not to use it unless it is absolutely necessary.
.BS 2 "The file descriptor bulletin board
.LP
.ix registry
.ix "file descriptor board
.ix "[/srv] file~system
.ix "[#s] device~driver
Sometimes, processes need to talk through a pipe, but they
do not have an appropriate ancestor where to create the pipe. This
happens when, after a process has been created, a newcomer wants
to talk to that process.
.PP
The program that implements the file system,
.CW fossil ,
.ix [fossil]
.ix "file server
.ix boot
is a perfect example. It is started (in the file server machine) during
the boot process. Once started, programs may use files by talking to
the file server using the network.
.PP
But there is a problem. The file system, see
.I fossil (4),
has to be able to accept commands from a human operator, to carry out administration
tasks. For
.CW fossil ,
a simple way is to create a pipe and attend one end of the pipe, reading commands
and writing replies (pipes are bi-directional).
Any process used by a human at the other end of the pipe
may talk to the file system, to administer it.
Here is an example of a conversation between a human
and the file system:
.ix "fossil console
.P1
main: fsys
main
main: sync
main sync: wrote 0 blocks
main: who
console
/srv/boot nemo
/srv/fossil nemo
/srv/vfossil nemo
/srv/fboot nemo
.P2
.LP
When we wrote
.CW fsys ,
fossil replied with the list of file systems. When we typed
.CW sync ,
fossil
.I synchronized
its changes with disk (any change to a file that was not yet copied to the
disk, was copied immediately). When we typed
.CW who ,
the file system wrote the list of users using the file system.
.PP
How can we reach the pipe used to talk to
.CW fossil ?
The directory
.CW /srv
.ix [/srv]
is special. It is a file descriptor bulletin board. A process can
.I post
.ix "file descriptor post
a file descriptor into this bulletin board by creating a file
on it. For example, in my system,
.CW /srv/fscons
is a file that corresponds to the end of the pipe used to talk to fossil.
.PP
The idea is not complex, once you realize that files in Plan 9 are not
real files, most of the times. The file
.CW /srv/fscons
is not a file, it looks like, but it is just a file interface for a file descriptor
that
.CW fossil
has open.
Because
.CW /srv/fscons
.I looks
like a file, you can open it and gain access to the file descriptor. And you
do not require a common ancestor with fossil!
.PP
For example, this, when executed in the file server, asks
.CW fossil
to write any pending change to the disk.
.P1
; echo sync >>/srv/fscons
.P2
.LP
.LP
When the shell opens
.CW /srv/fscons ,
it is not opening yet another file. It is obtaining a file descriptor that is
similar to the one posted into
.CW /srv/fscons
by
.CW fossil .
The result is the same of calling
.CW dup
to duplicate the descriptor kept inside
.ix [dup]
.CW /srv/fscons ,
however, you cannot call
.CW dup .
You do not have the file descriptor to duplicate, because it belongs to another
process.
.PP
This program is an example of how to use this bulletin board. It creates
one pipe and reads text from it, printing a copy to standard output, so we
could see what is read. The other end of the pipe is posted at
.CW /srv/echo ,
.ix "echo server
for us to use.
.ix [srvecho.c]
.so progs/srvecho.c.ms
.LP
The
.CW create
.ix [create]
call for
.CW /srv/echo
creates a file where the program can post a file descriptor. The way to
do the post is by writing the file descriptor number into the file, and closing it.
The created file at
.CW /srv
is just an artifact. What matters is that now there is another way to get to the
descriptor in
.CW fd[1] .
Because the program does not use that descriptor itself, it closes it. Note that
the pipe end is
.ix pipe
.ix "file server
.I not
closed at this point. The descriptor kept inside
.CW /srv/echo
is also leading to that end of the pipe, which therefore remains open.
From now on, the program reads from the other end of the pipe to do the echo.
.P1
; 8.srvecho &
; lc /srv
boot echo plumb.nemo.264 slashmnt
cs_net fscons slashdevs vol
; echo hi there! >>/srv/echo
hi there!
; ps | grep 8.srvecho
nemo 2553 0:00 0:00 24K Pread 8.srvecho
.P2
.LP
If we remove the file
.CW /srv/echo ,
and no process has the file descriptor open for that end of the pipe, our
program would receive an end of file indication at the other end of the pipe, and
terminate.
.P1
; rm /srv/echo
exiting
;
.P2
.LP
Files in
.CW /srv
are just file descriptors. They only difference is that they are
published in a bulletin board for anyone
to see. How is this done? In a simple way, each file for
.CW /srv
.ix [Chan]
contains a reference to the Chan of the descriptor posted in it. Figure
[[!posted descriptor!]] shows the elements involved in the session we have
just seen.
.LS
.PS 5i
.ps -2
right
boxht=.2
boxwid=1
B: [
down
circle rad .4 "Echo" "process"
line -> down " File descriptor" ljust " table" ljust
D: [ down
[ right
box invis wid .2 "0" ; F: box ]
D0: last [].F
[ right
box invis wid .2 "1" ; F: box ]
D1: last [].F
[ right
box invis wid .2 "2" ; F: box ]
D2: last [].F
[ right
box invis wid .2 "3" ; F: box ]
D3: last [].F
[ right
box invis wid .2 ; box invis "..."]
[ right
box invis wid .2 "n" ; F: box ]
]
spline -> from D.D3 right then down 1 then right
C: box wid 1.5 ht 2*boxht "file: pipe \f(CW ORDWR\fP" "\f(CWoffset: 0\fP"
arrow
box "pipe"
spline <- right then up .5 left .5 then up .5
C: box wid 1.5 ht 2*boxht "file: pipe \f(CW ORDWR\fP" "\f(CWoffset: 0\fP"
arrow <-
circle rad .5 "File" "\f(CW/srv/echo\fP"
]
.PE
.LE F A file descriptor posted at \f(CW/srv/echo\fP used to talk to a process through a pipe.
.BS 2 "Delivering messages
.LP
Presenting every resource as a file may be an inconvenience when programs need
to act after some success happens. For example, the program
.CW faces
.ix [faces]
.ix [mail]
(see figure [[!faces!]])
shows a small face image for each email received by the user, displaying an image
that describes the sender for each mail. When a mail arrives,
.CW faces
must show a new face to alert the user of the new incoming mail.
In this case, usually, the program must check out the files
of interest to see if the thing of interest happen. This is called
.B polling ,
and the thing of interest is called an
.B event .
.LS
.BP faces.ps 1.5i
.LE F The program \f(CWfaces\fP shows small faces for persons that sent email to us.
.PP
Polling has the problem of consuming resources each time a poll is made to check
.ix "busy waiting
.ix efficiency
out if an interesting event happen. Most of the times, nothing happens and the
poll is a waste. Therefore, it would be very
inefficient to be all the time polling for an event and, as a result, programs that poll
usually call
.CW sleep
.ix [sleep]
between each two polls. The following two programs wait until the file given
as a parameter changes, and then print a message to let us know. The first one
performs a continuous poll for the file, and the second one makes one poll each 5 seconds.
.so progs/poll.c.ms
.ix [poll.c]
.so progs/pollb.c.ms
.ix [pollb.c]
.LP
It is interesting to see how loaded is the system while executing each program.
The
.B "system load"
is a parameter that represents how busy the system is, and it is usually
indicative of how much work the system is doing.
The load is measured by determining which percentage of the time the system is running
a process and which percentage of the time the system is not.
In a typical system, most of the time there is just nothing to do.
Most processes will be blocked waiting for
something to happen (e.g., inside a
.CW read
waiting for the data to arrive). However, from time to time, there will be some processes
with a high demand of CPU time, like for example, a compiler trying to compile a program,
and the system load will increase because there's now some process that is often
.ix "CPU time
.ix "[Ready]
.ix "[Running]
.ix "process state
ready to run, or
running.
.PP
We can use the
.CW stats
.ix [stats]
.ix "system statistics
tool to display the system load.
This tool shows a graphic depicting the system load and other statistics. For example,
both figures [[!intensive polling!]]
and [[!sleeps between polls!]] show a window
running
.CW stats .
Figure [[!intensive polling!]] shows the system load for our first experiment regarding
polling. It is hard to see in a book, but the graph displayed by
.CW stats
is always scrolling from right to left as time goes by. Around the middle of the graph
it can be seen how the load increased sharply, and went to a situation where almost
always there was something to do. The system started to be heavily loaded.
This was the result of executing the following.
.P1
; 8.poll poll.c
\fI"...and the machine got very busy until we hit Delete\fP
\fBDelete\fP
;
.P2
.LS
.BP statspoll2.ps 1.3i
.LE F A window running \f(CWstats\fP while the intensive polling program increased the load.
.LP
The process
.CW 8.poll
was
.I always
polling for a change on its file. Therefore, there was always something to do.
.ix polling
Despite being run on a very fast machine,
.CW 8.poll
never ceased to poll. When the system decided that
.CW 8.poll
got enough processor time, and switched to execute any other process,
our polling process ceased to poll for a tiny fraction of time. Later on, it will
be put again in the processor and consume all the time given to it by the system.
When all processes are blocked waiting for something to happen,
.CW 8.poll
is still very likely to be ready to run. As a result, the system load is at its maximum.
Later, we pressed
.I delete
and killed
.CW 8.poll ,
and the system load came back to a more reasonable value.
.PP
Note that a high load does
.I not
mean that the system is unresponsive, i.e., that it cannot cope with any more work
to do. It just means that there is always something to do. Of course, given the
sufficient amount of things to do, the system will become unresponsive because
no process will be given enough processor time to complete soon enough. But
that does not need to be the case if the load is high.
.LS
.BP statspoll.ps 1.3i
.LE F The system load is not altered if the program sleeps between polls.
.PP
Compare what you saw with the load while executing our second version for
the polling program, which calls
.CW sleep
to perform one poll each 5 seconds. The window running
.CW stats
while we executed this program is shown in figure [[!sleeps between polls!]].
This program behaved nicely and did not alter much the system load. Most of the
time it was sleeping waiting for the time for its next poll. As an aside, it is
interesting to say that Plan 9 typically
exhibits a much lower system load than both figures show. The system used to capture
both images is a derivative of Plan 9, called Plan B, which uses polling for many things.
When there are many processes polling, the load naturally increases even if the
processes sleep between polls.
.PP
The
.CW sleep
.ix [sleep]
used by programs that poll introduces another problem: delays.
If the event does occurs and the polling program is
sleeping, it will not take an appropriate action until the
.CW sleep
completes. And this is a delay. If the process waiting for the event produces, as
a result, another event, the delay of any other process polling for the later event
is added to the chain.
.PP
The consequence of what we have discussed so far
is that most operating systems provide an abstraction to deliver events and
.ix event
to wait for them. The abstraction is usually called an
.B "event channel" ,
and is used to convey events from the ones that produce them to the ones that
await for them.
.PP
An event is a particular data structure, that contains the information about
the success it represents. This means that events can be used as a
communication means between the processes that produce them and the ones
that consume them.
.PP
In Plan 9, there is a service called
.B plumbing
.ix [plumber]
.ix "plumb message
.ix pipe
that provides a message delivery service. The name of the program is
.CW plumber
because it is meant to do the plumbing to convey data from message
producers to consumers. In effect, it provides a nice event delivery service.
The plumber is built upon the assumption that once you look at a particular
piece of data it is clear what to do with it. For example, if a message looks like
.CW http://lsub.org/ ...
then it is clear that it should probably be delivered to a web browser. If a message
looks like
.CW pnote.c:15 ,
then it is likely that it should be delivered to an editor, to open that file and show
the line after the colon.
.PP
Like many other programs, the plumber is used through a file interface. The files
that make up the interface for the plumber are usually available at
.ix "[/mnt/plumb] file system
.CW /mnt/plumb.
.P1
; lc /mnt/plumb
edit msntalk rules showmail
exec msword seemail song
image none send voice
man postscript sendmail www
.P2
.LP
Each one of these files (but for
.CW rules
.ix "plumber [rules]
and
.CW send )
.ix "plumber [send]
.ix "plumber port
is called a
.B port ,
and can be used to dispatch messages to applications reading from them.
The
.CW send
file is used to send a message to the plumber, which will choose an
appropriate port for it and then deliver the message to any process reading
from it.
.LS
.PS 5i
.ps -1
circlerad=.4
.R
right
S: [ down
circle "sender" "process"
arrow
P: box "\f(CWsend\fP"
]
move
[ down
circle "editor"
arrow <-
box "\f(CWedit\fP"
]
move
W: [ down
circle "web" "browser"
arrow <-
P: box "\f(CWwww\fP"
]
move
[ down
[ right; I1: circle "image" "viewer" ; move ; I2: circle "image" "viewer" ]
move
box "\f(CWimage\fP"
arrow <- from last [].I1.se to last box.n
arrow <- from last [].I2.sw to last box.n
]
spline from S.P.s down then right
line right 1.4 "\f(CWhttp://lsub.org/\fP" "message delivered by the plumber"
spline -> right 1 then to W.P.s
reset
.ps +1
.PE
.LE F The plumber provides ports, used to deliver messages to applications.
.PP
For example, figure [[!plumber ports!]] shows what would happen when
a process writes to the
.CW send
port a message carrying the data \f(CWhttp://lsub.org/\fP. Because the data looks like
something for a
.CW www
port, the plumber delivers the message to any process reading from that port.
If more than one process is reading from the port (as shown in the figure for
images), the message is delivered to
.ix "message delivering
.I all
of them.
.PP
Even if you didn't notice, you have been using the plumber a lot. Every time you click
.ix "[acme] plumbing
.ix "mouse button-3
with the mouse button-3 at something in Acme, the editor sends a message to the
plumber with the text where you did click. Most of the times, the plumber
determines that the message is for processes reading the port
.CW edit ,
.ix "[edit] plumb~port
i.e., editors. Thus, the message is conveyed back to Acme in many cases.
You may try it by hand. If you have an Acme running and you execute
.P1
; plumb /NOTICE
;
.P2
.LP
on a shell, the file
.CW /NOTICE
will show up in your editor. The plumber even knows that if there's no editor
reading from the
.CW edit
port, an editor should be started. You can try by executing again the
.CW plumb
command above, but this time, while no editor is running.
.PP
How does the plumber know what to do? The file
.CW $home/lib/plumbing
is read by the plumber when it starts (usually from your
.CW $home/lib/profile
.ix [profile]
.ix [plumbing]
while entering the system). This file has rules that instruct the plumber
to which port should each message be sent according to the message data.
Furthermore, the file may instruct the plumber to start a particular application
(e.g., an editor) when no one is listening at a given port. After the plumber
has been started, its rules can be updated by copying whatever rules are
necessary to the
.CW /mnt/plumb/rules
file.
.PP
It is still too early for us to inspect this file, because it uses
.I "regular expressions" ,
.ix "regular expression
that are yet to be discussed. However, it is useful to know that by default
certain messages are processed in a particular way:
.IP •
Files with particular formats, like MS Word files, are delivered usually to
the program
.CW page ,
.ix [page]
.ix "document viewer
.ix "MS~Word viewer
.ix "PostScript viewer
which converts them to postscript and shows their contents on a window.
.IP •
Most other files go to the editor. Optionally, there may be a
.CW :
followed by an
.ix "file address
.I address
after the file name, to instruct the editor to go to a particular piece of text
in the file. For example,
.CW /NOTICE:2
would make an editor show line 2 of
.CW /NOTICE .
There are other types of addresses, besides line numbers.
A very useful one is of the form
.CW /text .
That is, some text after a
.CW / ,
like in
.CW /NOTICE:/cent .
This causes the editor to
.ix "text search
.I search
for the text (for
.CW cent
in this case). The text that you type is actually a regular expression, and not
just a string. This is a more powerful mechanism to search for things, that
will be seen in a later chapter.
.IP •
Mail addresses get a new window running the
.CW mail
program.
.IP •
A file name ending in
.CW .h
is looked for at
.CW /sys/include ,
.ix [/sys/include]
and then passed to the editor. For example, a plumb of
.CW libc.h
would open
.CW /sys/include/libc.h
.IP •
A name for a manual page, like
.CW ls(1)
.ix "manual page
causes the editor to display the formatted manual page. Very convenient when
using acme. Type the manual page, and click with the button-3 on it.
.LP
We went this far, but we still do not know what a plumber message is.
A plumber message does not only carry data. Along with the data, there is some
metadata that supplies additional information about the data. Thus, each message
has a set of attributes and their values, besides the data.
.ix "plumb message attributes
Some
attributes are always present in a message (although their values might be empty).
Other attributes are used by programs using a particular kind of message, and
there can be any number of them. You may also invent any attribute that you need
if you use plumber messages for a particular thing. These are the standard
attributes for a message:
.IP
.B src
A string that names the source for the message, usually a program name.
.IP
.B dst
A string that names the destination port for the message. If it is not supplied,
the plumber tries to choose using the
.CW rules
file.
.IP
.B wdir
The working directory used by a process that is sending a message carrying a
file name. This is necessary to let the receipt of the message determine to which
file the message refers to. Note that a file name may be a relative path, and you
need to know with respect which (current working) directory it is relative to.
.IP
.B type
A string describing the type of data. Most of the times the type is just
.CW text ,
which is later, perhaps, interpreted as a file name or as the name for a manual
page.
.IP
.B ndata
Number of bytes in the data for the message.
.LP
How can you use the plumber? From the shell, the
.CW plumb
.ix "[plumb] command
.ix "[plumb] library
program lets you send messages, as you saw. From a C program, there is
a library called
.I plumb (2)
that provides an interface for using the plumber. The following program
listens for plumb messages sent to the
.CW edit
port, and prints the file name for each such message.
.so progs/edits.c.ms
.ix [edits.c]
.LP
The function
.CW plumbopen
.ix [plumbopen]
.ix "plumb~port open
opens the plumb port given as its first parameter (using the open mode indicated
by the second one). It returns an open file descriptor where we can read or write
plumb messages. In this case, we open the
.CW edit
port. The function opens
.CW /mnt/plumb/edit
if we do not supply a path for the file name. To receive a message, the program calls
.CW plumbrecv ,
.ix [plumbrecv]
.ix "plumb message receive
which blocks reading from the port until the plumber supplies the data from the message.
This function may have to read several times, until an entire message has been read.
It returns a pointer to the message read, which has this data structure:
.ix [Plumbattr]
.ix [Plumbmsg]
.ix "plumb message attribute
.P1
typedef struct Plumbattr Plumbattr;
typedef struct Plumbmsg Plumbmsg;
struct Plumbmsg
{
char *src;
char *dst;
char *wdir;
char *type;
Plumbattr *attr; // list of attributes
int ndata;
char *data;
};
struct Plumbattr
{
char *name;
char *value;
Plumbattr *next;
};
.P2
.LP
The program looks in the attribute list for the message, pointed to by the
.CW attr
field, for an attribute named
.CW addr ,
which is the address following the file name in the plumbed message.
To do so, it calls
.CW plumblookup ,
giving the
.CW attr
list and the name of the desired attribute. The working directory for the message,
the data, and the address attribute's value are printed next. At last, the
message data structure is deallocated by a call to
.CW plumbfree .
.PP
We can deliver messages to
our program by doing clicks on Acme, with the mouse button 3, and
also by running
.CW plumb
from the shell like we do below.
.ix [plumb]
.P1
; plumb /NOTICE:2
; plumb edits.c
; plumb /sys/doc/9/9.ps
; plumb edits.c:/main
;
.P2
.LP
The corresponding output for our program, which we did run at a different window,
follows. Note how the message for
.CW 9.ps
was not sent to the
.CW edit
port, and therefore is not received by our program. It was sent to a different
program,
.CW page ,
to display the postscript file.
.P1
.ps -2
; 8.edits
msg: wdir='/usr/nemo/9intro' data='/NOTICE' addr='2'
msg: wdir='/usr/nemo/9intro' data='/usr/nemo/9intro/edits.c' addr=''
msg: wdir='/usr/nemo/9intro' data='/usr/nemo/9intro/edits.c' addr='/main'
.ps +2
.P2
.LP
One last question. Which format is used to actually write and read messages
from the file that is the plumb port? Is it a esoteric format? No. It is simply a set
of lines with the source application, destination port, working directory, message
type, message attributes, and number of bytes of data, followed by the indicated
number of bytes carrying the data. This is easy to see by using
.CW cat
to read from the edit port while executing the same
.CW plumb
commands used above.
.P1
; cat /mnt/plumb/edit
plumb
edit
/usr/nemo/9intro
text
addr=2
7
/NOTICE \fINew line supplied by us\fP
plumb
edit
/usr/nemo/9intro
text
addr=
24
/usr/nemo/9intro/edits.c \fINew line supplied by us\fP
plumb
edit
/usr/nemo/9intro
text
addr=/main
24
/usr/nemo/9intro/edits.c \fINew line supplied by us\fP
\fBDelete\fP
;
.P2
.LP
Sending a plumb message is very simple, given the helper routines in
.I plumb (2).
The routine
.CW plumbsend
.ix [plumbsend]
sends a message as described by a
.CW Plumbmsg
structure. The routine
.CW plumbsendtext
.ix [plumbsendtext]
is a even more simple version, for those cases when the message is just a
text string.
.P1
.ps -2
; sig plumbsend plumbsendtext
int plumbsend(int fd, Plumbmsg *m)
int plumbsendtext(int , char *, char *, char *, char *)
.ps +2
.P2
.LP
For example, this would send a message with the text
.CW /NOTICE .
.P1
.ps -2
int fd;
fd = plumbopen("send", OWRITE);
if (fd < 0)
sysfatal("open: %r");
if (plumbsendtext(fd, argv0, nil, nil, "/NOTICE") < 0)
sysfatal("send: %r");
.ps +2
.P2
.LP
A similar effect can be achieved by initializing and sending a
.CW Plumbmsg
as follows.
.P1
.ps -2
Plumbmsg m;
int fd;
fd = plumbopen("send", OWRITE);
if (fd < 0)
sysfatal("open: %r");
m.src = m.dst = m.wdir = nil;
m.type = "text";
m.attr = nil;
m.data = "/NOTICE";
m.ndata = strlen(m.data);
if (plumbsend(fd, &m) < 0)
sysfatal("send: %r");
.ps +2
.P2
.SH
Problems
.IP 1
What would this command do?
.P1
cp /fd/1 /fd/0
.P2
.IP 2
Why do you think that the code to initialize standard input, output, and
error in the first process differs from this?
.P1
open("/dev/cons, ORDWR);
dup(0, 1);
dup(0, 2);
.P2
.IP 3
The code
.P1
fd = open("/NOTICE", OREAD);
dup(fd, 0);
close(fd);
.P2
.IP
may fail and leave standard input closed. When does this happen?
Why do you think this code was used for a program that redirected
standard input to
.CW /notice ?
.IP 4
Show that a process that reads from an empty pipe gets blocked and
will never run. Which state is reported by
.CW ps
for such process?
.IP 5
Modify the code for the
.CW srvecho
program to perform the echo through the pipe, and not to the
console. Use the program
.I con (1)
to connect to the pipe through
.CW /srv/echo
and test that it works.
.ds CH
.bp
\c