.TH OP 2
.SH NAME
Op, Rmsg, Tmsg, dir2text, istmsg, packdir, packdirsize, readmsg, qid2text, unpackdir \- interface to the Op file protocol
.SH SYNOPSIS
.EX
include "op.m";
op := load Op Op->PATH;

# Message types
Tattach,		# 1
Rattach,
Terror,		#  3 illegal
Rerror,
Tflush,		# 5
Rflush,
Tput,		# 7
Rput,
Tget,		# 9
Rget,
Tremove,		# 11
Rremove,
Tmax: con 1+iota;

NOFD:			con int ~0;
MAXDATA: 		con 16*1024;		# `reasonable' iounit (size of .data fields)

ODATA:		con int 1 <<1;		# put/get data
OSTAT:		con int 1 <<2;		# put/get stat
OCREATE:		con int 1 <<3;		# create the file (or truncate)
OMORE:		con int 1 <<4;		# more data going/comming later
OREMOVEC:		con int 1 <<5;		# remove after final put.

Tmsg: adt {
	tag: int;
	pick {
	Readerror =>
		error: string;		# tag is unused in this case
	Attach =>
		uname: string;		# user name responsible for rpcs
		path: string;		# subtree we want to attach to.
	Flush =>
		oldtag: int;		# tag for flushed request
	Put =>
		path: string;		# of file
		fd: int;			# for file
		mode : int;		# bit-or of OSTAT|ODATA|OCREATE|OMORE
		stat: Sys->Dir;		# for file
		offset: big;		# for data
		data: array of byte;
	Get =>
		path: string;		# of file
		fd: int;			# of file
		mode: int;			# bit-or of OSTAT|ODATA|OMORE
		nmsgs: int;		# max number of Rgets for reply. 0==unlimited.
		offset: big;		# byte offset (ignored for dirs)
		count: int;			# max data expected per message
	Remove => 
		path: string;		# of file
	}

	read:	fn(fd: ref Sys->FD, msize: int): ref Tmsg;
	unpack:	fn(a: array of byte): (int, ref Tmsg);
	pack:	fn(nil: self ref Tmsg): array of byte;
	packedsize:	fn(nil: self ref Tmsg): int;
	text:	fn(nil: self ref Tmsg): string;
	mtype: fn(nil: self ref Tmsg): int;
};

Rmsg: adt {
	tag: int;
	pick {
	Readerror =>
		error: string;		# tag is unused in this case
	Error =>
		ename: string;
	Attach or Flush =>
	Put =>
		fd: int;
		count: int;
		qid:	Sys->Qid;
		mtime: int;
	Get =>
		fd: int;
		mode: int;			# bit or of OSTAT|ODATA|OMORE
		stat: Sys->Dir;
		data: array of byte;
	Remove =>
	}

	read:	fn(fd: ref Sys->FD, msize: int): ref Rmsg;
	unpack:	fn(a: array of byte): (int, ref Rmsg);
	pack:	fn(nil: self ref Rmsg): array of byte;
	packedsize:	fn(nil: self ref Rmsg): int;
	text:	fn(nil: self ref Rmsg): string;
	mtype: fn(nil: self ref Rmsg): int;

};

init:	fn();

readmsg:	fn(fd: ref Sys->FD, msize: int): (array of byte, string);
istmsg:	fn(f: array of byte): int;

packdirsize:	fn(d: Sys->Dir): int;
packdir:	fn(d: Sys->Dir): array of byte;
unpackdir: fn(f: array of byte): (int, Sys->Dir);
dir2text:	fn(d: Sys->Dir): string;
qid2text:	fn(q: Sys->Qid): string;

.EE
.SH DESCRIPTION
.B Op
provides a Limbo interface for speaking the Octopus File Protocol, Op. See
.IR intro (O)
for a description of the protocol.
.PP
.B Init
initializes and prepares the module for operation.
.PP
.B Readmsg
reads an Op message from
.I fd
(a maximum of
.I msize
bytes), and returns it as an array of bytes. The second member of the tuple
returned is the error status (nil for no error). When
.I msize
is zero, a reasonable default is chosen by the module.
.PP
.B Istmsg
returns non-zero if the array of bytes
.I f
corresponds to an Op
.BR Tmsg .
.B Tmsg.read
is similar to
.BR readmsg ,
but reads an Op
.BR Tmsg
and unpacks it using
.BR Tmsg.unpack .
.PP
The converse of
.B Tmsg.unpack
is
.BR Tmsg.pack .
It packs a
.BR Tmsg
into network format, and returns the resulting array of bytes. The function
.B Tmsg.packedsize
may be used to obtain the size of a
.B Tmsg
while packed.
.PP
The function
.B Tmsg.text
returns a string with a printable representation of the message, for debugging.
.PP
In general, the adt for a
.B Tmsg
suffices. However,
.I mtype
returns a different (small) integer for different
.B Tmsgs ,
representing its type.
.PP
The same set of operations are available for
.B Rmsgs
(they are not described again here).
.PP
As an aid,
.B packdir
packages a directory entry,
.B packdirsize
reports the size in bytes of a packed directory, and
.B unpackdir
unpacks a directory entry. These functions are only necessary
for reading directories. Othersize, the
.B stat
fields in
.B Tmsgs
and
.B Rmsgs
suffice.
.PP
.B Dir2text
and
.B qid2text
return printable strings for directory entries and qids, also for
debugging purposes.
.PP
The meaning of the various constants defined is explained in section O
of this manual. In general, directories and qids use the same name
(and meaning) used in Styx.
.SH SOURCE
.B /usr/octopus/port/lib/op.b
.SH SEE ALSO
.IR intro (O),
.IR opmux (2),
and
.IR intro (5).