💾 Archived View for kamid.omarpolo.com › 9p.7.txt captured on 2024-05-12 at 14:57:43.

View Raw

More Information

⬅️ Previous capture (2023-01-29)

-=-=-=-=-=-=-

9P(7)		 Miscellaneous Information Manual	    9P(7)

NAME
     9P	 Simple Distributed File System

DESCRIPTION
     9P is a protocol that implements a distributed file systems.
     It provides primitives to manage (create, read, write and
     delete) sets of files remotely.  These files don't
     necessarily need to be actually stored on a disk, they may
     be, for example, synthesise on demand from external sources.

     A client transmits requests (T-messages) to a server, which
     returns replies (R-messages) to the client.  The combined
     acts of transmitting a request of a particular type and
     receiving a reply is called a transaction of that type.

     Each message consists of a sequence of bytes mostly grouped
     in one, two or four integer fields transmitted in little-
     endian order (least significant byte first).  Data items of
     larger or variable lengths are represented by a two-byte
     field specifying the length followed by the actual data.
     The only exception to this rule are QIDs, thirteen byte long
     objects, that are sent as-is.

     Text strings are represented with a two-byte count and the
     sequence of UNICODE codepoints encoded in UTF-8.  Text
     strings in 9p are not NUL-terminated.  The NUL-terminator is
     illegal in all text strings and thus excluded from paths,
     user names and so on.

     Fields are hereafter denoted as

	   type[1] tag[2] fid[4]

     to indicate that type is one byte long, tag two and fid
     four.  Strings are denoted as name[s] and are sent on the
     wire as

	   length[2] string[length]

     A qid, described later, is a 13-byte value that is sent on
     the wire as

	   type[1] version[4] path[8]

MESSAGE STRUCTURE
     Every message has a header with the following fields:

	   len[4] type[1] tag[2]

     where len indicates the overall length of the message,
     including itself; type is one byte indicating the type of
     the message and the tag is a number choosen by the client
     that indicate uniquely the request.  Then follows an
     optional body whose structure depends on the type of the
     message.

     The message types are as follows: (the header is omitted for
     brevity)

     version	Negotiate the version and maximum message size.

		msize[4] version[s]
		msize[4] version[s]

		The version request must be the first message
		sent, and the client cannot issue further
		requests until receiving the Rversion reply.  tag
		should be NOTAG (-1 or 255).  The client suggest
		a msize (the maximum size for packets) and the
		protocol version used, the server replies with a
		msize smaller or equal to the one proposed by the
		client.	 The version string must always begin
		with the two character 9P.  If the server don't
		understand the client required version, should
		reply with a Rversion using the version string
		unknown and not use a Rerror.

     attach	Populate the namespace

		fid[4] afid[4] uname[s] aname[s]
		qid[13]

		The attach message binds the given fid to the
		root of the file tree identified by aname.  uname
		identifies the user and afid specifies a fid
		previously established by an auth message, or the
		special NOFID value (defined as (u32int_t)~0) if
		the authentication is not required.

     clunk	Close fids.

		fid[4]
		empty response

		Once a fid has been clunked (closed) it becomes
		free and the same value can be used for
		subsequential walk or attach requests.

		The actual file on the disk is not removed unless
		it was opened with the ORCLOSE flag.

     error	Return an error string.

		no request
		ename[s]

		The Rerror message is used to return an error
		string describing the failure of a request.  The
		tag indicates the failed request.

		Note that there isn't a Terror request for
		obvious reason and it's not possible for a server
		to reply to a Tversion or Tflush using Rerror.

     flush	Abort an ongoing operation.

		oldtag[2]
		empty response

		Given the asynchronous nature of the protocol,
		the server may respond to the pending request
		before responding to the Tflush and is possible
		for a client to send multiple Tflush for the same
		operation.  The client must wait to receive a
		corresponding Rflush before reusing oldtag for
		subsequent messages.

		If a response for oldtag is received before the
		Rflush reply, the client must assume that the
		operation was completed with success (fid
		allocated, files created, ...) If no response is
		received before the Rflush then the transaction
		is considered to have been successfully
		cancelled.

		Note that the tag of this request and the
		corresponding reply is NOT oldtag but a new tag
		value.

     walk	Traverse a file tree.

		fid[4] newfid[4] nwname[2] nwname*(wname[s])
		nwqid[2] nwqid*(qid[13])

		The nwname components are walked in order
		starting from fid (which must point to a
		directory) and, if successful, newfid is
		associated to the reached file.

		It is possible for fid and newfid to be equal, in
		this case the fid is mutated, otherwise newfid
		must be unused.	 As a special case, a walk of
		zero components duplicates the fid.

		If the first element cannot be walked for any
		reason an Rerror is returned.  Otherwise, Rwalk
		is returned with a number of qids equal to the
		file viside by the walk.  A client can thus
		detect a walk when that the replied nwqid number
		is not equal to the nwname field in the request.
		Only when walk return successfully newfid will be
		affected.

		A maximum of 16 component can be used per walk
		request.

     open	Prepare a fid for I/O.

		fid[4] mode[1]
		qid[13] iounit[4]

		mode determines the type of I/O:
		      0x00 (OREAD)
			      Open the file for reading.
		      0x01 (OWRITE)
			      Open the file for writing.
		      0x02 (ORDWD)
			      Open the file for both reading and
			      writing.
		      0x03 (OEXEC)
			      Open for exec.

		Additionally, the following flags can be or'ed to
		mode:
		      0x10 (OTRUNC)
			      Truncate the file before opening
		      0x40 (ORCLOSE)
			      Remove the file upon clunk.

		The returned iounit is the optimal blocksize for
		I/O.

     create	Create a file

		fid[4] name[s] perm[4] mode[1]
		qid[13] iounit[4]

		The call attempts to create a file named name in
		the directory identified by fid according to perm
		and then to open it with mode into the given fid.

		It is illegal to use an already opened fid or to
		attempt to create the . or .. entries.

     read	Read data at offset

		fid[4] offset[8] count[4]
		count[4] data[count]

		fid must have been prepared for I/O with a
		previous open call.  The returned count is zero
		when reaching end-of-file and may be lesser than
		what requested.

		Directories are a stream of stat structures, as
		described in stat, and for them the read request
		message must have offset equal to zero or the
		value of offset in the previous read on the
		directory plus the number of bytes returned in
		the previous read.  Thus, is not possible to seek
		into directories except for rewinding.

     write	Write data at offset

		fid[4] offset[8] count[4] data[count]
		count[4]

		fid must have been prepared for I/O with a
		previous open or create call.  The returned count
		is the amount of data actually written and may
		differ from the one in the request.

     stat	Get file status

		fid[4]
		stat[n]

		The stat structure is made by the following
		fields:
		size[2]	    total byte count of the following
			    data
		type[2]	    for kernel use
		dev[4]	    for kernel use
		qid[13]	    server unique identifier of the file
		mode[4]	    permissions and flags
		atime[4]    last access time
		mtime[4]    last modification time
		length[8]   length of file in bytes
		name[s]	    file name (must be / if the file is
			    the root directory of the server)
		uid[s]	    owner name
		gid[s]	    group name
		muid[s]	    name of the user who last modified
			    the file.

		Note that the size is always present, even in the
		wstat call.  While it may be considered
		redundant, it's kept to simplify the parsing of
		the stat entries in a directory.

     wstat	Change file attributes

		fid[4] stat[n]
		empty response

		fid must have been prepared for writing with a
		previous open or create call.

		The stat structure is the same described in stat.

		The stat structure sent reflect what changes the
		client wishes to make to the given fid.	 To leave
		some fields as unchanged, use empty string or the
		maximum allowed value for integral fields.  For
		example, to avoid changing the permission of the
		fid use 0xFFFFFFFF, or (uint32_t)-1.

     remove	Remove and clunk fid

		fid[4]
		empty response

		After a remove call, even if an error is
		returned, the fid is closed.

SEE ALSO
     utf8(7), kamid(8)

OpenBSD 7.2		  July 30, 2021		      OpenBSD 7.2