README
¶
go9p
This is a golang implementation of the 9p2000 protocol. Provided is foremost an API to implement servers serving the protocol, but also some more primitive constructs if you'd like to dink with the protocol outside the confines of what the API provides.
Examples are available in examples/ (duh)
Docs available here: http://godoc.org/github.com/knusbaum/go9p
These programs are meant to be used with plan9port's 9pfuse (or some equivalent) https://github.com/9fans/plan9port
For example, you would mount the ramfs example with the following command:
9pfuse localhost:9999 /mnt/myramfs
Then you can copy files to/from the ramfs and do all the other stuff that you'd expect.
This is distributed under the MIT license
Copyright (c) 2016 Kyle Nusbaum
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Documentation
¶
Overview ¶
Package go9p is a Go implementation of the 9P2000 protocol. It imlements a parser and composer for 9P2000 messages as well as a server (See the Server type).
The server requires users to implement callbacks for certain operations. Open, Read, Write, Create, and Setup. See the docs for the *context structs for explanations of how to appropriately respond to these events.
IFCall, FCall, and all the T* and R* types are internal types used for parsing, etc. They're left exposed if you want to do some less structured 9P programming.
Details of the 9P2000 protocol can be found here: http://knusbaum.inlisp.org/res/rfc9p2000.html
Index ¶
- Constants
- func SliceForRead(ctx *ReadContext, file []byte) []byte
- type AuthContext
- type Client
- func (cli *Client) Connect(rw io.ReadWriter) error
- func (cli *Client) Create(path string, fmode uint32, omode Mode) (*File9P, error)
- func (cli *Client) ListDir(path string) ([]Stat, error)
- func (cli *Client) Open(path string, omode Mode) (*File9P, error)
- func (cli *Client) Stat(path string) (*Stat, error)
- type CreateContext
- type Ctx
- type DirReadContext
- type FCall
- type File
- type File9P
- type IFCall
- type Mode
- type OpenContext
- type ParseError
- type Qid
- type RAttach
- type RAuth
- type RClunk
- type RCreate
- type RError
- type RFlush
- type ROpen
- type RRead
- type RRemove
- type RStat
- type RWalk
- type RWrite
- type RWstat
- type ReadContext
- type RemoveContext
- type Server
- type Stat
- type TAttach
- type TAuth
- type TClunk
- type TCreate
- type TFlush
- type TOpen
- type TRVersion
- type TRead
- type TRemove
- type TStat
- type TWalk
- type TWrite
- type TWstat
- type UpdateContext
- type WriteContext
Constants ¶
const ( Oread = 0 Owrite = 1 Ordwr = 2 Oexec = 3 None = 4 Otrunc = 0x10 )
Open mode file constants
const ( Tversion = 100 Rversion = 101 Tauth = 102 Rauth = 103 Tattach = 104 Rattach = 105 Terror = 106 /* illegal */ Rerror = 107 Tflush = 108 Rflush = 109 Twalk = 110 Rwalk = 111 Topen = 112 Ropen = 113 Tcreate = 114 Rcreate = 115 Tread = 116 Rread = 117 Twrite = 118 Rwrite = 119 Tclunk = 120 Rclunk = 121 Tremove = 122 Rremove = 123 Tstat = 124 Rstat = 125 Twstat = 126 Rwstat = 127 )
Variables ¶
This section is empty.
Functions ¶
func SliceForRead ¶
func SliceForRead(ctx *ReadContext, file []byte) []byte
SliceForRead - Given a read context and a slice representing the full file contents, return a slice at offset ctx.Offset of ctx.Count bytes. Handles cases where file is nil, offset + count > len(file), etc. The return value is ready to be passed to ctx.Respond.
Types ¶
type AuthContext ¶
type AuthContext struct {
Ctx
}
AuthContext - The context given to the user's authentication functions
func (*AuthContext) SetAuthenticated ¶
func (ctx *AuthContext) SetAuthenticated(b bool)
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
type CreateContext ¶
CreateContext - The context passed to the Create callback in Server. NewPath - the full path of the new file (including Name) Name - the name of the new file. Perm - the permissions of the file. Lower 9 bits are Unix-style permissions (user/group/other rwxrwxrwx). The high bit (1 << 31) is the directory flag.
func (*CreateContext) Respond ¶
func (ctx *CreateContext) Respond(length uint64) *File
Respond - Creates the file requested and sets the length. Returns the new file.
type Ctx ¶
Ctx is the base context. All other contexts embed this type and therefore inherit the Fail() and UpdateFS() functions.
Fid is the file descriptor on which the request is operating. File is the file associated with the request. For Setup, File is the root directory, and for Create, it's the directory in which the client is trying to create a file. For Open, Read, and Write, File is the file to be opened, read, or written.
func (*Ctx) Fail ¶
Fail - Call this on the context when a request can't be fulfilled. The string is passed to the client as an explanation of the failure that occurred.
func (*Ctx) FileByPath ¶
func (*Ctx) UniqueFileID ¶
Returns an ID unique to a particular connection and file. Different connections can use the same Fids, so this is a way of tracking a particular connection/file pair.
func (*Ctx) UpdateFS ¶
func (ctx *Ctx) UpdateFS(fn func(*UpdateContext))
UpdateFS runs the argument function, passing it an update context so that it can make modifications to the filesystem. fn is not run immediately, but passed to the main routine. This removes the need for synchronization. You can be sure that only one routine is modifying the filesystem structure at any one time.
type DirReadContext ¶
type DirReadContext struct {
Ctx
// contains filtered or unexported fields
}
func (*DirReadContext) Respond ¶
func (ctx *DirReadContext) Respond()
Respond - Marks the directory ready for read by the client.
type FCall ¶
FCall - The base FCall type. All FCall-like types embed this and inherit its functions. For explanations of the functions, see IFCall.
type File ¶
File - Represents a file in the filesystem. Path - The full path of the file in the filesystem. Stat - The Stat struct associated with the file. Parent - A pointer to the file's parent directory.
func (*File) IsDirectory ¶
func (*File) ListSubfiles ¶
type IFCall ¶
type IFCall interface {
String() string
Parse([]byte) ([]byte, error)
Compose() []byte
GetFCall() *FCall
Reply(*filesystem, *connection, *Server) IFCall
}
IFCall - the interface that all FCall-like types imlement. String - typical human readable string representation. Parse - Parse the call from a slice. Compose - returns a slice containing the call serialized according the the 9P2000 protocol, ready to be written out to a client. GetFCall() - get the base FCall associated with this call. Reply() - Handles the fcall and calls appropriate functions in Server. Returns nil or an IFCall that should be sent as a response back to the client.
type OpenContext ¶
OpenContext - The context passed to the Open callback in Server. Mode is the requested open mode for the file. Mode can be ignored unless you want to do some special logic. The server handles the common case - it won't call Write on a file not opened for writing, etc.
func (*OpenContext) Respond ¶
func (ctx *OpenContext) Respond()
Respond - Tells the client the open operation was successful.
type ParseError ¶
type ParseError struct {
Err string
}
func (*ParseError) Error ¶
func (pe *ParseError) Error() string
type Qid ¶
Qid - Qids are unique ids for files. Qtype should be the upper 8 bits of the file's permissions (Stat.Mode)
func (*Qid) Compose ¶
Compose - Returns a slice of the Qid serialized to be written out on a 9P2000 stream.
type ReadContext ¶
ReadContext - The context passed to the Read callback in Server. Offset is the offset into the file that is requested Count is the number of bytes requested.
func (*ReadContext) Respond ¶
func (ctx *ReadContext) Respond(data []byte)
Respond - Sends requested data back to the client.
type RemoveContext ¶
type RemoveContext struct {
Ctx
}
RemoveContext - The context passed to the Create callback in Server.
type Server ¶
type Server struct {
Open func(ctx *OpenContext)
Read func(ctx *ReadContext)
DirRead func(ctx *DirReadContext) // CANNOT SPAWN GOROUTINES USING UPDATE CONTEXT!
Write func(ctx *WriteContext)
Close func(ctx *Ctx)
Create func(ctx *CreateContext)
Remove func(ctx *RemoveContext)
Setup func(ctx *UpdateContext)
Auth func(ctx *AuthContext, in <-chan []byte, out chan<- []byte) // Run in a separate goroutine
// contains filtered or unexported fields
}
Server struct contains functions which are called on file open, read, write, and create See the definitions of the various context types. All "inherit" Ctx and so the Fail() and AddFile() functions. Each implements a Respond() function. The parameters and behavior of each changes among the contexts
Setup is called once the server is up and running, and is the appropriate place to add any initial files to the server.
type Stat ¶
type Stat struct {
Stype uint16
Dev uint32
Qid Qid
Mode uint32
Atime uint32
Mtime uint32
Length uint64
Name string
Uid string
Gid string
Muid string
}
func (*Stat) ComposeLength ¶
type UpdateContext ¶
type UpdateContext struct {
Ctx
}
UpdateContext is the context given to functions passed to UpdateFS. UpdateContext has functions that allow a user to modify the filesystem, adding, removing files, etc.
func (*UpdateContext) AddFile ¶
func (ctx *UpdateContext) AddFile(mode uint32, length uint64, name string, owner string, parent *File) *File
AddFile - Use this function to add a file to the server. mode - The mode for the new file length - The length of the new file name - The file's name (not the full path) owner - The owner of the new file parent - The directory that the file will be created under. This function returns a pointer to the newly created file.
func (*UpdateContext) RemoveFile ¶
func (ctx *UpdateContext) RemoveFile(f *File)
RemoveFile - Remove a file from the filesystem.
type WriteContext ¶
WriteContext - The context passed to the Write callback in Server. Data - the data from the client that they want to write to the file Offset - the offset within the file that the data is to be written at Count - the number of bytes to be written. (this should correspond with len(Data)
func (*WriteContext) Respond ¶
func (ctx *WriteContext) Respond(count uint32)
Respond - Tells the client the number of bytes that were successfully written. This should be identical to Writecontext.Count. The client might consider it to be an error if the bytes written differs from the requested amount.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
ramfs
A memory-backed filesystem for storing files.
|
A memory-backed filesystem for storing files. |
|
utilfs
This is a sample filesystem that serves a couple "utilities" There's /time, which when read, will return a human-readable string of the current time.
|
This is a sample filesystem that serves a couple "utilities" There's /time, which when read, will return a human-readable string of the current time. |