aboutsummaryrefslogtreecommitdiff
path: root/man/man9/attach.9p
blob: 3a5104d5da241b44e7825d982efc23507fa7d94c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
.TH ATTACH 9P 
.SH NAME
attach, auth \- messages to establish a connection
.SH SYNOPSIS
.ta \w'\fLTauth 'u
.IR size [4]
.B Tauth
.IR tag [2]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.IR size [4]
.B Rauth
.IR tag [2]
.IR aqid [13]
.PP
.IR size [4]
.B Tattach
.IR tag [2]
.IR fid [4]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.IR size [4]
.B Rattach
.IR tag [2]
.IR qid [13]
.SH DESCRIPTION
.PP
The
.B attach
message serves as a fresh introduction from a user on
the client machine to the server.
The message identifies the user
.RI ( uname )
and may select
the file tree to access
.RI ( aname ).
The
.I afid
argument specifies a fid previously established by an
.B auth
message, as described below.
.PP
As a result of the
.B attach
transaction, the client will have a connection to the root
directory of the desired file tree,
represented by
.IR fid .
An error is returned if
.I fid
is already in use.
The server's idea of the root of the file tree is represented by the returned
.IR qid .
.PP
If the client does not wish to authenticate the connection, or knows that
authentication is not required, the
.I afid
field in the
.B attach
message should be set to
.BR NOFID ,
defined as
.B (u32int)~0
in
.BR <fcall.h> .
If the client does wish to authenticate, it must acquire and validate an
.I afid
using an
.B auth
message before doing the
.BR attach .
.PP
The
.B auth
message contains
.IR afid ,
a new fid to be established for authentication, and the
.I uname
and
.I aname
that will be those of the following
.B attach
message.
If the server does not require authentication, it returns
.B Rerror
to the
.B Tauth
message.
.PP
If the server does require authentication, it returns
.I aqid
defining a file of type
.B QTAUTH
(see
.IR intro (9P))
that may be read and written (using
.B read
and
.B write
messages in the usual way) to execute an authentication protocol.
That protocol's definition is not part of 9P itself.
.PP
Once the protocol is complete, the same
.I afid
is presented in the
.B attach
message for the user, granting entry.
The same validated
.I afid
may be used for multiple
.B attach
messages with the same
.I uname
and
.IR aname .
.SH ENTRY POINTS
.I Fsmount
and
.I fsauth
(see
.IM 9pclient (3) )
generate
.B attach
and
.B auth
transactions.
.\" An
.\" .B attach
.\" transaction will be generated for kernel devices
.\" (see
.\" .IR intro (3))
.\" when a system call evaluates a file name
.\" beginning with
.\" .LR # .
.\" .IR Pipe (2)
.\" generates an attach on the kernel device
.\" .IR pipe (3).
.\" The
.\" .I mount
.\" system call
.\" (see
.\" .IR bind (2))
.\" generates an
.\" .B attach
.\" message to the remote file server.
.\" When the kernel boots, an
.\" .I attach
.\" is made to the root device,
.\" .IR root (3),
.\" and then an
.\" .B attach
.\" is made to the requested file server machine.
.\" .PP
.\" An
.\" .B auth
.\" transaction is generated by the
.\" .IR fauth (2)
.\" system call or by the first
.\" .B mount
.\" system call on an uninitialized connection.
.SH SEE ALSO
.IM 9pclient (3) ,
.IR version (9P),
Plan 9's \fIauthsrv\fR(6)