1 .TH INTRO 4
2 .SH NAME
3 intro \- introduction to file servers
4 .SH DESCRIPTION
5 A Plan 9
6 .I "file server"
7 provides a file tree to processes.
8 This section of the manual describes servers that can be
9 mounted in a name space to give a file-like interface to interesting services.
10 A file server may be a provider of a conventional file system,
11 with files maintained on permanent storage,
12 or it may also be a process that synthesizes files in some manner.
13 .PP
14 In Plan 9, the kernel mount device
15 \fImnt\fR(3)
16 acts as a client to the 9P servers mounted in the current name space,
17 translating system calls such as
18 .MR open (2)
19 into 9P transactions such as
20 .IR open (9p).
21 The kernel also multiplexes the potentially many processes onto a single 9P conversation
22 with each server.
23 Finally, the kernel provides each process with its own private
24 .I name space
25 which it can customize at will.
26 Modern Unix systems do not provide these niceties, so 
27 the Unix port of these Plan 9 file servers provides them via other means.
28 .PP
29 On Unix, 9P clients do not access servers via the traditional
30 file system call interface.  Only the Unix name space can be accessed
31 that way.
32 Instead, 9P clients use the
33 .MR 9pclient (3)
34 library to connect and interact directly with particular 9P servers.
35 The
36 .MR 9p (1)
37 command-line client is useful for interactive use and in shell scripts.
38 .PP
39 To preserve the façade of a single 9P conversation with each server,
40 9P servers invoke
41 .MR 9pserve (4) ,
42 typically via
43 .MR post9pservice (3) .
44 .I 9pserve
45 announces a 9P service at a particular
46 network address and multiplexes the clients that connect to
47 that address onto a single 9P conversation with the server.
48 .PP
49 Each ported program operates in a pseudo-name space
50 that determines which 9P servers it is using.
51 The name space of a ported program is represented by a 
52 directory containing Unix domain sockets, one for each 9P server.
53 The directory defaults to
54 .BR /tmp/ns.$USER.$DISPLAY ,
55 meaning that all programs in an X Windows login session 
56 share a single name space.
57 Setting the
58 .B $NAMESPACE
59 environment variable overrides this default.
60 The
61 .MR namespace (1)
62 command prints the current name space directory.
63 .PP
64 Occasionally it is useful to be able to connect the input or output
65 of a standard Unix program to a file served by a 9P server.
66 The new
67 .IR openfd (9p)
68 9P transaction, which depends on file descriptor passing,
69 provides a sufficient workaround in many cases. 
70 .IR 9pserve 's
71 implementation of
72 .I openfd
73 (see also
74 .I fsopenfd
75 in
76 .MR 9pclient (3) )
77 returns the read or write end of a pipe;
78 a helper process transfers data between the other end of the pipe
79 and the 9P server.
80 Note that since the data is being transferred via a pipe,
81 9P read and write errors cannot be passed on to the Unix program.
82 The Unix program sees only end-of-file or a closed pipe.