From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/9p-cmdbuf.html | 128 +++++ man/man3/9p-fid.html | 170 ++++++ man/man3/9p-file.html | 258 +++++++++ man/man3/9p-intmap.html | 110 ++++ man/man3/9p.html | 434 +++++++++++++++ man/man3/9pclient.html | 250 +++++++++ man/man3/addpt.html | 174 ++++++ man/man3/aes.html | 85 +++ man/man3/allocimage.html | 321 +++++++++++ man/man3/arg.html | 152 ++++++ man/man3/arith3.html | 216 ++++++++ man/man3/atof.html | 170 ++++++ man/man3/bin.html | 131 +++++ man/man3/bio.html | 293 ++++++++++ man/man3/blowfish.html | 95 ++++ man/man3/cachechars.html | 292 ++++++++++ man/man3/cleanname.html | 71 +++ man/man3/color.html | 89 +++ man/man3/complete.html | 136 +++++ man/man3/cputime.html | 65 +++ man/man3/ctime.html | 150 +++++ man/man3/des.html | 170 ++++++ man/man3/dial.html | 241 ++++++++ man/man3/dirread.html | 114 ++++ man/man3/draw.html | 1174 +++++++++++++++++++++++++++++++++++++++ man/man3/dsa.html | 172 ++++++ man/man3/dup.html | 78 +++ man/man3/elgamal.html | 174 ++++++ man/man3/encode.html | 109 ++++ man/man3/errstr.html | 121 +++++ man/man3/event.html | 390 +++++++++++++ man/man3/exec.html | 146 +++++ man/man3/exits.html | 126 +++++ man/man3/fcall.html | 274 ++++++++++ man/man3/flate.html | 333 ++++++++++++ man/man3/fmtinstall.html | 339 ++++++++++++ man/man3/frame.html | 325 +++++++++++ man/man3/genrandom.html | 84 +++ man/man3/get9root.html | 109 ++++ man/man3/getcallerpc.html | 99 ++++ man/man3/getenv.html | 79 +++ man/man3/getfields.html | 136 +++++ man/man3/getns.html | 67 +++ man/man3/getsnarf.html | 73 +++ man/man3/getuser.html | 75 +++ man/man3/getwd.html | 84 +++ man/man3/graphics.html | 592 ++++++++++++++++++++ man/man3/html.html | 1206 +++++++++++++++++++++++++++++++++++++++++ man/man3/index.html | 647 ++++++++++++++++++++++ man/man3/intro.html | 288 ++++++++++ man/man3/ioproc.html | 211 +++++++ man/man3/ip.html | 345 ++++++++++++ man/man3/isalpharune.html | 96 ++++ man/man3/keyboard.html | 135 +++++ man/man3/lock.html | 222 ++++++++ man/man3/mach-cmd.html | 167 ++++++ man/man3/mach-file.html | 185 +++++++ man/man3/mach-map.html | 312 +++++++++++ man/man3/mach-stack.html | 232 ++++++++ man/man3/mach-swap.html | 124 +++++ man/man3/mach-symbol.html | 272 ++++++++++ man/man3/mach.html | 123 +++++ man/man3/malloc.html | 181 +++++++ man/man3/matrix.html | 263 +++++++++ man/man3/memdraw.html | 466 ++++++++++++++++ man/man3/memlayer.html | 325 +++++++++++ man/man3/memory.html | 123 +++++ man/man3/mouse.html | 249 +++++++++ man/man3/mousescrollsize.html | 108 ++++ man/man3/mp.html | 441 +++++++++++++++ man/man3/muldiv.html | 61 +++ man/man3/mux.html | 169 ++++++ man/man3/nan.html | 79 +++ man/man3/needstack.html | 98 ++++ man/man3/notify.html | 183 +++++++ man/man3/open.html | 130 +++++ man/man3/opentemp.html | 78 +++ man/man3/pipe.html | 111 ++++ man/man3/plumb.html | 257 +++++++++ man/man3/post9pservice.html | 67 +++ man/man3/postnote.html | 80 +++ man/man3/prime.html | 114 ++++ man/man3/print.html | 309 +++++++++++ man/man3/proto.html | 140 +++++ man/man3/pushtls.html | 261 +++++++++ man/man3/qball.html | 111 ++++ man/man3/quaternion.html | 163 ++++++ man/man3/quote.html | 164 ++++++ man/man3/rand.html | 190 +++++++ man/man3/rc4.html | 86 +++ man/man3/read.html | 109 ++++ man/man3/regexp.html | 178 ++++++ man/man3/rfork.html | 118 ++++ man/man3/rsa.html | 262 +++++++++ man/man3/rune.html | 157 ++++++ man/man3/runestrcat.html | 107 ++++ man/man3/sechash.html | 195 +++++++ man/man3/seek.html | 96 ++++ man/man3/sendfd.html | 85 +++ man/man3/setjmp.html | 110 ++++ man/man3/sleep.html | 95 ++++ man/man3/stat.html | 244 +++++++++ man/man3/strcat.html | 203 +++++++ man/man3/string.html | 244 +++++++++ man/man3/stringsize.html | 116 ++++ man/man3/subfont.html | 260 +++++++++ man/man3/sysfatal.html | 71 +++ man/man3/thread.html | 383 +++++++++++++ man/man3/time.html | 79 +++ man/man3/udpread.html | 105 ++++ man/man3/wait.html | 170 ++++++ man/man3/wctl.html | 78 +++ man/man3/window.html | 241 ++++++++ 113 files changed, 22752 insertions(+) create mode 100644 man/man3/9p-cmdbuf.html create mode 100644 man/man3/9p-fid.html create mode 100644 man/man3/9p-file.html create mode 100644 man/man3/9p-intmap.html create mode 100644 man/man3/9p.html create mode 100644 man/man3/9pclient.html create mode 100644 man/man3/addpt.html create mode 100644 man/man3/aes.html create mode 100644 man/man3/allocimage.html create mode 100644 man/man3/arg.html create mode 100644 man/man3/arith3.html create mode 100644 man/man3/atof.html create mode 100644 man/man3/bin.html create mode 100644 man/man3/bio.html create mode 100644 man/man3/blowfish.html create mode 100644 man/man3/cachechars.html create mode 100644 man/man3/cleanname.html create mode 100644 man/man3/color.html create mode 100644 man/man3/complete.html create mode 100644 man/man3/cputime.html create mode 100644 man/man3/ctime.html create mode 100644 man/man3/des.html create mode 100644 man/man3/dial.html create mode 100644 man/man3/dirread.html create mode 100644 man/man3/draw.html create mode 100644 man/man3/dsa.html create mode 100644 man/man3/dup.html create mode 100644 man/man3/elgamal.html create mode 100644 man/man3/encode.html create mode 100644 man/man3/errstr.html create mode 100644 man/man3/event.html create mode 100644 man/man3/exec.html create mode 100644 man/man3/exits.html create mode 100644 man/man3/fcall.html create mode 100644 man/man3/flate.html create mode 100644 man/man3/fmtinstall.html create mode 100644 man/man3/frame.html create mode 100644 man/man3/genrandom.html create mode 100644 man/man3/get9root.html create mode 100644 man/man3/getcallerpc.html create mode 100644 man/man3/getenv.html create mode 100644 man/man3/getfields.html create mode 100644 man/man3/getns.html create mode 100644 man/man3/getsnarf.html create mode 100644 man/man3/getuser.html create mode 100644 man/man3/getwd.html create mode 100644 man/man3/graphics.html create mode 100644 man/man3/html.html create mode 100644 man/man3/index.html create mode 100644 man/man3/intro.html create mode 100644 man/man3/ioproc.html create mode 100644 man/man3/ip.html create mode 100644 man/man3/isalpharune.html create mode 100644 man/man3/keyboard.html create mode 100644 man/man3/lock.html create mode 100644 man/man3/mach-cmd.html create mode 100644 man/man3/mach-file.html create mode 100644 man/man3/mach-map.html create mode 100644 man/man3/mach-stack.html create mode 100644 man/man3/mach-swap.html create mode 100644 man/man3/mach-symbol.html create mode 100644 man/man3/mach.html create mode 100644 man/man3/malloc.html create mode 100644 man/man3/matrix.html create mode 100644 man/man3/memdraw.html create mode 100644 man/man3/memlayer.html create mode 100644 man/man3/memory.html create mode 100644 man/man3/mouse.html create mode 100644 man/man3/mousescrollsize.html create mode 100644 man/man3/mp.html create mode 100644 man/man3/muldiv.html create mode 100644 man/man3/mux.html create mode 100644 man/man3/nan.html create mode 100644 man/man3/needstack.html create mode 100644 man/man3/notify.html create mode 100644 man/man3/open.html create mode 100644 man/man3/opentemp.html create mode 100644 man/man3/pipe.html create mode 100644 man/man3/plumb.html create mode 100644 man/man3/post9pservice.html create mode 100644 man/man3/postnote.html create mode 100644 man/man3/prime.html create mode 100644 man/man3/print.html create mode 100644 man/man3/proto.html create mode 100644 man/man3/pushtls.html create mode 100644 man/man3/qball.html create mode 100644 man/man3/quaternion.html create mode 100644 man/man3/quote.html create mode 100644 man/man3/rand.html create mode 100644 man/man3/rc4.html create mode 100644 man/man3/read.html create mode 100644 man/man3/regexp.html create mode 100644 man/man3/rfork.html create mode 100644 man/man3/rsa.html create mode 100644 man/man3/rune.html create mode 100644 man/man3/runestrcat.html create mode 100644 man/man3/sechash.html create mode 100644 man/man3/seek.html create mode 100644 man/man3/sendfd.html create mode 100644 man/man3/setjmp.html create mode 100644 man/man3/sleep.html create mode 100644 man/man3/stat.html create mode 100644 man/man3/strcat.html create mode 100644 man/man3/string.html create mode 100644 man/man3/stringsize.html create mode 100644 man/man3/subfont.html create mode 100644 man/man3/sysfatal.html create mode 100644 man/man3/thread.html create mode 100644 man/man3/time.html create mode 100644 man/man3/udpread.html create mode 100644 man/man3/wait.html create mode 100644 man/man3/wctl.html create mode 100644 man/man3/window.html (limited to 'man/man3') diff --git a/man/man3/9p-cmdbuf.html b/man/man3/9p-cmdbuf.html new file mode 100644 index 00000000..122a5857 --- /dev/null +++ b/man/man3/9p-cmdbuf.html @@ -0,0 +1,128 @@ + +9p-cmdbuf(3) - Plan 9 from User Space + + + + +
+
+
9P-CMDBUF(3)9P-CMDBUF(3) +
+
+

NAME
+ +
+ + Cmdbuf, parsecmd, respondcmderror, lookupcmd – control message + parsing
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct Cmdbuf
+ {
+ +
+ + char      *buf;
+ char      **f;
+ int       nf;
+ +
+ } Cmdbuf;
+ typedef struct Cmdtab
+ {
+ +
+ + int       index;
+ char      *cmd;
+ int       narg;
+ +
+ };
+ Cmdbuf        *parsecmd(char *p, int n)
+ Cmdtab        *lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab)
+ void          respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...)
+ +
+

DESCRIPTION
+ +
+ + These data structures and functions provide parsing of textual + control messages. +
+ + Parsecmd treats the n bytes at p (which need not be NUL-terminated) + as a UTF string and splits it using tokenize (see getfields(3)). + It returns a Cmdbuf structure holding pointers to each field in + the message. +
+ + Lookupcmd walks through the array ctab, which has ntab entries, + looking for the first Cmdtab that matches the parsed command. + (If the parsed command is empty, lookupcmd returns nil immediately.) + A Cmdtab matches the command if cmd is equal to cb−>f[0] or if + cmd is *. Once a matching Cmdtab has been + found, if narg is not zero, then the parsed command must have + exactly narg fields (including the command string itself). If + the command has the wrong number of arguments, lookupcmd returns + nil. Otherwise, it returns a pointer to the Cmdtab entry. If lookupcmd + does not find a matching command at all, it returns + nil. Whenever lookupcmd returns nil, it sets the system error + string. +
+ + Respondcmderror resoponds to request r with an error of the form + ‘fmt: cmd,’ where fmt is the formatted string and cmd is a reconstruction + of the parsed command. Fmt is often simply %r .
+ +
+

EXAMPLES
+ +
+ + This interface is not used in any distributed 9P servers. It was + lifted from the Plan 9 kernel. Almost any Plan 9 kernel driver + (/sys/src/9/*/dev*.c on Plan 9) is a good example.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/parse.c
+ +
+

SEE ALSO
+ +
+ + 9p(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-fid.html b/man/man3/9p-fid.html new file mode 100644 index 00000000..44bca53c --- /dev/null +++ b/man/man3/9p-fid.html @@ -0,0 +1,170 @@ + +9p-fid(3) - Plan 9 from User Space + + + + +
+
+
9P-FID(3)9P-FID(3) +
+
+

NAME
+ +
+ + Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, + removefid, Req, Reqpool, allocreqpool, freereqpool, allocreq, + closereq, lookupreq, removereq – 9P fid, request tracking
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct Fid
+ {
+ +
+ + ulong fid;
+ char    omode;    /* −1 if not open */
+ char    *uid;
+ Qid     qid;
+ File    *file;
+ void    *aux;
+ +
+ +
+ + ...
+ +
+ } Fid;
+ +
+ + typedef struct Req
+ {
+ +
+ + ulong tag;
+ Fcall ifcall;
+ Fcall ofcall;
+ Req     *oldreq;
+ void    *aux;
+ +
+ +
+ + ...
+ +
+ } Req;
+ +
+ + Fidpool* allocfidpool(void (*destroy)(Fid*))
+ void       freefidpool(Fidpool *p)
+ Fid*       allocfid(Fidpool *p, ulong fid)
+ Fid*       lookupfid(Fidpool *p, ulong fid)
+ void       closefid(Fid *f)
+ void       removefid(Fid *f)
+ +
+ + Reqpool* allocreqpool(void (*destroy)(Req*))
+ void       freereqpool(Reqpool *p)
+ Req*       allocreq(Reqpool *p, ulong tag)
+ Req*       lookupreq(Reqpool *p, ulong tag)
+ void       closereq(Req *f)
+ void       removereq(Req *r)
+ +
+

DESCRIPTION
+ +
+ + These routines provide management of Fid and Req structures from + Fidpools and Reqpools. They are primarily used by the 9P server + loop described in 9p(3). +
+ + Fid structures are intended to represent active fids in a 9P connection, + as Chan structures do in the Plan 9 kernel. The fid element is + the integer fid used in the 9P connection. Omode is the mode under + which the fid was opened, or −1 if this fid has not been opened + yet. Note that in addition to the values OREAD, + OWRITE, and ORDWR, omode can contain the various flags permissible + in an open call. To ignore the flags, use omode&OMASK. Omode should + not be changed by the client. The fid derives from a successful + authentication by uid. Qid contains the qid returned in the last + successful walk or create transaction + involving the fid. In a file tree-based server, the Fid’s file + element points at a File structure (see 9p-file(3)) corresponding + to the fid. The aux member is intended for use by the client to + hold information specific to a particular Fid. With the exception + of aux, these elements should be treated as read-only by + the client. +
+ + Allocfidpool creates a new Fidpool. Freefidpool destroys such + a pool. Allocfid returns a new Fid whose fid number is fid. There + must not already be an extant Fid with that number in the pool. + Once a Fid has been allocated, it can be looked up by fid number + using lookupfid. Fids are reference counted: both + allocfid and lookupfid increment the reference count on the Fid + structure before returning. When a reference to a Fid is no longer + needed, closefid should be called to note the destruction of the + reference. When the last reference to a Fid is removed, if destroy + (supplied when creating the fid pool) is not zero, it is + called with the Fid as a parameter. It should perform whatever + cleanup is necessary regarding the aux element. Removefid is equivalent + to closefid but also removes the Fid from the pool. Note that + due to lingering references, the return of removefid may not mean + that destroy has been called. +
+ + Allocreqpool, freereqpool, allocreq, lookupreq, closereq, and + removereq are analogous but operate on Reqpools and Req structures.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p
+ +
+

SEE ALSO
+ +
+ + 9p(3), 9p-file(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-file.html b/man/man3/9p-file.html new file mode 100644 index 00000000..63ae5042 --- /dev/null +++ b/man/man3/9p-file.html @@ -0,0 +1,258 @@ + +9p-file(3) - Plan 9 from User Space + + + + +
+
+
9P-FILE(3)9P-FILE(3) +
+
+

NAME
+ +
+ + Tree, alloctree, freetree, File, createfile, closefile, removefile, + walkfile, opendirfile, readdirfile, closedirfile, hasperm – in-memory + file hierarchy
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct File
+ {
+ +
+ + +
+ + Ref;
+ Dir;
+ void*aux;
+ +
+ +
+ +
+ + +
+ + ...
+ +
+ +
+ } File;
+ +
+ + typedef struct Tree
+ {
+ +
+ + +
+ + File *root;
+ +
+ +
+ +
+ + +
+ + ...
+ +
+ +
+ } Tree;
+ +
+ + Tree*      alloctree(char *uid, char *gid, ulong mode,
+ +
+ + +
+ + void (*destroy)(File*))
+ +
+ +
+ void       freetree(Tree *tree)
+ File*      createfile(File *dir, char *name, char *uid,
+ +
+ + +
+ + ulong mode, void *aux)
+ +
+ +
+ int        removefile(File *file)
+ void       closefile(File *file)
+ File*      walkfile(File *dir, char *path)
+ Readdir* opendirfile(File *dir)
+ long       readdirfile(Readdir *rdir, char *buf, long n)
+ void       closedirfile(Readdir *rdir)
+ int        hasperm(File *file, char *uid, int p)
+ +
+

DESCRIPTION
+ +
+ + Files and Trees provide an in-memory file hierarchy intended for + use in 9P file servers. +
+ + Alloctree creates a new tree of files, and freetree destroys it. + The root of the tree (also the root element in the structure) + will have mode mode and be owned by user uid and group gid. Destroy + is used when freeing File structures and is described later. +
+ + Files (including directories) other than the root are created + using createfile, which attempts to create a file named name in + the directory dir. If created, the file will have owner uid and + have a group inherited from the directory. Mode and the permissions + of dir are used to calculate the permission bits for the file + as + described in open(9p). It is permissible for name to be a slash-separated + path rather than a single element. +
+ + Removefile removes a file from the file tree. The file will not + be freed until the last reference to it has been removed. Directories + may only be removed when empty. Removefile returns zero on success, + –1 on error. It is correct to consider removefile to be closefile + with the side effect of removing the file when possible. +
+ + Walkfile evaluates path relative to the directory dir, returning + the resulting file, or zero if the named file or any intermediate + element does not exist. +
+ + The File structure’s aux pointer may be used by the client for + per-File storage. Files are reference-counted: if not zero, destroy + (specified in the call to alloctree) will be called for each file + when its last reference is removed or when the tree is freed. + Destroy should take care of any necessary cleanup related to + aux. When creating new file references by copying pointers, call + incref (see lock(3)) to update the reference count. To note the + removal of a reference to a file, call closefile. Createfile and + walkfile return new references. Removefile, closefile, and walkfile + (but not createfile) consume the passed reference. +
+ + Directories may be read, yielding a directory entry structure + (see stat(9p)) for each file in the directory. In order to allow + concurrent reading of directories, clients must obtain a Readdir + structure by calling opendirfile on a directory. Subsequent calls + to readdirfile will each yield an integral number of machine- + independent stat buffers, until end of directory. When finished, + call closedirfile to free the Readdir. +
+ + Hasperm does simplistic permission checking; it assumes only one-user + groups named by uid and returns non-zero if uid has permission + p (a bitwise-or of AREAD, AWRITE and AEXEC) according to file−>mode. + 9P servers written using File trees will do standard permission + checks automatically; hasperm may be + called explicitly to do additional checks. A 9P server may link + against a different hasperm implementation to provide more complex + groups.
+ +
+

EXAMPLE
+ +
+ + The following code correctly handles references when elementwise + walking a path and creating a file.
+ +
+ + f = tree−>root;
+ incref(f);
+ for(i=0; i<n && f!=nil; i++)
+ +
+ + f = walkfile(f, elem[i]);
+ +
+ if(f == nil)
+ +
+ + return nil;
+ +
+ nf = createfile(f, "foo", "nls", 0666, nil);
+ closefile(f);
+ return nf;
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/file.c
+ +
+

SEE ALSO
+ +
+ + 9p(3)
+ +
+

BUGS
+ +
+ + The reference counting is cumbersome.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-intmap.html b/man/man3/9p-intmap.html new file mode 100644 index 00000000..f6d1822f --- /dev/null +++ b/man/man3/9p-intmap.html @@ -0,0 +1,110 @@ + +9p-intmap(3) - Plan 9 from User Space + + + + +
+
+
9P-INTMAP(3)9P-INTMAP(3) +
+
+

NAME
+ +
+ + Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, + deletekey – integer to data structure maps
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + Intmap* allocmap(void (*inc)(void*))
+ void      freemap(Intmap *map, void (*dec)(void*))
+ void*     lookupkey(Intmap *map, ulong key)
+ void*     insertkey(Intmap *map, ulong key, void *val)
+ int       caninsertkey(Intmap *map, ulong key, void *val)
+ void*     lookupkey(Intmap *map, ulong key)
+ void*     deletekey(Intmap *map, ulong key)
+ +
+

DESCRIPTION
+ +
+ + An Intmap is an arbitrary mapping from integers to pointers. Allocmap + creates a new map, and freemap destroys it. The inc function is + called each time a new pointer is added to the map; similarly, + dec is called on each pointer left in the map when it is being + freed. Typically these functions maintain reference counts. + New entries are added to the map by calling insertkey, which will + return the previous value associated with the given key, or zero + if there was no previous value. Caninsertkey is like insertkey + but only inserts val if there is no current mapping. It returns + 1 if val was inserted, 0 otherwise. Lookupkey returns the pointer + associated with key, or zero if there is no such pointer. Deletekey + removes the entry for id from the map, returning the associated + pointer, if any. +
+ + Concurrent access to Intmaps is safe, moderated via a QLock stored + in the Intmap structure. +
+ + In anticipation of the storage of reference-counted structures, + an increment function inc may be specified at map creation time. + Lookupkey calls inc (if non-zero) on pointers before returning + them. If the reference count adjustments were left to the caller + (and thus not protected by the lock), it would be possible to + accidentally reclaim a structure if, for example, it was deleted + from the map and its reference count decremented between the return + of insertkey and the external increment. Insertkey and caninsertkey + do not call inc when inserting val into the map, nor do insertkey + or deletekey call inc when returning old map entries. + The rationale is that calling an insertion function transfers + responsibility for the reference to the map, and responsibility + is given back via the return value of deletekey or the next insertkey. + +
+ + Intmaps are used by the 9P library to implement Fidpools and Reqpools.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/intmap.c
+ +
+

SEE ALSO
+ +
+ + 9p(3), 9p-fid(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p.html b/man/man3/9p.html new file mode 100644 index 00000000..9896b0b7 --- /dev/null +++ b/man/man3/9p.html @@ -0,0 +1,434 @@ + +9p(3) - Plan 9 from User Space + + + + +
+
+
9P(3)9P(3) +
+
+

NAME
+ +
+ + Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, postmountsrv, + readbuf, readstr, respond, srv, threadpostmountsrv, walkandclone + – 9P file service
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct Srv {
+ +
+ + Tree* tree;
+ void    (*attach)(Req *r);
+ void    (*auth)(Req *r);
+ void    (*open)(Req *r);
+ void    (*create)(Req *r);
+ void    (*read)(Req *r);
+ void    (*write)(Req *r);
+ void    (*remove)(Req *r);
+ void    (*flush)(Req *r);
+ void    (*stat)(Req *r);
+ void    (*wstat)(Req *r);
+ void    (*walk)(Req *r);
+ char* (*walk1)(Fid *fid, char *name, Qid *qid);
+ char* (*clone)(Fid *oldfid, Fid *newfid);
+ void    (*destroyfid)(Fid *fid);
+ void    (*destroyreq)(Req *r);
+ void    (*end)(Srv *s);
+ void* aux;
+ int     infd;
+ int     outfd;
+ int     srvfd;
+ int     nopipe;
+ +
+ } Srv;
+ +
+ + int     srv(Srv *s)
+ void    postmountsrv(Srv *s, char *name, char *mtpt, int flag)
+ void    threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
+ int     postfd(char *srvname, int fd)
+ void    respond(Req *r, char *error)
+ ulong readstr(Req *r, char *src)
+ ulong readbuf(Req *r, void *src, ulong nsrc)
+ typedef int Dirgen(int n, Dir *dir, void *aux)
+ void    dirread9p(Req *r, Dirgen *gen, void *aux)
+ void    walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, + void *v),
+ +
+ + +
+ + char *(*clone)(Fid *old, Fid *new, void *v), void *v)
+ +
+ + +
+ +
+ void* emalloc9p(ulong n)
+ void* erealloc9p(void *v, ulong n)
+ char* estrdup9p(char *s)
+ +
+ + extern int chatty9p;
+ +
+

DESCRIPTION
+ +
+ + The function srv serves a 9P session by reading requests from + s−>infd, dispatching them to the function pointers kept in Srv, + and writing the responses to s−>outfd. (Typically, postmountsrv + or threadpostmountsrv initializes the infd and outfd structure + members. See the description below.) +
+ + Req and Fid structures are allocated one-to-one with uncompleted + requests and active fids, and are described in 9p-fid(3). +
+ + The behavior of srv depends on whether there is a file tree (see + 9p-file(3)) associated with the server, that is, whether the tree + element is nonzero. The differences are made explicit in the discussion + of the service loop below. The aux element is the client’s, to + do with as it pleases. +
+ + Srv does not return until the 9P conversation is finished. Since + it is usually run in a separate process so that the caller can + exit, the service loop has little chance to return gracefully + on out of memory errors. It calls emalloc9p, erealloc9p, and estrdup9p + to obtain its memory. The default implementations of these + functions act as malloc, realloc, and strdup but abort the program + if they run out of memory. If alternate behavior is desired, clients + can link against alternate implementations of these functions. + +
+ + Postmountsrv and threadpostmountsrv are wrappers that create a + separate process in which to run srv. They do the following:
+ +
+ + If s−>nopipe is zero (the common case), initialize s−>infd and s−>outfd + to be one end of a freshly allocated pipe, with s−>srvfd initialized + as the other end.
+ If name is non-nil, call postfd(s−>srvfd, name) to post s−>srvfd + as /srv/name.
+ Fork a child process via rfork(3) or procrfork (see thread(3)), + using the RFFDG, RFNAMEG, and RFMEM flags. The child process calls + close(s->srvfd) and then srv(s); it will exit once srv returns.
+ If mtpt is non-nil, call amount(s−>srvfd, mtpt, flag, ""); otherwise, + close s−>srvfd.
+ The parent returns to the caller. +
+ + +
+ If any error occurs during this process, the entire process is + terminated by calling sysfatal(3).
+

Service functions
+ The functions in a Srv structure named after 9P transactions are + called to satisfy requests as they arrive. If a function is provided, + it must arrange for respond to be called when the request is satisfied. + The only parameter of each service function is a Req* parameter + (say r). The incoming request parameters are + stored in r−>ifcall; r−>fid and r−>newfid are pointers to Fid structures + corresponding to the numeric fids in r−>ifcall; similarly, r−>oldreq + is the Req structure corresponding to r−>ifcall.oldtag. The outgoing + response data should be stored in r−>ofcall. The one exception + to this rule is that stat should fill in + r−>d rather than r−>ofcall.stat: the library will convert the structure + into the machine-independent wire representation. Similarly, wstat + may consult r−>d rather than decoding r−>ifcall.stat itself. When + a request has been handled, respond should be called with r and + an error string. If the request was satisfied + successfully, the error string should be a nil pointer. Note that + it is permissible for a function to return without itself calling + respond, as long as it has arranged for respond to be called at + some point in the future by another proc sharing its address space, + but see the discussion of flush below. Once respond has been + called, the Req* as well as any pointers it once contained must + be considered freed and not referenced. +
+ + If the service loop detects an error in a request (e.g., an attempt + to reuse an extant fid, an open of an already open fid, a read + from a fid opened for write, etc.) it will reply with an error + without consulting the service functions. +
+ + The service loop provided by srv (and indirectly by postmountsrv + and threadpostmountsrv) is single-threaded. If it is expected + that some requests might block, arranging for alternate processes + to handle them is suggested. +
+ + The constraints on the service functions are as follows. These + constraints are checked while the server executes. If a service + function fails to do something it ought to have, srv will call + endsrv and then abort.
+ Auth   If authentication is desired, the auth function should record + that afid is the new authentication fid and set afid->qid and ofcall.qid. + Auth may be nil, in which case it will be treated as having responded + with the error “argv0: authentication not required,” where argv0 + is the program name variable as set by + +
+ + ARGBEGIN (see arg(3)).
+ +
+ AttachThe attach function should check the authentication state + of afid if desired, and set r−>fid−>qid and ofcall.qid to the qid + of the file system root. Attach may be nil only if file trees + are in use; in this case, the qid will be filled from the root + of the tree, and no authentication will be done. + Walk   If file trees are in use, walk is handled internally, and + srv−>walk is never called.
+ +
+ + If file trees are not in use, walk should consult r−>ifcall.wname + and r−>ifcall.nwname, filling in ofcall.qid and ofcall.nqid, and + also copying any necessary aux state from r−>fid to r−>newfid when + the two are different. As long as walk sets ofcall.nqid appropriately, + it can respond with a nil error string + even when 9P demands an error (e.g., in the case of a short walk); + the library detects error conditions and handles them appropriately.
+ Because implementing the full walk message is intricate and prone + to error, the helper routine walkandclone will handle the request + given pointers to two functions walk1 and (optionally) clone . + Clone, if non-nil, is called to signal the creation of newfid + from oldfid. Typically a clone routine will copy or increment + a reference count in oldfid’s aux element. Walk1 should walk fid + to name, initializing fid−>qid to the new path’s qid. Both should + return nil on success or an error message on error. Walkandclone + will call respond after handling the request.
+ +
+ Walk1, Clone
+ +
+ + If the client provides functions srv−>walk1 and (optionally) srv−>clone, + the 9P service loop will call walkandclone with these functions + to handle the request. Unlike the walk1 above, srv−>walk1 must + fill in both fid−>qid and *qid with the new qid on a successful + walk.
+ +
+ Open   If file trees are in use, the file metadata will be consulted + on open, create, remove, and wstat to see if the requester has + the appropriate permissions. If not, an error will be sent back + without consulting a service function. +
+ + If not using file trees or the user has the appropriate permissions, + open is called with r−>ofcall.qid already initialized to the one + stored in the Fid structure (that is, the one returned in the + previous walk). If the qid changes, both should be updated.
+ CreateThe create function must fill in both r−>fid−>qid and r−>ofcall.qid + on success. When using file trees, create should allocate a new + File with createfile; note that createfile may return nil (because, + say, the file already exists). If the create function is nil, + srv behaves as though it were a function that always + +
+ + responded with the error “create prohibited”.
+ +
+ Remove
+ +
+ + Remove +
+ +
+ + should mark the file as removed, whether by calling removefile + when using file trees, or by updating an internal data structure. + In general it is not a good idea to clean up the aux information + associated with the corresponding File at this time, to avoid + memory errors if other fids have references to that + file. Instead, it is suggested that remove simply mark the file + as removed (so that further operations on it know to fail) and + wait until the file tree’s destroy function is called to reclaim + the aux pointer. If not using file trees, it is prudent to take + the analogous measures. If remove is not provided, all remove + requests will draw “remove prohibited” errors.
+ +
+ Read   The read function must be provided; it fills r−>ofcall.data + with at most r−>ifcall.count bytes of data from offset r−>ifcall.offset + of the file. It also sets r−>ofcall.count to the number of bytes + being returned. If using file trees, srv will handle reads of + directories internally, only calling read for requests on + +
+ + files. Readstr and readbuf are useful for satisfying read requests + on a string or buffer. Consulting the request in r−>ifcall, they + fill r−>ofcall.data and set r−>ofcall.count; they do not call respond. + Similarly, dirread9p can be used to handle directory reads in + servers not using file trees. The passed gen + function will be called as necessary to fill dir with information + for the nth entry in the directory. The string pointers placed + in dir should be fresh copies made with estrdup9p; they will be + freed by dirread9p after each successful call to gen. Gen should + return zero if it successfully filled dir, minus one on end of + directory.
+ +
+ WriteThe write function is similar but need not be provided. If + it is not, all writes will draw “write prohibited” errors. Otherwise, + write should attempt to write the r−>ifcall.count bytes of r−>ifcall.data + to offset r−>ifcall.offset of the file, setting r−>ofcall.count + to the number of bytes actually written. Most + +
+ + programs consider it an error to write less than the requested + amount.
+ +
+ Stat   Stat should fill r−>d with the stat information for r−>fid. + If using file trees, r−>d will have been initialized with the stat + info from the tree, and stat itself may be nil.
+ WstatThe wstat consults r−>d in changing the metadata for r−>fid + as described in stat(9p). When using file trees, srv will take + care to check that the request satisfies the permissions outlined + in stat(9p). Otherwise wstat should take care to enforce permissions + where appropriate.
+ Flush   Single-threaded servers, which always call respond before + returning from the service functions, need not provide a flush + implementation: flush is only necessary in multithreaded programs, + which arrange for respond to be called asynchronously. Flush should + cause the request r−>oldreq to be cancelled or + +
+ + hurried along. If oldreq is cancelled, this should be signalled + by calling respond on oldreq with error string ‘interrupted’. + Flush must respond to r with a nil error string. Flush may respond + to r before forcing a response to r−>oldreq. In this case, the + library will delay sending the Rflush message until the + response to r−>oldreq has been sent. +
+ + +
+ Destroyfid, destroyreq, and end are auxiliary functions, not called + in direct response to 9P requests.
+ Destroyfid
+ +
+ + When a Fid’s reference count drops to zero (i.e., it has been + clunked and there are no outstanding requests referring to it), + destroyfid is called to allow the program to dispose of the fid−>aux + pointer.
+ +
+ Destroyreq
+ +
+ + Similarly, when a Req’s reference count drops to zero (i.e., it + has been handled via respond and other outstanding pointers to + it have been closed), destroyreq is called to allow the program + to dispose of the r−>aux pointer.
+ +
+ End    Once the 9P service loop has finished (end of file been reached + on the service pipe or a bad message has been read), end is called + (if provided) to allow any final cleanup. For example, it was + used by the Palm Pilot synchronization file system (never finished) + to gracefully terminate the serial conversation once the + +
+ + file system had been unmounted. After calling end, the service + loop (which runs in a separate process from its caller) terminates + using _exits (see exits(3)). +
+ + +
+ If the chatty9p flag is at least one, a transcript of the 9P session + is printed on standard error. If the chatty9p flag is greater + than one, additional unspecified debugging output is generated. + By convention, servers written using this library accept the −D + option to increment chatty9p. + +

+

EXAMPLES
+ +
+ + /usr/local/plan9/src/lib9p/ramfs.c is an example of a simple single-threaded + file server. On Plan 9, see archfs, cdfs, nntpfs, webfs, and sshnet + for more examples. +
+ + In general, the File interface is appropriate for maintaining + arbitrary file trees (as in ramfs). The File interface is best + avoided when the tree structure is easily generated as necessary; + this is true when the tree is highly structured (as in cdfs and + nntpfs) or is maintained elsewhere.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p
+ +
+

SEE ALSO
+ +
+ + 9p-fid(3), 9p-file(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9pclient.html b/man/man3/9pclient.html new file mode 100644 index 00000000..4ae50c21 --- /dev/null +++ b/man/man3/9pclient.html @@ -0,0 +1,250 @@ + +9pclient(3) - Plan 9 from User Space + + + + +
+
+
9PCLIENT(3)9PCLIENT(3) +
+
+

NAME
+ +
+ + CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, + fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, + fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, + fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + #include <fcall.h> +
+ + #include <9pclient.h> +
+ + CFsys* fsmount(int fd, char *aname) +
+ + CFsys* nsmount(char *name, char *aname) +
+ + CFid*    fsroot(CFsys *fsys) +
+ + void     fsunmount(CFsys *fsys) +
+ + CFsys* fsinit(int fd) +
+ + int      fsversion(CFsys *fsys, int msize, char *version, int nversion) + +
+ + CFid     *fsauth(CFsys *fsys, char *uname, char *aname) +
+ + CFid     *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) + +
+ + void     fssetroot(CFsys *fsys, CFid *fid) +
+ + void     fsclose(CFid *fid) +
+ + CFid     *fscreate(CFsys *fs, char *path, int mode, ulong perm) +
+ + CFid*    fsopen(CFsys *fs, char *path, int mode) +
+ + long     fspread(CFid *fid, void *buf, long n, vlong offset) +
+ + long     fspwrite(CFid *fid, void *buf, long n, vlong offset) +
+ + long     fsread(CFid *fid, void *buf, long n) +
+ + long     fsreadn(CFid *fid, void *buf, long n) +
+ + long     fswrite(CFid *fid, void *buf, long n) +
+ + long     fsdirread(CFid *fid, Dir **d) +
+ + long     fsdirreadall(CFid *fid, Dir **d) +
+ + Dir*     fsdirstat(CFsys *fs, char *path) +
+ + Dir*     fsdirfstat(CFid *fid) +
+ + int      fsdirwstat(CFsys *fs, char *path, Dir *d) +
+ + int      fsdirfwstat(CFid *fid, Dir *d) +
+ + int      fsopenfd(CFsys *fs, char *path, int mode)
+ +
+

DESCRIPTION
+ +
+ + The 9pclient library helps client programs interact with 9P servers. + +
+ + A CFsys* represents a connection to a 9P server. A CFid* represents + an active fid on some connection; see intro(9p). +
+ + A new connection to a 9P server is typically established by fsmount + or nsmount. Fsmount initializes a new 9P conversation on the open + file descriptor fd; nsmount connects to a service named name in + the current name space directory (see intro(4)). Both attach to + the root of the file system using the attach name aname. + Fsroot returns the CFid* corresponding to this root. +
+ + Fsinit, fsversion, fsauth, fsattach, and fssetroot provide more + detailed control over the file system connection than fsmount + and nsmount. Fsinit allocates a new CFsys* corresponding to a + 9P conversation on the file descriptor fd. Fsversion executes + a version(9p) transaction to establish maximum message size and + 9P + version. Fsauth executes an auth(9p) transaction, returning the + new auth fid. (Fsread and fswrite can then be used to run the + authentication protocol over the fid.) Fsattach executes an attach(9p) + transaction to connect to the root of a file tree served by the + server. It presents afid (which may be nil) to establish + identity. Fssetroot sets the root fid used by fsopen, fsopenfd, + fsdirstat, and fsdirwstat, which evaluate rooted path names. +
+ + When a fid is no longer needed, it should be clunked by calling + fsclose and then considered freed. Similarly, when the connection + to the server is no longer needed, it should be closed by calling + fsunmount, which will take care of calling fsclose on the current + root fid. Once all fids have been clunked and the connection + has been closed (the order is not important), the allocated structures + will be freed and the file descriptor corresponding to the connection + will be closed (see close(2)). Fids are not reference counted: + when fsclose is called, the clunk transaction and freeing of storage + happen immediately. +
+ + Fscreate and fsopen establish new fids using the walk, create + and open transactions (see walk(9p) and open(9p)). The path argument + is evaluated relative to the CFsys root (see fsroot and fssetroot + above). The path is parsed as a slash-separated sequence of path + elements, as on Unix and Plan 9. Elements that are + empty or dot (.) are ignored. +
+ + Once opened, these fids can be read and written using fspread + and fspwrite, which execute read and write transactions (see read(9p)). + The library maintains an offset for each fid, analagous to the + offset maintained by the kernel for each open file descriptor. + Fsread and fswrite read and write from this offset, and + update it after successful calls. Calling fspread or fspwrite + with an offset of –1 is identical to calling fsread or fswrite. + Fsreadn calls fsread repeatedly to obtain exactly n bytes of data, + unless it encounters end-of-file or an error. +
+ + Reading an open a directory returns directory entries encoded + as described in stat(9p). Fsdirread calls fsread and then parses + the encoded entries into an array of Dir* data structures, storing + a pointer to the array in *d and returning the number of entries. + Fsdirreadall is similar but reads the entire directory. The + returned pointer should be freed with free (see malloc(3)) when + no longer needed. +
+ + Fsdirfstat and fsdirfwstat execute stat and wstat (see stat(9p)) + transactions. The Dir structure returned by fsdirfstat should + be freed with free (see malloc(3)) when no longer needed. +
+ + Fsdirstat and fsdirwstat are similar to fsdirfstat and fsdirfwstat + but operate on paths relative to the file system root (see fsopen + and fscreate above). +
+ + Fsopenfd opens a file on the 9P server for reading or writing + but returns a Unix file descriptor instead of a fid structure. + The file descriptor is actually one end of a pipe(2). A proxy + process on the other end is ferrying data between the pipe and + the 9P fid. Because of the implementation as a pipe, the only + signal of a + read or write error is the closing of the pipe. The file descriptor + remains valid even after the CFsys is unmounted.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9pclient
+ +
+

SEE ALSO
+ +
+ + intro(4), intro(9p)
+ +
+

BUGS
+ +
+ + The implementation should use a special version string to distinguish + between servers that support openfd(9p) and servers that do not. + +
+ + The interface does not provide access to the walk(9p) transaction, + or to open and create on already-established fids. +
+ + There is no fsseek.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/addpt.html b/man/man3/addpt.html new file mode 100644 index 00000000..1c327aaa --- /dev/null +++ b/man/man3/addpt.html @@ -0,0 +1,174 @@ + +addpt(3) - Plan 9 from User Space + + + + +
+
+
ADDPT(3)ADDPT(3) +
+
+

NAME
+ +
+ + addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, + eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, + Dx, Dy, Pt, Rect, Rpt – arithmetic on points and rectangles
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + Point       addpt(Point p, Point q) +
+ + Point       subpt(Point p, Point q) +
+ + Point       mulpt(Point p, int a) +
+ + Point       divpt(Point p, int a) +
+ + Rectangle rectaddpt(Rectangle r, Point p) +
+ + Rectangle rectsubpt(Rectangle r, Point p) +
+ + Rectangle insetrect(Rectangle r, int n) +
+ + Rectangle canonrect(Rectangle r) +
+ + int         eqpt(Point p, Point q) +
+ + int         eqrect(Rectangle r, Rectangle s) +
+ + int         ptinrect(Point p, Rectangle r) +
+ + int         rectinrect(Rectangle r, Rectangle s) +
+ + int         rectXrect(Rectangle r, Rectangle s) +
+ + int         rectclip(Rectangle *rp, Rectangle b) +
+ + void        combinerect(Rectangle *rp, Rectangle b) +
+ + int         Dx(Rectangle r) +
+ + int         Dy(Rectangle r) +
+ + Point       Pt(int x, int y) +
+ + Rectangle Rect(int x0, int y0, int x1, int y1) +
+ + Rectangle Rpt(Point p, Point q)
+ +
+

DESCRIPTION
+ +
+ + The functions Pt, Rect and Rpt construct geometrical data types + from their components. +
+ + Addpt returns the Point sum of its arguments: Pt(p.x+q.x, p.y+q.y). + Subpt returns the Point difference of its arguments: Pt(p.x−q.x, + p.y−q.y). Mulpt returns the Point Pt(p.x*a, p.y*a). Divpt returns + the Point Pt(p.x/a, p.y/a). +
+ + Rectaddpt returns the Rectangle Rect(add(r.min, p), add(r.max, + p)); rectsubpt returns the Rectangle Rpt(sub(r.min, p), sub(r.max, + p)). +
+ + Insetrect returns the Rectangle Rect(r.min.x+n, r.min.y+n, r.max.x−n, + r.max.y−n). +
+ + Canonrect returns a rectangle with the same extent as r, canonicalized + so that min.x ≤ max.x, and min.y ≤ max.y. +
+ + Eqpt compares its argument Points and returns 0 if unequal, 1 + if equal. Eqrect does the same for its argument Rectangles. +
+ + Ptinrect returns 1 if p is a point within r, and 0 otherwise. + +
+ + Rectinrect returns 1 if all the pixels in r are also in s, and + 0 otherwise. +
+ + RectXrect returns 1 if r and s share any point, and 0 otherwise. + +
+ + Rectclip clips in place the Rectangle pointed to by rp so that + it is completely contained within b. The return value is 1 if + any part of *rp is within b. Otherwise, the return value is 0 + and *rp is unchanged. +
+ + Combinerect overwrites *rp with the smallest rectangle sufficient + to cover all the pixels of *rp and b. +
+ + The functions Dx and Dy give the width (Δx) and height (Δy) of + a Rectangle. They are implemented as macros.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/aes.html b/man/man3/aes.html new file mode 100644 index 00000000..1a455c2f --- /dev/null +++ b/man/man3/aes.html @@ -0,0 +1,85 @@ + +aes(3) - Plan 9 from User Space + + + + +
+
+
AES(3)AES(3) +
+
+

NAME
+ +
+ + setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption + standard (rijndael)
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar + *ivec) +
+ + void aesCBCencrypt(uchar*, int, AESstate*) +
+ + void aesCBCdecrypt(uchar*, int, AESstate*) +
+ + +
+

DESCRIPTION
+ +
+ + +
+ + DES is being replaced by Rijndael, also known as AES, as the preferred + block ciper. setupAESstate, aesCBCencrypt, and aesCBCdecrypt implement + cipher block chaining encryption. Keybytes should be 16, 24, or + 32. The initialization vector ivec of AESbsize bytes should random + enough to be unlikely to be reused but + does not need to be cryptographically strongly unpredictable.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), blowfish(3), des(3), dsa(3), elgamal(3), rc4(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/allocimage.html b/man/man3/allocimage.html new file mode 100644 index 00000000..d36fb0eb --- /dev/null +++ b/man/man3/allocimage.html @@ -0,0 +1,321 @@ + +allocimage(3) - Plan 9 from User Space + + + + +
+
+
ALLOCIMAGE(3)ALLOCIMAGE(3) +
+
+

NAME
+ +
+ + allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, + loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, + wordsperline – allocating, freeing, reading, writing images
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + Image *allocimage(Display *d, Rectangle r,
+ +
+ + +
+ + ulong chan, int repl, int col)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ Image *allocimagemix(Display *d, ulong one, ulong three)
+ +
+ + void    freeimage(Image *i)
+ +
+ + int     nameimage(Image *i, char *name, int in)
+ +
+ + Image *namedimage(Display *d, char *name)
+ +
+ + ulong setalpha(ulong color, uchar alpha)
+ +
+ + int     loadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + int     cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + int     unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + Image *readimage(Display *d, int fd, int dolock)
+ +
+ + int     writeimage(int fd, Image *i, int dolock)
+ +
+ + int     bytesperline(Rectangle r, int d)
+ +
+ + int     wordsperline(Rectangle r, int d)
+ +
+ + enum
+ {
+ +
+ + DOpaque                     = 0xFFFFFFFF,
+ DTransparent                 = 0x00000000,
+ DBlack                      = 0x000000FF,
+ DWhite                      = 0xFFFFFFFF,
+ DRed                        = 0xFF0000FF,
+ DGreen                      = 0x00FF00FF,
+ DBlue                       = 0x0000FFFF,
+ DCyan                       = 0x00FFFFFF,
+ DMagenta                    = 0xFF00FFFF,
+ DYellow                     = 0xFFFF00FF,
+ DPaleyellow                 = 0xFFFFAAFF,
+ DDarkyellow                 = 0xEEEE9EFF,
+ DDarkgreen                  = 0x448844FF,
+ DPalegreen                  = 0xAAFFAAFF,
+ DMedgreen                   = 0x88CC88FF,
+ DDarkblue                   = 0x000055FF,
+ DPalebluegreen               = 0xAAFFFFFF,
+ DPaleblue                   = 0x0000BBFF,
+ DBluegreen                  = 0x008888FF,
+ DGreygreen                  = 0x55AAAAFF,
+ DPalegreygreen               = 0x9EEEEEFF,
+ DYellowgreen                 = 0x99994CFF,
+ DMedblue                    = 0x000099FF,
+ DGreyblue                   = 0x005DBBFF,
+ DPalegreyblue                = 0x4993DDFF,
+ DPurpleblue                 = 0x8888CCFF,
+ DNotacolor                  = 0xFFFFFF00,
+ DNofill                     = DNotacolor,
+
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + A new Image on Display d is allocated with allocimage; it will + have the rectangle, pixel channel format, and replication flag + given by its arguments. Convenient pixel channels like GREY1, + GREY2, CMAP8, RGB16, RGB24, and RGBA32 are predefined. All the + new image’s pixels will have initial value col. If col + is DNofill, no initialization is done. Representative useful values + of color are predefined: DBlack, DWhite, DRed, and so on. Colors + are specified by 32-bit numbers comprising, from most to least + significant byte, 8-bit values for red, green, blue, and alpha. + The values correspond to illumination, so 0 is black + and 255 is white. Similarly, for alpha 0 is transparent and 255 + is opaque. The id field will have been set to the identifying + number used by /dev/draw (see draw(3)), and the cache field will + be zero. If repl is true, the clip rectangle is set to a very + large region; if false, it is set to r. The depth field will be + set to the + number of bits per pixel specified by the channel descriptor (see + image(7)). Allocimage returns 0 if the server has run out of image + memory. +
+ + Allocimagemix is used to allocate background colors. On 8-bit + color-mapped displays, it returns a 2x2 replicated image with one + pixel colored the color one and the other three with three. (This + simulates a wider range of tones than can be represented by a + single pixel value on a color-mapped display.) On true color + displays, it returns a 1x1 replicated image whose pixel is the + result of mixing the two colors in a one to three ratio. +
+ + Freeimage frees the resources used by its argument image. +
+ + Nameimage publishes in the server the image i under the given + name. If in is non-zero, the image is published; otherwise i must + be already named name and it is withdrawn from publication. Namedimage + returns a reference to the image published under the given name + on Display d. These routines permit + unrelated applications sharing a display to share an image; for + example they provide the mechanism behind getwindow (see graphics(3)). + +
+ + The RGB values in a color are premultiplied by the alpha value; + for example, a 50% red is 0x7F00007F not 0xFF00007F. The function + setalpha performs the alpha computation on a given color, ignoring + its initial alpha value, multiplying the components by the supplied + alpha. For example, to make a 50% red + color value, one could execute setalpha(DRed, 0x7F). +
+ + The remaining functions deal with moving groups of pixel values + between image and user space or external files. There is a fixed + format for the exchange and storage of image data (see image(7)). + +
+ + Unloadimage reads a rectangle of pixels from image i into data, + whose length is specified by ndata. It is an error if ndata is + too small to accommodate the pixels. +
+ + Loadimage replaces the specified rectangle in image i with the + ndata bytes of data. +
+ + The pixels are presented one horizontal line at a time, starting + with the top-left pixel of r. In the data processed by these routines, + each scan line starts with a new byte in the array, leaving the + last byte of the previous line partially empty, if necessary. + Pixels are packed as tightly as possible within data, regardless + of + the rectangle being extracted. Bytes are filled from most to least + significant bit order, as the x coordinate increases, aligned + so x=0 would appear as the leftmost pixel of its byte. Thus, for + depth 1, the pixel at x offset 165 within the rectangle will be + in a data byte at bit-position 0x04 regardless of the overall + rectangle: 165 mod 8 equals 5, and 0x80 >> 5 equals 0x04. +
+ + Cloadimage does the same as loadimage, but for ndata bytes of + compressed image data (see image(7)). On each call to cloadimage, + the data must be at the beginning of a compressed data block, + in particular, it should start with the y coordinate and data + length for the block. +
+ + Loadimage, cloadimage, and unloadimage return the number of bytes + copied. +
+ + Readimage creates an image from data contained in an external + file (see image(7) for the file format); fd is a file descriptor + obtained by opening such a file for reading. The returned image + is allocated using allocimage. The dolock flag specifies whether + the Display should be synchronized for multithreaded access; + single-threaded programs can leave it zero. +
+ + Writeimage writes image i onto file descriptor fd, which should + be open for writing. The format is as described for readimage. + +
+ + Readimage and writeimage do not close fd. +
+ + Bytesperline and wordsperline return the number of bytes or words + occupied in memory by one scan line of rectangle r in an image + with d bits per pixel.
+ +
+

EXAMPLE
+ +
+ + To allocate a single-pixel replicated image that may be used to + paint a region red,
+ +
+ + red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), draw(3), image(7)
+ +
+

DIAGNOSTICS
+ +
+ + These functions return pointer 0 or integer –1 on failure, usually + due to insufficient memory. +
+ + May set errstr.
+ +
+

BUGS
+ +
+ + Depth must be a divisor or multiple of 8.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/arg.html b/man/man3/arg.html new file mode 100644 index 00000000..8ca66c80 --- /dev/null +++ b/man/man3/arg.html @@ -0,0 +1,152 @@ + +arg(3) - Plan 9 from User Space + + + + +
+
+
ARG(3)ARG(3) +
+
+

NAME
+ +
+ + ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt – process + option letters from argv
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + ARGBEGIN {
+ char *ARGF();
+ char *EARGF(code);
+ Rune ARGC();
+ } ARGEND
+ +
+ + extern char *argv0;
+ +
+

DESCRIPTION
+ +
+ + These macros assume the names argc and argv are in scope; see + exec(3). ARGBEGIN and ARGEND surround code for processing program + options. The code should be the cases of a C switch on option + characters; it is executed once for each option character. Options + end after an argument −−, before an argument −, or + before an argument that doesn’t begin with −. +
+ + The function macro ARGC returns the current option character, + as an integer. +
+ + The function macro ARGF returns the current option argument: a + pointer to the rest of the option string if not empty, or the + next argument in argv if any, or 0. ARGF must be called just once + for each option that takes an argument. The macro EARGF is like + ARGF but instead of returning zero runs code and, if that + returns, calls abort(3). A typical value for code is usage(), + as in EARGF(usage()). +
+ + After ARGBEGIN, argv0 is a copy of argv[0] (conventionally the + name of the program). +
+ + After ARGEND, argv points at a zero-terminated list of the remaining + argc arguments.
+ +
+

EXAMPLE
+ +
+ + This C program can take option b and option f, which requires + an argument.
+ +
+ + #include <u.h>
+ #include <libc.h>
+ void
+ main(int argc, char *argv[])
+ {
+ +
+ + char *f;
+ print("%s", argv[0]);
+ ARGBEGIN {
+ case 'b':
+ print(" −b");
+ break;
+ case 'f':
+ print(" −f(%s)", (f=ARGF())? f: "no arg");
+ break;
+ default:
+ print(" badflag('%c')", ARGC());
+ } ARGEND
+ print(" %d args:", argc);
+ while(*argv)
+ print(" '%s'", *argv++);
+ print("\n");
+ exits(nil);
+ +
+ }
+ +
+ + +
+ Here is the output from running the command prog −bffile1 −r −f + file2 arg1 arg2
+ +
+ + prog −b −f(file1) badflag('r') −f(file2) 2 args: 'arg1' 'arg2' + +
+ +
+ +
+ + + +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/include/libc.h
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/arith3.html b/man/man3/arith3.html new file mode 100644 index 00000000..71cf815c --- /dev/null +++ b/man/man3/arith3.html @@ -0,0 +1,216 @@ + +arith3(3) - Plan 9 from User Space + + + + +
+
+
ARITH3(3)ARITH3(3) +
+
+

NAME
+ +
+ + add3, sub3, neg3, div3, mul3, eqpt3, closept3, dot3, cross3, len3, + dist3, unit3, midpt3, lerp3, reflect3, nearseg3, pldist3, vdiv3, + vrem3, pn2f3, ppp2f3, fff2p3, pdiv4, add4, sub4 – operations on + 3-d points and planes
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + Point3 add3(Point3 a, Point3 b) +
+ + Point3 sub3(Point3 a, Point3 b) +
+ + Point3 neg3(Point3 a) +
+ + Point3 div3(Point3 a, double b) +
+ + Point3 mul3(Point3 a, double b) +
+ + int eqpt3(Point3 p, Point3 q) +
+ + int closept3(Point3 p, Point3 q, double eps) +
+ + double dot3(Point3 p, Point3 q) +
+ + Point3 cross3(Point3 p, Point3 q) +
+ + double len3(Point3 p) +
+ + double dist3(Point3 p, Point3 q) +
+ + Point3 unit3(Point3 p) +
+ + Point3 midpt3(Point3 p, Point3 q) +
+ + Point3 lerp3(Point3 p, Point3 q, double alpha) +
+ + Point3 reflect3(Point3 p, Point3 p0, Point3 p1) +
+ + Point3 nearseg3(Point3 p0, Point3 p1, Point3 testp) +
+ + double pldist3(Point3 p, Point3 p0, Point3 p1) +
+ + double vdiv3(Point3 a, Point3 b) +
+ + Point3 vrem3(Point3 a, Point3 b) +
+ + Point3 pn2f3(Point3 p, Point3 n) +
+ + Point3 ppp2f3(Point3 p0, Point3 p1, Point3 p2) +
+ + Point3 fff2p3(Point3 f0, Point3 f1, Point3 f2) +
+ + Point3 pdiv4(Point3 a) +
+ + Point3 add4(Point3 a, Point3 b) +
+ + Point3 sub4(Point3 a, Point3 b)
+ +
+

DESCRIPTION
+ +
+ + These routines do arithmetic on points and planes in affine or + projective 3-space. Type Point3 is
+ +
+ + typedef struct Point3 Point3;
+ struct Point3{
+ +
+ + double x, y, z, w;
+ +
+ };
+ +
+ + +
+ Routines whose names end in 3 operate on vectors or ordinary points + in affine 3-space, represented by their Euclidean (x,y,z) coordinates. + (They assume w=1 in their arguments, and set w=1 in their results.)
+ Name       Description
+ add3       Add the coordinates of two points.
+ sub3       Subtract coordinates of two points.
+ neg3       Negate the coordinates of a point.
+ mul3       Multiply coordinates by a scalar.
+ div3       Divide coordinates by a scalar.
+ eqpt3      Test two points for exact equality.
+ closept3   Is the distance between two points smaller than eps?
+ dot3       Dot product.
+ cross3     Cross product.
+ len3       Distance to the origin.
+ dist3      Distance between two points.
+ unit3      A unit vector parallel to p.
+ midpt3     The midpoint of line segment pq.
+ lerp3      Linear interpolation between p and q.
+ reflect3   The reflection of point p in the segment joining p0 and + p1.
+ nearseg3   The closest point to testp on segment p0 p1.
+ pldist3    The distance from p to segment p0 p1.
+ vdiv3      Vector divide -- the length of the component of a parallel + to b, in units of the length of b.
+ vrem3      Vector remainder -- the component of a perpendicular to b. + Ignoring roundoff, we have eqpt3(add3(mul3(b, vdiv3(a, b)), vrem3(a, + b)), a). +
+ + The following routines convert amongst various representations + of points and planes. Planes are represented identically to points, + by duality; a point p is on a plane q whenever p.x*q.x+p.y*q.y+p.z*q.z+p.w*q.w=0. + Although when dealing with affine points we assume p.w=1, we can’t + make the same + assumption for planes. The names of these routines are extra-cryptic. + They contain an f (for ‘face’) to indicate a plane, p for a point + and n for a normal vector. The number 2 abbreviates the word ‘to.’ + The number 3 reminds us, as before, that we’re dealing with affine + points. Thus pn2f3 takes a point and a normal + vector and returns the corresponding plane.
+ Name       Description
+ pn2f3      Compute the plane passing through p with normal n.
+ ppp2f3     Compute the plane passing through three points.
+ fff2p3     Compute the intersection point of three planes. +
+ + The names of the following routines end in 4 because they operate + on points in projective 4-space, represented by their homogeneous + coordinates.
+ pdiv4Perspective division. Divide p.w into p’s coordinates, converting + to affine coordinates. If p.w is zero, the result is the same + as the argument.
+ add4   Add the coordinates of two points.
+ sub4   Subtract the coordinates of two points.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry
+ +
+

SEE ALSO
+ +
+ + matrix(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/atof.html b/man/man3/atof.html new file mode 100644 index 00000000..ef464d0a --- /dev/null +++ b/man/man3/atof.html @@ -0,0 +1,170 @@ + +atof(3) - Plan 9 from User Space + + + + +
+
+
ATOF(3)ATOF(3) +
+
+

NAME
+ +
+ + atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, + strtoull – convert text to numbers
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + double atof(char *nptr)
+ +
+ + int      atoi(char *nptr)
+ +
+ + long     atol(char *nptr)
+ +
+ + vlong    atoll(char *nptr)
+ +
+ + double charstod(int (*f)(void *), void *a)
+ +
+ + double strtod(char *nptr, char **rptr)
+ +
+ + long     strtol(char *nptr, char **rptr, int base)
+ +
+ + vlong    strtoll(char *nptr, char **rptr, int base)
+ +
+ + ulong    strtoul(char *nptr, char **rptr, int base)
+ +
+ + vlong    strtoull(char *nptr, char **rptr, int base)
+ +
+

DESCRIPTION
+ +
+ + Atof, atoi, atol, and atoll convert a string pointed to by nptr + to floating, integer, long integer, and long long integer (vlong) + representation respectively. The first unrecognized character + ends the string. Leading C escapes are understood, as in strtol + with base zero (described below). +
+ + Atof recognizes an optional string of tabs and spaces, then an + optional sign, then a string of digits optionally containing a + decimal point, then an optional e or E followed by an optionally + signed integer. +
+ + Atoi and atol recognize an optional string of tabs and spaces, + then an optional sign, then a string of decimal digits. +
+ + Strtod, strtol, strtoll, strtoul, and strtoull behave similarly + to atof and atol and, if rptr is not zero, set *rptr to point + to the input character immediately after the string converted. + +
+ + Strtol, strtoll, strtoul, and strtoull interpret the digit string + in the specified base, from 2 to 36, each digit being less than + the base. Digits with value over 9 are represented by letters, + a-z or A-Z. If base is 0, the input is interpreted as an integral + constant in the style of C (with no suffixed type indicators): + numbers are + octal if they begin with 0, hexadecimal if they begin with 0x + or 0X, otherwise decimal. +
+ + Charstod interprets floating point numbers in the manner of atof, + but gets successive characters by calling (*f)(a). The last call + to f terminates the scan, so it must have returned a character + that is not a legal continuation of a number. Therefore, it may + be necessary to back up the input stream one character after + calling charstod.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + fscanf(3)
+ +
+

DIAGNOSTICS
+ +
+ + Zero is returned if the beginning of the input string is not interpretable + as a number; even in this case, rptr will be updated.
+ These routines set errstr.
+ +
+

BUGS
+ +
+ + Atoi and atol accept octal and hexadecimal numbers in the style + of C, contrary to the ANSI specification. +
+ + Atof, strtod, strtol, strtoul, strtoll, and strtoull are not provided: + they are expected to be provided by the underlying system. +
+ + Because they are implemented in the fmt library, charstod and + strtod are preprocessor macros defined as fmtcharstod and fmtstrtod. + +
+ + To avoid name conflicts with the underlying system, atoi, atol, + and atoll are preprocessor macros defined as p9atoi, p9atol, and + p9atoll; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/bin.html b/man/man3/bin.html new file mode 100644 index 00000000..f016622f --- /dev/null +++ b/man/man3/bin.html @@ -0,0 +1,131 @@ + +bin(3) - Plan 9 from User Space + + + + +
+
+
BIN(3)BIN(3) +
+
+

NAME
+ +
+ + binalloc, bingrow, binfree – grouped memory allocation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <bin.h> +
+ + +
+ + typedef struct BinBin; +
+ + void    *binalloc(Bin **bp, ulong size, int clr); +
+ + void    *bingrow(Bin **bp, void *op, ulong osize,
+ +
+ + +
+ + ulong size, int clr); +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    binfree(Bin **bp);
+ +
+

DESCRIPTION
+ +
+ + These routines provide simple grouped memory allocation and deallocation. + Items allocated with binalloc are added to the Bin pointed to + by bp. All items in a bin may be freed with one call to binfree; + there is no way to free a single item. +
+ + Binalloc returns a pointer to a new block of at least size bytes. + The block is suitably aligned for storage of any type of object. + No two active pointers from binalloc will have the same value. + The call binalloc(0) returns a valid pointer rather than null. + If clr is non-zero, the allocated memory is set to 0; otherwise, + the contents are undefined. +
+ + Bingrow is used to extend the size of a block of memory returned + by binalloc. Bp must point to the same bin group used to allocate + the original block, and osize must be the last size used to allocate + or grow the block. A pointer to a block of at least size bytes + is returned, with the same contents in the first osize + locations. If clr is non-zero, the remaining bytes are set to + 0, and are undefined otherwise. If op is nil, it and osize are + ignored, and the result is the same as calling binalloc. +
+ + Binalloc and bingrow allocate large chunks of memory using malloc(3) + and return pieces of these chunks. The chunks are free’d upon + a call to binfree.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libbin
+ +
+

SEE ALSO
+ +
+ + malloc(3)
+ +
+

DIAGNOSTICS
+ +
+ + binalloc and bingrow return 0 if there is no available memory.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/bio.html b/man/man3/bio.html new file mode 100644 index 00000000..78259922 --- /dev/null +++ b/man/man3/bio.html @@ -0,0 +1,293 @@ + +bio(3) - Plan 9 from User Space + + + + +
+
+
BIO(3)BIO(3) +
+
+

NAME
+ +
+ + Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, + Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, + Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered + – buffered input/output
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <bio.h> +
+ + Biobuf* Bopen(char *file, int mode) +
+ + Biobuf* Bfdopen(int fd, int mode) +
+ + int       Binit(Biobuf *bp, int fd, int mode) +
+ + int       Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) + +
+ + int       Bterm(Biobufhdr *bp) +
+ + int       Bprint(Biobufhdr *bp, char *format, ...) +
+ + int       Bvprint(Biobufhdr *bp, char *format, va_list arglist); +
+ + void*     Brdline(Biobufhdr *bp, int delim) +
+ + char*     Brdstr(Biobufhdr *bp, int delim, int nulldelim) +
+ + int       Blinelen(Biobufhdr *bp) +
+ + vlong     Boffset(Biobufhdr *bp) +
+ + int       Bfildes(Biobufhdr *bp) +
+ + int       Bgetc(Biobufhdr *bp) +
+ + long      Bgetrune(Biobufhdr *bp) +
+ + int       Bgetd(Biobufhdr *bp, double *d) +
+ + int       Bungetc(Biobufhdr *bp) +
+ + int       Bungetrune(Biobufhdr *bp) +
+ + vlong     Bseek(Biobufhdr *bp, vlong n, int type) +
+ + int       Bputc(Biobufhdr *bp, int c) +
+ + int       Bputrune(Biobufhdr *bp, long c) +
+ + long      Bread(Biobufhdr *bp, void *addr, long nbytes) +
+ + long      Bwrite(Biobufhdr *bp, void *addr, long nbytes) +
+ + int       Bflush(Biobufhdr *bp) +
+ + int       Bbuffered(Biobufhdr *bp) +
+ + +
+

DESCRIPTION
+ +
+ + These routines implement fast buffered I/O. I/O on different file + descriptors is independent. +
+ + Bopen opens file for mode OREAD or creates for mode OWRITE. It + calls malloc(3) to allocate a buffer. +
+ + Bfdopen allocates a buffer for the already-open file descriptor + fd for mode OREAD or OWRITE. It calls malloc(3) to allocate a + buffer. +
+ + Binit initializes a standard size buffer, type Biobuf, with the + open file descriptor passed in by the user. Binits initializes + a non-standard size buffer, type Biobufhdr, with the open file + descriptor, buffer area, and buffer size passed in by the user. + Biobuf and Biobufhdr are related by the declaration: + +
+ + typedef struct Biobuf Biobuf;
+ struct Biobuf
+ {
+ +
+ + Biobufhdr;
+ uchar b[Bungetsize+Bsize];
+ +
+ };
+ +
+ + +
+ Arguments of types pointer to Biobuf and pointer to Biobufhdr + can be used interchangeably in the following routines. +
+ + Bopen, Binit, or Binits should be called before any of the other + routines on that buffer. Bfildes returns the integer file descriptor + of the associated open file. +
+ + Bterm flushes the buffer for bp. If the buffer was allocated by + Bopen, the buffer is freed and the file is closed. +
+ + Brdline reads a string from the file associated with bp up to + and including the first delim character. The delimiter character + at the end of the line is not altered. Brdline returns a pointer + to the start of the line or 0 on end-of-file or read error. Blinelen + returns the length (including the delimiter) of the most recent + string + returned by Brdline. +
+ + Brdstr returns a malloc(3)-allocated buffer containing the next + line of input delimited by delim, terminated by a NUL (0) byte. + Unlike Brdline, which returns when its buffer is full even if + no delimiter has been found, Brdstr will return an arbitrarily + long line in a single call. If nulldelim is set, the terminal + delimiter will be + overwritten with a NUL. After a successful call to Brdstr, the + return value of Blinelen will be the length of the returned buffer, + excluding the NUL. +
+ + Bgetc returns the next character from bp, or a negative value + at end of file. Bungetc may be called immediately after Bgetc + to allow the same character to be reread. +
+ + Bgetrune calls Bgetc to read the bytes of the next UTF sequence + in the input stream and returns the value of the rune represented + by the sequence. It returns a negative value at end of file. Bungetrune + may be called immediately after Bgetrune to allow the same UTF + sequence to be reread as either bytes or a rune. + Bungetc and Bungetrune may back up a maximum of five bytes. +
+ + Bgetd uses charstod (see atof(3)) and Bgetc to read the formatted + floating-point number in the input stream, skipping initial blanks + and tabs. The value is stored in *d. +
+ + Bread reads nbytes of data from bp into memory starting at addr. + The number of bytes read is returned on success and a negative + value is returned if a read error occurred. +
+ + Bseek applies seek(3) to bp. It returns the new file offset. Boffset + returns the file offset of the next character to be processed. + +
+ + Bputc outputs the low order 8 bits of c on bp. If this causes + a write to occur and there is an error, a negative value is returned. + Otherwise, a zero is returned. +
+ + Bputrune calls Bputc to output the low order 16 bits of c as a + rune in UTF format on the output stream. +
+ + Bprint is a buffered interface to print(3). If this causes a write + to occur and there is an error, a negative value (Beof) is returned. + Otherwise, the number of bytes output is returned. Bvprint does + the same except it takes as argument a va_list parameter, so it + can be called within a variadic function. +
+ + Bwrite outputs nbytes of data starting at addr to bp. If this + causes a write to occur and there is an error, a negative value + is returned. Otherwise, the number of bytes written is returned. + +
+ + Bflush causes any buffered output associated with bp to be written. + The return is as for Bputc. Bflush is called on exit for every + buffer still open for writing. +
+ + Bbuffered returns the number of bytes in the buffer. When reading, + this is the number of bytes still available from the last read + on the file; when writing, it is the number of bytes ready to + be written.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libbio
+ +
+

SEE ALSO
+ +
+ + open(3), print(3), exits(3), utf(7),
+ +
+

DIAGNOSTICS
+ +
+ + Bio routines that return integers yield Beof if bp is not the + descriptor of an open file. Bopen returns zero if the file cannot + be opened in the given mode. All routines set errstr on error.
+ +
+

BUGS
+ +
+ + Brdline returns an error on strings longer than the buffer associated + with the file and also if the end-of-file is encountered before + a delimiter. Blinelen will tell how many characters are available + in these cases. In the case of a true end-of-file, Blinelen will + return zero. At the cost of allocating a buffer, Brdstr sidesteps + these issues. +
+ + The data returned by Brdline may be overwritten by calls to any + other bio routine on the same bp.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/blowfish.html b/man/man3/blowfish.html new file mode 100644 index 00000000..d8da66de --- /dev/null +++ b/man/man3/blowfish.html @@ -0,0 +1,95 @@ + +blowfish(3) - Plan 9 from User Space + + + + +
+
+
BLOWFISH(3)BLOWFISH(3) +
+
+

NAME
+ +
+ + setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt + - blowfish encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupBFstate(BFstate *s, uchar key[], int keybytes,                  uchar + *ivec) +
+ + void bfCBCencrypt(uchar *data, int len, BFstate *s) +
+ + void bfCBCdecrypt(uchar *data, int len, BFstate *s) +
+ + void bfECBencrypt(uchar *data, int len, BFstate *s) +
+ + void bfECBdecrypt(uchar *data, int len, BFstate *s)
+ +
+

DESCRIPTION
+ +
+ + +
+ + Blowfish is Bruce Schneier’s symmetric block cipher. It supports + variable length keys from 32 to 448 bits and has a block size + of 64 bits. Both CBC and ECB modes are supported. +
+ + setupBFstate takes a BFstate structure, a key of at most 56 bytes, + the length of the key in bytes, and an initialization vector of + 8 bytes (set to all zeroes if argument is nil). The encryption + and decryption functions take a BFstate structure, a data buffer, + and a length, which must be a multiple of eight bytes as padding + is + currently unsupported.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), des(3), dsa(3), elgamal(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cachechars.html b/man/man3/cachechars.html new file mode 100644 index 00000000..382b5e7e --- /dev/null +++ b/man/man3/cachechars.html @@ -0,0 +1,292 @@ + +cachechars(3) - Plan 9 from User Space + + + + +
+
+
CACHECHARS(3)CACHECHARS(3) +
+
+

NAME
+ +
+ + cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + +
+ + int    cachechars(Font *f, char **s, Rune **r, ushort *c, int max, + +
+ + +
+ + +
+ + int *widp, char **sfname) +
+ + +
+ +
+ int    loadchar(Font *f, Rune r, Cacheinfo *c, int h, +
+ + +
+ + +
+ + int noclr, char **sfname) +
+ + +
+ +
+ void agefont(Font *f)
+ +
+

DESCRIPTION
+ +
+ + A Font may contain too many characters to hold in memory simultaneously. + The graphics library and draw device (see draw(3)) cooperate to + solve this problem by maintaining a cache of recently used character + images. The details of this cooperation need not be known by most + programs: initdraw and its associated + font variable, openfont, stringwidth, string, and freefont are + sufficient for most purposes. The routines described below are + used internally by the graphics library to maintain the font cache. + +
+ + A Subfont is a set of images for a contiguous range of characters, + stored as a single image with the characters placed side-by-side + on a common baseline. It is described by the following data structures.
+ +
+ + typedef
+ struct Fontchar {
+ +
+ + int        x;          /* left edge of bits */
+ uchar      top;        /* first non−zero scan−line */
+ uchar      bottom;     /* last non−zero scan−line */
+ char       left;       /* offset of baseline */
+ uchar      width;      /* width of baseline */
+ +
+ } Fontchar;
+ typedef
+ struct Subfont {
+ +
+ + char       *name;
+ short      n;          /* number of chars in subfont */
+ uchar      height;     /* height of image */
+ char       ascent;     /* top of image to baseline */
+ Fontchar *info;      /* n+1 Fontchars */
+ Image      *bits;      /* of font */
+ +
+ } Subfont;
+ +
+ + +
+ The image fills the rectangle (0, 0, w, height), where w is the + sum of the horizontal extents (of non-zero pixels) for all characters. + The pixels to be displayed for character c are in the rectangle + (i−>x, i−>top, (i+1)−>x, i−>bottom) where i is &subfont−>info[c]. When + a character is displayed + at Point p in an image, the character rectangle is placed at (p.x+i−>left, + p.y) and the next character of the string is displayed at (p.x+i−>width, + p.y). The baseline of the characters is ascent rows down from + the top of the subfont image. The info array has n+1 elements, + one each for characters 0 + to n−1 plus an additional entry so the size of the last character + can be calculated. Thus the width, w, of the Image associated + with a Subfont s is s−>info[s−>n].x. +
+ + A Font consists of an overall height and ascent and a collection + of subfonts together with the ranges of runes (see utf(7)) they + represent. Fonts are described by the following structures.
+ +
+ + typedef
+ struct Cachefont {
+ +
+ + Rune        min;        /* value of 0th char in subfont */
+ Rune        max;        /* value+1 of last char in subfont */
+ int         offset;     /* posn in subfont of char at min */
+ char        *name;      /* stored in font */
+ char        *subfontname;/* to access subfont */
+ +
+ } Cachefont;
+ typedef
+ struct Cacheinfo {
+ +
+ + ushort      x;          /* left edge of bits */
+ uchar       width;      /* width of baseline */
+ schar       left;       /* offset of baseline */
+ Rune        value;      /* of char at this slot in cache */
+ ushort      age;
+ +
+ } Cacheinfo;
+ typedef
+ struct Cachesubf {
+ +
+ + ulong       age;        /* for replacement */
+ Cachefont *cf;        /* font info that owns us */
+ Subfont     *f;         /* attached subfont */
+ +
+ } Cachesubf;
+ typedef
+ struct Font {
+ +
+ + char        *name;
+ Display     *display;
+ short       height;     /* max ht of image;interline space*/
+ short       ascent;     /* top of image to baseline */
+ short       width;      /* widest so far; used in caching */
+ short       nsub;       /* number of subfonts */
+ ulong       age;        /* increasing counter; for LRU */
+ int         ncache;     /* size of cache */
+ int         nsubf;      /* size of subfont list */
+ Cacheinfo *cache;
+ Cachesubf *subf;
+ Cachefont **sub;      /* as read from file */
+ Image       *cacheimage;
+ +
+ } Font;
+ +
+ + +
+ The height and ascent fields of Font are described in graphics(3). + Sub contains nsub pointers to Cachefonts. A Cachefont connects + runes min through max, inclusive, to the subfont with file name + name; it corresponds to a line of the file describing the font. + +
+ + The characters are taken from the subfont starting at character + number offset (usually zero) in the subfont, permitting selection + of parts of subfonts. Thus the image for rune r is found in position + r−min+offset of the subfont. +
+ + For each font, the library, with support from the graphics server, + maintains a cache of subfonts and a cache of recently used character + images. The subf and cache fields are used by the library to maintain + these caches. The width of a font is the maximum of the horizontal + extents of the characters in the cache. + String draws a string by loading the cache and emitting a sequence + of cache indices to draw. Cachechars guarantees the images for + the characters pointed to by *s or *r (one of these must be nil + in each call) are in the cache of f. It calls loadchar to put + missing characters into the cache. Cachechars translates the + character string into a set of cache indices which it loads into + the array c, up to a maximum of n indices or the length of the + string. Cachechars returns in c the number of cache indices emitted, + updates *s to point to the next character to be processed, and + sets *widp to the total width of the characters processed. + Cachechars may return before the end of the string if it cannot + proceed without destroying active data in the caches. If it needs + to load a new subfont, it will fill *sfname with the name of the + subfont it needs and return –1. It can return zero if it is unable + to make progress because it cannot resize the caches. +
+ + Loadchar loads a character image into the character cache. Then + it tells the graphics server to copy the character into position + h in the character cache. If the current font width is smaller + than the horizontal extent of the character being loaded, loadfont + clears the cache and resets it to accept characters with the + bigger width, unless noclr is set, in which case it just returns + –1. If the character does not exist in the font at all, loadfont + returns 0; if it is unable to load the character without destroying + cached information, it returns –1, updating *sfname as described + above. It returns 1 to indicate success. +
+ + The age fields record when subfonts and characters have been used. + The font age is increased every time the font is used (agefont + does this). A character or subfont age is set to the font age + at each use. Thus, characters or subfonts with small ages are + the best candidates for replacement when the cache is full. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), subfont(3), image(7), font(7)
+ +
+

DIAGNOSTICS
+ +
+ + All of the functions use the graphics error function (see graphics(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cleanname.html b/man/man3/cleanname.html new file mode 100644 index 00000000..eba39965 --- /dev/null +++ b/man/man3/cleanname.html @@ -0,0 +1,71 @@ + +cleanname(3) - Plan 9 from User Space + + + + +
+
+
CLEANNAME(3)CLEANNAME(3) +
+
+

NAME
+ +
+ + cleanname – clean a path name
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ char*       cleanname(char *filename)
+ +
+

DESCRIPTION
+ +
+ + Cleanname takes a filename and by lexical processing only returns + the shortest string that names the same (possibly hypothetical) + file. It eliminates multiple and trailing slashes, and it lexically + interprets . and .. directory components in the name. The string + is overwritten in place. +
+ + The shortest string cleanname can return is two bytes: the null-terminated + string ".". Therefore filename must contain room for at least two + bytes.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/cleanname.c
+ +
+

SEE ALSO
+ +
+ + cleanname(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/color.html b/man/man3/color.html new file mode 100644 index 00000000..a8274707 --- /dev/null +++ b/man/man3/color.html @@ -0,0 +1,89 @@ + +color(3) - Plan 9 from User Space + + + + +
+
+
COLOR(3)COLOR(3) +
+
+

NAME
+ +
+ + cmap2rgb, cmap2rgba, rgb2cmap – colors and color maps
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + int    rgb2cmap(int red, int green, int blue) +
+ + int    cmap2rgb(int col) +
+ + int    cmap2rgba(int col)
+ +
+

DESCRIPTION
+ +
+ + These routines convert between ‘true color’ red/green/blue triples + and the Plan 9 color map. See color(7) for a description of RGBV, + the standard color map. +
+ + Rgb2cmap takes a trio of color values, scaled from 0 (no intensity) + to 255 (full intensity), and returns the index of the color in + RGBV closest to that represented by those values. +
+ + Cmap2rgb decomposes the color of RGBV index col and returns a + 24-bit integer with the low 8 bits representing the blue value, + the next 8 representing green, and the next 8 representing red. + Cmap2rgba decomposes the color of RGBV index col and returns a + 32-bit integer with the low 8 bits representing an alpha + value, defined to be 255, and the next 8 representing blue, then + green, then red, as for cmap2rgba shifted up 8 bits. This 32-bit + representation is the format used by draw(3) and memdraw(3) library + routines that take colors as arguments.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), image(7), color(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/complete.html b/man/man3/complete.html new file mode 100644 index 00000000..29453752 --- /dev/null +++ b/man/man3/complete.html @@ -0,0 +1,136 @@ + +complete(3) - Plan 9 from User Space + + + + +
+
+
COMPLETE(3)COMPLETE(3) +
+
+

NAME
+ +
+ + complete, freecompletion – file name completion
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <complete.h> +
+ + typedef struct CompletionCompletion;
+ struct Completion{
+ +
+ + uchar advance;
+ uchar complete;
+ char *string;
+ int nmatch;
+ int nfile;
+ char **filename;
+ +
+ };
+ +
+ + +
+ + Completion* complete(char *dir, char *s); +
+ + void freecompletion(Completion *c);
+ +
+

DESCRIPTION
+ +
+ + The complete function implements file name completion. Given a + directory dir and a string s, it returns an analysis of the file + names in that directory that begin with the string s. The fields + nmatch and nfile will be set to the number of files that match + the prefix and filename will be filled in with their names. If + the file named is a directory, a slash character will be appended + to it. +
+ + If no files match the string, nmatch will be zero, but complete + will return the full set of files in the directory, with nfile + set to their number. +
+ + The flag advance reports whether the string s can be extended + without changing the set of files that match. If true, string + will be set to the extension; that is, the value of string may + be appended to s by the caller to extend the embryonic file name + unambiguously. +
+ + The flag complete reports whether the extended file name uniquely + identifies a file. If true, string will be suffixed with a blank, + or a slash and a blank, depending on whether the resulting file + name identifies a plain file or a directory. +
+ + The freecompletion function frees a Completion structure and its + contents. +
+ + In rio(1) and acme(1), file name completion is triggered by a + control-F character or an Insert character.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libcomplete
+ +
+

SEE ALSO
+ +
+ + rio(1), acme(1)
+ +
+

DIAGNOSTICS
+ +
+ + The complete function returns a null pointer and sets errstr if + the directory is unreadable or there is some other error.
+ +
+

BUGS
+ +
+ + The behavior of file name completion should be controlled by the + plumber.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cputime.html b/man/man3/cputime.html new file mode 100644 index 00000000..fafc7f57 --- /dev/null +++ b/man/man3/cputime.html @@ -0,0 +1,65 @@ + +cputime(3) - Plan 9 from User Space + + + + +
+
+
CPUTIME(3)CPUTIME(3) +
+
+

NAME
+ +
+ + cputime, times – cpu time in this process and children
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      times(long t[4]) +
+ + double cputime(void)
+ +
+

DESCRIPTION
+ +
+ + If t is non-null, times fills it in with the number of milliseconds + spent in user code, system calls, child processes in user code, + and child processes in system calls. Cputime returns the sum of + those same times, converted to seconds. Times returns the elapsed + real time, in milliseconds, that the process has been + running.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/time.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ctime.html b/man/man3/ctime.html new file mode 100644 index 00000000..4c162391 --- /dev/null +++ b/man/man3/ctime.html @@ -0,0 +1,150 @@ + +ctime(3) - Plan 9 from User Space + + + + +
+
+
CTIME(3)CTIME(3) +
+
+

NAME
+ +
+ + ctime, localtime, gmtime, asctime, tm2sec, timezone – convert date + and time
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* ctime(long clock) +
+ + Tm*     localtime(long clock) +
+ + Tm*     gmtime(long clock) +
+ + char* asctime(Tm *tm) +
+ + long    tm2sec(Tm *tm)
+ +
+

DESCRIPTION
+ +
+ + Ctime converts a time clock such as returned by time(3) into ASCII + (sic) and returns a pointer to a 30-byte string in the following + form. All the fields have constant width. +
+ + +
+ + +
+ + Wed Aug    5 01:07:47 EST 1973\n\0 +
+ + +
+ +
+ Localtime and gmtime return pointers to structures containing + the broken-down time. Localtime corrects for the time zone and + possible daylight savings time; gmtime converts directly to GMT. + Asctime converts a broken-down time to ASCII and returns a pointer + to a 30-byte string.
+ +
+ + typedef
+ struct {
+ +
+ + int    sec;          /* seconds (range 0..59) */
+ int    min;          /* minutes (0..59) */
+ int    hour;         /* hours (0..23) */
+ int    mday;         /* day of the month (1..31) */
+ int    mon;          /* month of the year (0..11) */
+ int    year;         /* year A.D. – 1900 */
+ int    wday;         /* day of week (0..6, Sunday = 0) */
+ int    yday;         /* day of year (0..365) */
+ char zone[4];      /* time zone name */
+ int    tzoff;        /* time zone delta from GMT */
+ +
+ } Tm;
+ +
+ + +
+ Tm2sec converts a broken-down time to seconds since the start + of the epoch. It ignores wday, and assumes the local time zone + if zone is not GMT.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/date.c
+ /usr/local/plan9/src/lib9/ctime.c
+ +
+

SEE ALSO
+ +
+ + date(1), time(3)
+ +
+

BUGS
+ +
+ + The return values point to static data whose content is overwritten + by each call. +
+ + Daylight Savings Time is “normal” in the Southern hemisphere. + +
+ + These routines are not equipped to handle non-ASCII text, and + are provincial anyway. +
+ + To avoid name conflicts with the underlying system, ctime, localtime, + gmtime, asctime, and tm2sec are preprocessor macros defined as + p9ctime, p9localtime, p9gmtime, p9asctime, and p9tm2sec; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/des.html b/man/man3/des.html new file mode 100644 index 00000000..0752e8c8 --- /dev/null +++ b/man/man3/des.html @@ -0,0 +1,170 @@ + +des(3) - Plan 9 from User Space + + + + +
+
+
DES(3)DES(3) +
+
+

NAME
+ +
+ + setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, + desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, + des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, + setupDES3state, triple_block_cipher, - single and triple digital + encryption standard + +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void des_key_setup(uchar key[8], ulong schedule[32]) +
+ + void block_cipher(ulong *schedule, uchar *data,            int decrypting) + +
+ + void setupDESstate(DESstate *s, uchar key[8], uchar *ivec) +
+ + void desCBCencrypt(uchar*, int, DESstate*) +
+ + void desCBCdecrypt(uchar*, int, DESstate*) +
+ + void desECBencrypt(uchar*, int, DESstate*) +
+ + void desECBdecrypt(uchar*, int, DESstate*) +
+ + void triple_block_cipher(ulong keys[3][32], uchar*, int) +
+ + void setupDES3state(DES3state *s, uchar key[3][8],                  uchar *ivec) + +
+ + void des3CBCencrypt(uchar*, int, DES3state*) +
+ + void des3CBCdecrypt(uchar*, int, DES3state*) +
+ + void des3ECBencrypt(uchar*, int, DES3state*) +
+ + void des3ECBdecrypt(uchar*, int, DES3state*) +
+ + void key_setup(uchar[7], ulong[32]) +
+ + void des56to64(uchar *k56, uchar *k64) +
+ + void des64to56(uchar *k64, uchar *k56)
+ +
+

DESCRIPTION
+ +
+ + +
+ + The Digital Encryption Standard (DES) is a shared key or symmetric + encryption using either a 56 bit key for single DES or three 56 + bit keys for triple des. The keys are encoded into 64 bits where + every eight bit is parity. +
+ + The basic DES function, block_cipher, works on a block of 8 bytes, + converting them in place. It takes a key schedule, a pointer to + the block, and a flag indicating encrypting (0) or decrypting + (1). The key schedule is created from the key using des_key_setup. + +
+ + Since it is a bit awkward, block_cipher is rarely called directly. + Instead, one normally uses routines that encrypt larger buffers + of data and which may chain the encryption state from one buffer + to the next. These routines keep track of the state of the encryption + using a DESstate structure that contains the key + schedule and any chained state. SetupDESstate sets up the DESstate + structure using the key and an 8 byte initialization vector. +
+ + Electronic code book, using desECBencrypt and desECBdecrypt, is + the less secure mode. The encryption of each 8 bytes does not + depend on the encryption of any other. Hence the encryption is + a substitution cipher using 64 bit characters. +
+ + Cipher block chaining mode, using desCBCencrypt and desCBCdecrypt, + is more secure. Every block encrypted depends on the initialization + vector and all blocks encrypted before it. +
+ + For both CBC and ECB modes, a stream of data can be encrypted + as multiple buffers. However, all buffers except the last must + be a multiple of 8 bytes to ensure successful decryption of the + stream. +
+ + There are equivalent triple DES functions for each of the DES + functions. +
+ + In the past Plan 9 used a 56 bit or 7 byte format for DES keys. + To be compatible with the rest of the world, we’ve abandoned this + format. There are two functions: des56to64 and des64to56 to convert + back and forth between the two formats. Also a key schedule can + be set up from the 7 byte format using key_setup. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), dsa(3), elgamal(3), rc4(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dial.html b/man/man3/dial.html new file mode 100644 index 00000000..e1014859 --- /dev/null +++ b/man/man3/dial.html @@ -0,0 +1,241 @@ + +dial(3) - Plan 9 from User Space + + + + +
+
+
DIAL(3)DIAL(3) +
+
+

NAME
+ +
+ + dial, announce, listen, accept, reject, netmkaddr, dialparse – + make and break network connections
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int     dial(char *addr, char *local, char *dir, int *cfdp) +
+ + int     announce(char *addr, char *dir) +
+ + int     listen(char *dir, char *newdir) +
+ + int     accept(int ctl, char *dir) +
+ + int     reject(int ctl, char *dir, char *cause) +
+ + char* netmkaddr(char *addr, char *defnet, char *defservice) +
+ + int     dialparse(char *addr, char **net, char **unix,
+ +
+ + +
+ + u32int *host, int *port)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + For these routines, addr is a network address of the form network!netaddr!service, + network!netaddr, or simply netaddr. Network is tcp, udp, unix, + or the special token, net. Net is a free variable that stands + for any network in common between the source and the host netaddr. + Netaddr can be a host name, a + domain name, or a network address. +
+ + On Plan 9, the dir argument is a path name to a line directory + that has files for accessing the connection. To keep the same + function signatures, the Unix port of these routines uses strings + of the form /dev/fd/n instead of line directory paths. These strings + should be treated as opaque data and ignored. +
+ + Dial makes a call to destination addr on a multiplexed network. + If the network in addr is net, dial will try in succession all + networks in common between source and destination until a call + succeeds. It returns a file descriptor open for reading and writing + the data file in the line directory. The addr file in the line + directory contains the address called. Dial’s local, dir, and + cfdp arguments are not supported and must be zero. +
+ + Announce and listen are the complements of dial. Announce establishes + a network name to which calls can be made. Like dial, announce + returns an open ctl file. The netaddr used in announce may be + a local address or an asterisk, to indicate all local addresses, + e.g. tcp!*!echo. The listen routine takes as its + first argument the dir of a previous announce. When a call is + received, listen returns an open ctl file for the line the call + was received on. It sets newdir to the path name of the new line + directory. Accept accepts a call received by listen, while reject + refuses the call because of cause. Accept returns a file descriptor + for + the data file opened ORDWR. +
+ + Netmkaddr makes an address suitable for dialing or announcing. + It takes an address along with a default network and service to + use if they are not specified in the address. It returns a pointer + to static data holding the actual address to use. +
+ + Dialparse parses a network address as described above into a network + name, a Unix domain socket address, an IPv4 host address, and + an IPv4 port number.
+ +
+

EXAMPLES
+ +
+ + Make a call and return an open file descriptor to use for communications:
+ +
+ + int callkremvax(void)
+ {
+ +
+ + return dial("kremvax", 0, 0, 0);
+ +
+ }
+ +
+ + +
+ Connect to a Unix socket served by acme(4):
+ +
+ + int dialacme(void)
+ {
+ +
+ + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
+ +
+ }
+ +
+ + +
+ Announce as kremvax on TCP/IP and loop forever receiving calls + and echoing back to the caller anything sent:
+ +
+ + int
+ bekremvax(void)
+ {
+ +
+ + int dfd, acfd, lcfd;
+ char adir[40], ldir[40];
+ int n;
+ char buf[256];
+ acfd = announce("tcp!*!7", adir);
+ if(acfd < 0)
+ return −1;
+ for(;;){
+ /* listen for a call */
+ lcfd = listen(adir, ldir);
+ if(lcfd < 0)
+ return −1;
+ /* fork a process to echo */
+ switch(fork()){
+ case −1:
+ perror("forking");
+ close(lcfd);
+ break;
+ case 0:
+ /* accept the call and open the data file */
+ dfd = accept(lcfd, ldir);
+ if(dfd < 0)
+ return −1;
+ /* echo until EOF */
+ while((n = read(dfd, buf, sizeof(buf))) > 0)
+ write(dfd, buf, n);
+ exits(0);
+ default:
+ close(lcfd);
+ break;
+ }
+ }
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dial.c
+ /usr/local/plan9/src/lib9/announce.c
+ /usr/local/plan9/src/lib9/_p9dialparse.c
+ +
+

DIAGNOSTICS
+ +
+ + Dial, announce, and listen return –1 if they fail.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, dial, announce, + listen, netmkaddr, and reject are preprocessor macros defined + as p9dial, p9announce, and so on; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dirread.html b/man/man3/dirread.html new file mode 100644 index 00000000..7c5ba4ed --- /dev/null +++ b/man/man3/dirread.html @@ -0,0 +1,114 @@ + +dirread(3) - Plan 9 from User Space + + + + +
+
+
DIRREAD(3)DIRREAD(3) +
+
+

NAME
+ +
+ + dirread, dirreadall – read directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long dirread(int fd, Dir **buf) +
+ + long dirreadall(int fd, Dir **buf) +
+ + #define     STATMAX     65535U +
+ + #define     DIRMAX      (sizeof(Dir)+STATMAX)
+ +
+

DESCRIPTION
+ +
+ + The data returned by a read(3) on a directory is a set of complete + directory entries in a machine-independent format, exactly equivalent + to the result of a stat(3) on each file or subdirectory in the + directory. Dirread decodes the directory entries into a machine-dependent + form. It reads from fd and unpacks the data + into an array of Dir structures whose address is returned in *buf + (see stat(3) for the layout of a Dir). The array is allocated + with malloc(3) each time dirread is called. +
+ + Dirreadall is like dirread, but reads in the entire directory; + by contrast, dirread steps through a directory one read(3) at + a time. +
+ + Directory entries have variable length. A successful read of a + directory always returns an integral number of complete directory + entries; dirread always returns complete Dir structures. See read(9p) + for more information. +
+ + The constant STATMAX is the maximum size that a directory entry + can occupy. The constant DIRMAX is an upper limit on the size + necessary to hold a Dir structure and all the associated data. + +
+ + Dirread and dirreadall return the number of Dir structures filled + in buf. The file offset is advanced by the number of bytes actually + read.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dirread.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3), read(3)
+ +
+

DIAGNOSTICS
+ +
+ + Dirread and Dirreadall return zero for end of file and a negative + value for error. In either case, *buf is set to nil so the pointer + can always be freed with impunity. +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/draw.html b/man/man3/draw.html new file mode 100644 index 00000000..f90b16fc --- /dev/null +++ b/man/man3/draw.html @@ -0,0 +1,1174 @@ + +draw(3) - Plan 9 from User Space + + + + +
+
+
DRAW(3)DRAW(3) +
+
+

NAME
+ +
+ + Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl, + replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, + bezierop, bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop, + fillbezspline, fillbezsplineop, ellipse, ellipseop, fillellipse, + fillellipseop, arc, arcop, fillarc, fillarcop, icossin, icossin2, + border, string, stringop, stringn, stringnop, runestring, runestringop, + runestringn, runestringnop, stringbg, stringbgop, stringnbg, stringnbgop, + runestringbg, runestringbgop, runestringnbg, runestringnbgop, + _string, ARROW, drawsetdebug – graphics functions
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + typedef
+ struct Image
+ {
+ +
+ + Display     *display; /* display holding data */
+ int         id;         /* id of system−held Image */
+ Rectangle r;          /* rectangle in data area, local coords */
+ Rectangle clipr;      /* clipping region */
+ ulong       chan;       /* pixel channel format descriptor */
+ int         depth;      /* number of bits per pixel */
+ int         repl;       /* flag: data replicates to tile clipr */
+ Screen      *screen;    /* 0 if not a window */
+ Image       *next;      /* next in list of windows */
+ +
+ } Image;
+ +
+ + typedef enum
+ {
+ +
+ + /* Porter−Duff compositing operators */
+ Clear       = 0,
+ SinD = 8,
+ DinS = 4,
+ SoutD       = 2,
+ DoutS       = 1,
+ S          = SinD|SoutD,
+ SoverD      = SinD|SoutD|DoutS,
+ SatopD      = SinD|DoutS,
+ SxorD       = SoutD|DoutS,
+ D          = DinS|DoutS,
+ DoverS      = DinS|DoutS|SoutD,
+ DatopS      = DinS|SoutD,
+ DxorS       = DoutS|SoutD, /* == SxorD */
+ Ncomp = 12,
+ +
+ } Drawop;
+ +
+ + void    draw(Image *dst, Rectangle r, Image *src,
+ +
+ + +
+ + Image *mask, Point p)
+ +
+ + +
+ +
+ void    drawop(Image *dst, Rectangle r, Image *src,
+ +
+ + +
+ + Image *mask, Point p, Drawop op)
+ +
+ + +
+ +
+ void    gendraw(Image *dst, Rectangle r, Image *src, Point sp,
+ +
+ + +
+ + Image *mask, Point mp)
+ +
+ + +
+ +
+ void    gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
+ +
+ + +
+ + Image *mask, Point mp, Drawop op)
+ +
+ + +
+ +
+ int     drawreplxy(int min, int max, int x)
+ +
+ + Point drawrepl(Rectangle r, Point p)
+ +
+ + void    replclipr(Image *i, int repl, Rectangle clipr)
+ +
+ + void    line(Image *dst, Point p0, Point p1, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ void    lineop(Image *dst, Point p0, Point p1, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    poly(Image *dst, Point *p, int np, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ void    polyop(Image *dst, Point *p, int np, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    fillpoly(Image *dst, Point *p, int np, int wind,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    fillpolyop(Image *dst, Point *p, int np, int wind,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
+ +
+ + +
+ + int end0, int end1, int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ int     bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
+ +
+ + +
+ + int end0, int end1, int radius, Image *src, Point sp,
+ Drawop op)
+ +
+ + +
+ +
+ int     bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ int     bezsplineop(Image *dst, Point *pt, int npt, int end0, int + end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     bezsplinepts(Point *pt, int npt, Point **pp)
+ +
+ + int     fillbezier(Image *dst, Point p0, Point p1, Point p2, Point + p3,
+ +
+ + +
+ + int w, Image *src, Point sp)
+ +
+ + +
+ +
+ int     fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point + p3,
+ +
+ + +
+ + int w, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     fillbezspline(Image *dst, Point *pt, int npt, int w,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ int     fillbezsplineop(Image *dst, Point *pt, int npt, int w,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    ellipse(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    ellipseop(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    fillellipse(Image *dst, Point c, int a, int b,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    fillellipseop(Image *dst, Point c, int a, int b,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    arc(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, int alpha, int phi)
+ +
+ + +
+ +
+ void    arcop(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, int alpha, int phi, Drawop op)
+ +
+ + +
+ +
+ void    fillarc(Image *dst, Point c, int a, int b, Image *src,
+ +
+ + +
+ + Point sp, int alpha, int phi)
+ +
+ + +
+ +
+ void    fillarcop(Image *dst, Point c, int a, int b, Image *src,
+ +
+ + +
+ + Point sp, int alpha, int phi, Drawop op)
+ +
+ + +
+ +
+ int     icossin(int deg, int *cosp, int *sinp)
+ +
+ + int     icossin2(int x, int y, int *cosp, int *sinp)
+ +
+ + void    border(Image *dst, Rectangle r, int i, Image *color, Point + sp)
+ +
+ + Point string(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s)
+ +
+ + +
+ +
+ Point stringop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Drawop op)
+ +
+ + +
+ +
+ Point stringn(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len)
+ +
+ + +
+ +
+ Point stringnop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Drawop op)
+ +
+ + +
+ +
+ Point runestring(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r)
+ +
+ + +
+ +
+ Point runestringop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Drawop op)
+ +
+ + +
+ +
+ Point runestringn(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len)
+ +
+ + +
+ +
+ Point runestringnop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Drawop op)
+ +
+ + +
+ +
+ Point stringbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point stringbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point stringnbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point runestringbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point _string(Image *dst, Point p, Image *src,
+ +
+ + +
+ + Point sp, Font *f, char *s, Rune *r, int len,
+ Rectangle clipr, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ void    drawsetdebug(int on)
+ +
+ + enum
+ {
+ +
+ + +
+ + /* line ends */
+ Endsquare    = 0,
+ Enddisc      = 1,
+ Endarrow = 2,
+ Endmask      = 0x1F
+ +
+ +
+ };
+ +
+ + #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
+ +
+

DESCRIPTION
+ +
+ + The Image type defines rectangular pictures and the methods to + draw upon them; it is also the building block for higher level + objects such as windows and fonts. In particular, a window is + represented as an Image; no special operators are needed to draw + on a window. +
+ + r       The coordinates of the rectangle in the plane for which the Image + has defined pixel values. It should not be modified after the + image is created.
+ clipr   The clipping rectangle: operations that read or write the + image will not access pixels outside clipr. Frequently, clipr + is the same as r, but it may differ; see in particular the discussion + of repl. The clipping region may be modified dynamically using + replclipr (q.v.).
+ chan    The pixel channel format descriptor, as described in image(7). + The value should not be modified after the image is created.
+ depth   The number of bits per pixel in the picture; it is identically + chantodepth(chan) (see graphics(3)) and is provided as a convenience. + The value should not be modified after the image is created.
+ repl    A boolean value specifying whether the image is tiled to cover + the plane when used as a source for a drawing operation. If repl + is zero, operations are restricted to the intersection of r and + clipr. If repl is set, r defines the tile to be replicated and + clipr defines the portion of the plane covered by the + +
+ + +
+ + tiling, in other words, r is replicated to cover clipr; in such + cases r and clipr are independent.
+ For example, a replicated image with r set to ((0, 0), (1, 1)) + and clipr set to ((0, 0), (100, 100)), with the single pixel of + r set to blue, behaves identically to an image with r and clipr + both set to ((0, 0), (100, 100)) and all pixels set to blue. However, + the first image requires far less memory. The + replication flag may be modified dynamically using replclipr (q.v.). + +
+ + +
+ +
+ Most of the drawing functions come in two forms: a basic form, + and an extended form that takes an extra Drawop to specify a Porter-Duff + compositing operator to use. The basic forms assume the operator + is SoverD, which suffices for the vast majority of applications. + The extended forms are named by adding an + -op suffix to the basic form. Only the basic forms are listed + below.
+ draw(dst, r, src, mask, p)
+ +
+ + Draw is the standard drawing function. Only those pixels within + the intersection of dst−>r and dst−>clipr will be affected; draw + ignores dst−>repl. The operation proceeds as follows (this is a + description of the behavior, not the implementation):
+ 1.    If repl is set in src or mask, replicate their contents to fill + their clip rectangles.
+ 2.    Translate src and mask so p is aligned with r.min.
+ 3.    Set r to the intersection of r and dst−>r.
+ 4.    Intersect r with src−>clipr. If src−>repl is false, also intersect + r with src−>r.
+ 5.    Intersect r with mask−>clipr. If mask−>repl is false, also intersect + r with mask−>r.
+ 6.    For each location in r, combine the dst pixel with the src pixel + using the alpha value corresponding to the mask pixel. If the + mask has an explicit alpha channel, the alpha value corresponding + to the mask pixel is simply that pixel’s alpha channel. Otherwise, + the alpha value is the NTSC greyscale + +
+ + equivalent of the color value, with white meaning opaque and black + transparent. In terms of the Porter-Duff compositing algebra, + draw replaces the dst pixels with (src in mask) over dst. (In + the extended form, “over” is replaced by op).
+ +
+ The various pixel channel formats involved need not be identical. + If the channels involved are smaller than 8-bits, they will be + promoted before the calculation by replicating the extant bits; + after the calculation, they will be truncated to their proper + sizes.
+ +
+ gendraw(dst, r, src, p0, mask, p1)
+ +
+ + Similar to draw except that gendraw aligns the source and mask + differently: src is aligned so p0 corresponds to r.min and mask + is aligned so p1 corresponds to r.min. For most purposes with + simple masks and source images, draw is sufficient, but gendraw + is the general operator and the one all other + drawing primitives are built upon.
+ +
+ drawreplxy(min,max,x)
+ +
+ + Clips x to be in the half-open interval [min, max) by adding or + subtracting a multiple of max-min.
+ +
+ drawrepl(r,p)
+ +
+ + Clips the point p to be within the rectangle r by translating + the point horizontally by an integer multiple of rectangle width + and vertically by the height.
+ +
+ replclipr(i,repl,clipr)
+ +
+ + Because the image data is stored on the server, local modifications + to the Image data structure itself will have no effect. Repclipr + modifies the local Image data structure’s repl and clipr fields, + and notifies the server of their modification.
+ +
+ line(dst, p0, p1, end0, end1, thick, src, sp)
+ +
+ + Line draws in dst a line of width 1+2*thick pixels joining points + p0 and p1. The line is drawn using pixels from the src image aligned + so sp in the source corresponds to p0 in the destination. The + line touches both p0 and p1, and end0 and end1 specify how the + ends of the line are drawn. Endsquare + terminates the line perpendicularly to the direction of the line; + a thick line with Endsquare on both ends will be a rectangle. + Enddisc terminates the line by drawing a disc of diameter 1+2*thick + centered on the end point. Endarrow terminates the line with an + arrowhead whose tip touches the endpoint. + The macro ARROW permits explicit control of the shape of the arrow. + If all three parameters are zero, it produces the default arrowhead, + otherwise, a sets the distance along line from end of the regular + line to tip, b sets the distance along line from the barb to the + tip, and c sets the distance perpendicular to the + line from edge of line to the tip of the barb, all in pixels.
+ Line and the other geometrical operators are equivalent to calls + to gendraw using a mask produced by the geometric procedure.
+ +
+ poly(dst, p, np, end0, end1, thick, src, sp)
+ +
+ + Poly draws a general polygon; it is conceptually equivalent to + a series of calls to line joining adjacent points in the array + of Points p, which has np elements. The ends of the polygon are + specified as in line; interior lines are terminated with Enddisc + to make smooth joins. The source is aligned so sp + corresponds to p[0].
+ +
+ fillpoly(dst, p, np, wind, src, sp)
+ +
+ + Fillpoly is like poly but fills in the resulting polygon rather + than outlining it. The source is aligned so sp corresponds to + p[0]. The winding rule parameter wind resolves ambiguities about + what to fill if the polygon is self-intersecting. If wind is ~0, + a pixel is inside the polygon if the polygon’s winding number + about the point is non-zero. If wind is 1, a pixel is inside if + the winding number is odd. Complementary values (0 or ~1) cause + outside pixels to be filled. The meaning of other values is undefined. + The polygon is closed with a line if necessary.
+ +
+ bezier(dst, a, b, c, d, end0, end1, thick, src, sp)
+ +
+ + Bezier draws the cubic Bezier curve defined by Points a, b, c, + and d. The end styles are determined by end0 and end1; the thickness + of the curve is 1+2*thick. The source is aligned so sp in src + corresponds to a in dst.
+ +
+ bezspline(dst, p, end0, end1, thick, src, sp)
+ +
+ + Bezspline takes the same arguments as poly but draws a quadratic + B-spline (despite its name) rather than a polygon. If the first + and last points in p are equal, the spline has periodic end conditions.
+ +
+ bezsplinepts(pt, npt, pp)
+ +
+ + Bezsplinepts returns in pp a list of points making up the open + polygon that bezspline would draw. The caller is responsible for + freeing *pp.
+ +
+ fillbezier(dst, a, b, c, d, wind, src, sp)
+ +
+ + Fillbezier is to bezier as fillpoly is to poly.
+ +
+ fillbezspline(dst, p, wind, src, sp)
+ +
+ + Fillbezspline is like fillpoly but fills the quadratic B-spline + rather than the polygon outlined by p. The spline is closed with + a line if necessary.
+ +
+ ellipse(dst, c, a, b, thick, src, sp)
+ +
+ + Ellipse draws in dst an ellipse centered on c with horizontal + and vertical semiaxes a and b. The source is aligned so sp in + src corresponds to c in dst. The ellipse is drawn with thickness + 1+2*thick.
+ +
+ fillellipse(dst, c, a, b, src, sp)
+ +
+ + Fillellipse is like ellipse but fills the ellipse rather than + outlining it.
+ +
+ arc(dst, c, a, b, thick, src, sp, alpha, phi)
+ +
+ + Arc is like ellipse, but draws only that portion of the ellipse + starting at angle alpha and extending through an angle of phi. + The angles are measured in degrees counterclockwise from the positive + x axis.
+ +
+ fillarc(dst, c, a, b, src, sp, alpha, phi)
+ +
+ + Fillarc is like arc, but fills the sector with the source color.
+ +
+ icossin(deg, cosp, sinp)
+ +
+ + Icossin stores in *cosp and *sinp scaled integers representing + the cosine and sine of the angle deg, measured in integer degrees. + The values are scaled so cos(0) is 1024.
+ +
+ icossin2(x, y, cosp, sinp)
+ +
+ + Icossin2 is analogous to icossin, with the angle represented not + in degrees but implicitly by the point (x,y). It is to icossin + what atan2 is to atan (see sin(3)).
+ +
+ border(dst, r, i, color, sp)
+ +
+ + Border draws an outline of rectangle r in the specified color. + The outline has width i; if positive, the border goes inside the + rectangle; negative, outside. The source is aligned so sp corresponds + to r.min.
+ +
+ string(dst, p, src, sp, font, s)
+ +
+ + String draws in dst characters specified by the string s and font; + it is equivalent to a series of calls to gendraw using source + src and masks determined by the character shapes. The text is + positioned with the left of the first character at p.x and the + top of the line of text at p.y. The source is positioned so sp + in + src corresponds to p in dst. String returns a Point that is the + position of the next character that would be drawn if the string + were longer.
+ For characters with undefined or zero-width images in the font, + the character at font position 0 (NUL) is drawn.
+ The other string routines are variants of this basic form, and + have names that encode their variant behavior. Routines whose + names contain rune accept a string of Runes rather than UTF-encoded + bytes. Routines ending in n accept an argument, n, that defines + the number of characters to draw rather than + accepting a NUL-terminated string. Routines containing bg draw + the background behind the characters in the specified color (bg) + and alignment (bgp); normally the text is drawn leaving the background + intact.
+ The routine _string captures all this behavior into a single operator. + Whether it draws a UTF string or Rune string depends on whether + s or r is null (the string length is always determined by len). + If bg is non-null, it is used as a background color. The clipr + argument allows further management of clipping when + drawing the string; it is intersected with the usual clipping + rectangles to further limit the extent of the text.
+ +
+ drawsetdebug(on)
+ +
+ + Turns on or off debugging output (usually to a serial line) according + to whether on is non-zero.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), stringsize(3), color(7), utf(7), addpt(3) +
+ + T. Porter, T. Duff. “Compositing Digital Images”, Computer Graphics + (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
+ +
+

DIAGNOSTICS
+ +
+ + These routines call the graphics error function on fatal errors.
+ +
+

BUGS
+ +
+ + Anti-aliased characters can be drawn by defining a font with multiple + bits per pixel, but there are no anti-aliasing geometric primitives.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dsa.html b/man/man3/dsa.html new file mode 100644 index 00000000..765ddd7c --- /dev/null +++ b/man/man3/dsa.html @@ -0,0 +1,172 @@ + +dsa(3) - Plan 9 from User Space + + + + +
+
+
DSA(3)DSA(3) +
+
+

NAME
+ +
+ + dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, + dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature + algorithm
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + DSApriv*    dsagen(DSApub *opub) +
+ + DSAsig*     dsasign(DSApriv *k, mpint *m) +
+ + int         dsaverify(DSApub *k, DSAsig *sig, mpint *m) +
+ + DSApub*     dsapuballoc(void) +
+ + void        dsapubfree(DSApub*) +
+ + DSApriv*    dsaprivalloc(void) +
+ + void        dsaprivfree(DSApriv*) +
+ + DSAsig*     dsasigalloc(void) +
+ + void        dsasigfree(DSAsig*) +
+ + DSApub*     dsaprivtopub(DSApriv*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + DSA is the NIST approved digital signature algorithm. The owner + of a key publishes the public part of the key:
+ +
+ + struct DSApub
+ {
+ +
+ + mpint       *p;    // modulus
+ mpint       *q;    // group order, q divides p−1
+ mpint       *alpha;     // group generator
+ mpint       *key;       // alpha**secret mod p
+ +
+ };
+ +
+ This part can be used for verifying signatures (with dsaverify) + created by the owner. The owner signs (with dsasign) using his + private key:
+ +
+ + struct DSApriv
+ {
+ +
+ + DSApub      pub;
+ mpint       *secret; // (decryption key)
+ +
+ };
+ +
+ + +
+ Keys are generated using dsagen. If dsagen’s argument opub is + nil, a key is created using a new p and q generated by DSAprimes + (see prime(3)). Otherwise, p and q are copied from the old key. + +
+ + Dsaprivtopub returns a newly allocated copy of the public key + corresponding to the private key. +
+ + The routines dsapuballoc, dsapubfree, dsaprivalloc, and dsaprivfree + are provided to manage key storage. +
+ + Dsasign signs message m using a private key k yielding a
+ +
+ + struct DSAsig
+ {
+ +
+ + mpint       *r, *s;
+ +
+ };
+ +
+ Dsaverify returns 0 if the signature is valid and –1 if not. +
+ + The routines dsasigalloc and dsasigfree are provided to manage + signature storage.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dup.html b/man/man3/dup.html new file mode 100644 index 00000000..c601e3b2 --- /dev/null +++ b/man/man3/dup.html @@ -0,0 +1,78 @@ + +dup(3) - Plan 9 from User Space + + + + +
+
+
DUP(3)DUP(3) +
+
+

NAME
+ +
+ + dup – duplicate an open file descriptor
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int dup(int oldfd, int newfd)
+ +
+

DESCRIPTION
+ +
+ + Given a file descriptor, oldfd, referring to an open file, dup + returns a new file descriptor referring to the same file. +
+ + If newfd is –1 the system chooses the lowest available file descriptor. + Otherwise, dup will use newfd for the new file descriptor (closing + any old file associated with newfd).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dup.c
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, dup is a preprocessor + macro defined as p9dup; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/elgamal.html b/man/man3/elgamal.html new file mode 100644 index 00000000..a6518468 --- /dev/null +++ b/man/man3/elgamal.html @@ -0,0 +1,174 @@ + +elgamal(3) - Plan 9 from User Space + + + + +
+
+
ELGAMAL(3)ELGAMAL(3) +
+
+

NAME
+ +
+ + eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, + egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - + elgamal encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + EGpriv*     eggen(int nlen, int nrep) +
+ + mpint*      egencrypt(EGpub *k, mpint *in, mpint *out) +
+ + mpint*      egdecrypt(EGpriv *k, mpint *in, mpint *out) +
+ + EGsig*      egsign(EGpriv *k, mpint *m) +
+ + int         egverify(EGpub *k, EGsig *sig, mpint *m) +
+ + EGpub*      egpuballoc(void) +
+ + void        egpubfree(EGpub*) +
+ + EGpriv*     egprivalloc(void) +
+ + void        egprivfree(EGpriv*) +
+ + EGsig*      egsigalloc(void) +
+ + void        egsigfree(EGsig*) +
+ + EGpub*      egprivtopub(EGpriv*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + Elgamal is a public key encryption and signature algorithm. The + owner of a key publishes the public part of the key:
+ +
+ + struct EGpub
+ {
+ +
+ + mpint       *p;    // modulus
+ mpint       *alpha;     // generator
+ mpint       *key;       // (encryption key) alpha**secret mod p
+ +
+ };
+ +
+ This part can be used for encrypting data (with egencrypt) to + be sent to the owner. The owner decrypts (with egdecrypt) using + his private key:
+ +
+ + struct EGpriv
+ {
+ +
+ + EGpub       pub;
+ mpint       *secret; // (decryption key)
+ +
+ };
+ +
+ + +
+ Keys are generated using eggen. Eggen takes both bit length of + the modulus and the number of repetitions of the Miller-Rabin + primality test to run. If the latter is 0, it does the default + number of rounds. Egprivtopub returns a newly allocated copy of + the public key corresponding to the private key. +
+ + The routines egpuballoc, egpubfree, egprivalloc, and egprivfree + are provided to manage key storage. +
+ + Egsign signs message m using a private key k yielding a
+ +
+ + struct EGsig
+ {
+ +
+ + mpint       *r, *s;
+ +
+ };
+ +
+ Egverify returns 0 if the signature is valid and –1 if not. +
+ + The routines egsigalloc and egsigfree are provided to manage signature + storage.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/encode.html b/man/man3/encode.html new file mode 100644 index 00000000..c7a8132c --- /dev/null +++ b/man/man3/encode.html @@ -0,0 +1,109 @@ + +encode(3) - Plan 9 from User Space + + + + +
+
+
ENCODE(3)ENCODE(3) +
+
+

NAME
+ +
+ + dec64, enc64, dec32, enc32, dec16, enc16, encodefmt – encoding + byte arrays as strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    dec64(uchar *out, int lim, char *in, int n) +
+ + int    enc64(char *out, int lim, uchar *in, int n) +
+ + int    dec32(uchar *out, int lim, char *in, int n) +
+ + int    enc32(char *out, int lim, uchar *in, int n) +
+ + int    dec16(uchar *out, int lim, char *in, int n) +
+ + int    enc16(char *out, int lim, uchar *in, int n) +
+ + int    encodefmt(Fmt*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + Enc16, enc32 and enc64 create null terminated strings. They return + the size of the encoded string (without the null) or -1 if the + encoding fails. The encoding fails if lim, the length of the output + buffer, is too small. +
+ + Dec16, dec32 and dec64 return the number of bytes decoded or -1 + if the decoding fails. The decoding fails if the output buffer + is not large enough or, for base 32, if the input buffer length + is not a multiple of 8. +
+ + Encodefmt can be used with fmtinstall(3) and print(3) to print + encoded representations of byte arrays. The verbs are
+ H     base 16 (i.e. hexadecimal). The default encoding is in upper + case. The l flag forces lower case.
+ <     base 32
+ [     base 64 (same as MIME) +
+ + The length of the array is specified as f2. For example, to display + a 15 byte array as hex:
+ +
+ + char x[15];
+ fmtinstall('H', encodefmt);
+ print("%.*H\n", sizeof x, x);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/u32.c
+ /usr/local/plan9/src/lib9/u64.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/errstr.html b/man/man3/errstr.html new file mode 100644 index 00000000..547efc8d --- /dev/null +++ b/man/man3/errstr.html @@ -0,0 +1,121 @@ + +errstr(3) - Plan 9 from User Space + + + + +
+
+
ERRSTR(3)ERRSTR(3) +
+
+

NAME
+ +
+ + errstr, rerrstr, werrstr – description of last system call error
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int errstr(char *err, uint nerr) +
+ + void rerrstr(char *err, uint nerr) +
+ + void werrstr(char *fmt, ...)
+ +
+

DESCRIPTION
+ +
+ + When a system call fails it returns –1 and records a null terminated + string describing the error in a per-process buffer. Errstr swaps + the contents of that buffer with the contents of the array err. + Errstr will write at most nerr bytes into err; if the per-process + error string does not fit, it is silently truncated at a UTF + character boundary. The returned string is NUL-terminated. Usually + errstr will be called with an empty string, but the exchange property + provides a mechanism for libraries to set the return value for + the next call to errstr. +
+ + The per-process buffer is ERRMAX bytes long. Any error string + provided by the user will be truncated at ERRMAX−1 bytes. ERRMAX + is defined in <libc.h>. +
+ + If no system call has generated an error since the last call to + errstr with an empty string, the result is an empty string. +
+ + The verb r in print(3) calls errstr and outputs the error string. + +
+ + Rerrstr reads the error string but does not modify the per-process + buffer, so a subsequent errstr will recover the same string. +
+ + Werrstr takes a print style format as its argument and uses it + to format a string to pass to errstr. The string returned from + errstr is discarded. +
+ + The error string is maintained in parallel with the Unix error + number errno. Changing errno will reset the error string, and + changing the error string via errstr or werrstr will reset errno.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/errstr.c
+ +
+

DIAGNOSTICS
+ +
+ + Errstr always returns 0.
+ +
+

SEE ALSO
+ +
+ + intro(3), perror(3)
+ +
+

BUGS
+ +
+ + The implementation sets errno to the (somewhat arbitrary) constant + 0x19283745 when the error string is valid. When errno is set to + other values, the error string is synthesized using strerror(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/event.html b/man/man3/event.html new file mode 100644 index 00000000..87cff2fd --- /dev/null +++ b/man/man3/event.html @@ -0,0 +1,390 @@ + +event(3) - Plan 9 from User Space + + + + +
+
+
EVENT(3)EVENT(3) +
+
+

NAME
+ +
+ + event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, + ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, + edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu + – graphics events
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include    <u.h>
+ #include    <libc.h>
+ #include    <draw.h>
+ #include    <event.h>
+ #include    <cursor.h>
+ +
+ + void        einit(ulong keys)
+ +
+ + ulong       event(Event *e)
+ +
+ + Mouse       emouse(void)
+ +
+ + int         ekbd(void)
+ +
+ + int         ecanmouse(void)
+ +
+ + int         ecankbd(void)
+ +
+ + int         ereadmouse(Mouse *m)
+ +
+ + int         eatomouse(Mouse *m, char *buf, int n)
+ +
+ + ulong       estart(ulong key, int fd, int n)
+ +
+ + ulong       estartfn(int id, ulong key, int fd, int n,
+ +
+ + +
+ + int (*fn)(Event*, uchar*, int))
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ ulong       etimer(ulong key, int n)
+ +
+ + ulong       eread(ulong keys, Event *e)
+ +
+ + int         ecanread(ulong keys)
+ +
+ + void        eresized(int new)
+ +
+ + Rectangle egetrect(int but, Mouse *m)
+ +
+ + void        edrawgetrect(Rectangle r, int up)
+ +
+ + int         emenuhit(int but, Mouse *m, Menu *menu)
+ +
+ + +
+ + int         emoveto(Point p)
+ +
+ + +
+ + int         esetcursor(Cursor *c)
+ +
+ + extern Mouse      *mouse
+ +
+ + enum{
+ +
+ + +
+ + Emouse = 1,
+ Ekeyboard = 2,
+ +
+ +
+ };
+ +
+ + +
+

DESCRIPTION
+ +
+ + These routines provide an interface to multiple sources of input + for unthreaded programs. Threaded programs (see thread(3)) should + instead use the threaded mouse and keyboard interface described + in mouse(3) and keyboard(3). +
+ + Einit must be called first. If the argument to einit has the Emouse + and Ekeyboard bits set, the mouse and keyboard events will be + enabled; in this case, initdraw (see graphics(3)) must have already + been called. The user must provide a function called eresized + to be called whenever the window in which the process + is running has been resized; the argument new is a flag specifying + whether the program must call getwindow (see graphics(3)) to re-establish + a connection to its window. After resizing (and perhaps calling + getwindow), the global variable screen will be updated to point + to the new window’s Image structure. +
+ + As characters are typed on the keyboard, they are read by the + event mechanism and put in a queue. Ekbd returns the next rune + from the queue, blocking until the queue is non-empty. The characters + are read in raw mode, so they are available as soon as a complete + rune is typed. +
+ + When the mouse moves or a mouse button is pressed or released, + a new mouse event is queued by the event mechanism. Emouse returns + the next mouse event from the queue, blocking until the queue + is non-empty. Emouse returns a Mouse structure:
+ +
+ + struct Mouse
+ {
+ +
+ + int     buttons;
+ Point xy;
+ ulong msec;
+ +
+ };
+ +
+ + +
+ Buttons&1 is set when the left mouse button is pressed, buttons&2 + when the middle button is pressed, and buttons&4 when the right + button is pressed. The current mouse position is always returned + in xy. Msec is a time stamp in units of milliseconds. +
+ + Ecankbd and ecanmouse return non-zero when there are keyboard + or mouse events available to be read. +
+ + Ereadmouse reads the next mouse event from the file descriptor + connected to the mouse, converts the textual data into a Mouse + structure by calling eatomouse with the buffer and count from + the read call, and returns the number of bytes read, or –1 for + an error. +
+ + Estart can be used to register additional file descriptors to + scan for input. It takes as arguments the file descriptor to register, + the maximum length of an event message on that descriptor, and + a key to be used in accessing the event. The key must be a power + of 2 and must not conflict with any previous keys. If a zero + key is given, a key will be allocated and returned. Estartfn is + similar to estart, but processes the data received by calling + fn before returning the event to the user. The function fn is + called with the id of the event; it should return id if the event + is to be passed to the user, 0 if it is to be ignored. The variable + Event.v + can be used by fn to attach an arbitrary data item to the returned + Event structure.    Ekeyboard and Emouse are the keyboard and mouse + event keys. +
+ + Etimer starts a repeating timer with a period of n milliseconds; + it returns the timer event key, or zero if it fails. Only one + timer can be started. Extra timer events are not queued and the + timer channel has no associated data. +
+ + Eread waits for the next event specified by the mask keys of event + keys submitted to estart. It fills in the appropriate field of + the argument Event structure, which looks like:
+ +
+ + struct Event
+ {
+ +
+ + int     kbdc;
+ Mouse mouse;
+ int     n;
+ void    *v;
+ uchar data[EMAXMSG];
+ +
+ };
+ +
+ + +
+ Data is an array which is large enough to hold a 9P message. Eread + returns the key for the event which was chosen. For example, if + a mouse event was read, Emouse will be returned. +
+ + Event waits for the next event of any kind. The return is the + same as for eread. +
+ + As described in graphics(3), the graphics functions are buffered. + Event, eread, emouse, and ekbd all cause a buffer flush unless + there is an event of the appropriate type already queued. +
+ + Ecanread checks whether a call to eread(keys) would block, returning + 0 if it would, 1 if it would not. +
+ + Getrect prompts the user to sweep a rectangle. It should be called + with m holding the mouse event that triggered the egetrect (or, + if none, a Mouse with buttons set to 7). It changes to the sweep + cursor, waits for the buttons all to be released, and then waits + for button number but to be pressed, marking the initial + corner. If another button is pressed instead, egetrect returns + a rectangle with zero for both corners, after waiting for all + the buttons to be released. Otherwise, egetrect continually draws + the swept rectangle until the button is released again, and returns + the swept rectangle. The mouse structure pointed to by m will + contain the final mouse event. +
+ + Egetrect uses successive calls to edrawgetrect to maintain the + red rectangle showing the sweep-in-progress. The rectangle to + be drawn is specified by rc and the up parameter says whether + to draw (1) or erase (0) the rectangle. +
+ + Emenuhit displays a menu and returns a selected menu item number. + It should be called with m holding the mouse event that triggered + the emenuhit; it will call emouse to update it. A Menu is a structure:
+ +
+ + struct Menu
+ {
+ +
+ + char    **item;
+ char    *(*gen)(int);
+ int     lasthit;
+ +
+ };
+ +
+ + +
+ If item is nonzero, it should be a null-terminated array of the + character strings to be displayed as menu items. Otherwise, gen + should be a function that, given an item number, returns the character + string for that item, or zero if the number is past the end of + the list. Items are numbered starting at zero. Menuhit + waits until but is released, and then returns the number of the + selection, or –1 for no selection. The m argument is filled in + with the final mouse event. +
+ + Emoveto moves the mouse cursor to the position p on the screen. + +
+ + Esetcursor changes the cursor image to that described by the Cursor + c (see mouse(3)). If c is nil, it restores the image to the default + arrow.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + rio(1), graphics(3), plumb(3), draw(3)
+ +
+

BUGS
+ +
+ + Etimer and estart are unimplemented.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/exec.html b/man/man3/exec.html new file mode 100644 index 00000000..e5397352 --- /dev/null +++ b/man/man3/exec.html @@ -0,0 +1,146 @@ + +exec(3) - Plan 9 from User Space + + + + +
+
+
EXEC(3)EXEC(3) +
+
+

NAME
+ +
+ + exec, execl – execute a file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int exec(char *name, char* argv[])
+ +
+ + int execl(char *name, ...)
+ +
+

DESCRIPTION
+ +
+ + Exec and execl overlay the calling process with the named file, + then transfer to the entry point of the image of the file. +
+ + Name points to the name of the file to be executed; it must not + be a directory, and the permissions must allow the current user + to execute it (see stat(3)). It should also be a valid binary + image, as defined by the local operating system, or a shell script + (see rc(1)). The first line of a shell script must begin with + #! followed + by the name of the program to interpret the file and any initial + arguments to that program, for example
+ +
+ + #!/bin/rc
+ ls | mc
+ +
+ + +
+ When a C program is executed, it is called as follows:
+ +
+ + void main(int argc, char *argv[])
+ +
+ + +
+ Argv is a copy of the array of argument pointers passed to exec; + that array must end in a null pointer, and argc is the number + of elements before the null pointer. By convention, the first + argument should be the name of the program to be executed. Execl + is like exec except that argv will be an array of the parameters + that follow name in the call. The last argument to execl must + be a null pointer. +
+ + For a file beginning #!, the arguments passed to the program (/bin/rc + in the example above) will be the name of the file being executed, + any arguments on the #! line, the name of the file again, and + finally the second and subsequent arguments given to the original + exec call. The result honors the two conventions + of a program accepting as argument a file to be interpreted and + argv[0] naming the file being executed. +
+ + Most attributes of the calling process are carried into the result; + in particular, files remain open across exec (except those opened + with OCEXEC OR’d into the open mode; see open(3)); and the working + directory and environment (see getenv(3)) remain the same. However, + a newly exec’ed process has no notification + handlers (see notify(3)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/exec.c
+ /usr/local/plan9/src/lib9/execl.c
+ +
+

SEE ALSO
+ +
+ + prof(1), intro(3), stat(3)
+ +
+

DIAGNOSTICS
+ +
+ + If these functions fail, they return and set errstr. There can + be no return from a successful exec or execl; the calling image + is lost.
+ +
+

BUGS
+ +
+ + On Unix, unlike on Plan 9, exec and execl use the user’s current + path to locate prog. This is a clumsy way to deal with Unix’s + lack of a union directory for /bin. +
+ + To avoid name conflicts with the underlying system, exec and execl + are preprocessor macros defined as p9exec and p9execl; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/exits.html b/man/man3/exits.html new file mode 100644 index 00000000..cc94a468 --- /dev/null +++ b/man/man3/exits.html @@ -0,0 +1,126 @@ + +exits(3) - Plan 9 from User Space + + + + +
+
+
EXITS(3)EXITS(3) +
+
+

NAME
+ +
+ + exits, _exits, atexit, atexitdont, terminate – terminate process, + process cleanup
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void _exits(char *msg)
+ void exits(char *msg)
+ +
+ + int    atexit(void(*)(void))
+ +
+ + void atexitdont(void(*)(void))
+ +
+

DESCRIPTION
+ +
+ + Exits is the conventional way to terminate a process. _Exits also + terminates a process but does not call the registered atexit handlers + (q.v.). They can never return. +
+ + Msg conventionally includes a brief (maximum length ERRLEN) explanation + of the reason for exiting, or a null pointer or empty string to + indicate normal termination. The string is passed to the parent + process, prefixed by the name and process id of the exiting process, + when the parent does a wait(3). +
+ + Before calling _exits with msg as an argument, exits calls in + reverse order all the functions recorded by atexit. +
+ + Atexit records fn as a function to be called by exits. It returns + zero if it failed, nonzero otherwise. A typical use is to register + a cleanup routine for an I/O package. To simplify programs that + fork or share memory, exits only calls those atexit-registered + functions that were registered by the same process as that calling + exits. +
+ + Calling atexit twice (or more) with the same function argument + causes exits to invoke the function twice (or more). +
+ + There is a limit to the number of exit functions that will be + recorded; atexit returns 0 if that limit has been reached. +
+ + Atexitdont cancels a previous registration of an exit function.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/atexit.c
+ /usr/local/plan9/src/lib9/_exits.c
+ +
+

SEE ALSO
+ +
+ + fork(2), wait(3)
+ +
+

BUGS
+ +
+ + Because of limitations of Unix, the exit status of a process can + only be an 8-bit integer. Exit status 0 is used for empty exit + messages, and 1 for non-empty messages. +
+ + Exit codes 97 through 99 are used by the thread library to signal + internal synchronization errors between the main program and a + proxy process that implements backgrounding. +
+ + To avoid name conflicts with the underlying system, atexit and + atexitdont are preprocessor macros defined as p9atexit and p9atexitdont; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/fcall.html b/man/man3/fcall.html new file mode 100644 index 00000000..926b47dc --- /dev/null +++ b/man/man3/fcall.html @@ -0,0 +1,274 @@ + +fcall(3) - Plan 9 from User Space + + + + +
+
+
FCALL(3)FCALL(3) +
+
+

NAME
+ +
+ + Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, + read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File + protocol
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h> +
+ + uint convS2M(Fcall *f, uchar *ap, uint nap) +
+ + uint convD2M(Dir *d, uchar *ap, uint nap) +
+ + uint convM2S(uchar *ap, uint nap, Fcall *f) +
+ + uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) +
+ + int dirfmt(Fmt*) +
+ + int fcallfmt(Fmt*) +
+ + int dirmodefmt(Fmt*) +
+ + int read9pmsg(int fd, uchar *buf, uint nbuf) +
+ + int statcheck(uchar *buf, uint nbuf) +
+ + uint sizeS2M(Fcall *f) +
+ + uint sizeD2M(Dir *d)
+ +
+

DESCRIPTION
+ +
+ + These routines convert messages in the machine-independent format + of the Plan 9 file protocol, 9P, to and from a more convenient + form, an Fcall structure: +
+ + #define MAXWELEM 16
+ typedef
+ struct Fcall
+ {
+ +
+ + uchar type;
+ u32int      fid;
+ ushort      tag;
+ union {
+ +
+ + struct {
+ u32int msize;              /* Tversion, Rversion */
+ char     *version;           /* Tversion, Rversion */
+ };
+ struct {
+ ushort oldtag;             /* Tflush */
+ };
+ struct {
+ char     *ename;             /* Rerror */
+ };
+ struct {
+ Qid      qid;                /* Rattach, Ropen, Rcreate */
+ u32int iounit;             /* Ropen, Rcreate */
+ };
+ struct {
+ Qid      aqid;               /* Rauth */
+ };
+ struct {
+ u32int afid;               /* Tauth, Tattach */
+ char     *uname;             /* Tauth, Tattach */
+ char     *aname;             /* Tauth, Tattach */
+ };
+ struct {
+ u32int perm;               /* Tcreate */
+ char     *name;              /* Tcreate */
+ uchar    mode;               /* Tcreate, Topen */
+ };
+ struct {
+ u32int newfid;             /* Twalk */
+ ushort nwname;             /* Twalk */
+ char     *wname[MAXWELEM];    /* Twalk */
+ };
+ struct {
+ ushort nwqid;              /* Rwalk */
+ Qid      wqid[MAXWELEM];      /* Rwalk */
+ };
+ struct {
+ vlong    offset;             /* Tread, Twrite */
+ u32int count;              /* Tread, Twrite, Rread */
+ char     *data;              /* Twrite, Rread */
+ };
+ struct {
+ ushort nstat;              /* Twstat, Rstat */
+ uchar    *stat;              /* Twstat, Rstat */
+ };
+ +
+ };
+ +
+ } Fcall;
+ /* these are implemented as macros */
+ uchar       GBIT8(uchar*)
+ ushort      GBIT16(uchar*)
+ ulong       GBIT32(uchar*)
+ vlong       GBIT64(uchar*)
+ void        PBIT8(uchar*, uchar)
+ void        PBIT16(uchar*, ushort)
+ void        PBIT32(uchar*, ulong)
+ void        PBIT64(uchar*, vlong)
+ #define     BIT8SZ       1
+ #define     BIT16SZ      2
+ #define     BIT32SZ      4
+ #define     BIT64SZ      8
+ +
+ + This structure is defined in <fcall.h>. See section 5 for a full + description of 9P messages and their encoding. For all message + types, the type field of an Fcall holds one of Tversion, Rversion, + Tattach, Rattach, etc. (defined in an enumerated type in <fcall.h>). + Fid is used by most messages, and + tag is used by all messages. The other fields are used selectively + by the message types given in comments. +
+ + ConvM2S takes a 9P message at ap of length nap, and uses it to + fill in Fcall structure f. If the passed message including any + data for Twrite and Rread messages is formatted properly, the + return value is the number of bytes the message occupied in the + buffer ap, which will always be less than or equal to nap; + otherwise it is 0. For Twrite and Tread messages, data is set + to a pointer into the argument message, not a copy. +
+ + ConvS2M does the reverse conversion, turning f into a message + starting at ap. The length of the resulting message is returned. + For Twrite and Rread messages, count bytes starting at data are + copied into the message. +
+ + The constant IOHDRSZ is a suitable amount of buffer to reserve + for storing the 9P header; the data portion of a Twrite or Rread + will be no more than the buffer size negotiated in the Tversion/Rversion + exchange, minus IOHDRSZ. +
+ + The routine sizeS2M returns the number of bytes required to store + the machine-independent representation of the Fcall structure + f, including its initial 32-bit size field. In other words, it + reports the number of bytes produced by a successful call to convS2M. + +
+ + Another structure is Dir, used by the routines described in stat(3). + ConvM2D converts the machine-independent form starting at ap into + d and returns the length of the machine-independent encoding. + The strings in the returned Dir structure are stored at successive + locations starting at strs. Usually strs will + point to storage immediately after the Dir itself. It can also + be a nil pointer, in which case the string pointers in the returned + Dir are all nil; however, the return value still includes their + length. +
+ + ConvD2M does the reverse translation, also returning the length + of the encoding. If the buffer is too short, the return value + will be BIT16SZ and the correct size will be returned in the first + BIT16SZ bytes. (If the buffer is less that BIT16SZ, the return + value is zero; therefore a correct test for complete packing of + the + message is that the return value is greater than BIT16SZ). The + macro GBIT16 can be used to extract the correct value. The related + macros with different sizes retrieve the corresponding-sized quantities. + PBIT16 and its brethren place values in messages. With the exception + of handling short buffers in convD2M, + these macros are not usually needed except by internal routines. + +
+ + Analogous to sizeS2M, sizeD2M returns the number of bytes required + to store the machine-independent representation of the Dir structure + d, including its initial 16-bit size field. +
+ + The routine statcheck checks whether the nbuf bytes of buf contain + a validly formatted machine-independent Dir entry suitable as + an argument, for example, for the wstat (see stat(3)) system call. + It checks that the sizes of all the elements of the the entry + sum to exactly nbuf, which is a simple but effective test + of validity. Nbuf and buf should include the second two-byte (16-bit) + length field that precedes the entry when formatted in a 9P message + (see stat(9p)); in other words, nbuf is 2 plus the sum of the + sizes of the entry itself. Statcheck also verifies that the length + field has the correct value (that is, nbuf−2). It returns 0 + for a valid entry and −1 for an incorrectly formatted entry. +
+ + Dirfmt, fcallfmt, and dirmodefmt are formatting routines, suitable + for fmtinstall(3). They convert Dir*, Fcall*, and long values + into string representations of the directory buffer, Fcall buffer, + or file mode value. Fcallfmt assumes that dirfmt has been installed + with format letter D and dirmodefmt with format + letter M. +
+ + Read9pmsg calls read(3) multiple times, if necessary, to read + an entire 9P message into buf. The return value is 0 for end of + file, or -1 for error; it does not return partial messages.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + intro(3), 9p(3), stat(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/flate.html b/man/man3/flate.html new file mode 100644 index 00000000..41591034 --- /dev/null +++ b/man/man3/flate.html @@ -0,0 +1,333 @@ + +flate(3) - Plan 9 from User Space + + + + +
+
+
FLATE(3)FLATE(3) +
+
+

NAME
+ +
+ + deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, + inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, + flateerr, mkcrctab, blockcrc, adler32 – deflate compression
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <flate.h> +
+ + +
+ + int      deflateinit(void) +
+ + int      deflate(void *wr, int (*w)(void*,void*,int),
+ +
+ + +
+ + void *rr, int (*r)(void*,void*,int),
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflatezlib(void *wr, int (*w)(void*,void*,int),
+ +
+ + +
+ + void *rr, int (*r)(void*,void*,int),
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflateblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize,
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflatezlibblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize,
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflateinit(void) +
+ + int      inflate(void *wr, int (*w)(void*, void*, int),
+ +
+ + +
+ + void *getr, int (*get)(void*)) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflatezlib(void *wr, int (*w)(void*, void*, int),
+ +
+ + +
+ + void *getr, int (*get)(void*)) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflateblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflatezlibblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ char     *flateerr(int error) +
+ + ulong    *mkcrctab(ulong poly) +
+ + ulong    blockcrc(ulong *tab, ulong crc, void *buf, int n) +
+ + ulong    adler32(ulong adler, void *buf, int n)
+ +
+

DESCRIPTION
+ +
+ + These routines compress and decompress data using the deflate + compression algorithm, which is used for most gzip, zip, and zlib + files. +
+ + Deflate compresses input data retrieved by calls to r with arguments + rr, an input buffer, and a count of bytes to read. R should return + the number of bytes read; end of input is signaled by returning + zero, an input error by returning a negative number. The compressed + output is written to w with arguments wr, the + output data, and the number of bytes to write. W should return + the number of bytes written; writing fewer than the requested + number of bytes is an error. Level indicates the amount of computation + deflate should do while compressing the data. Higher levels usually + take more time and produce smaller outputs. Valid + values are 1 to 9, inclusive; 6 is a good compromise. If debug + is non-zero, cryptic debugging information is produced on standard + error. +
+ + Inflate reverses the process, converting compressed data into + uncompressed output. Input is retrieved one byte at a time by + calling get with the argument getr. End of input of signaled by + returning a negative value. The uncompressed output is written + to w, which has the same interface as for deflate. +
+ + Deflateblock and inflateblock operate on blocks of memory but + are otherwise similar to deflate and inflate. +
+ + The zlib functions are similar, but operate on files with a zlib + header and trailer. +
+ + Deflateinit or inflateinit must be called once before any call + to the corresponding routines. +
+ + If the above routines fail, they return a negative number indicating + the problem. The possible values are FlateNoMem, FlateInputFail, + FlateOutputFail, FlateCorrupted, and FlateInternal. Flateerr converts + the number into a printable message. FlateOk is defined to be + zero, the successful return value for deflateinit, + deflate, deflatezlib, inflateinit, inflate, and inflatezlib. The + block functions return the number of bytes produced when they + succeed. +
+ + Mkcrctab allocates (using malloc(3)), initializes, and returns + a table for rapid computation of 32 bit CRC values using the polynomial + poly. Blockcrc uses tab, a table returned by mkcrctab, to update + crc for the n bytes of data in buf, and returns the new value. + Crc should initially be zero. Blockcrc pre-conditions and + post-conditions crc by ones complementation. +
+ + Adler32 updates the Adler 32-bit checksum of the n butes of data + in buf. The initial value of adler (that is, its value after seeing + zero bytes) should be 1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libflate
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/fmtinstall.html b/man/man3/fmtinstall.html new file mode 100644 index 00000000..848c1333 --- /dev/null +++ b/man/man3/fmtinstall.html @@ -0,0 +1,339 @@ + +fmtinstall(3) - Plan 9 from User Space + + + + +
+
+
FMTINSTALL(3)FMTINSTALL(3) +
+
+

NAME
+ +
+ + fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, + fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, + runefmtstrinit, runefmtstrflush, errfmt – support for user-defined + print formats and output routines
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + typedef struct Fmt    Fmt;
+ struct Fmt{
+ +
+ + uchar     runes;    /* output buffer is runes or chars? */
+ void      *start; /* of buffer */
+ void      *to;      /* current place in the buffer */
+ void      *stop;    /* end of the buffer; overwritten if flush fails */
+ int       (*flush)(Fmt*);/* called when to == stop */
+ void      *farg;    /* to make flush a closure */
+ int       nfmt;     /* num chars formatted so far */
+ va_list args;     /* args passed to dofmt */
+ int       r;        /* % format Rune */
+ int       width;
+ int       prec;
+ ulong     flags;
+ +
+ };
+ enum{
+ +
+ + FmtWidth      = 1,
+ FmtLeft       = FmtWidth << 1,
+ FmtPrec       = FmtLeft << 1,
+ FmtSharp      = FmtPrec << 1,
+ FmtSpace      = FmtSharp << 1,
+ FmtSign       = FmtSpace << 1,
+ FmtZero       = FmtSign << 1,
+ FmtUnsigned = FmtZero << 1,
+ FmtShort      = FmtUnsigned << 1,
+ FmtLong       = FmtShort << 1,
+ FmtVLong      = FmtLong << 1,
+ FmtComma      = FmtVLong << 1,
+ FmtFlag       = FmtComma << 1
+ +
+ };
+ +
+ + +
+ + int     fmtfdinit(Fmt *f, int fd, char *buf, int nbuf); +
+ + int     fmtfdflush(Fmt *f); +
+ + int     fmtstrinit(Fmt *f); +
+ + char* fmtstrflush(Fmt *f); +
+ + int     runefmtstrinit(Fmt *f); +
+ + Rune* runefmtstrflush(Fmt *f);
+ +
+ + int     fmtinstall(int c, int (*fn)(Fmt*)); +
+ + int     dofmt(Fmt *f, char *fmt); +
+ + int     dorfmt(Fmt*, Rune *fmt); +
+ + int     fmtprint(Fmt *f, char *fmt, ...); +
+ + int     fmtvprint(Fmt *f, char *fmt, va_list v); +
+ + int     fmtrune(Fmt *f, int r); +
+ + int     fmtstrcpy(Fmt *f, char *s); +
+ + int     fmtrunestrcpy(Fmt *f, Rune *s); +
+ + int     errfmt(Fmt *f);
+ +
+

DESCRIPTION
+ +
+ + The interface described here allows the construction of custom + print(3) verbs and output routines. In essence, they provide access + to the workings of the formatted print code. +
+ + The print(3) suite maintains its state with a data structure called + Fmt. A typical call to print(3) or its relatives initializes a + Fmt structure, passes it to subsidiary routines to process the + output, and finishes by emitting any saved state recorded in the + Fmt. The details of the Fmt are unimportant to outside users, + except + insofar as the general design influences the interface. The Fmt + records whether the output is in runes or bytes, the verb being + processed, its precision and width, and buffering parameters. + Most important, it also records a flush routine that the library + will call if a buffer overflows. When printing to a file descriptor, + the + flush routine will emit saved characters and reset the buffer; + when printing to an allocated string, it will resize the string + to receive more output. The flush routine is nil when printing + to fixed-size buffers. User code need never provide a flush routine; + this is done internally by the library.
+

Custom output routines
+ To write a custom output routine, such as an error handler that + formats and prints custom error messages, the output sequence + can be run from outside the library using the routines described + here. There are two main cases: output to an open file descriptor + and output to a string. +
+ + To write to a file descriptor, call fmtfdinit to initialize the + local Fmt structure f, giving the file descriptor fd, the buffer + buf, and its size nbuf. Then call fmtprint or fmtvprint to generate + the output. These behave like fprint (see print(3)) or vfprint + except that the characters are buffered until fmtfdflush is called + and the return value is either 0 or –1. A typical example of this + sequence appears in the Examples section. +
+ + The same basic sequence applies when outputting to an allocated + string: call fmtstrinit to initialize the Fmt, then call fmtprint + and fmtvprint to generate the output. Finally, fmtstrflush will + return the allocated string, which should be freed after use. + To output to a rune string, use runefmtstrinit and runefmtstrflush. + Regardless of the output style or type, fmtprint or fmtvprint + generates the characters.
+

Custom format verbs
+ Fmtinstall is used to install custom verbs and flags labeled by + character c, which may be any non-zero Unicode character. Fn should + be declared as
+ +
+ + int     fn(Fmt*)
+ +
+ + +
+ Fp−>r is the flag or verb character to cause fn to be called. In + fn, fp−>width, fp−>prec are the width and precision, and fp−>flags + the decoded flags for the verb (see print(3) for a description + of these items). The standard flag values are: FmtSign (+), FmtLeft + (−), FmtSpace (' '), FmtSharp (#), + FmtComma (,), FmtLong (l), FmtShort (h), FmtUnsigned (u), and + FmtVLong (ll). The flag bits FmtWidth and FmtPrec identify whether + a width and precision were specified. +
+ + Fn is passed a pointer to the Fmt structure recording the state + of the output. If fp−>r is a verb (rather than a flag), fn should + use Fmt−>args to fetch its argument from the list, then format + it, and return zero. If fp−>r is a flag, fn should return one. + All interpretation of fp−>width, fp−>prec, and fp->flags is + left up to the conversion routine. Fmtinstall returns 0 if the + installation succeeds, –1 if it fails. +
+ + Fmtprint and fmtvprint may be called to help prepare output in + custom conversion routines. However, these functions clear the + width, precision, and flags. Both functions return 0 for success + and –1 for failure. +
+ + The functions dofmt and dorfmt are the underlying formatters; + they use the existing contents of Fmt and should be called only + by sophisticated conversion routines. These routines return the + number of characters (bytes of UTF or runes) produced. +
+ + Some internal functions may be useful to format primitive types. + They honor the width, precision and flags as described in print(3). + Fmtrune formats a single character r. Fmtstrcpy formats a string + s; fmtrunestrcpy formats a rune string s. Errfmt formats the system + error string. All these routines return zero for + successful execution. Conversion routines that call these functions + will work properly regardless of whether the output is bytes or + runes.
+ +

+

EXAMPLES
+ +
+ + This function prints an error message with a variable number of + arguments and then quits. Compared to the corresponding example + in print(3), this version uses a smaller buffer, will never truncate + the output message, but might generate multiple write system calls + to produce its output. + +
+ + #pragma    varargck argpos    error     1
+ void fatal(char *fmt, ...)
+ {
+ +
+ + Fmt f;
+ char buf[64];
+ va_list arg;
+ fmtfdinit(&f, 1, buf, sizeof buf);
+ fmtprint(&f, "fatal: ");
+ va_start(arg, fmt);
+ fmtvprint(&f, fmt, arg);
+ va_end(arg);
+ fmtprint(&f, "\n");
+ fmtfdflush(&f);
+ exits("fatal error");
+ +
+ }
+ +
+ + +
+ This example adds a verb to print complex numbers.
+ +
+ + typedef
+ struct {
+ +
+ + double    r, i;
+ +
+ } Complex;
+ #pragma    varargck type "X" Complex
+ int
+ Xfmt(Fmt *f)
+ {
+ +
+ + Complex c;
+ c = va_arg(f−>args, Complex);
+ return fmtprint(f, "(%g,%g)", c.r, c.i);
+ +
+ }
+ main(...)
+ {
+ +
+ + Complex x = (Complex){ 1.5, −2.3 };
+ fmtinstall('X', Xfmt);
+ print("x = %X\n", x);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/fmt
+ +
+

SEE ALSO
+ +
+ + print(3), utf(7), errstr(3)
+ +
+

DIAGNOSTICS
+ +
+ + These routines return negative numbers or nil for errors and set + errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/frame.html b/man/man3/frame.html new file mode 100644 index 00000000..4a80453c --- /dev/null +++ b/man/man3/frame.html @@ -0,0 +1,325 @@ + +frame(3) - Plan 9 from User Space + + + + +
+
+
FRAME(3)FRAME(3) +
+
+

NAME
+ +
+ + frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, + frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, + frdrawsel0, frgetmouse – frames of text
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <thread.h>
+ #include <mouse.h>
+ #include <frame.h>
+ +
+ + void    frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols)
+ +
+ + void    frsetrects(Frame *f, Rectangle r, Image *b)
+ +
+ + void    frinittick(Frame *f)
+ +
+ + void    frclear(Frame *f, int resize)
+ +
+ + ulong frcharofpt(Frame *f, Point pt)
+ +
+ + Point frptofchar(Frame *f, ulong p)
+ +
+ + void    frinsert(Frame *f, Rune *r0, Rune *r1, ulong p)
+ +
+ + int     frdelete(Frame *f, ulong p0, ulong p1)
+ +
+ + void    frselect(Frame *f, Mousectl *m)
+ +
+ + void    frtick(Frame *f, Point pt, int up)
+ +
+ + void    frselectpaint(Frame *f, Point p0, Point p1, Image *col)
+ +
+ + void    frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1,
+ +
+ + +
+ + int highlighted)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1,
+ +
+ + +
+ + Image *back, Image *text)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ enum{
+ +
+ + BACK,
+ HIGH,
+ BORD,
+ TEXT,
+ HTEXT,
+ NCOL
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + This library supports frames of editable text in a single font + on raster displays, such as in sam(1) and 9term(1). Frames may + hold any character except NUL (0). Long lines are folded and tabs + are at fixed intervals. +
+ + The user-visible data structure, a Frame, is defined in <frame.h>:
+ +
+ + typedef struct Frame Frame;
+ struct Frame
+ {
+ +
+ + Font        *font;           /* of chars in the frame */
+ Display     *display;         /* on which frame appears */
+ Image       *b;              /* on which frame appears */
+ Image       *cols[NCOL];      /* text and background colors */
+ Rectangle r;               /* in which text appears */
+ Rectangle entire;           /* of full frame */
+ Frbox       *box;
+ ulong       p0, p1;           /* selection */
+ ushort      nbox, nalloc;
+ ushort      maxtab;           /* max size of tab, in pixels */
+ ushort      nchars;           /* # runes in frame */
+ ushort      nlines;           /* # lines with text */
+ ushort      maxlines;         /* total # lines in frame */
+ ushort      lastlinefull;     /* last line fills frame */
+ ushort      modified;         /* changed since frselect() */
+ Image       *tick;           /* typing tick */
+ Image       *tickback;        /* saved image under tick */
+ int         ticked;           /* flag: is tick onscreen? */
+ +
+ };
+ +
+ + +
+ Frbox is an internal type and is not used by the interface. P0 + and p1 may be changed by the application provided the selection + routines are called afterwards to maintain a consistent display. + Maxtab determines the size of tab stops. Frinit sets it to 8 times + the width of a 0 (zero) character in the font; it may be + changed before any text is added to the frame. The other elements + of the structure are maintained by the library and should not + be modified directly. +
+ + The text within frames is not directly addressable; instead frames + are designed to work alongside another structure that holds the + text. The typical application is to display a section of a longer + document such as a text file or terminal session. Usually the + program will keep its own copy of the text in the window + (probably as an array of Runes) and pass components of this text + to the frame routines to display the visible portion. Only the + text that is visible is held by the Frame; the application must + check maxlines, nlines, and lastlinefull to determine, for example, + whether new text needs to be appended at the + end of the Frame after calling frdelete (q.v.). +
+ + There are no routines in the library to allocate Frames; instead + the interface assumes that Frames will be components of larger + structures. Frinit prepares the Frame f so characters drawn in + it will appear in the single Font ft. It then calls frsetrects + and frinittick to initialize the geometry for the Frame. The Image + b is where the Frame is to be drawn; Rectangle r defines the limit + of the portion of the Image the text will occupy. The Image pointer + may be null, allowing the other routines to be called to maintain + the associated data structure in, for example, an obscured window. + +
+ + The array of Images cols sets the colors in which text and borders + will be drawn. The background of the frame will be drawn in cols[BACK]; + the background of highlighted text in cols[HIGH]; borders and + scroll bar in cols[BORD]; regular text in cols[TEXT]; and highlighted + text in cols[HTEXT]. +
+ + Frclear frees the internal structures associated with f, permitting + another frinit or frsetrects on the Frame. It does not clear the + associated display. If f is to be deallocated, the associated + Font and Image must be freed separately. The resize argument should + be non-zero if the frame is to be redrawn with a + different font; otherwise the frame will maintain some data structures + associated with the font. +
+ + To resize a Frame, use frclear and frinit and then frinsert (q.v.) + to recreate the display. If a Frame is being moved but not resized, + that is, if the shape of its containing rectangle is unchanged, + it is sufficient to use draw(3) to copy the containing rectangle + from the old to the new location and then call frsetrects to + establish the new geometry. (It is unnecessary to call frinittick + unless the font size has changed.) No redrawing is necessary. + +
+ + Frames hold text as runes, not as bytes. Frptofchar returns the + location of the upper left corner of the p’th rune, starting from + 0, in the Frame f. If f holds fewer than p runes, frptofchar returns + the location of the upper right corner of the last character in + f. Frcharofpt is the inverse: it returns the index of the closest + rune whose image’s upper left corner is up and to the left of + pt. +
+ + Frinsert inserts into Frame f starting at rune index p the runes + between r0 and r1. If a NUL (0) character is inserted, chaos will + ensue. Tabs and newlines are handled by the library, but all other + characters, including control characters, are just displayed. + For example, backspaces are printed; to erase a character, use + frdelete. +
+ + Frdelete deletes from the Frame the text between p0 and p1; p1 + points at the first rune beyond the deletion. +
+ + Frselect tracks the mouse to select a contiguous string of text + in the Frame. When called, a mouse button is typically down. Frselect + will return when the button state has changed (some buttons may + still be down) and will set f−>p0 and f−>p1 to the selected range + of text. +
+ + Programs that wish to manage the selection themselves have several + routines to help. They involve the maintenance of the ‘tick’, + the vertical line indicating a null selection between characters, + and the colored region representing a non-null selection. Frtick + draws (if up is non-zero) or removes (if up is zero) the tick + at + the screen position indicated by pt. Frdrawsel repaints a section + of the frame, delimited by character positions p0 and p1, either + with plain background or entirely highlighted, according to the + flag highlighted, managing the tick appropriately. The point pt0 + is the geometrical location of p0 on the screen; like all of the + selection-helper routines’ Point arguments, it must be a value + generated by frptofchar. Frdrawsel0 is a lower-level routine, + taking as arguments a background color, back, and text color, + text. It assumes that the tick is being handled (removed beforehand, + replaced afterwards, as required) by its caller. Frselectpaint + uses a solid color, col, to paint a region of the frame defined + by the Points p0 and p1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libframe
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), cachechars(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/genrandom.html b/man/man3/genrandom.html new file mode 100644 index 00000000..0cddd21d --- /dev/null +++ b/man/man3/genrandom.html @@ -0,0 +1,84 @@ + +genrandom(3) - Plan 9 from User Space + + + + +
+
+
GENRANDOM(3)GENRANDOM(3) +
+
+

NAME
+ +
+ + genrandom, prng – random number generation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void genrandom(uchar *buf, int nbytes) +
+ + void prng(uchar *buf, int nbytes)
+ +
+

DESCRIPTION
+ +
+ + Most security software requires a source of random or, at the + very least, unguessable numbers. +
+ + Genrandom fills a buffer with bytes from the X9.17 pseudo-random + number generator. The X9.17 generator is seeded by 24 truly random + bytes read via truerand (see rand(3)). +
+ + Prng uses the native rand(3) pseudo-random number generator to + fill the buffer. Used with srand, this function can produce a + reproducible stream of pseudo random numbers useful in testing. + +
+ + Both functions may be passed to mprand (see mp(3)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/get9root.html b/man/man3/get9root.html new file mode 100644 index 00000000..6ca02c02 --- /dev/null +++ b/man/man3/get9root.html @@ -0,0 +1,109 @@ + +get9root(3) - Plan 9 from User Space + + + + +
+
+
GET9ROOT(3)GET9ROOT(3) +
+
+

NAME
+ +
+ + get9root, unsharp – get path to root of Plan 9 tree
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       get9root(void) +
+ + char*       unsharp(char *path)
+ +
+

DESCRIPTION
+ +
+ + This tree of Plan 9 software is conventionally installed in /usr/local/plan9 + but may be installed in other places (for example, users without + the ability to write to /usr/local may with to install it in their + own home directories). The environment variable $PLAN9 should + contain the path to the root. Get9root + returns a static pointer to the pathname of root, first checking + $PLAN9 and defaulting to /usr/local/plan9. +
+ + The lack of a fixed location for the Plan 9 tree makes it difficult + to hard-code paths to files. Unsharp replaces a leading #9 in + path with the root of the tree. Unsharp also replaces a leading + #d with the path to the underlying system’s file descriptor dup + device, typically /dev/fd. The string returned from unsharp, if + different from path, should be freed with free (see malloc(3)) + when no longer needed. +
+ + As a convention, programs should never unsharp paths obtained + from user input.
+ +
+

EXAMPLE
+ +
+ + The plumber(4) uses this code to find unrooted file names included + by plumb rules.
+ +
+ + snprint(buf, sizeof buf, "#9/plumb/%s", name);
+ fd = open(unsharp(buf), OREAD);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getns.c
+ +
+

SEE ALSO
+ +
+ + intro(4)
+ +
+

BUGS
+ +
+ + Get9root could be smarter about finding the tree when $PLAN9 is + not set.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getcallerpc.html b/man/man3/getcallerpc.html new file mode 100644 index 00000000..72a835d1 --- /dev/null +++ b/man/man3/getcallerpc.html @@ -0,0 +1,99 @@ + +getcallerpc(3) - Plan 9 from User Space + + + + +
+
+
GETCALLERPC(3)GETCALLERPC(3) +
+
+

NAME
+ +
+ + getcallerpc – fetch return PC of current function
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + ulong getcallerpc(void *firstarg)
+ +
+

DESCRIPTION
+ +
+ + Getcallerpc is a portable way to discover the PC to which the + current function will return. Firstarg should be a pointer to + the first argument to the function in question.
+ +
+

EXAMPLE
+ +
+ + +
+ + void
+ printpc(ulong arg)
+ {
+ +
+ + print("Called from %.8lux\n", getcallerpc(&arg));
+ +
+ }
+ void
+ main(int argc, char *argv[])
+ {
+ +
+ + printpc(0);
+ printpc(0);
+ printpc(0);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/
+ +
+

BUGS
+ +
+ + The firstarg parameter should not be necessary.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getenv.html b/man/man3/getenv.html new file mode 100644 index 00000000..5b51354c --- /dev/null +++ b/man/man3/getenv.html @@ -0,0 +1,79 @@ + +getenv(3) - Plan 9 from User Space + + + + +
+
+
GETENV(3)GETENV(3) +
+
+

NAME
+ +
+ + getenv, putenv – access environment variables
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* getenv(char *name)
+ int     putenv(char *name, char *val)
+ +
+

DESCRIPTION
+ +
+ + Getenv fetches the environment value associated with name into + memory allocated with malloc(3), 0-terminates it, and returns + a pointer to that area. If no file exists, 0 is returned. +
+ + Putenv sets the environment value associated with name to val.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getenv.c
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, getenv and + putenv are preprocessor macros defined as p9getenv and p9putenv; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getfields.html b/man/man3/getfields.html new file mode 100644 index 00000000..7c1d8f64 --- /dev/null +++ b/man/man3/getfields.html @@ -0,0 +1,136 @@ + +getfields(3) - Plan 9 from User Space + + + + +
+
+
GETFIELDS(3)GETFIELDS(3) +
+
+

NAME
+ +
+ + getfields, gettokens, tokenize – break a string into fields
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int     getfields(char *str, char **args, int maxargs, int multiflag,
+ +
+ + +
+ + char *delims) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int     gettokens(char *str, char **args, int maxargs, char *delims) + +
+ + int     tokenize(char *str, char **args, int maxargs)
+ +
+

DESCRIPTION
+ +
+ + Getfields places into the array args pointers to the first maxargs + fields of the null terminated UTF string str. Delimiters between + these fields are set to null. +
+ + Fields are substrings of str whose definition depends on the value + of multiflag. If multiflag is zero, adjacent fields are separated + by exactly one delimiter. For example
+ +
+ + +
+ + getfields("#alice#bob##charles###", arg, 3, 0, "#");
+ +
+ +
+ yields three substrings: null-string , alice, and bob##charles###. + If the multiflag argument is not zero, a field is a non-empty + string of non-delimiters. For example
+ +
+ + +
+ + getfields("#alice#bob##charles###", arg, 3, 1, "#");
+ +
+ +
+ yields the three substrings: alice, bob, and charles###. +
+ + Getfields returns the number of fields pointed to. +
+ + Gettokens is the same as getfields with multiflag non-zero, except + that fields may be quoted using single quotes, in the manner of + rc(1). See quote(3) for related quote-handling software. +
+ + Tokenize is gettokens with delims set to "\t\r\n ".
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/tokenize.c
+ +
+

SEE ALSO
+ +
+ + strtok in strcat(3), quote(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getns.html b/man/man3/getns.html new file mode 100644 index 00000000..e5da2bb2 --- /dev/null +++ b/man/man3/getns.html @@ -0,0 +1,67 @@ + +getns(3) - Plan 9 from User Space + + + + +
+
+
GETNS(3)GETNS(3) +
+
+

NAME
+ +
+ + getns – get path to name space directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       getns(void)
+ +
+

DESCRIPTION
+ +
+ + Getns returns a pointer to a malloced string that contains the + path to the name space directory for the current process. The + name space directory is a clumsy substitute for Plan 9’s per-process + name spaces; see intro(4) for details.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getns.c
+ +
+

SEE ALSO
+ +
+ + intro(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getsnarf.html b/man/man3/getsnarf.html new file mode 100644 index 00000000..3f3e7512 --- /dev/null +++ b/man/man3/getsnarf.html @@ -0,0 +1,73 @@ + +getsnarf(3) - Plan 9 from User Space + + + + +
+
+
GETSNARF(3)GETSNARF(3) +
+
+

NAME
+ +
+ + getsnarf, putsnarf – window system snarf (cut and paste) buffer
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + char *getsnarf(void) +
+ + void putsnarf(char *text)
+ +
+

DESCRIPTION
+ +
+ + Getsnarf and putsnarf access the window system’s snarf (cut and + paste) buffer. +
+ + Getsnarf returns a copy of the current buffer; the returned pointer + should be freed with free (see malloc(3)) when no longer needed. + +
+ + Putsnarf sets the buffer to the text string text. +
+ + Callers should assume that the snarf buffer is UTF. If the window + system does not keep the buffer in UTF, getsnarf and putsnarf + will convert as necessary.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/x11−itrans.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getuser.html b/man/man3/getuser.html new file mode 100644 index 00000000..c34b23cf --- /dev/null +++ b/man/man3/getuser.html @@ -0,0 +1,75 @@ + +getuser(3) - Plan 9 from User Space + + + + +
+
+
GETUSER(3)GETUSER(3) +
+
+

NAME
+ +
+ + getuser, sysname – get user or system name
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       getuser(void) +
+ + char*       sysname(void)
+ +
+

DESCRIPTION
+ +
+ + Getuser returns a pointer to static data which contains the null-terminated + name of the user who owns the current process. Getuser calls getuid(2) + and then reads /etc/passwd to find the corresponding name. +
+ + Sysname returns a pointer to static data which contains the name + of the machine on which the current process is running. Sysname + looks first for an environment variable $sysname. If there is + no such variable, sysname calls gethostname(2) and truncates the + returned name at the first dot. If gethostname fails, + sysname returns the default name gnot. +
+ + Unlike getuser, sysname caches the string, deriving the host name + only once.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getuser.c
+ /usr/local/plan9/src/lib9/sysname.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getwd.html b/man/man3/getwd.html new file mode 100644 index 00000000..1f5d2288 --- /dev/null +++ b/man/man3/getwd.html @@ -0,0 +1,84 @@ + +getwd(3) - Plan 9 from User Space + + + + +
+
+
GETWD(3)GETWD(3) +
+
+

NAME
+ +
+ + getwd – get current directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* getwd(char *buf, int size)
+ +
+

DESCRIPTION
+ +
+ + Getwd fills buf with a null-terminated string representing the + current directory and returns buf. +
+ + Getwd places no more than size bytes in the buffer provided.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getwd.c
+ +
+

SEE ALSO
+ +
+ + pwd(1)
+ +
+

DIAGNOSTICS
+ +
+ + On error, zero is returned. Errstr(3) may be consulted for more + information.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, getwd is a + preprocessor macro defined as p9getwd; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/graphics.html b/man/man3/graphics.html new file mode 100644 index 00000000..92f08c00 --- /dev/null +++ b/man/man3/graphics.html @@ -0,0 +1,592 @@ + +graphics(3) - Plan 9 from User Space + + + + +
+
+
GRAPHICS(3)GRAPHICS(3) +
+
+

NAME
+ +
+ + Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, + initdisplay, closedisplay, getdefont, getwindow, gengetwindow, + flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, + cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, + chantostr, chantodepth – interactive graphics + +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <cursor.h>
+ +
+ + int     initdraw(void (*errfun)(Display*, char*), char *font,
+ +
+ + +
+ + char *label)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int     geninitdraw(char *devdir, void(*errfun)(Display*, char*),
+ +
+ + +
+ + +
+ + char *font, char *label, char *mousedir, char *windir,
+ int ref)
+ +
+ + +
+ +
+ int     newwindow(char *str)
+ +
+ + void    drawerror(Display *d, char *msg)
+ +
+ + Display*initdisplay(char *devdir, char *win, void(*errfun)(Display*, + char*))
+ +
+ + void    closedisplay(Display *d)
+ +
+ + Font* getdefont(Display *d)
+ +
+ + int     flushimage(Display *d, int vis)
+ +
+ + int     bufimage(Display *d, int n)
+ +
+ + int     lockdisplay(Display *d)
+ +
+ + int     unlockdisplay(Display *d)
+ +
+ + int     getwindow(Display *d, int ref)
+ +
+ + int     gengetwindow(Display *d, char *winname,
+ +
+ + +
+ + Image **ip, Screen **sp, int ref)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    cursorswitch(Cursor *curs)
+ +
+ + void    cursorset(Point p)
+ +
+ + Font* openfont(Display *d, char *name)
+ +
+ + Font* buildfont(Display *d, char *desc, char *name)
+ +
+ + void    freefont(Font *f)
+ +
+ + int     Pfmt(Fmt*)
+ +
+ + int     Rfmt(Fmt*)
+ +
+ + ulong strtochan(char *s)
+ +
+ + char* chantostr(char *s, ulong chan)
+ +
+ + int     chantodepth(ulong chan)
+ +
+ + extern Display *display
+ +
+ + extern Image     *screen
+ +
+ + extern Screen     *_screen
+ +
+ + extern Font      *font
+ +
+

DESCRIPTION
+ +
+ + A Display structure represents a connection to the graphics device, + draw(3), holding all graphics resources associated with the connection, + including in particular raster image data in use by the client + program. The structure is defined (in part) as:
+ +
+ + typedef
+ struct Display
+ {
+ +
+ + ...
+ void     (*error)(Display*, char*);
+ ...
+ Image    *black;
+ Image    *white;
+ Image    *opaque;
+ Image    *transparent;
+ Image    *image;
+ Font     *defaultfont;
+ Subfont*defaultsubfont;
+ ...
+ +
+ };
+ +
+ + +
+ A Point is a location in an Image (see below and draw(3)), such + as the display, and is defined as:
+ +
+ + typedef
+ struct Point {
+ +
+ + int x;
+ int y;
+ +
+ } Point;
+ +
+ + +
+ The coordinate system has x increasing to the right and y increasing + down. +
+ + A Rectangle is a rectangular area in an image.
+ +
+ + typedef
+ struct Rectangle {
+ +
+ + Point min;        /* upper left */
+ Point max;        /* lower right */
+ +
+ } Rectangle;
+ +
+ + +
+ By definition, min.x≤max.x and min.y≤max.y. By convention, the right + (maximum x) and bottom (maximum y) edges are excluded from the + represented rectangle, so abutting rectangles have no points in + common. Thus, max contains the coordinates of the first point + beyond the rectangle. +
+ + The Image data structure is defined in draw(3). +
+ + A Font is a set of character images, indexed by runes (see utf(7)). + The images are organized into Subfonts, each containing the images + for a small, contiguous set of runes. The detailed format of these + data structures, which are described in detail in cachechars(3), + is immaterial for most applications. Font and + Subfont structures contain two interrelated fields: ascent, the + distance from the top of the highest character (actually the top + of the image holding all the characters) to the baseline, and + height, the distance from the top of the highest character to + the bottom of the lowest character (and hence, the interline + spacing). See cachechars(3) for more details. +
+ + Buildfont parses the font description in the buffer desc, returning + a Font* pointer that can be used by string (see draw(3)) to draw + characters from the font. Openfont does the same, but reads the + description from the named file. Freefont frees a font. The convention + for naming font files is: + +
+ + /lib/font/bit/name/range.size.font +
+ + +
+ where size is approximately the height in pixels of the lower + case letters (without ascenders or descenders). Range gives some + indication of which characters will be available: for example + ascii, latin1, euro, or unicode. Euro includes most European languages, + punctuation marks, the International Phonetic + Alphabet, etc., but no Oriental languages. Unicode includes every + character for which appropriate-sized images exist on the system. + +
+ + A Cursor is defined:
+ +
+ + typedef struct
+ Cursor {
+ +
+ + Point offset;
+ uchar clr[2*16];
+ uchar set[2*16];
+ +
+ } Cursor;
+ +
+ + +
+ The arrays are arranged in rows, two bytes per row, left to right + in big-endian order to give 16 rows of 16 bits each. A cursor + is displayed on the screen by adding offset to the current mouse + position, using clr as a mask to draw white at the pixels where + clr is one, and then drawing black at the pixels where set + is one. +
+ + The routine initdraw connects to the display; it returns –1 if + it fails and sets the error string. Initdraw sets up the global + variables display (the Display structure representing the connection), + screen (an Image representing the display memory itself or, if + rio(1) is running, the client’s window), and font (the + default font for text). The arguments to initdraw include a label, + which is written to /dev/label if non-nil so that it can be used + to identify the window when hidden (see rio(1)). The font is created + by reading the named font file. If font is null, initdraw reads + the file named in the environment variable $font; if + $font is not set, it imports the default (usually minimal) font + from the operating system. The global font will be set to point + to the resulting Font structure. The errfun argument is a graphics + error function to call in the event of a fatal error in the library; + it must never return. Its arguments are the display pointer + and an error string. If errfun is nil, the library provides a + default, called drawerror. Another effect of initdraw is that + it installs print(3) formats Pfmt and Rfmt as %P and %R for printing + Points and Rectangles. +
+ + The geninitdraw function provides a less automated way to establish + a connection, for programs that wish to connect to multiple displays. + Devdir is the name of the directory containing the device files + for the display (if nil, default /dev); errfun, font, and label + are as in initdraw; mousedir and windir are the directories + holding the mouse and winname files; and ref specifies the refresh + function to be used to create the window, if running under rio(1) + (see window(3)). +
+ + Initdisplay is part of geninitdraw; it sets up the display structures + but does not allocate any fonts or call getwindow. The arguments + are similar to those of initdraw; win names the directory, default + /dev, in which the files associated with the window reside. Closedisplay + disconnects the display and frees the associated + data structures. Getdefont builds a Font structure from in-core + data describing a default font. None of these routines is needed + by most programs, since initdraw calls them as needed. +
+ + The data structures associated with the display must be protected + in a multi-process program, because they assume only one process + will be using them at a time. Multi-process programs should set + display−>locking to 1, to notify the library to use a locking protocol + for its own accesses, and call lockdisplay and + unlockdisplay around any calls to the graphics library that will + cause messages to be sent to the display device. Initdraw and + geninitdraw initialize the display to the locked state. +
+ + Getwindow returns a pointer to the window associated with the + application; it is called automatically by initdraw to establish + the screen pointer but must be called after each resizing of the + window to restore the library’s connection to the window. If rio + is not running, it returns display−>image; otherwise it + negotiates with rio by looking in /dev/winname to find the name + of the window and opening it using namedimage (see allocimage(3)). + The resulting window will be created using the refresh method + ref (see window(3)); this should almost always be Refnone because + rio provides backing store for the window. +
+ + Getwindow overwrites the global variables screen, a pointer to + the Image defining the window (or the overall display, if no window + system is running); and _screen, a pointer to the Screen representing + the root of the window’s hierarchy. (See window(3). The overloading + of the screen word is an unfortunate + historical accident.) Getwindow arranges that screen point to + the portion of the window inside the border; sophisticated clients + may use _screen to make further subwindows. Gengetwindow’s extra + arguments are the full path of the window’s winname file and pointers + to be overwritten with the values of the + ‘global’ Image and Screen variables for the new window. +
+ + The mouse cursor is always displayed. The initial cursor is an + arrow. Cursorswitch causes the argument cursor to be displayed + instead. A zero argument causes a switch back to the arrow cursor. + Cursorset moves the mouse cursor to position p, provided (if in + a window) that the requesting program is executing in the + current window and the mouse is within the window boundaries; + otherwise cursorset is a no-op. +
+ + The graphics functions described in draw(3), allocimage(3), cachechars(3), + and subfont(3) are implemented by writing commands to files under + /dev/draw (see draw(3)); the writes are buffered, so the functions + may not take effect immediately. Flushimage flushes the buffer, + doing all pending graphics operations. If + vis is non-zero, any changes are also copied from the ‘soft screen’ + (if any) in the driver to the visible frame buffer. The various + allocation routines in the library flush automatically, as does + the event package (see event(3)); most programs do not need to + call flushimage. It returns –1 on error. +
+ + Bufimage is used to allocate space for n bytes in the display + buffer. It is used by all the graphics routines to send messages + to the display. +
+ + The functions strtochan and chantostr convert between the channel + descriptor strings used by image(7) and the internal ulong representation + used by the graphics protocol (see draw(3)’s b message). Chantostr + writes at most nine bytes into the buffer pointed at by s and + returns s on success, 0 on failure. + Chantodepth returns the number of bits per pixel used by the format + specified by chan. Both chantodepth and strtochan return 0 when + presented with bad input.
+ +
+

EXAMPLES
+ +
+ + To reconnect to the window after a resize event,
+ +
+ + if(getwindow(display, Refnone) < 0)
+ +
+ + sysfatal("resize failed: %r");
+ +
+ +
+ +
+ + + +
+ +
+ To create and set up a new rio(1) window,
+ +
+ + Image *screen2;
+ Screen *_screen2;
+ srvwsys = getenv("wsys");
+ if(srvwsys == nil)
+ +
+ + sysfatal("can't find $wsys: %r");
+ +
+ rfork(RFNAMEG); /* keep mount of rio private */
+ fd = open(srvwsys, ORDWR);
+ if(fd < 0)
+ +
+ + sysfatal("can't open $wsys: %r");
+ +
+ /* mount creates window; see rio(4) */
+ if(mount(fd, −1, "/tmp", MREPL, "new −dx 300−dy 200") < 0)
+ +
+ + sysfatal("can't mount new window: %r");
+ +
+ if(gengetwindow(display, "/tmp/winname",
+ +
+ + &screen2, &_screen2, Refnone) < 0)
+ sysfatal("resize failed: %r");
+ +
+ /* now open /tmp/cons, /tmp/mouse */
+ ...
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/font/bit    directory of fonts
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + rio(1), addpt(3), allocimage(3), cachechars(3), subfont(3), draw(3), + event(3), frame(3), print(3), window(3), draw(3), image(7), font(7)
+ +
+

DIAGNOSTICS
+ +
+ + An error function may call errstr(3) for further diagnostics.
+ +
+

BUGS
+ +
+ + The names clr and set in the Cursor structure are reminders of + an archaic color map and might be more appropriately called white + and black. +
+ + These manual pages contain many references to the now-fictitious + /dev/draw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/html.html b/man/man3/html.html new file mode 100644 index 00000000..465edcdb --- /dev/null +++ b/man/man3/html.html @@ -0,0 +1,1206 @@ + +html(3) - Plan 9 from User Space + + + + +
+
+
HTML(3)HTML(3) +
+
+

NAME
+ +
+ + parsehtml, printitems, validitems, freeitems, freedocinfo, dimenkind, + dimenspec, targetid, targetname, fromStr, toStr – HTML parser
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <html.h>
+ +
+ + Item*    parsehtml(uchar* data, int datalen, Rune* src, int mtype,
+ +
+ + +
+ + int chset, Docinfo** pdi)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void     printitems(Item* items, char* msg)
+ +
+ + int      validitems(Item* items)
+ +
+ + void     freeitems(Item* items)
+ +
+ + void     freedocinfo(Docinfo* d)
+ +
+ + int      dimenkind(Dimen d)
+ +
+ + int      dimenspec(Dimen d)
+ +
+ + int      targetid(Rune* s)
+ +
+ + Rune*    targetname(int targid)
+ +
+ + uchar* fromStr(Rune* buf, int n, int chset)
+ +
+ + Rune*    toStr(uchar* buf, int n, int chset)
+ +
+

DESCRIPTION
+ +
+ + +
+ + This library implements a parser for HTML 4.0 documents. The parsed + HTML is converted into an intermediate representation that describes + how the formatted HTML should be laid out. +
+ + Parsehtml parses an entire HTML document contained in the buffer + data and having length datalen. The URL of the document should + be passed in as src. Mtype is the media type of the document, + which should be either TextHtml or TextPlain. The character set + of the document is described in chset, which can be + one of US_Ascii, ISO_8859_1, UTF_8 or Unicode. The return value + is a linked list of Item structures, described in detail below. + As a side effect, *pdi is set to point to a newly created Docinfo + structure, containing information pertaining to the entire document. + +
+ + The library expects two allocation routines to be provided by + the caller, emalloc and erealloc. These routines are analogous + to the standard malloc and realloc routines, except that they + should not return if the memory allocation fails. In addition, + emalloc is required to zero the memory. +
+ + For debugging purposes, printitems may be called to display the + contents of an item list; individual items may be printed using + the %I print verb, installed on the first call to parsehtml. validitems + traverses the item list, checking that all of the pointers are + valid. It returns 1 is everything is ok, and 0 if an error was + found. Normally, one would not call these routines directly. Instead, + one sets the global variable dbgbuild and the library calls them + automatically. One can also set warn, to cause the library to + print a warning whenever it finds a problem with the input document, + and dbglex, to print debugging information in the + lexer. +
+ + When an item list is finished with, it should be freed with freeitems. + Then, freedocinfo should be called on the pointer returned in + *pdi. +
+ + Dimenkind and dimenspec are provided to interpret the Dimen type, + as described in the section Dimension Specifications. +
+ + Frame target names are mapped to integer ids via a global, permanent + mapping. To find the value for a given name, call targetid, which + allocates a new id if the name hasn’t been seen before. The name + of a given, known id may be retrieved using targetname. The library + predefines FTtop, FTself, FTparent and + FTblank. +
+ + The library handles all text as Unicode strings (type Rune*). + Character set conversion is provided by fromStr and toStr. FromStr + takes n Unicode characters from buf and converts them to the character + set described by chset. ToStr takes n bytes from buf, interpretted + as belonging to character set chset, and converts + them to a Unicode string. Both routines null-terminate the result, + and use emalloc to allocate space for it.
+

Items
+ The return value of parsehtml is a linked list of variant structures, + with the generic portion described by the following definition: + +
+ + typedef struct Item Item;
+ struct Item
+ {
+ +
+ + Item*      next;
+ int        width;
+ int        height;
+ int        ascent;
+ int        anchorid;
+ int        state;
+ Genattr* genattr;
+ int        tag;
+ +
+ };
+ +
+ + The field next points to the successor in the linked list of items, + while width, height, and ascent are intended for use by the caller + as part of the layout process. Anchorid, if non-zero, gives the + integer id assigned by the parser to the anchor that this item + is in (see section Anchors). State is a collection of + flags and values described as follows: +
+ + enum
+ {
+ +
+ + IFbrk =           0x80000000,
+ IFbrksp =         0x40000000,
+ IFnobrk =         0x20000000,
+ IFcleft =         0x10000000,
+ IFcright =        0x08000000,
+ IFwrap =          0x04000000,
+ IFhang =          0x02000000,
+ IFrjust =         0x01000000,
+ IFcjust =         0x00800000,
+ IFsmap =          0x00400000,
+ IFindentshift = 8,
+ IFindentmask =    (255<<IFindentshift),
+ IFhangmask =      255
+ +
+ };
+ +
+ + IFbrk is set if a break is to be forced before placing this item. + IFbrksp is set if a 1 line space should be added to the break + (in which case IFbrk is also set). IFnobrk is set if a break is + not permitted before the item. IFcleft is set if left floats should + be cleared (that is, if the list of pending left floats should + be placed) before this item is placed, and IFcright is set for + right floats. In both cases, IFbrk is also set. IFwrap is set + if the line containing this item is allowed to wrap. IFhang is + set if this item hangs into the left indent. IFrjust is set if + the line containing this item should be right justified, and IFcjust + is + set for center justified lines. IFsmap is used to indicate that + an image is a server-side map. The low 8 bits, represented by + IFhangmask, indicate the current hang into left indent, in tenths + of a tabstop. The next 8 bits, represented by IFindentmask and + IFindentshift, indicate the current indent in tab + stops. +
+ + The field genattr is an optional pointer to an auxiliary structure, + described in the section Generic Attributes. +
+ + Finally, tag describes which variant type this item has. It can + have one of the values Itexttag, Iruletag, Iimagetag, Iformfieldtag, + Itabletag, Ifloattag or Ispacertag. For each of these values, + there is an additional structure defined, which includes Item + as an unnamed initial substructure, + and then defines additional fields. +
+ + Items of type Itexttag represent a piece of text, using the following + structure: +
+ + struct Itext
+ {
+ +
+ + Item;
+ Rune* s;
+ int     fnt;
+ int     fg;
+ uchar voff;
+ uchar ul;
+ +
+ };
+ +
+ + Here s is a null-terminated Unicode string of the actual characters + making up this text item, fnt is the font number (described in + the section Font Numbers), and fg is the RGB encoded color for + the text. Voff measures the vertical offset from the baseline; + subtract Voffbias to get the actual value (negative values + represent a displacement down the page). The field ul is the underline + style: ULnone if no underline, ULunder for conventional underline, + and ULmid for strike-through. +
+ + Items of type Iruletag represent a horizontal rule, as follows: + +
+ + struct Irule
+ {
+ +
+ + Item;
+ uchar align;
+ uchar noshade;
+ int     size;
+ Dimen wspec;
+ +
+ };
+ +
+ + Here align is the alignment specification (described in the corresponding + section), noshade is set if the rule should not be shaded, size + is the height of the rule (as set by the size attribute), and + wspec is the desired width (see section Dimension Specifications). + +
+ + Items of type Iimagetag describe embedded images, for which the + following structure is defined: +
+ + struct Iimage
+ {
+ +
+ + Item;
+ Rune*     imsrc;
+ int       imwidth;
+ int       imheight;
+ Rune*     altrep;
+ Map*      map;
+ int       ctlid;
+ uchar     align;
+ uchar     hspace;
+ uchar     vspace;
+ uchar     border;
+ Iimage* nextimage;
+ +
+ };
+ +
+ + Here imsrc is the URL of the image source, imwidth and imheight, + if non-zero, contain the specified width and height for the image, + and altrep is the text to use as an alternative to the image, + if the image is not displayed. Map, if set, points to a structure + describing an associated client-side image map. + Ctlid is reserved for use by the application, for handling animated + images. Align encodes the alignment specification of the image. + Hspace contains the number of pixels to pad the image with on + either side, and Vspace the padding above and below. Border is + the width of the border to draw around the + image. Nextimage points to the next image in the document (the + head of this list is Docinfo.images). +
+ + For items of type Iformfieldtag, the following structure is defined: + +
+ + struct Iformfield
+ {
+ +
+ + Item;
+ Formfield* formfield;
+ +
+ };
+ +
+ + This adds a single field, formfield, which points to a structure + describing a field in a form, described in section Forms. +
+ + For items of type Itabletag, the following structure is defined: + +
+ + struct Itable
+ {
+ +
+ + Item;
+ Table* table;
+ +
+ };
+ +
+ + Table points to a structure describing the table, described in + the section Tables. +
+ + For items of type Ifloattag, the following structure is defined: + +
+ + struct Ifloat
+ {
+ +
+ + Item;
+ Item*     item;
+ int       x;
+ int       y;
+ uchar     side;
+ uchar     infloats;
+ Ifloat* nextfloat;
+ +
+ };
+ +
+ + The item points to a single item (either a table or an image) + that floats (the text of the document flows around it), and side + indicates the margin that this float sticks to; it is either ALleft + or ALright. X and y are reserved for use by the caller; these + are typically used for the coordinates of the top of the float. + Infloats is used by the caller to keep track of whether it has + placed the float. Nextfloat is used by the caller to link together + all of the floats that it has placed. +
+ + For items of type Ispacertag, the following structure is defined: + +
+ + struct Ispacer
+ {
+ +
+ + Item;
+ int     spkind;
+ +
+ };
+ +
+ + Spkind encodes the kind of spacer, and may be one of ISPnull (zero + height and width), ISPvline (takes on height and ascent of the + current font), ISPhspace (has the width of a space in the current + font) and ISPgeneral (for all other purposes, such as between + markers and lists). +

Generic Attributes
+ +
+ + The genattr field of an item, if non-nil, points to a structure + that holds the values of attributes not specific to any particular + item type, as they occur on a wide variety of underlying HTML + tags. The structure is as follows: +
+ + typedef struct Genattr Genattr;
+ struct Genattr
+ {
+ +
+ + Rune*     id;
+ Rune*     class;
+ Rune*     style;
+ Rune*     title;
+ SEvent* events;
+ +
+ };
+ +
+ + Fields id, class, style and title, when non-nil, contain values + of correspondingly named attributes of the HTML tag associated + with this item. Events is a linked list of events (with corresponding + scripted actions) associated with the item: +
+ + typedef struct SEvent SEvent;
+ struct SEvent
+ {
+ +
+ + SEvent* next;
+ int       type;
+ Rune*     script;
+ +
+ };
+ +
+ + Here, next points to the next event in the list, type is one of + SEonblur, SEonchange, SEonclick, SEondblclick, SEonfocus, SEonkeypress, + SEonkeyup, SEonload, SEonmousedown, SEonmousemove, SEonmouseout, + SEonmouseover, SEonmouseup, SEonreset, SEonselect, + SEonsubmit or SEonunload, and script is the text of the associated + script.
+

Dimension Specifications
+ +
+ + Some structures include a dimension specification, used where + a number can be followed by a % or a * to indicate percentage + of total or relative weight. This is encoded using the following + structure: +
+ + typedef struct Dimen Dimen;
+ struct Dimen
+ {
+ +
+ + int kindspec;
+ +
+ };
+ +
+ + Separate kind and spec values are extracted using dimenkind and + dimenspec. Dimenkind returns one of Dnone, Dpixels, Dpercent or + Drelative. Dnone means that no dimension was specified. In all + other cases, dimenspec should be called to find the absolute number + of pixels, the percentage of total, or the + relative weight.
+

Background Specifications
+ +
+ + It is possible to set the background of the entire document, and + also for some parts of the document (such as tables). This is + encoded as follows: +
+ + typedef struct Background Background;
+ struct Background
+ {
+ +
+ + Rune* image;
+ int     color;
+ +
+ };
+ +
+ + Image, if non-nil, is the URL of an image to use as the background. + If this is nil, color is used instead, as the RGB value for a + solid fill color.
+

Alignment Specifications
+ +
+ + Certain items have alignment specifiers taken from the following + enumerated type: +
+ + enum
+ {
+ +
+ + ALnone = 0, ALleft, ALcenter, ALright, ALjustify,
+ ALchar, ALtop, ALmiddle, ALbottom, ALbaseline
+ +
+ };
+ +
+ + These values correspond to the various alignment types named in + the HTML 4.0 standard. If an item has an alignment of ALleft or + ALright, the library automatically encapsulates it inside a float + item. +
+ + Tables, and the various rows, columns and cells within them, have + a more complex alignment specification, composed of separate vertical + and horizontal alignments: +
+ + typedef struct Align Align;
+ struct Align
+ {
+ +
+ + uchar halign;
+ uchar valign;
+ +
+ };
+ +
+ + Halign can be one of ALnone, ALleft, ALcenter, ALright, ALjustify + or ALchar. Valign can be one of ALnone, ALmiddle, ALbottom, ALtop + or ALbaseline.
+

Font Numbers
+ +
+ + Text items have an associated font number (the fnt field), which + is encoded as style*NumSize+size. Here, style is one of FntR, + FntI, FntB or FntT, for roman, italic, bold and typewriter font + styles, respectively, and size is Tiny, Small, Normal, Large or + Verylarge. The total number of possible + font numbers is NumFnt, and the default font number is DefFnt + (which is roman style, normal size).
+

Document Info
+ +
+ + Global information about an HTML page is stored in the following + structure: +
+ + typedef struct Docinfo Docinfo;
+ struct Docinfo
+ {
+ +
+ + // stuff from HTTP headers, doc head, and body tag
+ Rune*         src;
+ Rune*         base;
+ Rune*         doctitle;
+ Background    background;
+ Iimage*       backgrounditem;
+ int           text;
+ int           link;
+ int           vlink;
+ int           alink;
+ int           target;
+ int           chset;
+ int           mediatype;
+ int           scripttype;
+ int           hasscripts;
+ Rune*         refresh;
+ Kidinfo*      kidinfo;
+ int           frameid;
+ // info needed to respond to user actions
+ Anchor*       anchors;
+ DestAnchor* dests;
+ Form*         forms;
+ Table*        tables;
+ Map*          maps;
+ Iimage*       images;
+ +
+ };
+ +
+ + Src gives the URL of the original source of the document, and + base is the base URL. Doctitle is the document’s title, as set + by a <title> element. Background is as described in the section + Background Specifications, and backgrounditem is set to be an + image item for the document’s background image + (if given as a URL), or else nil. Text gives the default foregound + text color of the document, link the unvisited hyperlink color, + vlink the visited hyperlink color, and alink the color for highlighting + hyperlinks (all in 24-bit RGB format). Target is the default target + frame id. Chset and mediatype are as for + the chset and mtype parameters to parsehtml. Scripttype is the + type of any scripts contained in the document, and is always TextJavascript. + Hasscripts is set if the document contains any scripts. Scripting + is currently unsupported. Refresh is the contents of a <meta http−equiv=Refresh + ...> tag, if any. Kidinfo is set if this document is a frameset + (see section Frames). Frameid is this document’s frame id. +
+ + Anchors is a list of hyperlinks contained in the document, and + dests is a list of hyperlink destinations within the page (see + the following section for details). Forms, tables and maps are + lists of the various forms, tables and client-side maps contained + in the document, as described in subsequent sections. + Images is a list of all the image items in the document.
+

Anchors
+ +
+ + The library builds two lists for all of the <a> elements (anchors) + in a document. Each anchor is assigned a unique anchor id within + the document. For anchors which are hyperlinks (the href attribute + was supplied), the following structure is defined: +
+ + typedef struct Anchor Anchor;
+ struct Anchor
+ {
+ +
+ + Anchor* next;
+ int       index;
+ Rune*     name;
+ Rune*     href;
+ int       target;
+ +
+ };
+ +
+ + Next points to the next anchor in the list (the head of this list + is Docinfo.anchors). Index is the anchor id; each item within + this hyperlink is tagged with this value in its anchorid field. + Name and href are the values of the correspondingly named attributes + of the anchor (in particular, href is the URL to go + to). Target is the value of the target attribute (if provided) + converted to a frame id. +
+ + Destinations within the document (anchors with the name attribute + set) are held in the Docinfo.dests list, using the following structure: + +
+ + typedef struct DestAnchor DestAnchor;
+ struct DestAnchor
+ {
+ +
+ + DestAnchor* next;
+ int           index;
+ Rune*         name;
+ Item*         item;
+ +
+ };
+ +
+ + Next is the next element of the list, index is the anchor id, + name is the value of the name attribute, and item is points to + the item within the parsed document that should be considered + to be the destination.
+

Forms
+ +
+ + Any forms within a document are kept in a list, headed by Docinfo.forms. + The elements of this list are as follows: +
+ + typedef struct Form Form;
+ struct Form
+ {
+ +
+ + Form*        next;
+ int          formid;
+ Rune*        name;
+ Rune*        action;
+ int          target;
+ int          method;
+ int          nfields;
+ Formfield* fields;
+ +
+ };
+ +
+ + Next points to the next form in the list. Formid is a serial number + for the form within the document. Name is the value of the form’s + name or id attribute. Action is the value of any action attribute. + Target is the value of the target attribute (if any) converted + to a frame target id. Method is one of HGet or + HPost. Nfields is the number of fields in the form, and fields + is a linked list of the actual fields. +
+ + The individual fields in a form are described by the following + structure: +
+ + typedef struct Formfield Formfield;
+ struct Formfield
+ {
+ +
+ + Formfield* next;
+ int          ftype;
+ int          fieldid;
+ Form*        form;
+ Rune*        name;
+ Rune*        value;
+ int          size;
+ int          maxlength;
+ int          rows;
+ int          cols;
+ uchar        flags;
+ Option*      options;
+ Item*        image;
+ int          ctlid;
+ SEvent*      events;
+ +
+ };
+ +
+ + Here, next points to the next field in the list. Ftype is the + type of the field, which can be one of Ftext, Fpassword, Fcheckbox, + Fradio, Fsubmit, Fhidden, Fimage, Freset, Ffile, Fbutton, Fselect + or Ftextarea. Fieldid is a serial number for the field within + the form. Form points back + to the form containing this field. Name, value, size, maxlength, + rows and cols each contain the values of corresponding attributes + of the field, if present. Flags contains per-field flags, of which + FFchecked and FFmultiple are defined. Image is only used for fields + of type Fimage; it points to an + image item containing the image to be displayed. Ctlid is reserved + for use by the caller, typically to store a unique id of an associated + control used to implement the field. Events is the same as the + corresponding field of the generic attributes associated with + the item containing this field. Options is only used by + fields of type Fselect; it consists of a list of possible options + that may be selected for that field, using the following structure: + +
+ + typedef struct Option Option;
+ struct Option
+ {
+ +
+ + Option* next;
+ int       selected;
+ Rune*     value;
+ Rune*     display;
+ +
+ };
+ +
+ + Next points to the next element of the list. Selected is set if + this option is to be displayed initially. Value is the value to + send when the form is submitted if this option is selected. Display + is the string to display on the screen for this option.
+

Tables
+ +
+ + The library builds a list of all the tables in the document, headed + by Docinfo.tables. Each element of this list has the following + format: +
+ + typedef struct Table Table;
+ struct Table
+ {
+ +
+ + Table*         next;
+ int           tableid;
+ Tablerow*      rows;
+ int           nrow;
+ Tablecol*      cols;
+ int           ncol;
+ Tablecell*     cells;
+ int           ncell;
+ Tablecell*** grid;
+ Align          align;
+ Dimen          width;
+ int           border;
+ int           cellspacing;
+ int           cellpadding;
+ Background     background;
+ Item*          caption;
+ uchar          caption_place;
+ Lay*           caption_lay;
+ int           totw;
+ int           toth;
+ int           caph;
+ int           availw;
+ Token*         tabletok;
+ uchar          flags;
+ +
+ };
+ +
+ + Next points to the next element in the list of tables. Tableid + is a serial number for the table within the document. Rows is + an array of row specifications (described below) and nrow is the + number of elements in this array. Similarly, cols is an array + of column specifications, and ncol the size of this array. + Cells is a list of all cells within the table (structure described + below) and ncell is the number of elements in this list. Note + that a cell may span multiple rows and/or columns, thus ncell + may be smaller than nrow*ncol. Grid is a two-dimensional array + of cells within the table; the cell at row i and column j is + Table.grid[i][j]. A cell that spans multiple rows and/or columns + will be referenced by grid multiple times, however it will only + occur once in cells. Align gives the alignment specification for + the entire table, and width gives the requested width as a dimension + specification. Border, cellspacing + and cellpadding give the values of the corresponding attributes + for the table, and background gives the requested background for + the table. Caption is a linked list of items to be displayed as + the caption of the table, either above or below depending on whether + caption_place is ALtop or ALbottom. + Most of the remaining fields are reserved for use by the caller, + except tabletok, which is reserved for internal use. The type + Lay is not defined by the library; the caller can provide its + own definition. +
+ + The Tablecol structure is defined for use by the caller. The library + ensures that the correct number of these is allocated, but leaves + them blank. The fields are as follows: +
+ + typedef struct Tablecol Tablecol;
+ struct Tablecol
+ {
+ +
+ + int     width;
+ Align align;
+ Point pos;
+ +
+ };
+ +
+ + The rows in the table are specified as follows: +
+ + typedef struct Tablerow Tablerow;
+ struct Tablerow
+ {
+ +
+ + Tablerow*    next;
+ Tablecell* cells;
+ int          height;
+ int          ascent;
+ Align        align;
+ Background background;
+ Point        pos;
+ uchar        flags;
+ +
+ };
+ +
+ + Next is only used during parsing; it should be ignored by the + caller. Cells provides a list of all the cells in a row, linked + through their nextinrow fields (see below). Height, ascent and + pos are reserved for use by the caller. Align is the alignment + specification for the row, and background is the + background to use, if specified. Flags is used by the parser; + ignore this field. +
+ + The individual cells of the table are described as follows: +
+ + typedef struct Tablecell Tablecell;
+ struct Tablecell
+ {
+ +
+ + Tablecell* next;
+ Tablecell* nextinrow;
+ int          cellid;
+ Item*        content;
+ Lay*         lay;
+ int          rowspan;
+ int          colspan;
+ Align        align;
+ uchar        flags;
+ Dimen        wspec;
+ int          hspec;
+ Background background;
+ int          minw;
+ int          maxw;
+ int          ascent;
+ int          row;
+ int          col;
+ Point        pos;
+ +
+ };
+ +
+ + Next is used to link together the list of all cells within a table + (Table.cells), whereas nextinrow is used to link together all + the cells within a single row (Tablerow.cells). Cellid provides + a serial number for the cell within the table. Content is a linked + list of the items to be laid out within the cell. Lay + is reserved for the user to describe how these items have been + laid out. Rowspan and colspan are the number of rows and columns + spanned by this cell, respectively. Align is the alignment specification + for the cell. Flags is some combination of TFparsing, TFnowrap + and TFisth or’d together. Here + TFparsing is used internally by the parser, and should be ignored. + TFnowrap means that the contents of the cell should not be wrapped + if they don’t fit the available width, rather, the table should + be expanded if need be (this is set when the nowrap attribute + is supplied). TFisth means that the cell was created + by the <th> element (rather than the <td> element), indicating that + it is a header cell rather than a data cell. Wspec provides a + suggested width as a dimension specification, and hspec provides + a suggested height in pixels. Background gives a background specification + for the individual cell. Minw, maxw, + ascent and pos are reserved for use by the caller during layout. + Row and col give the indices of the row and column of the top + left-hand corner of the cell within the table grid.
+

Client-side Maps
+ +
+ + The library builds a list of client-side maps, headed by Docinfo.maps, + and having the following structure: +
+ + typedef struct Map Map;
+ struct Map
+ {
+ +
+ + Map*    next;
+ Rune* name;
+ Area* areas;
+ +
+ };
+ +
+ + Next points to the next element in the list, name is the name + of the map (use to bind it to an image), and areas is a list of + the areas within the image that comprise the map, using the following + structure: +
+ + typedef struct Area Area;
+ struct Area
+ {
+ +
+ + Area*    next;
+ int      shape;
+ Rune*    href;
+ int      target;
+ Dimen* coords;
+ int      ncoords;
+ +
+ };
+ +
+ + Next points to the next element in the map’s list of areas. Shape + describes the shape of the area, and is one of SHrect, SHcircle + or SHpoly. Href is the URL associated with this area in its role + as a hypertext link, and target is the target frame it should + be loaded in. Coords is an array of coordinates for + the shape, and ncoords is the size of this array (number of elements).
+

Frames
+ +
+ + If the Docinfo.kidinfo field is set, the document is a frameset. + In this case, it is typical for parsehtml to return nil, as a + document which is a frameset should have no actual items that + need to be laid out (such will appear only in subsidiary documents). + It is possible that items will be returned by a malformed + document; the caller should check for this and free any such items. + +
+ + The Kidinfo structure itself reflects the fact that framesets + can be nested within a document. If is defined as follows: +
+ + typedef struct Kidinfo Kidinfo;
+ struct Kidinfo
+ {
+ +
+ + Kidinfo* next;
+ int        isframeset;
+ // fields for "frame"
+ Rune*      src;
+ Rune*      name;
+ int        marginw;
+ int        marginh;
+ int        framebd;
+ int        flags;
+ // fields for "frameset"
+ Dimen*     rows;
+ int        nrows;
+ Dimen*     cols;
+ int        ncols;
+ Kidinfo* kidinfos;
+ Kidinfo* nextframeset;
+ +
+ };
+ +
+ + Next is only used if this structure is part of a containing frameset; + it points to the next element in the list of children of that + frameset. Isframeset is set when this structure represents a frameset; + if clear, it is an individual frame. +
+ + Some fields are used only for framesets. Rows is an array of dimension + specifications for rows in the frameset, and nrows is the length + of this array. Cols is the corresponding array for columns, of + length ncols. Kidinfos points to a list of components contained + within this frameset, each of which may be a + frameset or a frame. Nextframeset is only used during parsing, + and should be ignored. +
+ + The remaining fields are used if the structure describes a frame, + not a frameset. Src provides the URL for the document that should + be initially loaded into this frame. Note that this may be a relative + URL, in which case it should be interpretted using the containing + document’s URL as the base. Name gives the name of + the frame, typically supplied via a name attribute in the HTML. + If no name was given, the library allocates one. Marginw, marginh + and framebd are the values of the marginwidth, marginheight and + frameborder attributes, respectively. Flags can contain some combination + of the following: FRnoresize (the + frame had the noresize attribute set, and the user should not + be allowed to resize it), FRnoscroll (the frame should not have + any scroll bars), FRhscroll (the frame should have a horizontal + scroll bar), FRvscroll (the frame should have a vertical scroll + bar), FRhscrollauto (the frame should be automatically + given a horizontal scroll bar if its contents would not otherwise + fit), and FRvscrollauto (the frame gets a vertical scrollbar only + if required).
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libhtml
+ +
+

SEE ALSO
+ +
+ + fmt(1) +
+ + W3C World Wide Web Consortium, “HTML 4.01 Specification”.
+ +
+

BUGS
+ +
+ + The entire HTML document must be loaded into memory before any + of it can be parsed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/index.html b/man/man3/index.html new file mode 100644 index 00000000..90e8d3cf --- /dev/null +++ b/man/man3/index.html @@ -0,0 +1,647 @@ + + +Manual Section 3 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 3 - Plan 9 from User Space +
+
+
intro(3)intro – introduction to library functions +
+
+
+
9p(3)Srv +dirread9p +emalloc9p +erealloc9p +estrdup9p +postfd +postmountsrv +readbuf +readstr +respond +srv +threadpostmountsrv +walkandclone – 9P file service +
+
+
+
9p-cmdbuf(3)Cmdbuf, parsecmd, respondcmderror, lookupcmd – control message parsing +
+
+
+
9p-fid(3)Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid +Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq – 9P fid, request tracking +
+
+
+
9p-file(3)Tree, alloctree, freetree +File, createfile, closefile, removefile, walkfile +opendirfile, readdirfile, closedirfile, hasperm – in-memory file hierarchy +
+
+
+
9p-intmap(3)Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey +deletekey – integer to data structure maps +
+
+
+
9pclient(3)CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library +
+
+
+
addpt(3)addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, Dx, Dy, Pt, Rect, Rpt – arithmetic on points and rectangles +
+
+
+
aes(3)setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption standard (rijndael) +
+
+
+
allocimage(3)allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline – allocating, freeing, reading, writing images +
+
+
+
arg(3)ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt – process option letters from argv +
+
+
+
arith3(3)add3, sub3, neg3, div3, mul3, eqpt3, closept3, dot3, cross3, len3, dist3, unit3, midpt3, lerp3, reflect3, nearseg3, pldist3, vdiv3, vrem3, pn2f3, ppp2f3, fff2p3, pdiv4, add4, sub4 – operations on 3-d points and planes +
+
+
+
atof(3)atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull – convert text to numbers +
+
+
+
bin(3)binalloc, bingrow, binfree – grouped memory allocation +
+
+
+
bio(3)Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered – buffered input/output +
+
+
+
blowfish(3)setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt - blowfish encryption +
+
+
+
cachechars(3)cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities +
+
+
+
cleanname(3)cleanname – clean a path name +
+
+
+
color(3)cmap2rgb, cmap2rgba, rgb2cmap – colors and color maps +
+
+
+
complete(3)complete, freecompletion – file name completion +
+
+
+
cputime(3)cputime, times – cpu time in this process and children +
+
+
+
ctime(3)ctime, localtime, gmtime, asctime, tm2sec, timezone – convert date and time +
+
+
+
des(3)setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, setupDES3state, triple_block_cipher, - single and triple digital encryption standard +
+
+
+
dial(3)dial, announce, listen, accept, reject, netmkaddr, dialparse – make and break network connections +
+
+
+
dirread(3)dirread, dirreadall – read directory +
+
+
+
draw(3)Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl +replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop +bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop +fillbezspline, fillbezsplineop, ellipse, ellipseop +fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop +icossin, icossin2, border, string, stringop, stringn, stringnop +runestring, runestringop, runestringn, runestringnop, stringbg +stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop +runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug – graphics functions +
+
+
+
dsa(3)dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature algorithm +
+
+
+
dup(3)dup – duplicate an open file descriptor +
+
+
+
elgamal(3)eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - elgamal encryption +
+
+
+
encode(3)dec64, enc64, dec32, enc32, dec16, enc16, encodefmt – encoding byte arrays as strings +
+
+
+
errstr(3)errstr, rerrstr, werrstr – description of last system call error +
+
+
+
event(3)event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu – graphics events +
+
+
+
exec(3)exec, execl – execute a file +
+
+
+
exits(3)exits, _exits, atexit, atexitdont, terminate – terminate process, process cleanup +
+
+
+
fcall(3)Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File protocol +
+
+
+
flate(3)deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 – deflate compression +
+
+
+
fmtinstall(3)fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt – support for user-defined print formats and output routines +
+
+
+
frame(3)frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse – frames of text +
+
+
+
genrandom(3)genrandom, prng – random number generation +
+
+
+
get9root(3)get9root, unsharp – get path to root of Plan 9 tree +
+
+
+
getcallerpc(3)getcallerpc – fetch return PC of current function +
+
+
+
getenv(3)getenv, putenv – access environment variables +
+
+
+
getfields(3)getfields, gettokens, tokenize – break a string into fields +
+
+
+
getns(3)getns – get path to name space directory +
+
+
+
getsnarf(3)getsnarf, putsnarf – window system snarf (cut and paste) buffer +
+
+
+
getuser(3)getuser, sysname – get user or system name +
+
+
+
getwd(3)getwd – get current directory +
+
+
+
graphics(3)Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth – interactive graphics +
+
+
+
html(3)parsehtml +printitems +validitems +freeitems +freedocinfo +dimenkind +dimenspec +targetid +targetname +fromStr +toStr +– HTML parser +
+
+
+
ioproc(3)closeioproc +iocall +ioclose +iointerrupt +iodial +ioopen +ioproc +ioread +ioread9pmsg +ioreadn +iorecvfd +iosendfd +iosleep +iowrite – slave I/O processes for threaded programs +
+
+
+
ip(3)eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, readipifc – Internet protocol +
+
+
+
isalpharune(3)isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, tolowerrune, totitlerune, toupperrune – Unicode character classes and cases +
+
+
+
keyboard(3)initkeyboard, ctlkeyboard, closekeyboard – keyboard control +
+
+
+
lock(3)lock, canlock, unlock +qlock, canqlock, qunlock +rlock, canrlock, runlock +wlock, canwlock, wunlock +rsleep, rwakeup, rwakeupall +incref, decref +– spin locks, queueing rendezvous locks, reader-writer locks, rendezvous points, and reference counts +
+
+
+
mach(3)machbytype, machbyname – machine-independent access to executables and programs +
+
+
+
mach-cmd(3)attachargs, attachcore, attachdynamic, attachproc, proctextfile – debugging processes and core files +
+
+
+
mach-file(3)crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc +procnotes – machine-independent access to exectuable files and running processes +
+
+
+
mach-map(3)allocmap, addseg, findseg, addrtoseg +addrtosegafter, removeseg, freemap +get1, get2, get4, get8 +put1, put2, put4, put8 +rget, rput, fpformat +locnone, locaddr, locconst, locreg, locindir +loccmp, loceval, locfmt, locsimplify +lget1, lget2, lget4, lget8 +lput1, lput2, lput4, lput8 – machine-independent +
+
+
+
mach-stack(3)stacktrace, localaddr, unwindframe, windindex, windreglocs – stack traces +
+
+
+
mach-swap(3)beswap2, beswap4, beswap8, beieeeftoa32, beieeeftoa64, beieeeftoa80 +beload2, beload4, beload8 +leswap2, leswap4, leswap8, leieeeftoa32, leieeeftoa64, leieeeftoa80 +leload2, leload4, leload8, ieeeftoa32, ieeeftoa64 – machine-independent access to byte-ordered data +
+
+
+
mach-symbol(3)symopen, symclose, findhdr, indexsym, lookupsym, findsym +findexsym, flookupsym, ffindsym +lookuplsym, indexlsym, findlsym +symoff, pc2file, file2pc, line2pc, fnbound, fileline +pc2line – symbol table access functions +
+
+
+
malloc(3)malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag – memory allocator +
+
+
+
matrix(3)ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport – Geometric transformations +
+
+
+
memdraw(3)Memimage +Memdata +Memdrawparam +memimageinit +wordaddr +byteaddr +memimagemove +allocmemimage +allocmemimaged +readmemimage +creadmemimage +writememimage +freememimage +memsetchan +loadmemimage +cloadmemimage +unloadmemimage +memfillcolor +memarc +mempoly +memellipse +memfillpoly +memimageline +memimagedraw +drawclip +memlinebbox +memlineendsize +allocmemsubfont +openmemsubfont +freememsubfont +memsubfontwidth +getmemdefont +memimagestring +iprint +hwdraw – drawing routines for memory-resident images +
+
+
+
memlayer(3)memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn – windows of memory-resident images +
+
+
+
memory(3)memccpy, memchr, memcmp, memcpy, memmove, memset – memory operations +
+
+
+
mouse(3)initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor – mouse control +
+
+
+
mousescrollsize(3)mousescrollsize – compute mouse scroll increment +
+
+
+
mp(3)mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpfactorial, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree – extended precision arithmetic +
+
+
+
muldiv(3)muldiv, umuldiv – high-precision multiplication and division +
+
+
+
mux(3)Mux, muxinit, muxrpc, muxthreads – protocol multiplexor +
+
+
+
nan(3)NaN, Inf, isNaN, isInf – not-a-number and infinity functions +
+
+
+
needstack(3)needstack – check for execution stack overflow +
+
+
+
notify(3)notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff – handle asynchronous process notification +
+
+
+
open(3)open, create, close – open a file for reading or writing, create file +
+
+
+
opentemp(3)opentemp – create a uniquely-named file +
+
+
+
pipe(3)pipe – create an interprocess channel +
+
+
+
plumb(3)eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg – plumb messages +
+
+
+
post9pservice(3)post9pservice – post 9P service for use by clients +
+
+
+
postnote(3)postnote – send a note to a process or process group +
+
+
+
prime(3)genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, smallprimetest – prime number generation +
+
+
+
print(3)print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted output +
+
+
+
proto(3)rdproto – parse and process a proto file listing +
+
+
+
pushtls(3)pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption to a communication channel +
+
+
+
qball(3)qball – 3-d rotation controller +
+
+
+
quaternion(3)qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt – Quaternion arithmetic +
+
+
+
quote(3)quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote – quoted character strings +
+
+
+
rand(3)rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand – random number generator +
+
+
+
rc4(3)setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption +
+
+
+
read(3)read, readn, write, pread, pwrite – read or write file +
+
+
+
regexp(3)regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror – regular expression +
+
+
+
rfork(3)rfork – manipulate process state +
+
+
+
rsa(3)asn1dump +asn1toRSApriv +decodepem +decodepemchain +rsadecrypt +rsaencrypt +rsafill, +rsagen +rsaprivalloc +rsaprivfree +rsaprivtopub +rsapuballoc +rsapubfree +X509toRSApub +X509dump +X509gen +X509req +X509verify – RSA encryption algorithm +
+
+
+
rune(3)runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf – rune/UTF conversion +
+
+
+
runestrcat(3)runestrcat +runestrncat +runestrcmp +runestrncmp +runestrcpy +runestrncpy +runestrecpy +runestrlen +runestrchr +runestrrchr +runestrdup +runestrstr – rune string operations +
+
+
+
sechash(3)md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle – cryptographically secure hashes +
+
+
+
seek(3)seek – change file offset +
+
+
+
sendfd(3)sendfd, recvfd – pass file descriptors along Unix domain sockets +
+
+
+
setjmp(3)setjmp, longjmp, notejmp – non-local goto +
+
+
+
sleep(3)sleep, alarm – delay, ask for delayed note +
+
+
+
stat(3)stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir – get and put file status +
+
+
+
strcat(3)strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr – string operations +
+
+
+
string(3)s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline, s_allocinstack, s_freeinstack, s_rdinstack – extensible strings +
+
+
+
stringsize(3)stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, runestringnwidth – graphical size of strings +
+
+
+
subfont(3)allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont – subfont manipulation +
+
+
+
sysfatal(3)sysfatal – system error messages +
+
+
+
thread(3)alt +chancreate +chanfree +chaninit +chanprint +chansetname +mainstacksize +proccreate +procdata +recv +recvp +recvul +send +sendp +sendul +nbrecv +nbrecvp +nbrecvul +nbsend +nbsendp +nbsendul +threadcreate +threaddata +threadexec +threadexecl +threadexits +threadexitsall +threadgetgrp +threadgetname +threadint +threadintgrp +threadkill +threadkillgrp +threadmain +threadnotify +threadid +threadpid +threadsetgrp +threadsetname +threadsetstate +threadspawn +threadwaitchan +yield – thread and proc management +
+
+
+
time(3)time, nsec – time in seconds and nanoseconds since epoch +
+
+
+
udpread(3)udpread, udpwrite – read and write UDP packets +
+
+
+
wait(3)await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid – wait for a process to exit +
+
+
+
wctl(3)drawresizewindow, drawsetlabel, drawtopwindow – window management +
+
+
+
window(3)Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow – window management +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man3/intro.html b/man/man3/intro.html new file mode 100644 index 00000000..f6f4b311 --- /dev/null +++ b/man/man3/intro.html @@ -0,0 +1,288 @@ + +intro(3) - Plan 9 from User Space + + + + +
+
+
INTRO(3)INTRO(3) +
+
+

NAME
+ +
+ + intro – introduction to library functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ +
+ + #include any Unix headers
+ +
+ + #include <libc.h>
+ +
+ + #include <auth.h>
+ +
+ + #include <bio.h>
+ +
+ + #include <draw.h>
+ +
+ + #include <fcall.h>
+ +
+ + #include <frame.h>
+ +
+ + #include <mach.h>
+ +
+ + #include <regexp.h>
+ +
+ + #include <thread.h>
+ +
+

DESCRIPTION
+ +
+ + This section describes functions in various libraries. For the + most part, each library is defined by a single C include file, + such as those listed above, and a single archive file containing + the library proper. The name of the archive is /usr/local/plan9/lib/libx.a, + where x is the base of the include file name, + stripped of a leading lib if present. For example, <draw.h> defines + the contents of library /usr/local/plan9/lib/libdraw.a, which + may be abbreviated when named to the loader as −ldraw. In practice, + each include file contains a magic pragma that directs the loader + to pick up the associated archive + automatically, so it is rarely necessary to tell the loader which + libraries a program needs; see 9c(1). +
+ + The library to which a function belongs is defined by the header + file that defines its interface. The ‘C library’, libc, contains + most of the basic subroutines such as strlen. Declarations for + all of these functions are in <libc.h>, which must be preceded by + (needs) an include of <u.h>. The graphics library, draw, is + defined by <draw.h>, which needs <libc.h> and <u.h>. The Buffered I/O + library, libbio, is defined by <bio.h>, which needs <libc.h> and <u.h>. + The ANSI C Standard I/O library, libstdio, is defined by <stdio.h>, + which needs <u.h>. There are a few other, less commonly used libraries + defined on + individual pages of this section. +
+ + The include file <u.h>, a prerequisite of several other include + files, declares the architecture-dependent and -independent types, + including: uchar, ushort, and ulong, the unsigned integer types; + schar, the signed char type; vlong and uvlong, the signed and + unsigned very long integral types; Rune, the Unicode + character type; u8int, u16int, u32int, and u64int, the unsigned + integral types with specific widths; jmp_buf, the type of the + argument to setjmp and longjmp, plus macros that define the layout + of jmp_buf (see setjmp(3)); and the macros va_arg and friends + for accessing arguments of variadic functions (identical to the + macros defined in <stdarg.h> in ANSI C). +
+ + Plan 9 and Unix use many similarly-named functions for different + purposes: for example, Plan 9’s dup is closer to (but not exactly) + Unix’s dup2. To avoid name conflicts, <libc.h> defines many of these + names as preprocessor macros to add a p9 prefix, so that dup becomes + p9dup. To disable this renaming, + #define NOPLAN9DEFINES before including <libc.h>. If Unix headers + must be included in a program, they should be included after <u.h>, + which sets important preprocessor directives (for example, to + enable 64-bit file offsets), but before <libc.h>, to avoid renaming + problems. +

Name space
+ Files are collected into a hierarchical organization called a + file tree starting in a directory called the root. File names, + also called paths, consist of a number of /-separated path elements + with the slashes corresponding to directories. A path element + must contain only printable characters (those outside the control + spaces of ASCII and Latin-1). A path element cannot contain a + slash. +
+ + When a process presents a file name to Plan 9, it is evaluated + by the following algorithm. Start with a directory that depends + on the first character of the path: / means the root of the main + hierarchy, and anything else means the process’s current working + directory. Then for each path element, look up the element in + the directory, advance to that directory, do a possible translation + (see below), and repeat. The last step may yield a directory or + regular file.
+

File I/O
+ Files are opened for input or output by open or create (see open(3)). + These calls return an integer called a file descriptor which identifies + the file to subsequent I/O calls, notably read(3) and write. The + system allocates the numbers by selecting the lowest unused descriptor. + They are allocated dynamically; there is no + visible limit to the number of file descriptors a process may + have open. They may be reassigned using dup(3). File descriptors + are indices into a kernel resident file descriptor table. Each + process has an associated file descriptor table. In threaded programs + (see thread(3)), the file descriptor table is shared by all the + procs. +
+ + By convention, file descriptor 0 is the standard input, 1 is the + standard output, and 2 is the standard error output. With one + exception, the operating system is unaware of these conventions; + it is permissible to close file 0, or even to replace it by a + file open only for writing, but many programs will be confused + by such + chicanery. The exception is that the system prints messages about + broken processes to file descriptor 2. +
+ + Files are normally read or written in sequential order. The I/O + position in the file is called the file offset and may be set + arbitrarily using the seek(3) system call. +
+ + Directories may be opened like regular files. Instead of reading + them with read(3), use the Dir structure-based routines described + in dirread(3). The entry corresponding to an arbitrary file can + be retrieved by dirstat (see stat(3)) or dirfstat; dirwstat and + dirfwstat write back entries, thus changing the properties of + a + file. +
+ + New files are made with create (see open(3)) and deleted with + remove(3). Directories may not directly be written; create, remove, + wstat, and fwstat alter them. +
+ + Pipe(3) creates a connected pair of file descriptors, useful for + bidirectional local communication.
+

Process execution and control
+ A new process is created when an existing one calls fork(2). The + new (child) process starts out with copies of the address space + and most other attributes of the old (parent) process. In particular, + the child starts out running the same program as the parent; exec(3) + will bring in a different one. +
+ + Each process has a unique integer process id; a set of open files, + indexed by file descriptor; and a current working directory (changed + by chdir(2)). +
+ + Each process has a set of attributes -- memory, open files, name + space, etc. -- that may be shared or unique. Flags to rfork control + the sharing of these attributes. +
+ + A process terminates by calling exits(3). A parent process may + call wait(3) to wait for some child to terminate. A bit of status + information may be passed from exits to wait. On Plan 9, the status + information is an arbitrary text string, but on Unix it is a single + integer. The Plan 9 interface persists here, although the + functionality does not. Instead, empty strings are converted to + exit status 0 and non-empty strings to 1. +
+ + A process can go to sleep for a specified time by calling sleep(3). + +
+ + There is a notification mechanism for telling a process about + events such as address faults, floating point faults, and messages + from other processes. A process uses notify(3) to register the + function to be called (the notification handler) when such events + occur.
+

Multithreading
+ Where possible according to the ANSI C standard, the main C library + works properly in multiprocess programs; malloc, print, and the + other routines use locks (see lock(3)) to synchronize access to + their data structures. The graphics library defined in <draw.h> + is also multi-process capable; details are in graphics(3). + In general, though, multiprocess programs should use some form + of synchronization to protect shared data. +
+ + The thread library, defined in <thread.h>, provides support for + multiprocess programs. It includes a data structure called a Channel + that can be used to send messages between processes, and coroutine-like + threads, which enable multiple threads of control within a single + process. The threads within a process + are scheduled by the library, but there is no pre-emptive scheduling + within a process; thread switching occurs only at communication + or synchronization points. +
+ + Most programs using the thread library comprise multiple processes + communicating over channels, and within some processes, multiple + threads. Since I/O calls may block, a system call may block all + the threads in a process. Therefore, a program that shouldn’t + block unexpectedly will use a process to serve the I/O + request, passing the result to the main processes over a channel + when the request completes. For examples of this design, see ioproc(3) + or mouse(3).
+ +

+

SEE ALSO
+ +
+ + nm(1), 9c(1)
+ +
+

DIAGNOSTICS
+ +
+ + Math functions in libc return special values when the function + is undefined for the given arguments or when the value is not + representable (see nan(3)). +
+ + Some of the functions in libc are system calls and many others + employ system calls in their implementation. All system calls + return integers, with –1 indicating that an error occurred; errstr(3) + recovers a string describing the error. Some user-level library + functions also use the errstr mechanism to report errors. + Functions that may affect the value of the error string are said + to “set errstr”; it is understood that the error string is altered + only if an error occurs.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ioproc.html b/man/man3/ioproc.html new file mode 100644 index 00000000..092bac91 --- /dev/null +++ b/man/man3/ioproc.html @@ -0,0 +1,211 @@ + +ioproc(3) - Plan 9 from User Space + + + + +
+
+
IOPROC(3)IOPROC(3) +
+
+

NAME
+ +
+ + closeioproc, iocall, ioclose, iointerrupt, iodial, ioopen, ioproc, + ioread, ioread9pmsg, ioreadn, iorecvfd, iosendfd, iosleep, iowrite + – slave I/O processes for threaded programs
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ typedef struct Ioproc Ioproc;
+ Ioproc* ioproc(void);
+ int       ioclose(Ioproc *io, int fd);
+ int       iodial(Ioproc *io, char *addr, char *local, char *dir, char + *cdfp);
+ int       ioopen(Ioproc *io, char *file, int omode);
+ long      ioread(Ioproc *io, int fd, void *a, long n);
+ int       ioread9pmsg(Ioproc *io, int fd, void *a, uint n);
+ long      ioreadn(Ioproc *io, int fd, void *a, long n);
+ int       iorecvfd(int socket);
+ int       iosendfd(int socket, int fd);
+ int       iosleep(int milli);
+ long      iowrite(Ioproc *io, int fd, void *a, long n);
+ void      iointerrupt(Ioproc *io);
+ void      closeioproc(Ioproc *io);
+ long      iocall(Ioproc *io, long (*op)(va_list *arg), ...);
+ +
+

DESCRIPTION
+ +
+ + +
+ + These routines provide access to I/O in slave procs. Since the + I/O itself is done in a slave proc, other threads in the calling + proc can run while the calling thread waits for the I/O to complete. + +
+ + Ioproc forks a new slave proc and returns a pointer to the Ioproc + associated with it. Ioproc uses mallocz and proccreate; if either + fails, it calls sysfatal rather than return an error. +
+ + Ioclose, iodial, ioopen, ioread, ioread9pmsg, ioreadn, iorecvfd, + iosendfd, iosleep, and iowrite execute the similarly named library + or system calls (see close(2), dial(3), open(3), read(3), fcall(3), + sendfd(3), and sleep(3)) in the slave process associated with + io. It is an error to execute more than one call at a time in + an I/O + proc. +
+ + Iointerrupt interrupts the call currently executing in the I/O + proc. If no call is executing, iointerrupt is a no-op. +
+ + Closeioproc terminates the I/O proc and frees the associated Ioproc + . +
+ + Iocall is a primitive that may be used to implement more slave + I/O routines. Iocall arranges for op to be called in io’s proc, + with arg set to the variable parameter list, returning the value + that op returns.
+ +
+

EXAMPLE
+ +
+ + Relay messages between two file descriptors, counting the total + number of bytes seen:
+ +
+ + int tot;
+ void
+ relaythread(void *v)
+ {
+ +
+ + int *fd, n;
+ char buf[1024];
+ Ioproc *io;
+ fd = v;
+ io = ioproc();
+ while((n = ioread(io, fd[0], buf, sizeof buf)) > 0){
+ if(iowrite(io, fd[1], buf, n) != n)
+ sysfatal("iowrite: %r");
+ tot += n;
+ }
+ closeioproc(io);
+ +
+ }
+ void
+ relay(int fd0, int fd1)
+ {
+ +
+ + int fd[4];
+ fd[0] = fd[3] = fd0;
+ fd[1] = fd[2] = fd1;
+ threadcreate(relaythread, fd, 8192);
+ threadcreate(relaythread, fd+2, 8192);
+ +
+ }
+ +
+ + +
+ If the two relaythread instances were running in different procs, + the common access to tot would be unsafe. +
+ + Implement ioread:
+ +
+ + static long
+ _ioread(va_list *arg)
+ {
+ +
+ + int fd;
+ void *a;
+ long n;
+ fd = va_arg(*arg, int);
+ a = va_arg(*arg, void*);
+ n = va_arg(*arg, long);
+ return read(fd, a, n);
+ +
+ }
+ long
+ ioread(Ioproc *io, int fd, void *a, long n)
+ {
+ +
+ + return iocall(io, _ioread, fd, a, n);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + dial(3), open(3), read(3), thread(3)
+ +
+

BUGS
+ +
+ + Iointerrupt is currently unimplemented.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ip.html b/man/man3/ip.html new file mode 100644 index 00000000..0376fa95 --- /dev/null +++ b/man/man3/ip.html @@ -0,0 +1,345 @@ + +ip(3) - Plan 9 from User Space + + + + +
+
+
IP(3)IP(3) +
+
+

NAME
+ +
+ + eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, + myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, + v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, + readipifc – Internet protocol
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <ip.h> +
+ + int    eipfmt(Fmt*) +
+ + ulong       parseip(uchar *ipaddr, char *str) +
+ + ulong       parseipmask(uchar *ipaddr, char *str) +
+ + char*       v4parseip(uchar *ipaddr, char *str) +
+ + ulong       v4parsecidr(uchar *addr, uchar *mask, char *str) +
+ + int    parseether(uchar *eaddr, char *str) +
+ + int    myetheraddr(uchar *eaddr, char *dev) +
+ + int    myipaddr(uchar *ipaddr, char *net) +
+ + void maskip(uchar *from, uchar *mask, uchar *to) +
+ + int    equivip(uchar *ipaddr1, uchar *ipaddr2) +
+ + uchar*      defmask(uchar *ipaddr) +
+ + int    isv4(uchar *ipaddr) +
+ + void v4tov6(uchar *ipv6, uchar *ipv4) +
+ + void v6tov4(uchar *ipv4, uchar *ipv6) +
+ + ushort      nhgets(void *p) +
+ + uint nhgetl(void *p) +
+ + uvlong      nhgetv(void *p) +
+ + void hnputs(void *p, ushort v) +
+ + void hnputl(void *p, uint v) +
+ + void hnputv(void *p, uvlong v) +
+ + ushort      ptclbsum(uchar *a, int n) +
+ + Ipifc*      readipifc(char *net, Ipifc *ifc, int index) +
+ + uchar       IPv4bcast[IPaddrlen]; +
+ + uchar       IPv4allsys[IPaddrlen]; +
+ + uchar       IPv4allrouter[IPaddrlen]; +
+ + uchar       IPallbits[IPaddrlen]; +
+ + uchar       IPnoaddr[IPaddrlen]; +
+ + uchar       v4prefix[IPaddrlen];
+ +
+

DESCRIPTION
+ +
+ + These routines are used by Internet Protocol (IP) programs to + manipulate IP and Ethernet addresses. Plan 9, by default, uses + V6 format IP addresses. Since V4 addresses fit into the V6 space, + all IP addresses can be represented. IP addresses are stored as + a string of 16 unsigned chars, Ethernet addresses as 6 + unsigned chars. Either V4 or V6 string representation can be used + for IP addresses. For V4 addresses, the representation can be + (up to) 4 decimal integers from 0 to 255 separated by periods. + For V6 addresses, the representation is (up to) 8 hex integers + from 0x0 to 0xFFFF separated by colons. Strings of 0 + integers can be elided using two colons. For example, FFFF::1111 + is equivalent to FFFF:0:0:0:0:0:0:1111. The string representation + for IP masks is a superset of the address representation. It includes + slash notation that indicates the number of leading 1 bits in + the mask. Thus, a V4 class C mask can be + represented as FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00, 255.255.255.0, + or /120. The string representation of Ethernet addresses is exactly + 12 hexadecimal digits. +
+ + Eipfmt is a print(3) formatter for Ethernet (verb E) addresses, + IP V6 (verb I) addresses, IP V4 (verb V) addresses, and IP V6 + (verb M) masks. +
+ + Parseip converts a string pointed to by str to a 16-byte IP address + starting at ipaddr. As a concession to backwards compatibility, + if the string is a V4 address, the return value is an unsigned + long integer containing the big-endian V4 address. If not, the + return value is 6. Parseipmask converts a string pointed to by + str + to a 6-byte IP mask starting at ipaddr. It too returns an unsigned + long big-endian V4 address or 6. Both routines return -1 on errors. + +
+ + V4parseip converts a string pointed to by str to a 4-byte V4 IP + address starting at ipaddr. +
+ + V4parsecidr converts a string of the form addr/mask, pointed to + by str, to a 4-byte V4 IP address starting at ipaddr and a 4-byte + V4 IP mask starting at mask. +
+ + Myipaddr returns the first valid IP address in the IP stack rooted + at net. +
+ + Parseether converts a string pointed to by str to a 6-byte Ethernet + address starting at eaddr. Myetheraddr reads the Ethernet address + string from file dev/1/stats and parses it into eaddr. Both routines + return a negative number on errors. +
+ + Maskip places the bit-wise AND of the IP addresses pointed to + by its first two arguments into the buffer pointed to by the third. + +
+ + Equivip returns non-zero if the IP addresses pointed to by its + two arguments are equal. +
+ + Defmask returns the standard class A, B, or C mask for ipaddr. + +
+ + Isv4 returns non-zero if the V6 address is in the V4 space, that + is, if it starts with 0:0:0:0:0:0:FFFF. V4tov6 converts the V4 + address, v4ip, to a V6 address and puts the result in v6ip. V6tov4 + converts the V6 address, v6ip, to a V4 address and puts the result + in v4ip. +
+ + Hnputs, hnputl, and hnputv are used to store 16-, 32-, and 64-bit + integers into IP big-endian form. Nhgets, nhgetl, and nhgetv convert + big-endian 2-, 4-, and 8-byte quantities into integers. +
+ + Pctlbsum returns the one’s complement checksum used in IP protocols, + typically invoked as
+ hnputs(hdr−>cksum, ~ptclbsum(data, len) & 0xffff);
+ +
+ + A number of standard IP addresses in V6 format are also defined. + They are:
+ IPv4bcast
+ +
+ + the V4 broadcast address
+ +
+ IPv4allsys
+ +
+ + the V4 all systems multicast address
+ +
+ IPv4allrouter
+ +
+ + the V4 all routers multicast address
+ +
+ IPallbits
+ +
+ + the V6 all bits on address
+ +
+ IPnoaddr
+ +
+ + the V6 null address, all zeros
+ +
+ v4prefix
+ +
+ + the IP V6 prefix to all embedded V4 addresses +
+ + +
+ Readipifc returns information about a particular interface (index + >= 0) or all IP interfaces (index < 0) configured under a mount + point net, default /net. Each interface is described by one Ipifc + structure which in turn points to a linked list of Iplifc structures + describing the addresses assigned to this interface. If the list + ifc is supplied, that list is freed. Thus, subsequent calls can + be used to free the list returned by the previous call. Ipifc + is: +
+ + typedef struct Ipifc
+ {
+ +
+ + Ipifc       *next;
+ Iplifc      *lifc;          /* local addressses */
+ /* per ip interface */
+ int    index;          /* number of interface in ipifc dir */
+ char dev[64];    /* associated physical device */
+ int    mtu;        /* max transfer unit */
+ long validlt;    /* valid life time */
+ long preflt;          /* preferred life time */
+ uchar       sendra6;    /* on == send router adv */
+ uchar       recvra6;    /* on == rcv router adv */
+ ulong       pktin;          /* packets read */
+ ulong       pktout;          /* packets written */
+ ulong       errin;          /* read errors */
+ ulong       errout;          /* write errors */
+ Ipv6rp      rp;         /* route advertisement params */
+ +
+ } Ipifc;
+ +
+ + Iplifc is: +
+ + struct Iplifc
+ {
+ +
+ + Iplifc      *next;
+ uchar       ip[IPaddrlen];
+ uchar       mask[IPaddrlen];
+ uchar       net[IPaddrlen];           /* ip & mask */
+ ulong       preflt;              /* preferred lifetime */
+ ulong       validlt;         /* valid lifetime */
+ +
+ };
+ +
+ + Ipv6rp is: struct Ipv6rp {       int     mflag;       int     oflag;       int     maxraint; +     /* max route adv interval */       int     minraint;     /* min route adv interval + */       int     linkmtu;       int     reachtime;       int     rxmitra;       int     ttl;       int     routerlt; +      }; +
+ + Dev contains the first 64 bytes of the device configured with + this interface. Net is ip&mask if the network is multipoint or + the remote address if the network is point to point.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libip
+ +
+

SEE ALSO
+ +
+ + print(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/isalpharune.html b/man/man3/isalpharune.html new file mode 100644 index 00000000..99c2f387 --- /dev/null +++ b/man/man3/isalpharune.html @@ -0,0 +1,96 @@ + +isalpharune(3) - Plan 9 from User Space + + + + +
+
+
ISALPHARUNE(3)ISALPHARUNE(3) +
+
+

NAME
+ +
+ + isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, + tolowerrune, totitlerune, toupperrune – Unicode character classes + and cases
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int isalpharune(Rune c) +
+ + int islowerrune(Rune c) +
+ + int isspacerune(Rune c) +
+ + int istitlerune(Rune c) +
+ + int isupperrune(Rune c) +
+ + Rune tolowerrune(Rune c) +
+ + Rune totitlerune(Rune c) +
+ + Rune toupperrune(Rune c)
+ +
+

DESCRIPTION
+ +
+ + These routines examine and operate on Unicode characters, in particular + a subset of their properties as defined in the Unicode standard. + Unicode defines some characters as alphabetic and specifies three + cases: upper, lower, and title. Analogously to isalpha(3) for + ASCII, these routines test types and modify cases for + Unicode characters. The names are self-explanatory. +
+ + The case-conversion routines return the character unchanged if + it has no case.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/utf/runetype.c
+ +
+

SEE ALSO
+ +
+ + isalpha(3), The Unicode Standard.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/keyboard.html b/man/man3/keyboard.html new file mode 100644 index 00000000..19dc833d --- /dev/null +++ b/man/man3/keyboard.html @@ -0,0 +1,135 @@ + +keyboard(3) - Plan 9 from User Space + + + + +
+
+
KEYBOARD(3)KEYBOARD(3) +
+
+

NAME
+ +
+ + initkeyboard, ctlkeyboard, closekeyboard – keyboard control
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ #include <keyboard.h>
+ +
+ + Keyboardctl      *initkeyboard(char *file)
+ +
+ + int             ctlkeyboard(Keyboardctl *kc, char *msg)
+ +
+ + void            closekeyboard(Keyboard *kc)
+ +
+

DESCRIPTION
+ +
+ + These functions access and control a keyboard interface for character-at-a-time + I/O in a multi-threaded environment, usually in combination with + mouse(3). They use the message-passing Channel interface in the + threads library (see thread(3)); programs that wish a more event-driven, + single-threaded approach + should use event(3). +
+ + Initkeyboard opens a connection to the keyboard and returns a + Keyboardctl structure:
+ +
+ + typedef struct Keyboardct Keyboardctl;
+ struct Keyboardctl
+ {
+ +
+ + Channel *c;         /* chan(Rune[20]) */
+ char      *file;
+ int       consfd;     /* to cons file */
+ int       ctlfd;      /* to ctl file */
+ int       pid;        /* of slave proc */
+ +
+ };
+ +
+ + +
+ The argument to initkeyboard is ignored (on Plan 9, it is the + name of the keyboard device). +
+ + Once the Keyboardctl is set up a message containing a Rune will + be sent on the Channel Keyboardctl.c to report each character + read from the device. +
+ + Ctlkeyboard is used to set the state of the interface, typically + to turn raw mode on and off. It writes the string msg to the control + file associated with the device, which is assumed to be the regular + device file name with the string ctl appended. +
+ + Closekeyboard closes the file descriptors associated with the + keyboard, kills the slave processes, and frees the Keyboardctl + structure. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), event(3), thread(3).
+ +
+

BUGS
+ +
+ + Because the interface delivers complete runes, there is no way + to report lesser actions such as shift keys or even individual + bytes.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/lock.html b/man/man3/lock.html new file mode 100644 index 00000000..72d66e12 --- /dev/null +++ b/man/man3/lock.html @@ -0,0 +1,222 @@ + +lock(3) - Plan 9 from User Space + + + + +
+
+
LOCK(3)LOCK(3) +
+
+

NAME
+ +
+ + lock, canlock, unlock, qlock, canqlock, qunlock, rlock, canrlock, + runlock, wlock, canwlock, wunlock, rsleep, rwakeup, rwakeupall + incref, decref – spin locks, queueing rendezvous locks, reader-writer + locks, rendezvous points, and reference counts
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ +
+ + void lock(Lock *l)
+ int    canlock(Lock *l)
+ void unlock(Lock *l)
+ +
+ + void qlock(QLock *l)
+ int    canqlock(QLock *l)
+ void qunlock(QLock *l)
+ +
+ + void rlock(RWLock *l)
+ int    canrlock(RWLock *l)
+ void runlock(RWLock *l)
+ +
+ + void wlock(RWLock *l)
+ int    canwlock(RWLock *l)
+ void wunlock(RWLock *l)
+ +
+ + typedef struct Rendez {
+ +
+ + QLock *l;
+ +
+ +
+ + ...
+ +
+ } Rendez;
+ +
+ + void rsleep(Rendez *r)
+ int    rwakeup(Rendez *r)
+ int    rwakeupall(Rendez *r)
+ +
+ + #include <thread.h>
+ +
+ + typedef struct Ref {
+ +
+ + long ref;
+ +
+ } Ref;
+ +
+ + void incref(Ref*)
+ long decref(Ref*)
+ +
+

DESCRIPTION
+ +
+ + These routines are used to synchronize processes sharing memory. + +
+ + Locks are spin locks, QLocks and RWLocks are different types of + queueing locks, and Rendezes are rendezvous points. +
+ + Locks and rendezvous points have trivial implementations in programs + not using the thread library (see thread(3)), since such programs + have no concurrency. +
+ + Used carelessly, spin locks can be expensive and can easily generate + deadlocks. Their use is discouraged, especially in programs that + use the thread library because they prevent context switches between + threads. +
+ + Lock blocks until the lock has been obtained. Canlock is non-blocking. + It tries to obtain a lock and returns a non-zero value if it was + successful, 0 otherwise. Unlock releases a lock. +
+ + QLocks have the same interface but are not spin locks; instead + if the lock is taken qlock will suspend execution of the calling + thread until it is released. +
+ + Although Locks are the more primitive lock, they have limitations; + for example, they cannot synchronize between tasks in the same + proc. Use QLocks instead. +
+ + RWLocks manage access to a data structure that has distinct readers + and writers. Rlock grants read access; runlock releases it. Wlock + grants write access; wunlock releases it. Canrlock and canwlock + are the non-blocking versions. There may be any number of simultaneous + readers, but only one writer. Moreover, if + write access is granted no one may have read access until write + access is released. +
+ + All types of lock should be initialized to all zeros before use; + this puts them in the unlocked state. +
+ + Rendezes are rendezvous points. Each Rendez r is protected by + a QLock r−>l, which must be held by the callers of rsleep, rwakeup, + and rwakeupall. Rsleep atomically releases r−>l and suspends execution + of the calling task. After resuming execution, rsleep will reacquire + r−>l before returning. If any processes + are sleeping on r, rwakeup wakes one of them. it returns 1 if + a process was awakened, 0 if not. Rwakeupall wakes all processes + sleeping on r, returning the number of processes awakened. Rwakeup + and rwakeupall do not release r−>l and do not suspend execution + of the current task. +
+ + Before use, Rendezes should be initialized to all zeros except + for r−>l pointer, which should point at the QLock that will guard + r. +
+ + A Ref contains a long that can be incremented and decremented + atomically: Incref increments the Ref in one atomic operation. + Decref atomically decrements the Ref and returns zero if the resulting + value is zero, non-zero otherwise.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/qlock.c
+ /usr/local/plan9/src/libthread
+ +
+

BUGS
+ +
+ + Locks are not always spin locks. Instead they are usually implemented + using the pthreads library’s pthread_mutex_t, whose implementation + method is not defined. +
+ + On pthreads-based systems, the implementation of Lock never calls + pthread_mutex_destroy to free the pthread_mutex_t’s. This leads + to resource leaks on FreeBSD 5 (though not on Linux 2.6, where + pthread_mutex_destroy is a no-op). +
+ + On systems that do not have a usable pthreads implementation, + the Lock implementation provided by libthread is still not exactly + a spin lock. After each unsuccessful attempt, lock calls sleep(0) + to yield the CPU; this handles the common case where some other + process holds the lock. After a thousand + unsuccessful attempts, lock sleeps for 100ms between attempts. + Another another thousand unsuccessful attempts, lock sleeps for + a full second between attempts. Locks are not intended to be held + for long periods of time. The 100ms and full second sleeps are + only heuristics to avoid tying up the CPU when a + process deadlocks. As discussed above, if a lock is to be held + for much more than a few instructions, the queueing lock types + should be almost always be used.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-cmd.html b/man/man3/mach-cmd.html new file mode 100644 index 00000000..978e80b5 --- /dev/null +++ b/man/man3/mach-cmd.html @@ -0,0 +1,167 @@ + +mach-cmd(3) - Plan 9 from User Space + + + + +
+
+
MACH-CMD(3)MACH-CMD(3) +
+
+

NAME
+ +
+ + attachargs, attachcore, attachdynamic, attachproc, proctextfile + – debugging processes and core files
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int      attachcore(Fhdr *hdr) +
+ + int      attachproc(int pid) +
+ + int      attachdynamic(void) +
+ + char*    proctextfile(int pid) +
+ + int      attachargs(int argc, char **argv, int omode) +
+ + extern Fhdr* symhdr;
+ extern     char*    symfil;
+ extern     Map*    symmap;
+ extern     Fhdr*    fhdrlist;
+ extern     Fhdr*    corhdr;
+ extern     char*    corfil;
+ extern     Map*    cormap;
+ extern     int      corpid;
+ extern     Regs*    correg;
+ +
+

DESCRIPTION
+ +
+ + These routines provide access to the objects a typical debugger + manipulates: an executable binary, some number of shared libraries, + a memory image in the form of a core dump or active process, and + a register set. +
+ + The maintained state is:
+ symhdr
+ +
+ + The file header for the main binary.
+ +
+ symfilThe file name of the main binary.
+ symmap
+ +
+ + The memory map of the main binary.
+ +
+ fhdrlist
+ +
+ + A linked list (via the Fhdr.next fields) of all currently open + headers (see symopen in mach-symbol(3)). When dynamically linked + objects have been attached, they are present in this linked list, + and therefore included in searches by indexsym, lookupsym, and + findsym (see mach-symbol(3)). + +
+ corhdrThe file header for the core dump, if any.
+ corfilThe file name of the core dump, if any.
+ cormap
+ +
+ + The memory map of the core dump or attached process.
+ +
+ corpidThe process id of the attached process, if any.
+ corregThe register set of the core dump or attached process. If + these fields are not valid, they are zeroed. +
+ + Attachcore and attachproc attach to an opened core file or an + executing process. They set corhdr, corfil, cormap, corpid, and + correg. +
+ + Proctextfile returns the name of the main binary for the process + with id pid. +
+ + Attachdynamic requires that the memory image already be attached. + It reads the dynamic linker’s internal run-time data structures + and then opens all the dynamic objects that are currently loaded. + +
+ + Attachargs uses all of these functions while parsing an argument + vector as would be passed to a debugger like db(1) or acid(1). + It expects a list of executable files, core dump files, or process + ids, given in any order. If extra arguments are given (for example, + more than one executable, or both a core dump and a + process id), they are ignored and diagnostics are printed to standard + error. If arguments are missing (for example, the process id is + given without an executable file), attachargs fills them in as + best it can.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3), mach-map(3)
+ +
+

BUGS
+ +
+ + The interface needs to be changed to support multiple threads, + each with its own register set.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-file.html b/man/man3/mach-file.html new file mode 100644 index 00000000..7fd1a578 --- /dev/null +++ b/man/man3/mach-file.html @@ -0,0 +1,185 @@ + +mach-file(3) - Plan 9 from User Space + + + + +
+
+
MACH-FILE(3)MACH-FILE(3) +
+
+

NAME
+ +
+ + crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, + detachproc, ctlproc, procnotes – machine-independent access to + exectuable files and running processes
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int     crackhdr(int fd, Fhdr *hdr)
+ void    uncrackhdr(Fhdr *hdr) +
+ + int     mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)
+ void    unmapfile(Fhdr *hdr, Map *map)
+ int     mapproc(int pid, Map *map, Regs **regs)
+ void    unmapproc(Map *map)
+ int     detachproc(int pid)
+ int     ctlproc(int pid, char *msg)
+ int     procnotes(int pid, char ***notes)
+ +
+

DESCRIPTION
+ +
+ + These functions parse executable files and provide access to those + files and to running processes. +
+ + Crackhdr opens and parses the named executable file. The returned + data structure hdr is initialized with a machine-independent description + of the header information. The following fields are the most commonly + used:
+ macha pointer to the Mach structure for the target architecture
+ mname
+ +
+ + the name of the target architecture
+ +
+ fname
+ +
+ + a description of the kind of file (e.g., executable, core dump)
+ +
+ aname
+ +
+ + a description of the application binary interface this file uses; + typically it is the name of an operating system If the global + variable mach is nil, crackhdr points it to the same Mach structure. + +
+ + +
+ Mapfile adds the segments found in hdr to map. If hdr is an executable + file, there are typically three segments: text, data, and a zero-backed + bss. If hdr is a dynamic shared library, its segments are relocated + by base before being mapping. +
+ + If hdr is a core file, there is one segment named core for each + contiguous section of memory recorded in the core file. There + are often quite a few of these, as most operating systems omit + clean memory pages when writing core files (Mac OS X is the only + exception among the supported systems). Because core files + have such holes, it is typically necessary to construct the core + map by calling mapfile on the executable and then calling it again + on the core file. Newly-added segments are mapped on top of existing + segments, so this arrangement will use the core file for the segments + it contains but fall back to the executable for the + rest. +
+ + Unmapfile removes the mappings in map corresponding to hdr. +
+ + Mapproc attaches to a running program and adds its segments to + the given map. It adds one segment for each contiguous section + of mapped memory. On systems where this information cannot be + determined, it adds a single segment covering the entire address + space. Accessing areas of this segment that are + actually not mapped in the process address space will cause the + get/put routines to return errors. +
+ + Unmapproc removes the mappings in map corresponding to pid. Detachproc + detaches from all previously attached processes. +
+ + Ctlproc manipulates the process with id pid according to the message + msg. Valid messages include:
+ killterminate the process
+ startstop
+ +
+ + start the process and wait for it to stop
+ +
+ sysstop
+ +
+ + arrange for the process to stop at its next system call, start + the process, and then wait for it to stop
+ +
+ waitstop
+ +
+ + wait for the process to stop
+ +
+ start
+ +
+ + start the process +
+ + +
+ Procnotes fills *notes with a pointer to an array of strings representing + pending notes waiting for the process. (On Unix, these notes are + textual descriptions of any pending signals.) Procnotes returns + the number of pending notes. The memory at *notes should be freed + via free (see malloc(3)) when no longer needed. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-map(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-map.html b/man/man3/mach-map.html new file mode 100644 index 00000000..ddf7275f --- /dev/null +++ b/man/man3/mach-map.html @@ -0,0 +1,312 @@ + +mach-map(3) - Plan 9 from User Space + + + + +
+
+
MACH-MAP(3)MACH-MAP(3) +
+
+

NAME
+ +
+ + allocmap, addseg, findseg, addrtoseg, addrtosegafter, removeseg, + freemap, get1, get2, get4, get8, put1, put2, put4, put8, rget, + rput, fpformat, locnone, locaddr, locconst, locreg, locindir, + loccmp, loceval, locfmt, locsimplify, lget1, lget2, lget4, lget8, + lput1, lput2, lput4, lput8 – machine-independent access to address + spaces and register sets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + typedef struct Map Map;
+ typedef struct Seg Seg;
+ +
+ + struct Seg
+ {
+ +
+ + char    *name;
+ char    *file;
+ int     fd;
+ ulong    base;
+ ulong    size;
+ ulong    offset;
+ int     (*rw)(Map*, Seg*, ulong, void*, uint, int);
+ +
+ };
+ +
+ + struct Map
+ {
+ +
+ + Seg     *seg;
+ int     nseg;
+ ...
+ +
+ };
+ +
+ + Map    *allocmap(void)
+ int     addseg(Map *map, Seg seg)
+ int     findseg(Map *map, char *name, char *file)
+ int     addrtoseg(Map *map, ulong addr, Seg *seg)
+ int     addrtosegafter(Map *map, ulong addr, Seg *seg)
+ void    removeseg(Map *map, int i)
+ void    freemap(Map *map)
+ +
+ + int     get1(Map *map, ulong addr, uchar *a, uint n)
+ int     get2(Map *map, ulong addr, u16int *u)
+ int     get4(Map *map, ulong addr, u32int *u)
+ int     get8(Map *map, ulong addr, u64int *u)
+ +
+ + int     put1(Map *map, ulong addr, uchar *a, uint n)
+ int     put2(Map *map, ulong addr, u16int u)
+ int     put4(Map *map, ulong addr, u32int u)
+ int     put8(Map *map, ulong addr, u64int u)
+ +
+ + int     rget(Regs *regs, char *reg, ulong *u)
+ int     fpformat(Map *map, char *reg, char *a, uint n, char code);
+ +
+ + int     rput(Regs *regs, char *name, ulong u)
+ +
+ + Loc    locnone(void)
+ Loc    locaddr(ulong addr)
+ Loc    locconst(ulong con)
+ Loc    locreg(char *reg)
+ Loc    locindir(char *reg, long offset)
+ +
+ + int     loccmp(Loc *a, Loc *b)
+ int     loceval(Map *map, Loc loc, ulong *addr)
+ int     locfmt(Fmt *fmt)
+ int     locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc)
+ +
+ + int     lget1(Map *map, Loc loc, uchar *a, uint n)
+ int     lget2(Map *map, Loc loc, u16int *u)
+ int     lget4(Map *map, Loc loc, u32int *u)
+ int     lget8(Map *map, Loc loc, u64int *u)
+ +
+ + int     lput1(Map *map, Loc loc, uchar *a, uint n)
+ int     lput2(Map *map, Loc loc, u16int u)
+ int     lput4(Map *map, Loc loc, u32int u)
+ int     lput8(Map *map, Loc loc, u64int u)
+ +
+ + +
+

DESCRIPTION
+ +
+ + These functions provide a processor-independent interface for + accessing executable files, core files, and running processes + via maps, data structures that provides access to an address space + and register set. The functions described in mach-file(3) are + typically used to construct these maps. Related library functions + described in mach-symbol(3) provide similar access to symbol tables. + +
+ + Each map comprises an optional register set and one or more segments, + each associating a non-overlapping range of memory addresses with + a logical section of an executable file or of a running process’s + address space. Other library functions then use a map and the + architecture-specific data structures to provide + a generic interface to the processor-dependent data. +
+ + Each segment has a name (e.g., text or data) and may be associated + with a particular file. A segment represents a range of accessible + address space. Segments may be backed an arbitary access function + (if the rw pointer is non-nil), or by the contents of an open + file (using the fd file descriptor). Each range has a + starting address in the space (base) and an extent (size). In + segments mapped by files, the range begins at byte offset in the + file. The rw function is most commonly used to provide access + to executing processes via ptrace(2) and to zeroed segments. +
+ + Allocmap creates an empty map; freemap frees a map. +
+ + Addseg adds the given segment to the map, resizing the map’s seg + array if necessary. A negative return value indicates an allocation + error. +
+ + Findseg returns the index of the segment with the given name (and, + if file is non-nil, the given file), or –1 if no such segment is + found. +
+ + Addrtoseg returns the index of the segment containing for the + given address, or –1 if that address is not mapped. Segments may + have overlapping address ranges: addseg appends segments to the + end of the seg array in the map, and addrtoseg searches the map + backwards from the end, so the most recently mapped + segment wins. +
+ + Addrtosegafter returns the index of the segment containing the + lowest mapped address greater than addr. +
+ + Removeseg removes the segment at the given index. +
+ + Get1, get2, get4, and get8 retrieve the data stored at address + addr in the address space associated with map. Get1 retrieves + n bytes of data beginning at addr into buf. Get2, get4 and get8 + retrieve 16-bit, 32-bit and 64-bit values respectively, into the + location pointed to by u. The value is byte-swapped if the source + byte order differs from that of the current architecture. This + implies that the value returned by get2, get4, and get8 may not + be the same as the byte sequences returned by get1 when n is two, + four or eight; the former may be byte-swapped, the latter reflects + the byte order of the target architecture. These functions + return the number of bytes read or a –1 when there is an error. + +
+ + Put1, put2, put4, and put8 write to the address space associated + with map. The address is translated using the map parameters and + multi-byte quantities are byte-swapped, if necessary, before they + are written. Put1 transfers n bytes stored at buf; put2, put4, + and put8 write the 16-bit, 32-bit or 64-bit quantity + contained in val, respectively. The number of bytes transferred + is returned. A –1 return value indicates an error. +
+ + When representing core files or running programs, maps also provide + access to the register set. Rget and rput read or write the register + named by reg. If the register is smaller than a ulong, the high + bits are ignored. +
+ + Fpformat converts the contents of a floating-point register to + a string. Buf is the address of a buffer of n bytes to hold the + resulting string. Code must be either F or f, selecting double + or single precision, respectively. If code is F, the contents + of the specified register and the following register are interpreted + as a + double-precision floating-point number; this is meaningful only + for architectures that implement double-precision floats by combining + adjacent single-precision registers. +
+ + A location represents a place in an executing image capable of + storing a value. Note that locations are typically passed by value + rather than by reference. +
+ + Locnone returns an unreadable, unwritable location. Locaddr returns + a location representing the memory address addr. Locreg returns + a location representing the register reg. Locindir returns an + location representing the memory address at offset added to the + value of reg. Locconst returns an imaginary unwritable + location holding the constant con; such locations are useful for + passing specific constants to functions expect locations, such + as unwind (see mach-stack(3)). +
+ + Loccmp compares two locations, returning negative, zero, or positive + values if *a is less than, equal to, or greater than *b, respectively. + Register locations are ordered before memory addresses, which + are ordered before indirections. +
+ + Locfmt is a print(3)-verb that formats a Loc structure (not a + pointer to one). +
+ + Indirection locations are needed in some contexts (e.g., when + using findlsym (see mach-symbol(3))), but bothersome in most. + Locsimplify rewrites indirections as absolute memory addresses, + by evaluating the register using the given map and adding the + offset. +
+ + The functions lget1, lget2, lget4, lget8, lput1, lput2, lput4, + and lput8 read and write the given locations, using the get, put, + rget, and rput function families as necessary.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3)
+ +
+

DIAGNOSTICS
+ +
+ + These routines set errstr.
+ +
+

BUGS
+ +
+ + This man page needs to describe Regs and Regdesc
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-stack.html b/man/man3/mach-stack.html new file mode 100644 index 00000000..d08258bd --- /dev/null +++ b/man/man3/mach-stack.html @@ -0,0 +1,232 @@ + +mach-stack(3) - Plan 9 from User Space + + + + +
+
+
MACH-STACK(3)MACH-STACK(3) +
+
+

NAME
+ +
+ + stacktrace, localaddr, unwindframe, windindex, windreglocs – stack + traces
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int     stacktrace(Map *map, Rgetter rget, Tracer trace) +
+ + int     localaddr(Map *map, Regs *regs, char *fn, char *val, ulong + *val) +
+ + int     unwindframe(Map *map, Regs *regs, ulong *next, Symbol *sym) + +
+ + int     windindex(char *regname) +
+ + Loc*    windreglocs(void)
+ +
+

DESCRIPTION
+ +
+ + Stacktrace provides machine-independent implementations of process + stack traces. They must retrieve data and register contents from + an executing image. Sometimes the desired registers are not the + current registers but rather a set of saved registers stored elsewhere + in memory. The caller may specify an initial + register set in the form of an Rgetter function, of the form +
+ + +
+ + ulong rget(Map *map, char *name)
+ +
+ + +
+ It returns the contents of a register when given a map and a register + name. It is usually sufficient for the register function to return + meaningful values only for SP and PC, and for the link register + (usually LR) on CISC machines. +
+ + Given the map and the rgetter, stacktrace unwinds the stack starting + at the innermost function. At each level in the trace, it calls + the tracer function, which has the form +
+ + +
+ + int trace(Map *map, ulong pc, ulong callerpc,
+ +
+ + Rgetter rget, Symbol *s)
+ +
+ +
+ +
+ + + +
+ +
+ The tracer is passed the map, the current program counter, the + program counter of the caller (zero if the caller is unknown), + a new rget function, and a symbol (see mach-symbol(3)) describing + the current function (nil if no symbol is known). The value returned + by the tracer controls whether the stack trace continues: a + zero or negative return value stops the trace, while a positive + return value continues it. +
+ + The rgetter passed to the tracer is not the rgetter passed to + stacktrace itself. Instead, it is a function returning the register + values at the time of the call, to the extent that they can be + reconstructed. The most common use for this rgetter is as an argument + to lget4, etc., when evaluating the locations of local + variables. +
+ + Localaddr uses stacktrace to walk up the stack looking for the + innermost instance of a function named fn ; once it finds the + function, it looks for the parameter or local variable var, storing + the address of the variable in val. +
+ + Unwindframe is the low-level function on which stacktrace is built. + Given the current memory image in map and the current register + set in regs , unwindframe fills in next with the values of the + register set at the time of the call to the function in the current + program counter. Sym should be the symbol corresponding to + the current function, if available. +
+ + The next array holds only the winding registers, typically the + caller-save registers and the program counter and stack pointer. + The order of registers in the array is called the winding order. + The winding set can be found in the array mach−>windreg, which + has mach−>nwindreg entries. Windindex returns the index of + the named register in the winding order. Windreglocs returns an + array of Loc structures corresponding to the winding registers, + in the winding order.
+ +
+

EXAMPLE
+ +
+ + The following code writes a simple stack trace to standard output, + stopping after at most 20 stack frames.
+ +
+ + static int
+ trace(Map *map, ulong pc, ulong callerpc,
+ +
+ + Rgetter rget, Symbol *s, int depth)
+ +
+ {
+ +
+ + char buf[512];
+ int i, first;
+ u32int v;
+ Symbol s2;
+ if(sym)
+ print("%s+%lx", s->name, pc - loceval(s->loc));
+ else
+ print("%lux", pc);
+ print("(");
+ first = 0;
+ for(i=0; indexlsym(s, &i, &s2)>=0; i++){
+ if(s.class != CPARAM)
+ continue;
+ if(first++)
+ print(", ");
+ if(lget4(map, rget, s->loc, &v) >= 0)
+ print("%s=%#lux", s->name, (ulong)v);
+ else
+ print("%s=???", s->name);
+ }
+ print(") called from ");
+ symoff(buf, sizeof buf, callerpc, CTEXT);
+ print("%s\n", buf);
+ return depth < 20;
+ +
+ }
+ +
+ + if(stacktrace(map, nil, trace) <= 0)
+ print("no stack frame0);
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3)
+ +
+

BUGS
+ +
+ + Need to talk about Regs
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-swap.html b/man/man3/mach-swap.html new file mode 100644 index 00000000..5eefd9d6 --- /dev/null +++ b/man/man3/mach-swap.html @@ -0,0 +1,124 @@ + +mach-swap(3) - Plan 9 from User Space + + + + +
+
+
MACH-SWAP(3)MACH-SWAP(3) +
+
+

NAME
+ +
+ + beswap2, beswap4, beswap8, beieeeftoa32, beieeeftoa64, beieeeftoa80, + beload2, beload4, beload8, leswap2, leswap4, leswap8, leieeeftoa32, + leieeeftoa64, leieeeftoa80, leload2, leload4, leload8, ieeeftoa32, + ieeeftoa64 – machine-independent access to byte-ordered data
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + u16int beswap2(u16int u)
+ u32int    beswap4(u32int u)
+ u64int    beswap8(u64int u) +
+ + int     beieeeftoa32(char *a, uint n, void *f)
+ int      beieeeftoa64(char *a, uint n, void *f)
+ int      beieeeftoa80(char *a, uint n, void *f) +
+ + u16int beload2(uchar *p)
+ u32int    beload4(uchar *p)
+ u64int    beload8(uchar *p) +
+ + u16int leswap2(u16int u)
+ u32int    leswap4(u32int u)
+ u64int    leswap8(u64int u) +
+ + int     leieeeftoa32(char *a, uint n, void *f)
+ int      leieeeftoa64(char *a, uint n, void *f)
+ int      leieeeftoa80(char *a, uint n, void *f) +
+ + u16int leload2(uchar *p)
+ u32int    leload4(uchar *p)
+ u64int    leload8(uchar *p) +
+ + int     ieeeftoa32(char *a, uint n, u32int u)
+ int      ieeeftoa64(char *a, uint n, u32int hi, u32int lo)
+ +
+

DESCRIPTION
+ +
+ + These functions provide machine-independent access to data in + a particular byte order. +
+ + Beswap2, beswap4, and beswap8 return the 2-byte, 4-byte, and 8-byte + big-endian representation of the bytes in val, respectively. +
+ + Beload2, beload4, and beload8 return the 2-byte, 4-byte, and 8-byte + big-endian interpretation of the bytes at p, respectively. +
+ + Beieeeftoa32, beieeeftoa64, and beieeeftoa80 format the big-endian + 4-byte, 8-byte, or 10-byte IEEE floating-point value at f into + the n-byte string buffer a. +
+ + Leswap2, leswap4, etc. are the little-endian equivalents of the + routines just described. +
+ + Ieeeftoa32 and ieeeftoa64 format a local machine byte-order floating-point + value into the n-byte string buffer a. Ieeeftoa32 expects a 32-bit + floating-point value stored in the bits of u. Ieeeftoa64 expects + a 64-bit floating-point value whose high 32-bits are in hi and + low 32-bits are in lo. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-symbol.html b/man/man3/mach-symbol.html new file mode 100644 index 00000000..246d51b4 --- /dev/null +++ b/man/man3/mach-symbol.html @@ -0,0 +1,272 @@ + +mach-symbol(3) - Plan 9 from User Space + + + + +
+
+
MACH-SYMBOL(3)MACH-SYMBOL(3) +
+
+

NAME
+ +
+ + symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym, + flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, + pc2file, file2pc, line2pc, fnbound, fileline, pc2line – symbol + table access functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int      symopen(Fhdr *hdr)
+ void     symclose(Fhdr *hdr)
+ Fhdr     *findhdr(char *name)
+ extern    Fhdr* fhdrlist; +
+ + int      indexsym(uint n, Symbol *s)
+ int      lookupsym(char *fn, char *var, Symbol *s)
+ int      findsym(Loc loc, uint class, Symbol *s) +
+ + int      findexsym(Fhdr *hdr, uint n, Symbol *s)
+ Symbol *flookupsym(Fhdr *hdr, char *name)
+ Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +
+ + int      indexlsym(Symbol *s1, uint n, Symbol *s2)
+ int      lookuplsym(Symbol *s1, char *name, Symbol *s2)
+ int      findlsym(Symbol *s1, Loc loc, Symbol *s2) +
+ + int      symoff(char *a, uint n, ulong addr, uint class) +
+ + int      pc2file(ulong pc, char *file, uint n, ulong *line)
+ int      pc2line(ulong pc, ulong *line)
+ int      fileline(ulong pc, char *buf, uint n)
+ int      file2pc(char *file, ulong line, ulong *pc)
+ int      line2pc(ulong basepc, ulong line, ulong *pc)
+ int      fnbound(ulong pc, ulong bounds[2])
+ +
+

DESCRIPTION
+ +
+ + These functions provide machine-independent access to the symbol + table of an executable file or executing process. Mach(3), mach-file(3), + and mach-map(3) describe additional library functions for accessing + executable files and executing processes. +
+ + Symopen uses the data in the Fhdr structure filled by crackhdr + (see mach-file(3)) to initialize in-memory structures used to + access the symbol tables contained in the file. Symclose frees + the structures. The rest of the functions described here access + a composite symbol table made up of all currently open tables. + +
+ + The set of all currently open Fhdrs is maintained as a linked + list starting at fhdrlist (chained via Fhdr.next). +
+ + Findhdr searches the currently open Fhdrs for one whose file name + ends with the path name (that is, libc.so matches /usr/lib/libc.so + but not mylibc.so). +
+ + The Symbol data structure:
+ +
+ + typedef struct Symbol Symbol;
+ struct Symbol
+ {
+ +
+ + char    *name;
+ Loc    loc;
+ Loc    hiloc;
+ char    class;
+ char    type;
+ ...
+ +
+ };
+ +
+ + +
+ describes a symbol table entry. The value field contains the offset + of the symbol within its address space: global variables relative + to the beginning of the data segment, text beyond the start of + the text segment, and automatic variables and parameters relative + to the stack frame. The type field contains the type of + the symbol:
+ +
+ + T     text segment symbol
+ t     static text segment symbol
+ D     data segment symbol
+ d     static data segment symbol
+ B     bss segment symbol
+ b     static bss segment symbol
+ a     automatic (local) variable symbol
+ p     function parameter symbol
+ U     undefined symbol
+ +
+ + +
+ The class field assigns the symbol to a general class; CTEXT, + CDATA, CAUTO, and CPARAM are the most popular. +
+ + Indexsym stores information for the n th symbol into s. The symbols + are ordered by increasing address. +
+ + Lookupsym fills a Symbol structure with symbol table information. + Global variables and functions are represented by a single name; + local variables and parameters are uniquely specified by a function + and variable name pair. Arguments fn and var contain the name + of a function and variable, respectively. If both are + non-zero, the symbol table is searched for a parameter or automatic + variable. If only var is zero, the text symbol table is searched + for function fn. If only fn is zero, the global variable table + is searched for var. +
+ + Findsym returns the symbol table entry of type class stored near + addr. The selected symbol is a global variable or function with + address nearest to and less than or equal to addr. Class specification + CDATA searches only the global variable symbol table; class CTEXT + limits the search to the text symbol table. Class + specification CANY searches the text table first, then the global + table. +
+ + Findexsym, flookupsym, and ffindsym are similar to indexsym, lookupsym, + and findsym, but operate only on the symbols from hdr. Flookupsym + and ffindsym return pointers to data stored in the hdr, which + must not be modified or freed. +
+ + Indexlsym, lookuplsym, and findlsym are similar to indexsym, lookupsym, + and findsym, but operate on the smaller symbol table of parameters + and variables local to the function represented by symbol s1. + +
+ + Indexlsym writes symbol information for the nth local symbol of + function s1 to s2. Function parameters appear first in the ordering, + followed by local symbols. +
+ + Lookuplsym writes symbol information for the symbol named name + in function s1 to s2. +
+ + Findlsym searches for a symbol local to the function s1 whose + location is exactly loc, writing its symbol information to s2. + Loc is almost always an indirection through a frame pointer register; + the details vary from architecture to architecture. +
+ + Symoff converts a location to a symbol reference. The string containing + that reference is of the form ‘name+offset’, where ‘name’ is the + name of the nearest symbol with an address less than or equal + to the target address, and ‘offset’ is the hexadecimal offset + beyond that symbol. If ‘offset’ is zero, only the name of the + symbol is printed. If no symbol is found within 4096 bytes of + the address, the address is formatted as a hexadecimal address. + Buf is the address of a buffer of n bytes to receive the formatted + string. Addr is the address to be converted. Type is the type + code of the search space: CTEXT, CDATA, or CANY. Symoff + returns the length of the formatted string contained in buf. +
+ + Pc2file searches the symbol table to find the file and line number + corresponding to the instruction at program counter pc. File is + the address of a buffer of n bytes to receive the file name. Line + receives the line number. +
+ + Pc2line is like pc2file but neglects to return information about + the source file. +
+ + Fileline is also like pc2file, but returns the file and line number + in the n-byte text buffer buf, formatted as ‘file:line’. +
+ + File2pc performs the opposite mapping: it stores in pc a text + address associated with line line in file file. +
+ + Line2pc is similar: it converts a line number to an instruction + address, storing it in pc. Since a line number does not uniquely + identify an instruction (e.g., every source file has line 1), + basepc specifies a text address from which the search begins. + Usually this is the address of the first function in the file + of interest. +
+ + Fnbound returns the start and end addresses of the function containing + the text address supplied as the first argument. The second argument + is an array of two unsigned longs; fnbound places the bounding + addresses of the function in the first and second elements of + this array. The start address is the address of the + first instruction of the function; the end address is the first + address beyond the end of the target function. +
+ + All functions return 0 on success and –1 on error. When an error + occurs, a message describing it is stored in the system error + buffer where it is available via errstr.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3), mach-map(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach.html b/man/man3/mach.html new file mode 100644 index 00000000..d69e5929 --- /dev/null +++ b/man/man3/mach.html @@ -0,0 +1,123 @@ + +mach(3) - Plan 9 from User Space + + + + +
+
+
MACH(3)MACH(3) +
+
+

NAME
+ +
+ + machbytype, machbyname – machine-independent access to executables + and programs
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + +
+ + void machbytype(int type) +
+ + int machbyname(char *name) +
+ + extern Mach *mach;
+ +
+

DESCRIPTION
+ +
+ + Libmach provides an interface for accessing the executable files + and executing images of various architectures and operating systems. + The interface is machine-independent, meaning that, for example, + Mac OS X core dumps may be inspected using an x86 Linux machine + and vice versa. In its current form, the library is + mainly useful for writing debuggers of one sort or another. +
+ + An architecture is described primarily by a Mach structure, which + contains data structures and parameters describing the particular + architecture. Most library functions assume that the global variable + mach points at the structure for the architecture being debugged. + It is set implicitly by crackhdr (see mach-file(3)) and + can be set explicitly by calling machbyname or machbytype. +
+ + There is no operating system-specific structure akin to mach. + Typically the choice of operating system on a particular architecture + affects only the executable and core dump formats; the various + file parsers deduce the operating system from information in the + binary files themselves and adjust accordingly. +
+ + The supported architectures are 386 (Intel 32-bit x86) 386 and + later) and power (IBM PowerPC, typically running Mac OS X). +
+ + Other manual pages describe the library functions in detail. +
+ + Mach-cmd(3) describes some convenience routines for attaching + to processes and core files. +
+ + Mach-file(3) describes the manipulation of binary files. +
+ + Mach-map(3) describes the interface to address spaces and register + sets in executable files and executing programs. +
+ + Mach-stack(3) describes support for unwinding the stack. +
+ + Mach-swap(3) describes helper functions for accessing data in + a particular byte order. +
+ + Mach-symbol(3) describes the interface to debugging symbol information.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach-file(3), mach-map(3), mach-stack(3), mach-swap(3), mach-symbol(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/malloc.html b/man/man3/malloc.html new file mode 100644 index 00000000..9c30c293 --- /dev/null +++ b/man/man3/malloc.html @@ -0,0 +1,181 @@ + +malloc(3) - Plan 9 from User Space + + + + +
+
+
MALLOC(3)MALLOC(3) +
+
+

NAME
+ +
+ + malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, + getmalloctag, getrealloctag – memory allocator
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void* malloc(ulong size) +
+ + void* mallocz(ulong size, int clr) +
+ + void    free(void *ptr) +
+ + void* realloc(void *ptr, ulong size) +
+ + void* calloc(ulong nelem, ulong elsize) +
+ + void    setmalloctag(void *ptr, ulong tag) +
+ + ulong getmalloctag(void *ptr) +
+ + void    setrealloctag(void *ptr, ulong tag) +
+ + ulong getrealloctag(void *ptr)
+ +
+

DESCRIPTION
+ +
+ + Malloc and free provide a simple memory allocation package. Malloc + returns a pointer to a new block of at least size bytes. The block + is suitably aligned for storage of any type of object. No two + active pointers from malloc will have the same value. The call + malloc(0) returns a valid pointer rather than null. +
+ + The argument to free is a pointer to a block previously allocated + by malloc; this space is made available for further allocation. + It is legal to free a null pointer; the effect is a no-op. The + contents of the space returned by malloc are undefined. Mallocz + behaves as malloc, except that if clr is non-zero, the memory + returned will be zeroed. +
+ + Realloc changes the size of the block pointed to by ptr to size + bytes and returns a pointer to the (possibly moved) block. The + contents will be unchanged up to the lesser of the new and old + sizes. Realloc takes on special meanings when one or both arguments + are zero:
+ realloc(0, size)
+ +
+ + means malloc(size); returns a pointer to the newly-allocated memory
+ +
+ realloc(ptr, 0)
+ +
+ + means free(ptr); returns null
+ +
+ realloc(0, 0)
+ +
+ + no-op; returns null +
+ + +
+ Calloc allocates space for an array of nelem elements of size + elsize. The space is initialized to zeros. Free frees such a block. + +
+ + The memory allocator on Plan 9 maintains two word-sized fields + associated with each block, the “malloc tag” and the “realloc + tag”. By convention, the malloc tag is the PC that allocated the + block, and the realloc tag the PC that last reallocated the block. + These may be set or examined with setmalloctag, getmalloctag, + setrealloctag, and getrealloctag. When allocating blocks directly + with malloc and realloc, these tags will be set properly. If a + custom allocator wrapper is used, the allocator wrapper can set + the tags itself (usually by passing the result of getcallerpc(3) + to setmalloctag) to provide more useful information about the + source + of allocation.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/malloc.c
+ /usr/local/plan9/src/lib9/malloctag.c
+ +
+

SEE ALSO
+ +
+ + trump (in acid(1)), getcallerpc(3)
+ +
+

DIAGNOSTICS
+ +
+ + Malloc, realloc and calloc return 0 if there is no available memory. + Errstr is likely to be set. If the allocated blocks have no malloc + or realloc tags, getmalloctag and getrealloctag return ~0. +
+ + The trump library for acid can be used to obtain traces of malloc + execution; see acid(1).
+ +
+

BUGS
+ +
+ + The different specification of calloc is bizarre. +
+ + User errors can corrupt the storage arena. The most common gaffes + are (1) freeing an already freed block, (2) storing beyond the + bounds of an allocated block, and (3) freeing data that was not + obtained from the allocator. When malloc and free detect such + corruption, they abort. +
+ + To avoid name conflicts with the system versions of these functions, + malloc, realloc, calloc, and free are preprocessor macros defined + as p9malloc, p9realloc, p9calloc, and p9free; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/matrix.html b/man/man3/matrix.html new file mode 100644 index 00000000..ad72d10a --- /dev/null +++ b/man/man3/matrix.html @@ -0,0 +1,263 @@ + +matrix(3) - Plan 9 from User Space + + + + +
+
+
MATRIX(3)MATRIX(3) +
+
+

NAME
+ +
+ + ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, + xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, + xform, ixform, persp, look, viewport – Geometric transformations
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + void ident(Matrix m) +
+ + void matmul(Matrix a, Matrix b) +
+ + void matmulr(Matrix a, Matrix b) +
+ + double determinant(Matrix m) +
+ + void adjoint(Matrix m, Matrix madj) +
+ + double invertmat(Matrix m, Matrix inv) +
+ + Point3 xformpoint(Point3 p, Space *to, Space *from) +
+ + Point3 xformpointd(Point3 p, Space *to, Space *from) +
+ + Point3 xformplane(Point3 p, Space *to, Space *from) +
+ + Space *pushmat(Space *t) +
+ + Space *popmat(Space *t) +
+ + void rot(Space *t, double theta, int axis) +
+ + void qrot(Space *t, Quaternion q) +
+ + void scale(Space *t, double x, double y, double z) +
+ + void move(Space *t, double x, double y, double z) +
+ + void xform(Space *t, Matrix m) +
+ + void ixform(Space *t, Matrix m, Matrix inv) +
+ + int persp(Space *t, double fov, double n, double f) +
+ + void look(Space *t, Point3 eye, Point3 look, Point3 up) +
+ + void viewport(Space *t, Rectangle r, double aspect)
+ +
+

DESCRIPTION
+ +
+ + These routines manipulate 3-space affine and projective transformations, + represented as 4×4 matrices, thus:
+ +
+ + typedef double Matrix[4][4];
+ +
+ + +
+ Ident stores an identity matrix in its argument. Matmul stores + a×b in a. Matmulr stores b×a in b. Determinant returns the determinant + of matrix m. Adjoint stores the adjoint (matrix of cofactors) + of m in madj. Invertmat stores the inverse of matrix m in minv, + returning m’s determinant. Should m be singular + (determinant zero), invertmat stores its adjoint in minv. +
+ + The rest of the routines described here manipulate Spaces and + transform Point3s. A Point3 is a point in three-space, represented + by its homogeneous coordinates:
+ +
+ + typedef struct Point3 Point3;
+ struct Point3{
+ +
+ + double x, y, z, w;
+ +
+ };
+ +
+ + +
+ The homogeneous coordinates (x, y, z, w) represent the Euclidean + point (x/w, y/w, z/w) if w!=0, and a “point at infinity” if w=0. + +
+ + A Space is just a data structure describing a coordinate system:
+ +
+ + typedef struct Space Space;
+ struct Space{
+ +
+ + Matrix t;
+ Matrix tinv;
+ Space *next;
+ +
+ };
+ +
+ + +
+ It contains a pair of transformation matrices and a pointer to + the Space’s parent. The matrices transform points to and from + the “root coordinate system,” which is represented by a null Space + pointer. +
+ + Pushmat creates a new Space. Its argument is a pointer to the + parent space. Its result is a newly allocated copy of the parent, + but with its next pointer pointing at the parent. Popmat discards + the Space that is its argument, returning a pointer to the stack. + Nominally, these two functions define a stack of + transformations, but pushmat can be called multiple times on the + same Space multiple times, creating a transformation tree. +
+ + Xformpoint and Xformpointd both transform points from the Space + pointed to by from to the space pointed to by to. Either pointer + may be null, indicating the root coordinate system. The difference + between the two functions is that xformpointd divides x, y, z, + and w by w, if w!=0, making (x, y, z) the Euclidean + coordinates of the point. +
+ + Xformplane transforms planes or normal vectors. A plane is specified + by the coefficients (a, b, c, d) of its implicit equation ax+by+cz+d=0. + Since this representation is dual to the homogeneous representation + of points, libgeometry represents planes by Point3 structures, + with (a, b, c, d) stored in (x, y, z, w). +
+ + The remaining functions transform the coordinate system represented + by a Space. Their Space * argument must be non-null -- you can’t + modify the root Space. Rot rotates by angle theta (in radians) + about the given axis, which must be one of XAXIS, YAXIS or ZAXIS. + Qrot transforms by a rotation about an + arbitrary axis, specified by Quaternion q. +
+ + Scale scales the coordinate system by the given scale factors + in the directions of the three axes. Move translates by the given + displacement in the three axial directions. +
+ + Xform transforms the coordinate system by the given Matrix. If + the matrix’s inverse is known a priori, calling ixform will save + the work of recomputing it. +
+ + Persp does a perspective transformation. The transformation maps + the frustum with apex at the origin, central axis down the positive + y axis, and apex angle fov and clipping planes y=n and y=f into + the double-unit cube. The plane y=n maps to y’=-1, y=f maps to + y’=1. +
+ + Look does a view-pointing transformation. The eye point is moved + to the origin. The line through the eye and look points is aligned + with the y axis, and the plane containing the eye, look and up + points is rotated into the x-y plane. +
+ + Viewport maps the unit-cube window into the given screen viewport. + The viewport rectangle r has r.min at the top left-hand corner, + and r.max just outside the lower right-hand corner. Argument aspect + is the aspect ratio (dx/dy) of the viewport’s pixels (not of the + whole viewport). The whole window is transformed + to fit centered inside the viewport with equal slop on either + top and bottom or left and right, depending on the viewport’s + aspect ratio. The window is viewed down the y axis, with x to + the left and z up. The viewport has x increasing to the right + and y increasing down. The window’s y coordinates are mapped, + unchanged, into the viewport’s z coordinates.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/matrix.c
+ +
+

SEE ALSO
+ +
+ + arith3(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memdraw.html b/man/man3/memdraw.html new file mode 100644 index 00000000..57a0c96c --- /dev/null +++ b/man/man3/memdraw.html @@ -0,0 +1,466 @@ + +memdraw(3) - Plan 9 from User Space + + + + +
+
+
MEMDRAW(3)MEMDRAW(3) +
+
+

NAME
+ +
+ + Memimage, Memdata, Memdrawparam, memimageinit, wordaddr, byteaddr, + memimagemove, allocmemimage, allocmemimaged, readmemimage, creadmemimage, + writememimage, freememimage, memsetchan, loadmemimage, cloadmemimage, + unloadmemimage, memfillcolor, memarc, mempoly, memellipse, + memfillpoly, memimageline, memimagedraw, drawclip, memlinebbox, + memlineendsize, allocmemsubfont, openmemsubfont, freememsubfont, + memsubfontwidth, getmemdefont, memimagestring, iprint, hwdraw + – drawing routines for memory-resident images
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <memdraw.h>
+ +
+ + typedef struct Memdata
+ {
+ +
+ + ulong       *base;      /* allocated data pointer */
+ uchar       *bdata;     /* first byte of actual data; word−aligned */
+ int         ref;        /* number of Memimages using this data */
+ void*       imref;      /* last image that pointed at this */
+ int         allocd;     /* is this malloc'd? */
+ +
+ } Memdata;
+ enum {
+ +
+ + Frepl       = 1<<0,     /* is replicated */
+ Fsimple     = 1<<1,     /* is 1x1 */
+ Fgrey       = 1<<2,     /* is grey */
+ Falpha      = 1<<3,     /* has explicit alpha */
+ Fcmap       = 1<<4,     /* has cmap channel */
+ Fbytes      = 1<<5,     /* has only 8−bit channels */
+ +
+ };
+ typedef struct Memimage
+ {
+ +
+ + Rectangle r;          /* rectangle in data area, local coords */
+ Rectangle clipr;      /* clipping region */
+ int         depth;      /* number of bits of storage per pixel */
+ int         nchan;      /* number of channels */
+ ulong       chan;       /* channel descriptions */
+ Memdata     *data;      /* pointer to data */
+ int         zero;       /* data−>bdata+zero==&byte containing (0,0) */
+ ulong       width;      /* width in words of a single scan line */
+ Memlayer    *layer;     /* nil if not a layer*/
+ ulong       flags;
+ +
+ +
+ + ...
+ +
+ } Memimage;
+ typedef struct Memdrawparam
+ {
+ +
+ + Memimage    *dst;
+ Rectangle r;
+ Memimage    *src;
+ Rectangle sr;
+ Memimage    *mask;
+ Rectangle mr;
+ +
+ +
+ + ...
+ +
+ } Memdrawparam;
+ int           drawdebug;
+ +
+ + void          memimageinit(void)
+ ulong*        wordaddr(Memimage *i, Point p)
+ uchar*        byteaddr(Memimage *i, Point p)
+ void          memimagemove(void *from, void *to)
+ +
+ + Memimage*     allocmemimage(Rectangle r, ulong chan)
+ Memimage*     allocmemimaged(Rectangle r, ulong chan, Memdata *data)
+ Memimage*     readmemimage(int fd)
+ Memimage*     creadmemimage(int fd)
+ int           writememimage(int fd, Memimage *i)
+ void          freememimage(Memimage *i)
+ int           memsetchan(Memimage*, ulong)
+ +
+ + int           loadmemimage(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int nbuf)
+ +
+ +
+ int           cloadmemimage(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int nbuf)
+ +
+ +
+ int           unloadmemimage(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int nbuf)
+ +
+ +
+ void          memfillcolor(Memimage *i, ulong color)
+ +
+ + void          memarc(Memimage *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Memimage *src, Point sp, int alpha, int phi, Drawop op)
+ +
+ +
+ void          mempoly(Memimage *dst, Point *p, int np, int end0,
+ +
+ + +
+ + int end1, int radius, Memimage *src, Point sp, Drawop op)
+ +
+ +
+ void          memellipse(Memimage *dst, Point c, int a, int b,
+ +
+ + +
+ + int thick, Memimage *src, Point sp, Drawop op)
+ +
+ +
+ void          memfillpoly(Memimage *dst, Point *p, int np, int wind,
+ +
+ + +
+ + Memimage *src, Point sp, Drawop op)
+ +
+ +
+ void          memimageline(Memimage *dst, Point p0, Point p1, int end0,
+ +
+ + +
+ + int end1, int radius, Memimage *src, Point sp, Drawop op)
+ +
+ +
+ void          memimagedraw(Memimage *dst, Rectangle r, Memimage *src,
+ +
+ + +
+ + Point sp, Memimage *mask, Point mp, Drawop op)
+ +
+ + +
+ +
+ int           drawclip(Memimage *dst, Rectangle *dr, Memimage *src,
+ +
+ + +
+ + Point *sp, Memimage *mask, Point *mp,
+ Rectangle *sr, Rectangle *mr)
+ +
+ +
+ Rectangle     memlinebbox(Point p0, Point p1, int end0, int end1,
+ +
+ + +
+ + int radius)
+ +
+ +
+ int           memlineendsize(int end)
+ +
+ + Memsubfont* allocmemsubfont(char *name, int n, int height,
+ +
+ + +
+ + int ascent, Fontchar *info, Memimage *i)
+ +
+ +
+ Memsubfont* openmemsubfont(char *name)
+ void          freememsubfont(Memsubfont *f)
+ Point         memsubfontwidth(Memsubfont *f, char *s)
+ Memsubfont* getmemdefont(void)
+ Point         memimagestring(Memimage *dst, Point p, Memimage *color,
+ +
+ + +
+ + Point cp, Memsubfont *f, char *cs, Drawop op)
+ +
+ + +
+ +
+ int           iprint(char *fmt, ...)
+ int           hwdraw(Memdrawparam *param)
+ +
+

DESCRIPTION
+ +
+ + The Memimage type defines memory-resident rectangular pictures + and the methods to draw upon them; Memimages differ from Images + (see draw(3)) in that they are manipulated directly in user memory + rather than by RPCs to the /dev/draw hierarchy. The library is + the basis for the kernel draw(3) driver and also + used by a number of programs that must manipulate images without + a display. +
+ + The r, clipr, depth, nchan, and chan structure elements are identical + to the ones of the same name in the Image structure. +
+ + The flags element of the Memimage structure holds a number of + bits of information about the image. In particular, it subsumes + the purpose of the repl element of Image structures. +
+ + Memimageinit initializes various static data that the library + depends on, as well as the replicated solid color images memopaque, + memtransparent, memblack, and memwhite. It should be called before + referring to any of these images and before calling any of the + other library functions. +
+ + Each Memimage points at a Memdata structure that in turn points + at the actual pixel data for the image. This allows multiple images + to be associated with the same Memdata. The first word of the + data pointed at by the base element of Memdata points back at + the Memdata structure, so that in the Plan 9 kernel, + the memory allocator (see Plan 9’s pool(3)) can compact image + memory using memimagemove. +
+ + Because images can have different coordinate systems, the zero + element of the Memimage structure contains the offset that must + be added to the bdata element of the corresponding Memdata structure + in order to yield a pointer to the data for the pixel (0,0). Adding + width machine words to this pointer moves it + down one scan line. The depth element can be used to determine + how to move the pointer horizontally. Note that this method works + even for images whose rectangles do not include the origin, although + one should only dereference pointers corresponding to pixels within + the image rectangle. Wordaddr and + byteaddr perform these calculations, returning pointers to the + word and byte, respectively, that contain the beginning of the + data for a given pixel. +
+ + Allocmemimage allocages images with a given rectangle and channel + descriptor (see strtochan in graphics(3)), creating a fresh Memdata + structure and associated storage. Allocmemimaged is similar but + uses the supplied Memdata structure rather than a new one. The + readmemimage function reads an + uncompressed bitmap from the given file descriptor, while creadmemimage + reads a compressed bitmap. Writememimage writes a compressed representation + of i to file descriptor fd. For more on bitmap formats, see image(7). + Freememimage frees images returned by any of these routines. The + Memimage structure + contains some tables that are used to store precomputed values + depending on the channel descriptor. Memsetchan updates the chan + element of the structure as well as these tables, returning –1 + if passed a bad channel descriptor. +
+ + Loadmemimage and cloadmemimage replace the pixel data for a given + rectangle of an image with the given buffer of uncompressed or + compressed data, respectively. When calling cloadmemimage, the + buffer must contain an integral number of compressed chunks of + data that exactly cover the rectangle. + Unloadmemimage retrieves the uncompressed pixel data for a given + rectangle of an image. All three return the number of bytes consumed + on success, and –1 in case of an error. +
+ + Memfillcolor fills an image with the given color, a 32-bit number + as described in color(3). +
+ + Memarc, mempoly, memellipse, memfillpoly, memimageline, and memimagedraw + are identical to the arc, poly, ellipse, fillpoly, line, and gendraw, + routines described in draw(3), except that they operate on Memimages + rather than Images. Similarly, allocmemsubfont, openmemsubfont, + freememsubfont, + memsubfontwidth, getmemdefont, and memimagestring are the Memimage + analogues of allocsubfont, openfont, freesubfont, strsubfontwidth, + getdefont, and string (see subfont(3) and graphics(3)), except + that they operate only on Memsubfonts rather than Fonts. +
+ + Drawclip takes the images involved in a draw operation, together + with the destination rectangle dr and source and mask alignment + points sp and mp, and clips them according to the clipping rectangles + of the images involved. It also fills in the rectangles sr and + mr with rectangles congruent to the returned + destination rectangle but translated so the upper left corners + are the returned sp and mp. Drawclip returns zero when the clipped + rectangle is empty. Memlinebbox returns a conservative bounding + box containing a line between two points with given end styles + and radius. Memlineendsize calculates the extra length + added to a line by attaching an end of a given style. +
+ + The hwdraw and iprint functions are no-op stubs that may be overridden + by clients of the library. Hwdraw is called at each call to memimagedraw + with the current request’s parameters. If it can satisfy the request, + it should do so and return 1. If it cannot satisfy the request, + it should return 0. This allows (for + instance) the kernel to take advantage of hardware acceleration. + Iprint should format and print its arguments; it is given much + debugging output when the global integer variable drawdebug is + non-zero. In the kernel, iprint prints to a serial line rather + than the screen, for obvious reasons. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + addpt(3), color(3), draw(3), graphics(3), memlayer(3), stringsize(3), + subfont(3), color(7), utf(7)
+ +
+

BUGS
+ +
+ + Memimagestring is unusual in using a subfont rather than a font, + and in having no parameter to align the source. +
+ + These functions are archived into libdraw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memlayer.html b/man/man3/memlayer.html new file mode 100644 index 00000000..c21f5bf6 --- /dev/null +++ b/man/man3/memlayer.html @@ -0,0 +1,325 @@ + +memlayer(3) - Plan 9 from User Space + + + + +
+
+
MEMLAYER(3)MEMLAYER(3) +
+
+

NAME
+ +
+ + memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, + memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, + memltofront, memltofrontn, memltorear, memltorearn – windows of + memory-resident images
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <memdraw.h>
+ #include <memlayer.h>
+ +
+ + typedef struct Memscreen Memscreen;
+ typedef struct Memlayer Memlayer;
+ typedef void (*Refreshfn)(Memimage*, Rectangle, void*);
+ struct Memscreen
+ {
+ +
+ + Memimage    *frontmost; /* frontmost layer on screen */
+ Memimage    *rearmost;    /* rearmost layer on screen */
+ Memimage    *image;       /* upon which all layers are drawn */
+ Memimage    *fill;        /* if non−zero, picture to use when repainting + */
+ +
+ };
+ struct Memlayer
+ {
+ +
+ + Rectangle screenr;      /* true position of layer on screen */
+ Point       delta;        /* add delta to go from image coords to screen */
+ Memscreen *screen;      /* screen this layer belongs to */
+ Memimage    *front;       /* window in front of this one */
+ Memimage    *rear;        /* window behind this one*/
+ int         clear;        /* layer is fully visible */
+ Memimage    *save;        /* save area for obscured parts */
+ Refreshfn refreshfn;    /* fn to refresh obscured parts if save==nil + */
+ void        *refreshptr;/* argument to refreshfn */
+ +
+ };
+ +
+ + Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void + *arg, ulong col)
+ +
+ + void        memlnorefresh(Memimage *i, Rectangle r, void *arg)
+ +
+ + int         memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)
+ +
+ + int         memldelete(Memimage *i)
+ +
+ + int         memlfree(Memimage *i)
+ +
+ + int         memlexpose(Memimage *i, Rectangle r)
+ +
+ + int         memlhide(Memimage *i, Rectangle r)
+ +
+ + void        memltofront(Memimage *i)
+ +
+ + void        memltofrontn(Memimage**ia, int n)
+ +
+ + void        memltorear(Memimage *i)
+ +
+ + void        memltorearn(Memimage **ia , int n)
+ +
+ + int         memlorigin(Memimage *i, Point log, Point phys)
+ +
+ + void        memdraw(Image *dst, Rectangle r,
+ +
+ + +
+ + Image *src, Point sp, Image *mask, Point mp, Drawop op)
+ +
+ +
+ int         memload(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int n, int iscompressed) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int         memunload(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int n) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ +
+

DESCRIPTION
+ +
+ + These functions build upon the memdraw(3) interface to maintain + overlapping graphical windows on in-memory images. They are used + by the kernel to implement the windows interface presented by + draw(3) and window(3) and probably have little use outside of + the kernel. +
+ + The basic function is to extend the definition of a Memimage (see + memdraw(3)) to include overlapping windows defined by the Memlayer + type. The first fields of the Memlayer structure are identical + to those in Memimage, permitting a function that expects a Memimage + to be passed a Memlayer, and vice versa. + Both structures have a save field, which is nil in a Memimage + and points to ‘backing store’ in a Memlayer. The layer routines + accept Memimages or Memlayers; if the image is a Memimage the + underlying Memimage routine is called; otherwise the layer routines + recursively subdivide the geometry, reducing the + operation into a smaller component that ultimately can be performed + on a Memimage, either the display on which the window appears, + or the backing store. +
+ + Memlayers are associated with a Memscreen that holds the data + structures to maintain the windows and connects them to the associated + image. The fill color is used to paint the background when a window + is deleted. There is no function to establish a Memscreen; to + create one, allocate the memory, zero + frontmost and rearmost, set fill to a valid fill color or image, + and set image to the Memimage (or Memlayer) on which the windows + will be displayed. +
+ + Memlalloc allocates a Memlayer of size r on Memscreen s. If col + is not DNofill, the new window will be initialized by painting + it that color. +
+ + The refresh function fn and associated argument arg will be called + by routines in the library to restore portions of the window uncovered + due to another window being deleted or this window being pulled + to the front of the stack. The function, when called, receives + a pointer to the image (window) being refreshed, the + rectangle that has been uncovered, and the arg recorded when the + window was created. A couple of predefined functions provide built-in + management methods: memlnorefresh does no backup at all, useful + for making efficient temporary windows; while a nil function specifies + that the backing store + (Memlayer.save) will be used to keep the obscured data. Other + functions may be provided by the client. Memlsetrefresh allows + one to change the function associated with the window. +
+ + Memldelete deletes the window i, restoring the underlying display. + Memlfree frees the data structures without unlinking the window + from the associated Memscreen or doing any graphics. +
+ + Memlexpose restores rectangle r within the window, using the backing + store or appropriate refresh method. Memlhide goes the other way, + backing up r so that that portion of the screen may be modified + without losing the data in this window. +
+ + Memltofront pulls i to the front of the stack of windows, making + it fully visible. Memltofrontn pulls the n windows in the array + ia to the front as a group, leaving their internal order unaffected. + Memltorear and memltorearn push the windows to the rear. +
+ + Memlorigin changes the coordinate systems associated with the + window i. The points log and phys represent the upper left corner + (min) of the window’s internal coordinate system and its physical + location on the screen. Changing log changes the interpretation + of coordinates within the window; for example, setting it + to (0, 0) makes the upper left corner of the window appear to + be the origin of the coordinate system, regardless of its position + on the screen. Changing phys changes the physical location of + the window on the screen. When a window is created, its logical + and physical coordinates are the same, so + +
+ + +
+ + memlorigin(i, i−>r.min, i−>r.min)
+ +
+ +
+ would be a no-op. +
+ + Memdraw and memline are implemented in the layer library but provide + the main entry points for drawing on memory-resident windows. + They have the signatures of memimagedraw and memimageline (see + memdraw(3)) but accept Memlayer or Memimage arguments both. +
+ + Memload and memunload are similarly layer-savvy versions of loadmemimage + and unloadmemimage. The iscompressed flag to memload specifies + whether the n bytes of data in buf are in compressed image format + (see image(7)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), memdraw(3), stringsize(3), window(3), draw(3)
+ +
+

BUGS
+ +
+ + These functions are archived into libdraw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memory.html b/man/man3/memory.html new file mode 100644 index 00000000..a67101b7 --- /dev/null +++ b/man/man3/memory.html @@ -0,0 +1,123 @@ + +memory(3) - Plan 9 from User Space + + + + +
+
+
MEMORY(3)MEMORY(3) +
+
+

NAME
+ +
+ + memccpy, memchr, memcmp, memcpy, memmove, memset – memory operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void* memccpy(void *s1, void *s2, int c, long n) +
+ + void* memchr(void *s, int c, long n) +
+ + int     memcmp(void *s1, void *s2, long n) +
+ + void* memcpy(void *s1, void *s2, long n) +
+ + void* memmove(void *s1, void *s2, long n) +
+ + void* memset(void *s, int c, long n)
+ +
+

DESCRIPTION
+ +
+ + These functions operate efficiently on memory areas (arrays of + bytes bounded by a count, not terminated by a zero byte). They + do not check for the overflow of any receiving memory area. +
+ + Memccpy copies bytes from memory area s2 into s1, stopping after + the first occurrence of byte c has been copied, or after n bytes + have been copied, whichever comes first. It returns a pointer + to the byte after the copy of c in s1, or zero if c was not found + in the first n bytes of s2. +
+ + Memchr returns a pointer to the first occurrence of byte c in + the first n bytes of memory area s, or zero if c does not occur. + +
+ + Memcmp compares its arguments, looking at the first n bytes only, + and returns an integer less than, equal to, or greater than 0, + according as s1 is lexicographically less than, equal to, or greater + than s2. The comparison is bytewise unsigned. +
+ + Memcpy copies n bytes from memory area s2 to s1. It returns s1. + +
+ + Memmove works like memcpy, except that it is guaranteed to work + if s1 and s2 overlap. +
+ + Memset sets the first n bytes in memory area s to the value of + byte c. It returns s.
+ +
+

SOURCE
+ +
+ + All these routines have portable C implementations in /usr/local/plan9/src/lib9.
+ +
+

SEE ALSO
+ +
+ + strcat(3)
+ +
+

BUGS
+ +
+ + ANSI C does not require memcpy to handle overlapping source and + destination; on Plan 9, it does, so memmove and memcpy behave + identically. +
+ + If memcpy and memmove are handed a negative count, they abort.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mouse.html b/man/man3/mouse.html new file mode 100644 index 00000000..5e2b278d --- /dev/null +++ b/man/man3/mouse.html @@ -0,0 +1,249 @@ + +mouse(3) - Plan 9 from User Space + + + + +
+
+
MOUSE(3)MOUSE(3) +
+
+

NAME
+ +
+ + initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, + drawgetrect, menuhit, setcursor – mouse control
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <thread.h>
+ #include <mouse.h>
+ #include <cursor.h>
+ +
+ + Mousectl    *initmouse(char *file, Image *i)
+ +
+ + int         readmouse(Mousectl *mc)
+ +
+ + int         atomouse();
+ +
+ + void        closemouse(Mousectl *mc)
+ +
+ + void        moveto(Mousectl *mc, Point pt)
+ +
+ + void        setcursor(Mousectl *mc, Cursor *c)
+ +
+ + Rectangle getrect(int but, Mousectl *mc)
+ +
+ + void        drawgetrect(Rectangle r, int up)
+ +
+ + int         menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)
+ +
+

DESCRIPTION
+ +
+ + These functions access and control a mouse in a multi-threaded + environment. They use the message-passing Channel interface in + the threads library (see thread(3)); programs that wish a more + event-driven, single-threaded approach should use event(3). +
+ + The state of the mouse is recorded in a structure, Mouse, defined + in <mouse.h>:
+ +
+ + typedef struct Mouse Mouse;
+ struct Mouse
+ {
+ +
+ + int         buttons;     /* bit array: LMR=124 */
+ Point       xy;
+ ulong       msec;
+ +
+ };
+ +
+ + +
+ The Point xy records the position of the cursor, buttons the state + of the buttons (three bits representing, from bit 0 up, the buttons + from left to right, 0 if the button is released, 1 if it is pressed), + and msec, a millisecond time stamp. +
+ + The routine initmouse returns a structure through which one may + access the mouse:
+ +
+ + typedef struct Mousectl Mousectl;
+ struct Mousectl
+ {
+ +
+ + Mouse;
+ Channel     *c;          /* chan(Mouse)[16] */
+ Channel     *resizec;    /* chan(int)[2] */
+ char        *file;
+ int         mfd;         /* to mouse file */
+ int         cfd;         /* to cursor file */
+ int         pid;         /* of slave proc */
+ Image*      image;       /* of associated window/display */
+ +
+ };
+ +
+ + +
+ The arguments to initmouse are a file naming the device file connected + to the mouse and an Image (see draw(3)) on which the mouse will + be visible. Typically the file is nil, which requests the default + /dev/mouse; and the image is the window in which the program is + running, held in the variable screen after a call + to initdraw. +
+ + Once the Mousectl is set up, mouse motion will be reported by + messages of type Mouse sent on the Channel Mousectl.c. Typically, + a message will be sent every time a read of /dev/mouse succeeds, + which is every time the state of the mouse changes. +
+ + When the window is resized, a message is sent on Mousectl.resizec. + The actual value sent may be discarded; the receipt of the message + tells the program that it should call getwindow (see graphics(3)) + to reconnect to the window. +
+ + Readmouse updates the Mouse structure held in the Mousectl, blocking + if the state has not changed since the last readmouse or message + sent on the channel. It calls flushimage (see graphics(3)) before + blocking, so any buffered graphics requests are displayed. +
+ + Closemouse closes the file descriptors associated with the mouse, + kills the slave processes, and frees the Mousectl structure. +
+ + Moveto moves the mouse cursor on the display to the position specified + by pt. +
+ + Setcursor sets the image of the cursor to that specified by c. + If c is nil, the cursor is set to the default. The format of the + cursor data is spelled out in <cursor.h> and described in graphics(3). + +
+ + Getrect returns the dimensions of a rectangle swept by the user, + using the mouse, in the manner rio(1) or sam(1) uses to create + a new window. The but argument specifies which button the user + must press to sweep the window; any other button press cancels + the action. The returned rectangle is all zeros if the user + cancels. +
+ + Getrect uses successive calls to drawgetrect to maintain the red + rectangle showing the sweep-in-progress. The rectangle to be drawn + is specified by rc and the up parameter says whether to draw (1) + or erase (0) the rectangle. +
+ + Menuhit provides a simple menu mechanism. It uses a Menu structure + defined in <mouse.h>:
+ +
+ + typedef struct Menu Menu;
+ struct Menu
+ {
+ +
+ + char        **item;
+ char        *(*gen)(int);
+ int         lasthit;
+ +
+ };
+ +
+ + +
+ Menuhit behaves the same as its namesake emenuhit described in + event(3), with two exceptions. First, it uses a Mousectl to access + the mouse rather than using the event interface; and second, it + creates the menu as a true window on the Screen scr (see window(3)), + permitting the menu to be displayed in parallel + with other activities on the display. If scr is null, menuhit + behaves like emenuhit, creating backing store for the menu, writing + the menu directly on the display, and restoring the display when + the menu is removed. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), event(3), keyboard(3), thread(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mousescrollsize.html b/man/man3/mousescrollsize.html new file mode 100644 index 00000000..3aa816fb --- /dev/null +++ b/man/man3/mousescrollsize.html @@ -0,0 +1,108 @@ + +mousescrollsize(3) - Plan 9 from User Space + + + + +
+
+
MOUSESCROLLSIZE(3)MOUSESCROLLSIZE(3) +
+
+

NAME
+ +
+ + mousescrollsize – compute mouse scroll increment
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + int     mousescrollsize(int maxlines)
+ +
+

DESCRIPTION
+ +
+ + Mousescrollsize computes the number of lines of text that should + be scrolled in response to a mouse scroll wheel click. Maxlines + is the number of lines visible in the text window. +
+ + The default scroll increment is one line. This default can be + overridden by setting the $mousescrollsize environment variable + to an integer, which specifies a constant number of lines, or + to a real number followed by a percent character, indicating that + the scroll increment should be a percentage of the total + number of lines in the window. For example, setting $mousescrollsize + to 50% causes a half-window scroll increment. +
+ + Mousescrollsize is used by 9term(1) and acme(1) to set their scrolling + behavior.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/scroll.c
+ +
+

SEE ALSO
+ +
+ + 9term(1), acme(1)
+ +
+

BUGS
+ +
+ + Libdraw expects up and down scroll wheel events to be expressed + as clicks of mouse buttons 4 and 5, but the XFree86 default is + to ignore the scroll wheel. To enable the scroll wheel, change + your InputDevice section of XF86Config−4 to look like:
+ +
+ + Section "InputDevice"
+ +
+ + Identifier       "Mouse0"
+ Driver      "mouse"
+ Option      "Device" "/dev/psaux"
+ # next four lines enable scroll wheel as buttons 4 and 5
+ Option      "Buttons" "5"
+ Option      "Emulate3Buttons" "off"
+ Option      "Protocol" "ImPS/2"
+ Option      "ZAxisMapping" "4 5"
+ +
+ EndSection
+ +
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mp.html b/man/man3/mp.html new file mode 100644 index 00000000..86dc7455 --- /dev/null +++ b/man/man3/mp.html @@ -0,0 +1,441 @@ + +mp(3) - Plan 9 from User Space + + + + +
+
+
MP(3)MP(3) +
+
+

NAME
+ +
+ + mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, + mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, + mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, + mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpfactorial, + mpcmp, mpextendedgcd, + mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, + mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, + crtpre, crtin, crtout, crtprefree, crtresfree – extended precision + arithmetic
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h> +
+ + mpint*      mpnew(int n) +
+ + void mpfree(mpint *b) +
+ + void mpsetminbits(int n) +
+ + void mpbits(mpint *b, int n) +
+ + void mpnorm(mpint *b) +
+ + mpint*      mpcopy(mpint *b) +
+ + void mpassign(mpint *old, mpint *new) +
+ + mpint*      mprand(int bits, void (*gen)(uchar*, int), mpint *b) +
+ + mpint*      strtomp(char *buf, char **rptr, int base, mpint *b) +
+ + char*       mptoa(mpint *b, int base, char *buf, int blen) +
+ + int    mpfmt(Fmt*) +
+ + mpint*      betomp(uchar *buf, uint blen, mpint *b) +
+ + int    mptobe(mpint *b, uchar *buf, uint blen, uchar **bufp) +
+ + mpint*      letomp(uchar *buf, uint blen, mpint *b) +
+ + int    mptole(mpint *b, uchar *buf, uint blen, uchar **bufp) +
+ + uint mptoui(mpint*) +
+ + mpint*      uitomp(uint, mpint*) +
+ + int    mptoi(mpint*) +
+ + mpint*      itomp(int, mpint*) +
+ + mpint*      vtomp(vlong, mpint*) +
+ + vlong       mptov(mpint*) +
+ + mpint*      uvtomp(uvlong, mpint*) +
+ + uvlong      mptouv(mpint*) +
+ + void mpadd(mpint *b1, mpint *b2, mpint *sum) +
+ + void mpmagadd(mpint *b1, mpint *b2, mpint *sum) +
+ + void mpsub(mpint *b1, mpint *b2, mpint *diff) +
+ + void mpmagsub(mpint *b1, mpint *b2, mpint *diff) +
+ + void mpleft(mpint *b, int shift, mpint *res) +
+ + void mpright(mpint *b, int shift, mpint *res) +
+ + void mpmul(mpint *b1, mpint *b2, mpint *prod) +
+ + void mpexp(mpint *b, mpint *e, mpint *m, mpint *res) +
+ + void mpmod(mpint *b, mpint *m, mpint *remainder) +
+ + void mpdiv(mpint *dividend, mpint *divisor,    mpint *quotient, mpint + *remainder) +
+ + mpint*      mpfactorial(ulong n) +
+ + int    mpcmp(mpint *b1, mpint *b2) +
+ + int    mpmagcmp(mpint *b1, mpint *b2) +
+ + void mpextendedgcd(mpint *a, mpint *b, mpint *d, mpint *x, mpint + *y) +
+ + void mpinvert(mpint *b, mpint *m, mpint *res) +
+ + int    mpsignif(mpint *b) +
+ + int    mplowbits0(mpint *b) +
+ + void mpdigdiv(mpdigit *dividend, mpdigit divisor, mpdigit *quotient) + +
+ + void mpvecadd(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *sum) +
+ + void mpvecsub(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *diff) +
+ + void mpvecdigmuladd(mpdigit *b, int n, mpdigit m, mpdigit *p) + +
+ + int    mpvecdigmulsub(mpdigit *b, int n, mpdigit m, mpdigit *p) +
+ + void mpvecmul(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *p) +
+ + int    mpveccmp(mpdigit *a, int alen, mpdigit *b, int blen) +
+ + CRTpre*     crtpre(int nfactors, mpint **factors) +
+ + CRTres*     crtin(CRTpre *crt, mpint *x) +
+ + void crtout(CRTpre *crt, CRTres *r, mpint *x) +
+ + void crtprefree(CRTpre *cre) +
+ + void crtresfree(CRTres *res) +
+ + mpint       *mpzero, *mpone, *mptwo
+ +
+

DESCRIPTION
+ +
+ + +
+ + These routines perform extended precision integer arithmetic. + The basic type is mpint, which points to an array of mpdigits, + stored in little-endian order:
+ typedef struct mpint mpint;
+ struct mpint
+ {
+ +
+ + int    sign;     /* +1 or −1 */
+ int    size;     /* allocated digits */
+ int    top;      /* significant digits */
+ mpdigit     *p;
+ char flags;
+ +
+ };
+ +
+ + The sign of 0 is +1. +
+ + The size of mpdigit is architecture-dependent and defined in /$cputype/include/u.h. + Mpints are dynamically allocated and must be explicitly freed. + Operations grow the array of digits as needed. +
+ + In general, the result parameters are last in the argument list. + +
+ + Routines that return an mpint will allocate the mpint if the result + parameter is nil. This includes strtomp, itomp, uitomp, and btomp. + These functions, in addition to mpnew and mpcopy, will return + nil if the allocation fails. +
+ + Input and result parameters may point to the same mpint. The routines + check and copy where necessary. +
+ + Mpnew creates an mpint with an initial allocation of n bits. If + n is zero, the allocation will be whatever was specified in the + last call to mpsetminbits or to the initial value, 1056. Mpfree + frees an mpint. Mpbits grows the allocation of b to fit at least + n bits. If b−>top doesn’t cover n bits it increases it to do so. + Unless + you are writing new basic operations, you can restrict yourself + to mpnew(0) and mpfree(b). +
+ + Mpnorm normalizes the representation by trimming any high order + zero digits. All routines except mpbits return normalized results. + +
+ + Mpcopy creates a new mpint with the same value as b while mpassign + sets the value of new to be that of old. +
+ + Mprand creates an n bit random number using the generator gen. + Gen takes a pointer to a string of uchar’s and the number to fill + in. +
+ + Strtomp and mptoa convert between ASCII and mpint representations + using the base indicated. Only the bases 10, 16, 32, and 64 are + supported. Anything else defaults to 16. Strtomp skips any leading + spaces or tabs. Strtomp’s scan stops when encountering a digit + not valid in the base. If rptr is not zero, *rptr is + set to point to the character immediately after the string converted. + If the parse pterminates before any digits are found, strtomp + return nil. Mptoa returns a pointer to the filled buffer. If the + parameter buf is nil, the buffer is allocated. Mpfmt can be used + with fmtinstall(3) and print(3) to print hexadecimal + representations of mpints. +
+ + Mptobe and mptole convert an mpint to a byte array. The former + creates a big endian representation, the latter a little endian + one. If the destination buf is not nil, it specifies the buffer + of length blen for the result. If the representation is less than + blen bytes, the rest of the buffer is zero filled. If buf is nil, + then a + buffer is allocated and a pointer to it is deposited in the location + pointed to by bufp. Sign is ignored in these conversions, i.e., + the byte array version is always positive. +
+ + Betomp, and letomp convert from a big or little endian byte array + at buf of length blen to an mpint. If b is not nil, it refers + to a preallocated mpint for the result. If b is nil, a new integer + is allocated and returned as the result. +
+ + The integer conversions are:
+ mptoui    mpint->unsigned int
+ uitomp    unsigned int->mpint
+ mptoi     mpint->int
+ itomp     int->mpint
+ mptouv    mpint->unsigned vlong
+ uvtomp    unsigned vlong->mpint
+ mptov     mpint->vlong
+ vtomp     vlong->mpint +
+ + When converting to the base integer types, if the integer is too + large, the largest integer of the appropriate sign and size is + returned. +
+ + The mathematical functions are:
+ mpadd      sum = b1 + b2.
+ mpmagadd   sum = abs(b1) + abs(b2).
+ mpsub      diff = b1 − b2.
+ mpmagsub    diff = abs(b1) − abs(b2).
+ mpleft      res = b<<shift.
+ mpright     res = b>>shift.
+ mpmul      prod = b1*b2.
+ mpexp      if m is nil, res = b**e. Otherwise, res = b**e mod m.
+ mpmod      remainder = b % m.
+ mpdiv      quotient = dividend/divisor. remainder = dividend % divisor.
+ mpfactorial   returns factorial of n.
+ mpcmp      returns -1, 0, or +1 as b1 is less than, equal to, or greater + than b2.
+ mpmagcmp   the same as mpcmp but ignores the sign and just compares + magnitudes. +
+ + Mpextendedgcd computes the greatest common denominator, d, of + a and b. It also computes x and y such that a*x + b*y = d. Both + a and b are required to be positive. If called with negative arguments, + it will return a gcd of 0. +
+ + Mpinverse computes the multiplicative inverse of b mod m. +
+ + Mpsignif returns the bit offset of the left most 1 bit in b. Mplowbits0 + returns the bit offset of the right most 1 bit. For example, for + 0x14, mpsignif would return 4 and mplowbits0 would return 2. +
+ + The remaining routines all work on arrays of mpdigit rather than + mpint’s. They are the basis of all the other routines. They are + separated out to allow them to be rewritten in assembler for each + architecture. There is also a portable C version for each one.
+ mpdigdiv          quotient = dividend[0:1] / divisor.
+ mpvecadd          sum[0:alen] = a[0:alen−1] + b[0:blen−1]. We assume alen + >= blen and that sum has room for alen+1 digits.
+ mpvecsub          diff[0:alen−1] = a[0:alen−1] − b[0:blen−1]. We assume + that alen >= blen and that diff has room for alen digits.
+ mpvecdigmuladd     p[0:n] += m * b[0:n−1]. This multiplies a an array + of digits times a scalar and adds it to another array. We assume + p has room for n+1 digits.
+ mpvecdigmulsub     p[0:n] −= m * b[0:n−1]. This multiplies a an array + of digits times a scalar and subtracts it fromo another array. + We assume p has room for n+1 digits. It returns +1 is the result + is positive and -1 if negative.
+ mpvecmul         p[0:alen*blen] = a[0:alen−1] * b[0:blen−1]. We assume + that p has room for alen*blen+1 digits.
+ mpveccmp         This returns -1, 0, or +1 as a - b is negative, 0, or + positive. +
+ + mptwo, mpone and mpzero are the constants 2, 1 and 0. These cannot + be freed.
+

Chinese remainder theorem
+ +
+ + When computing in a non-prime modulus, n, it is possible to perform + the computations on the residues modulo the prime factors of n + instead. Since these numbers are smaller, multiplication and exponentiation + can be much faster. +
+ + Crtin computes the residues of x and returns them in a newly allocated + structure:
+ +
+ + typedef struct CRTres      CRTres;
+ {
+ +
+ + int    n;     // number of residues
+ mpint       *r[n];      // residues
+ +
+ };
+ +
+ + +
+ Crtout takes a residue representation of a number and converts + it back into the number. It also frees the residue structure. + +
+ + Crepre saves a copy of the factors and precomputes the constants + necessary for converting the residue form back into a number modulo + the product of the factors. It returns a newly allocated structure + containing values. +
+ + Crtprefree and crtresfree free CRTpre and CRTres structures respectively.
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libmp
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/muldiv.html b/man/man3/muldiv.html new file mode 100644 index 00000000..486020ca --- /dev/null +++ b/man/man3/muldiv.html @@ -0,0 +1,61 @@ + +muldiv(3) - Plan 9 from User Space + + + + +
+
+
MULDIV(3)MULDIV(3) +
+
+

NAME
+ +
+ + muldiv, umuldiv – high-precision multiplication and division
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long    muldiv(long a, long b, long c) +
+ + ulong umuldiv(ulong a, ulong b, ulong c)
+ +
+

DESCRIPTION
+ +
+ + Muldiv returns a*b/c, using a vlong to hold the intermediate result. + Umuldiv is the equivalent for unsigned integers. They can be used + to scale integer values without worry about overflowing the intermediate + result. +
+ + On some architectures, these routines can generate a trap if the + final result does not fit in a long or ulong; on others they will + silently truncate.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mux.html b/man/man3/mux.html new file mode 100644 index 00000000..e3e7e4c8 --- /dev/null +++ b/man/man3/mux.html @@ -0,0 +1,169 @@ + +mux(3) - Plan 9 from User Space + + + + +
+
+
MUX(3)MUX(3) +
+
+

NAME
+ +
+ + Mux, muxinit, muxrpc, muxthreads – protocol multiplexor
+ +
+

SYNOPSIS
+ +
+ + #include <mux.h> +
+ + struct Mux
+ {
+ +
+ + uint mintag;
+ uint maxtag;
+ int (*settag)(Mux *mux, void *msg, uint tag);
+ int (*gettag)(Mux *mux, void *msg);
+ int (*send)(Mux *mux, void *msg);
+ void *(*recv)(Mux *mux);
+ void *aux;
+ ... /* private fields follow */
+ +
+ };
+ +
+ + void    muxinit(Mux *mux);
+ +
+ + void* muxrpc(Mux *mux, void *request);
+ +
+ + void    muxprocs(Mux *mux);
+ +
+

DESCRIPTION
+ +
+ + Libmux is a generic protocol multiplexor. A client program initializes + a Mux structure with information about the protocol (mainly in + the form of helper functions) and can then use muxrpc to execute + individual RPCs without worrying about details of multiplexing + requests and demultiplexing responses. +
+ + Libmux assumes that the protocol messages contain a tag (or message + ID) field that exists for the sole purpose of demultiplexing messages. + Libmux chooses the tags and then calls a helper function to put + them in the outgoing messages. Libmux calls another helper function + to retrieve tags from incoming messages. + It also calls helper functions to send and receive packets. +
+ + A client should allocate a Mux structure and then call muxinit + to initialize the library’s private elements. The client must + initialize the following elements:
+ mintag, maxtag
+ +
+ + The range of valid tags; maxtag is the maximum valid tag plus + one, so that maxtag–mintag is equal to the number of valid tags. + If libmux runs out of tags (all tags are being used for RPCs currently + in progress), a new call to muxrpc will block until an executing + call finishes.
+ +
+ settag, gettag
+ +
+ + Set or get the tag value in a message.
+ +
+ send, recv
+ +
+ + Send or receive protocol messages on the connection. Recv should + block until a message is available and should return nil if the + connection is closed. Libmux will arrange that only one call to + recv is active at a time.
+ +
+ aux   An auxiliary pointer for use by the client. Once a client has + initialized the Mux structure, it can call muxrpc to execute RPCs. + The request is the message passed to settag and send. The return + value is the response packet, as provided by recv, or nil if an + error occurred. Muxprocs allocates new procs (see + +
+ + thread(3)) in which to run send and recv. After a call to muxprocs, + muxrpc will run send and recv in these procs instead of in the + calling proc. This is useful if the implementation of either (particularly + recv) blocks an entire proc and there are other threads in the + calling proc that need to remain active. + +
+ +
+

EXAMPLE
+ +
+ + See /usr/local/plan9/src/lib9pclient/fs.c for an example of using + libmux with 9P (see intro(9p)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmux
+ +
+

SEE ALSO
+ +
+ + thread(3), intro(9p)
+ +
+

BUGS
+ +
+ + Libmux does not know how to free protocol messages, so message + arriving with unexpected or invalid tags are leaked. +
+ + Using mintag other than zero is not well tested and probably buggy.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/nan.html b/man/man3/nan.html new file mode 100644 index 00000000..e644116b --- /dev/null +++ b/man/man3/nan.html @@ -0,0 +1,79 @@ + +nan(3) - Plan 9 from User Space + + + + +
+
+
NAN(3)NAN(3) +
+
+

NAME
+ +
+ + NaN, Inf, isNaN, isInf – not-a-number and infinity functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + double NaN(void) +
+ + double Inf(int) +
+ + int      isNaN(double) +
+ + int      isInf(double, int)
+ +
+

DESCRIPTION
+ +
+ + The IEEE floating point standard defines values called ‘not-a-number’ + and positive and negative ‘infinity’. These values can be produced + by such things as overflow and division by zero. Also, the library + functions sometimes return them when the arguments are not in + the domain, or the result is out of range. +
+ + NaN returns a double that is not-a-number. IsNaN returns true + if its argument is not-a-number. +
+ + Inf(i) returns positive infinity if i is greater than or equal + to zero, else negative infinity. IsInf returns true if its first + argument is infinity with the same sign as the second argument.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/nan.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/needstack.html b/man/man3/needstack.html new file mode 100644 index 00000000..bba5fbe8 --- /dev/null +++ b/man/man3/needstack.html @@ -0,0 +1,98 @@ + +needstack(3) - Plan 9 from User Space + + + + +
+
+
NEEDSTACK(3)NEEDSTACK(3) +
+
+

NAME
+ +
+ + needstack – check for execution stack overflow
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int    needstack(int n)
+ +
+

DESCRIPTION
+ +
+ + Stack overflow in the thread library leads to bugs that are difficult + to diagnose. The Plan 9 libraries are careful about not allocating + large structures on the stack, so typically four or eight kilobytes + is plenty of stack for a thread. Other libraries are not always + as careful. Calling needstack indicates to the thread library + that an external routine is about to be called that will require + n bytes of stack space. If there is not enough space left on the + stack, the thread library prints an error and terminates the program. + The call needstack(0) can be used to check whether the stack is + currently overflowed. +
+ + Needstack is defined in libc.h so that library functions used + in threaded and non-threaded contexts can call it. The implementation + of needstack in lib9 is a no-op. +
+ + Needstack should be thought of as a comment checked at run time, + like assert(3).
+ +
+

EXAMPLE
+ +
+ + The X Window library implementation of XLookupString allocates + some very large buffers on the stack, so /usr/local/plan9/src/libdraw/x11−itrans.c + calls needstack(20*1024) before making calls to XLookupString. + If a thread (in this case, the keyboard-reading thread used inside + the draw(3) + library) does not allocate a large enough stack, the problem is + diagnosed immediately rather than left to corrupt memory.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/needstack.c
+ /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + thread(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/notify.html b/man/man3/notify.html new file mode 100644 index 00000000..9899e701 --- /dev/null +++ b/man/man3/notify.html @@ -0,0 +1,183 @@ + +notify(3) - Plan 9 from User Space + + + + +
+
+
NOTIFY(3)NOTIFY(3) +
+
+

NAME
+ +
+ + notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff + – handle asynchronous process notification
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int notify(void (*f)(void*, char*)) +
+ + int noted(int v) +
+ + int atnotify(int (*f)(void*, char*), int in) +
+ + int noteenable(char *msg)
+ int notedisable(char *msg) +
+ + int notifyon(char *msg)
+ int notifyoff(char *msg)
+ +
+

DESCRIPTION
+ +
+ + When a process raises an exceptional condition such as dividing + by zero or writing on a closed pipe, a note is posted to communicate + the exception. A note may also be posted by another process via + postnote(3). On Unix, notes are implemented as signals. +
+ + When a note is received, the action taken depends on the note. + See signal(7) for the full description of the defaults. +
+ + The default actions may be overridden. The notify function registers + a notification handler to be called within the process when a + note is received. The argument to notify replaces the previous + handler, if any. An argument of zero cancels a previous handler, + restoring the default action. A fork(2) system call leaves the + handler registered in both the parent and the child; exec(3) restores + the default behavior. Handlers may not perform floating point + operations. +
+ + After a note is posted, the handler is called with two arguments: + the first is unimplemented and should not be used (on Plan 9 it + is a Ureg structure giving the current values of registers); the + second is a pointer to the note itself, a null-terminated string. + +
+ + A notification handler must finish either by exiting the program + or by calling noted; if the handler returns the behavior is undefined + and probably erroneous. Until the program calls noted, any further + externally-generated notes (e.g., hangup or alarm) will be held + off, and any further notes generated by erroneous + behavior by the program (such as divide by zero) will kill the + program. The argument to noted defines the action to take: NDFLT + instructs the system to perform the default action as if the handler + had never been registered; NCONT instructs the system to resume + the process at the point it was notified. In neither case + does noted return to the handler. If the note interrupted an incomplete + system call, that call returns an error (with error string interrupted) + after the process resumes. A notification handler can also jump + out to an environment set up with setjmp using the notejmp function + (see setjmp(3)). +
+ + Unix provides a fixed set of notes (typically there are 32) called + signals. It also allows a process to block certain notes from + being delivered (see sigprocmask(2)) and to ignore certain notes + by setting the signal hander to the special value SIG_IGN (see + signal(2)). Noteenable and notedisable enable or disable receipt + of + a particular note by changing the current process’s blocked signal + mask. Receipt of a disabled note will be postponed until it is + reenabled. Notifyon and notifyoff enable or disable whether the + notification handler is called upon receipt of the note; if the + handler is not called, the note is discarded. +
+ + Regardless of the origin of the note or the presence of a handler, + if the process is being debugged (see ptrace(2)) the arrival of + a note puts the process in the Stopped state and awakens the debugger. + +
+ + Rather than using the system calls notify and noted, most programs + should use atnotify to register notification handlers. The parameter + in is non-zero to register the function f, and zero to cancel + registration. A handler must return a non-zero number if the note + was recognized (and resolved); otherwise it must return + zero. When the system posts a note to the process, each handler + registered with atnotify is called with arguments as described + above until one of the handlers returns non-zero. Then noted is + called with argument NCONT. If no registered function returns + non-zero, atnotify calls noted with argument NDFLT. +
+ + The set of notes a process may receive is system-dependent, but + there is a common set that includes: +
+ + +
+ + Note                          Meaning               Unix signal
+ interrupt                    user interrupt (DEL key)     SIGINTR
+ hangup                       I/O connection closed      SIGHUP
+ alarm                        alarm expired           SIGLARM
+ quit                         quit from keyboard        SIGQUIT
+ kill                         process requested to exit    SIGTERM
+ sys: kill                    process forced to exit      SIGKILL
+ sys: bus error                bus error              SIGBUS
+ sys: segmentation violation    segmentation violation      SIGSEGV
+ sys: write on closed pipe      write on closed pipe       SIGPIPE
+ sys: child                    child wait status change     SIGCHLD
+ +
+ + +
+ See /usr/local/plan9/src/lib9/await.c (sic) for the full list. + +
+ + The notes prefixed sys: are usually generated by the operating + system.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/notify.c
+ /usr/local/plan9/src/lib9/atnotify.c
+ +
+

SEE ALSO
+ +
+ + intro(3), notejmp in setjmp(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/open.html b/man/man3/open.html new file mode 100644 index 00000000..64f85c55 --- /dev/null +++ b/man/man3/open.html @@ -0,0 +1,130 @@ + +open(3) - Plan 9 from User Space + + + + +
+
+
OPEN(3)OPEN(3) +
+
+

NAME
+ +
+ + open, create, close – open a file for reading or writing, create + file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int open(char *file, int omode) +
+ + int create(char *file, int omode, ulong perm) +
+ + int close(int fd)
+ +
+

DESCRIPTION
+ +
+ + Open opens the file for I/O and returns an associated file descriptor. + Omode is one of OREAD, OWRITE, ORDWR, or OEXEC, asking for permission + to read, write, read and write, or execute, respectively. In addition, + there are three values that can be ORed with the omode: OTRUNC + says to truncate the file to zero length + before opening it; OCEXEC says to close the file when an exec(3) + or execl system call is made; and ORCLOSE says to remove the file + when it is closed (by everyone who has a copy of the file descriptor). + Open fails if the file does not exist or the user does not have + permission to open it for the requested purpose (see + stat(3) for a description of permissions). The user must have + write permission on the file if the OTRUNC bit is set. For the + open system call (unlike the implicit open in exec(3)), OEXEC + is actually identical to OREAD. +
+ + Create creates a new file or prepares to rewrite an existing file, + opens it according to omode (as described for open), and returns + an associated file descriptor. If the file is new, the owner is + set to the userid of the creating process group; the group to + that of the containing directory; the permissions to perm ANDed + with + the permissions of the containing directory. If the file already + exists, it is truncated to 0 length, and the permissions, owner, + and group remain unchanged. The created file is a directory if + the DMDIR bit is set in perm, an exclusive-use file if the DMEXCL + bit is set, and an append-only file if the DMAPPEND bit is set. + Exclusive-use files may be open for I/O by only one client at + a time, but the file descriptor may become invalid if no I/O is + done for an extended period; see open(9p). +
+ + Create fails if the path up to the last element of file cannot + be evaluated, if the user doesn’t have write permission in the + final directory, if the file already exists and does not permit + the access defined by omode, of if there there are no free file + descriptors. In the last case, the file may be created even when + an error is + returned. +
+ + Since create may succeed even if the file exists, a special mechanism + is necessary for those applications that require an atomic create + operation. If the OEXCL (0x1000) bit is set in the mode for a + create, the call succeeds only if the file does not already exist; + see open(9p) for details. +
+ + Close closes the file associated with a file descriptor. Provided + the file descriptor is a valid open descriptor, close is guaranteed + to close it; there will be no error. Files are closed automatically + upon termination of a process; close allows the file descriptor + to be reused.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + intro(3), stat(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/opentemp.html b/man/man3/opentemp.html new file mode 100644 index 00000000..9ec47571 --- /dev/null +++ b/man/man3/opentemp.html @@ -0,0 +1,78 @@ + +opentemp(3) - Plan 9 from User Space + + + + +
+
+
OPENTEMP(3)OPENTEMP(3) +
+
+

NAME
+ +
+ + opentemp – create a uniquely-named file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int opentemp(char *template)
+ +
+

DESCRIPTION
+ +
+ + Opentemp replaces template by a unique file name, and returns + the address of the template. The template should look like a file + name with eleven trailing Xs. The Xs are replaced by a letter + followed by the current process id. Letters from a to z are tried + until the name of a file that does not yet exist (see access(2)) + is + generated. Opentemp then creates the file for reading and writing + and returns the file descriptor. +
+ + If no such name can be generated, opentemp returns –1. +
+ + Opentemp avoids races. Two simultaneous calls to opentemp will + never return the same name.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/opentemp.c
+ +
+

SEE ALSO
+ +
+ + create in open(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/pipe.html b/man/man3/pipe.html new file mode 100644 index 00000000..b087ae8b --- /dev/null +++ b/man/man3/pipe.html @@ -0,0 +1,111 @@ + +pipe(3) - Plan 9 from User Space + + + + +
+
+
PIPE(3)PIPE(3) +
+
+

NAME
+ +
+ + pipe – create an interprocess channel
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int pipe(int fd[2])
+ +
+

DESCRIPTION
+ +
+ + Pipe creates a buffered channel for interprocess I/O communication. + Two file descriptors are returned in fd. Data written to fd[1] + is available for reading from fd[0] and data written to fd[0] + is available for reading from fd[1]. +
+ + After the pipe has been established, cooperating processes created + by subsequent fork(2) calls may pass data through the pipe with + read and write calls. +
+ + When all the data has been read from a pipe and the writer has + closed the pipe or exited, read(3) will return 0 bytes. Writes + to a pipe with no reader will generate a note sys: write on closed + pipe.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/pipe.c
+ +
+

SEE ALSO
+ +
+ + intro(3), read(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + If a read or a write of a pipe is interrupted, some unknown number + of bytes may have been transferred. +
+ + Pipe is a macro defined as p9pipe to avoid name conflicts with + Unix’s pipe system call. +
+ + Unix pipes are not guaranteed to be bidirectional. In order to + ensure a bidirectional channel, p9pipe creates Unix domain sockets + via the socketpair(2) instead of Unix pipes. +
+ + The implementation of pipes as Unix domain sockets causes problems + with some Unix implementations of /dev/fd, Unix’s dup device. + If a Unix domain socket is open as file descriptor 0, some implementations + disallow the opening of /dev/fd/0; instead one must connect(2) + to it. If this functionality is important + (as it is for rc(1)), one must #undef pipe and fall back on the + (possibly unidirectional) Unix pipes.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/plumb.html b/man/man3/plumb.html new file mode 100644 index 00000000..d7649698 --- /dev/null +++ b/man/man3/plumb.html @@ -0,0 +1,257 @@ + +plumb(3) - Plan 9 from User Space + + + + +
+
+
PLUMB(3)PLUMB(3) +
+
+

NAME
+ +
+ + eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, + plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, + plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, + plumbunpackattr, Plumbmsg – plumb messages
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <plumb.h> +
+ + +
+ + int          plumbopen(char *port, int omode) +
+ + int          plumbsend(int fd, Plumbmsg *m) +
+ + int          plumbsendtext(int fd, char *src, char *dst, char *wdir, char + *data) +
+ + void         plumbfree(Plumbmsg *m) +
+ + Plumbmsg*    plumbrecv(int fd) +
+ + char*        plumbpack(Plumbmsg *m, int *np) +
+ + Plumbmsg*    plumbunpack(char *buf, int n) +
+ + Plumbmsg*    plumbunpackpartial(char *buf, int n, int *morep) +
+ + char*        plumbpackattr(Plumbattr *a) +
+ + Plumbattr* plumbunpackattr(char *a) +
+ + char*        plumblookup(Plumbattr *a, char *name) +
+ + Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) +
+ + Plumbattr* plumbdelattr(Plumbattra *a, char *name) +
+ + int          eplumb(int key, char *port) +
+ + #include <9pclient.h> +
+ + CFid         *plumbopenfid(char *port, int omode) +
+ + Plumbmsg*    plumbrecvfid(CFid *fid) +
+ + int          plumbsendtofid(CFid *fid, Plumbmsg *m)
+ +
+

DESCRIPTION
+ +
+ + These routines manipulate plumb(7) messages, transmitting them, + receiving them, and converting them between text and these data + structures:
+ +
+ + typedef
+ struct Plumbmsg
+ {
+ +
+ + char        *src;
+ char        *dst;
+ char        *wdir;
+ char        *type;
+ Plumbattr *attr;
+ int         ndata;
+ char        *data;
+ +
+ } Plumbmsg;
+ typedef
+ struct Plumbattr
+ {
+ +
+ + char        *name;
+ char        *value;
+ Plumbattr *next;
+ +
+ } Plumbattr;
+ +
+ + +
+ Plumbopen opens the named plumb port, using open(3) mode omode. + If port begins with a slash, it is taken as a literal file name; + otherwise plumbopen searches for the location of the plumber(4) + service and opens the port there. +
+ + For programs using the event(3) interface, eplumb registers, using + the given key, receipt of messages from the named port. +
+ + Plumbsend formats and writes message m to the file descriptor + fd, which will usually be the result of plumbopen("send", OWRITE). + Plumbsendtext is a simplified version for text-only messages; + it assumes type is text, sets attr to nil, and sets ndata to strlen(data). + +
+ + Plumbfree frees all the data associated with the message m, all + the components of which must therefore have been allocated with + malloc(3). +
+ + Plumbrecv returns the next message available on the file descriptor + fd, or nil for error. +
+ + Plumbpack encodes message m as a character string in the format + of plumb(7), setting *np to the length in bytes of the string. + Plumbunpack does the inverse, translating the n bytes of buf into + a Plumbmsg. +
+ + Plumbunpackpartial enables unpacking of messages that arrive in + pieces. The first call to plumbunpackpartial for a given message + must be sufficient to unpack the header; subsequent calls permit + unpacking messages with long data sections. For each call, buf + points to the beginning of the complete message received + so far, and n reports the total number of bytes received for that + message. If the message is complete, the return value will be + as in plumbunpack. If not, and morep is not null, the return value + will be nil and *morep will be set to the number of bytes remaining + to be read for this message to be complete (recall that + the byte count is in the header). Those bytes should be read by + the caller, placed at location buf+n, and the message unpacked + again. If an error is encountered, the return value will be nil + and *morep will be zero. +
+ + Plumbpackattr converts the list a of Plumbattr structures into + a null-terminated string. If an attribute value contains white + space, quote characters, or equal signs, the value will be quoted + appropriately. A newline character will terminate processing. + Plumbunpackattr converts the null-terminated string a back into + a list of Plumbattr structures. +
+ + Plumblookup searches the Plumbattr list a for an attribute with + the given name and returns the associated value. The returned + string is the original value, not a copy. If the attribute has + no value, the returned value will be the empty string; if the + attribute does not occur in the list at all, the value will be + nil. +
+ + Plumbaddattr appends the new Plumbattr (which may be a list) to + the attribute list a and returns the new list. Plumbattr searches + the list a for the first attribute with name name and deletes + it from the list, returning the resulting list. Plumbdelattr is + a no-op if no such attribute exists. +
+ + The file descriptor returned by plumbopen is created with fsopenfd + (see 9pclient(3)), which masks information about read and write + errors. This is acceptable for use in plumbrecv but not for plumbsend, + which depends on seeing details of write errors. Plumbopenfid, + plumbrecvfid, and plumbsendtofid provide an + explicit interface to lib9pclient that preserves the exact error + details.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libplumb
+ +
+

SEE ALSO
+ +
+ + plumb(1), event(3), plumber(4), plumb(7)
+ +
+

DIAGNOSTICS
+ +
+ + When appropriate, including when a plumbsend fails, these routine + set errstr.
+ +
+

BUGS
+ +
+ + To avoid rewriting clients that use plumbsend, the call plumbopen("send", + OWRITE) returns a useless file descriptor (it is opened to /dev/null). + Plumbsend looks for this particular file descriptor and uses a + static copy of the CFid instead.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/post9pservice.html b/man/man3/post9pservice.html new file mode 100644 index 00000000..62238d0d --- /dev/null +++ b/man/man3/post9pservice.html @@ -0,0 +1,67 @@ + +post9pservice(3) - Plan 9 from User Space + + + + +
+
+
POST9PSERVICE(3)POST9PSERVICE(3) +
+
+

NAME
+ +
+ + post9pservice – post 9P service for use by clients
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int post9pservice(int fd, char *name)
+ +
+

DESCRIPTION
+ +
+ + Post9pservice invokes 9pserve(4) to post a new 9P service in the + current “name space” (see intro(4)) named name. Clients connecting + to the posted service are multiplexed onto a single 9P conversation + with the server on file descriptor fd.
+ +
+

SEE ALSO
+ +
+ + intro(4), 9pserve(4)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/post9p.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/postnote.html b/man/man3/postnote.html new file mode 100644 index 00000000..b08507e5 --- /dev/null +++ b/man/man3/postnote.html @@ -0,0 +1,80 @@ + +postnote(3) - Plan 9 from User Space + + + + +
+
+
POSTNOTE(3)POSTNOTE(3) +
+
+

NAME
+ +
+ + postnote – send a note to a process or process group
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    postnote(int who, int pid, char *note)
+ +
+

DESCRIPTION
+ +
+ + Postnote sends a note to a process or process group. If who is + PNPROC, then note is sent to the process with id pid. If who is + PNGROUP, the note is delivered to the process group which has + the process with id pid as a member. For PNGROUP only, if the + calling process is in the target group, the note is not delivered + to + that process. +
+ + If the write is successful, zero is returned. Otherwise –1 is returned.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/postnote.c
+ +
+

SEE ALSO
+ +
+ + notify(3), intro(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/prime.html b/man/man3/prime.html new file mode 100644 index 00000000..abaffda0 --- /dev/null +++ b/man/man3/prime.html @@ -0,0 +1,114 @@ + +prime(3) - Plan 9 from User Space + + + + +
+
+
PRIME(3)PRIME(3) +
+
+

NAME
+ +
+ + genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, + smallprimetest – prime number generation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + int    smallprimetest(mpint *p) +
+ + int    probably_prime(mpint *p, int nrep) +
+ + void genprime(mpint *p, int n, int nrep) +
+ + void gensafeprime(mpint *p, mpint *alpha, int n, int accuracy) + +
+ + void genstrongprime(mpint *p, int n, int nrep) +
+ + void DSAprimes(mpint *q, mpint *p, uchar seed[SHA1dlen])
+ +
+

DESCRIPTION
+ +
+ + +
+ + Public key algorithms abound in prime numbers. The following routines + generate primes or test numbers for primality. +
+ + Smallprimetest checks for divisibility by the first 10000 primes. + It returns 0 if p is not divisible by the primes and –1 if it is. + +
+ + Probably_prime uses the Miller-Rabin test to test p. It returns + non-zero if P is probably prime. The probability of it not being + prime is 1/4**nrep. +
+ + Genprime generates a random n bit prime. Since it uses the Miller-Rabin + test, nrep is the repetition count passed to probably_prime. Gensafegprime + generates an n-bit prime p and a generator alpha of the multiplicative + group of integers mod p; there is a prime q such that p-1=2*q. + Genstrongprime generates a + prime, p, with the following properties:
+ –     (p-1)/2 is prime. Therefore p-1 has a large prime factor, p’.
+ –p’-1 has a large prime factor
+ –p+1 has a large prime factor +
+ + DSAprimes generates two primes, q and p, using the NIST recommended + algorithm for DSA primes. q divides p-1. The random seed used + is also returned, so that skeptics can later confirm the computation. + Be patient; this is a slow algorithm.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + aes(3) blowfish(3), des(3), elgamal(3), rsa(3),
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/print.html b/man/man3/print.html new file mode 100644 index 00000000..8640efc7 --- /dev/null +++ b/man/man3/print.html @@ -0,0 +1,309 @@ + +print(3) - Plan 9 from User Space + + + + +
+
+
PRINT(3)PRINT(3) +
+
+

NAME
+ +
+ + print, fprint, sprint, snprint, seprint, smprint, runesprint, + runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, + vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted + output
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int     print(char *format, ...) +
+ + int     fprint(int fd, char *format, ...) +
+ + int     sprint(char *s, char *format, ...) +
+ + int     snprint(char *s, int len, char *format, ...) +
+ + char* seprint(char *s, char *e, char *format, ...) +
+ + char* smprint(char *format, ...) +
+ + int     runesprint(Rune *s, char *format, ...) +
+ + int     runesnprint(Rune *s, int len, char *format, ...) +
+ + Rune* runeseprint(Rune *s, Rune *e, char *format, ...) +
+ + Rune* runesmprint(char *format, ...) +
+ + int     vfprint(int fd, char *format, va_list v) +
+ + int     vsnprint(char *s, int len, char *format, va_list v) +
+ + char* vseprint(char *s, char *e, char *format, va_list v) +
+ + char* vsmprint(char *format, va_list v) +
+ + int     runevsnprint(Rune *s, int len, char *format, va_list v) +
+ + Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) + +
+ + Rune* runevsmprint(Rune *format, va_list v) +
+ + +
+

DESCRIPTION
+ +
+ + Print writes text to the standard output. Fprint writes to the + named output file descriptor: a buffered form is described in + bio(3). Sprint places text followed by the NUL character (\0) + in consecutive bytes starting at s; it is the user’s responsibility + to ensure that enough storage is available. Each function returns + the + number of bytes transmitted (not including the NUL in the case + of sprint), or a negative value if an output error was encountered. + +
+ + Snprint is like sprint, but will not place more than len bytes + in s. Its result is always NUL-terminated and holds the maximal + number of complete UTF-8 characters that can fit. Seprint is like + snprint, except that the end is indicated by a pointer e rather + than a count and the return value points to the terminating NUL + of + the resulting string. Smprint is like sprint, except that it prints + into and returns a string of the required length, which is allocated + by malloc(3). +
+ + The routines runesprint, runesnprint, runeseprint, and runesmprint + are the same as sprint, snprint, seprint and smprint except that + their output is rune strings instead of byte strings. +
+ + Finally, the routines vfprint, vsnprint, vseprint, vsmprint, runevsnprint, + runevseprint, and runevsmprint are like their v−less relatives + except they take as arguments a va_list parameter, so they can + be called within a variadic function. The Example section shows + a representative usage. +
+ + Each of these functions converts, formats, and prints its trailing + arguments under control of a format string. The format contains + two types of objects: plain characters, which are simply copied + to the output stream, and conversion specifications, each of which + results in fetching of zero or more arguments. The results + are undefined if there are arguments of the wrong type or too + few arguments for the format. If the format is exhausted while + arguments remain, the excess is ignored. +
+ + Each conversion specification has the following format:
+ +
+ + % [flags] verb +
+ + +
+ The verb is a single character and each flag is a single character + or a (decimal) numeric string. Up to two numeric strings may be + used; the first is called width, the second precision. A period + can be used to separate them, and if the period is present then + width and precision are taken to be zero if missing, otherwise + they are ‘omitted’. Either or both of the numbers may be replaced + with the character *, meaning that the actual number will be obtained + from the argument list as an integer. The flags and numbers are + arguments to the verb described below. +
+ + The numeric verbs d, o, b, x, and X format their arguments in + decimal, octal, binary, hexadecimal, and upper case hexadecimal. + Each interprets the flags 0, h, hh, l, u, +, −, ,, and # to mean + pad with zeros, short, byte, long, unsigned, always print a sign, + left justified, commas every three digits, and alternate format. + Also, a space character in the flag position is like +, but prints + a space instead of a plus sign for non-negative values. If neither + short nor long is specified, then the argument is an int. If unsigned + is specified, then the argument is interpreted as a positive number + and no sign is output. If two l flags are given, then + the argument is interpreted as a vlong (usually an 8-byte, sometimes + a 4-byte integer). If precision is not omitted, the number is + padded on the left with zeros until at least precision digits + appear. If precision is explicitly 0, and the number is 0, no + digits are generated, and alternate formatting does not apply. + Then, + if alternate format is specified, for o conversion, the number + is preceded by a 0 if it doesn’t already begin with one; for x + conversion, the number is preceded by 0x; for X conversion, the + number is preceded by 0X. Finally, if width is not omitted, the + number is padded on the left (or right, if left justification + is specified) + with enough blanks to make the field at least width characters + long. +
+ + The floating point verbs f, e, E, g, and G take a double argument. + Each interprets the flags 0, L +, −, and # to mean pad with zeros, + long double argument, always print a sign, left justified, and + alternate format. Width is the minimum field width and, if the + converted value takes up less than width characters, it is + padded on the left (or right, if ‘left justified’) with spaces. + Precision is the number of digits that are converted after the + decimal place for e, E, and f conversions, and precision is the + maximum number of significant digits for g and G conversions. + The f verb produces output of the form [−]digits[.digits]. E + conversion appends an exponent E[−]digits, and e conversion appends + an exponent e[−]digits. The g verb will output the argument in + either e or f with the goal of producing the smallest output. + Also, trailing zeros are omitted from the fraction part of the + output, and a trailing decimal point appears only if it is + followed by a digit. The G verb is similar, but uses E format + instead of e. When alternate format is specified, the result will + always contain a decimal point, and for g and G conversions, trailing + zeros are not removed. +
+ + The s verb copies a NUL-terminated string (pointer to char) to + the output. The number of characters copied (n) is the minimum + of the size of the string and precision. These n characters are + justified within a field of width characters as described above. + If a precision is given, it is safe for the string not to be nul- + terminated as long as it is at least precision characters (not + bytes!) long. The S verb is similar, but it interprets its pointer + as an array of runes (see utf(7)); the runes are converted to + UTF before output. +
+ + The c verb copies a single char (promoted to int) justified within + a field of width characters as described above. The C verb is + similar, but works on runes. +
+ + The p verb formats a pointer value. At the moment, it is a synonym + for x, but that will change if pointers and integers are different + sizes. +
+ + The r verb takes no arguments; it copies the error string returned + by a call to errstr(3). +
+ + Custom verbs may be installed using fmtinstall(3).
+ +
+

EXAMPLE
+ +
+ + This function prints an error message with a variable number of + arguments and then quits.
+ +
+ + void fatal(char *msg, ...)
+ {
+ +
+ + char buf[1024], *out;
+ va_list arg;
+ out = seprint(buf, buf+sizeof buf, "Fatal error: ");
+ va_start(arg, msg);
+ out = vseprint(out, buf+sizeof buf, msg, arg);
+ va_end(arg);
+ write(2, buf, out−buf);
+ exits("fatal error");
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/libfmt
+ +
+

SEE ALSO
+ +
+ + fmtinstall(3), fprintf(3), utf(7)
+ +
+

DIAGNOSTICS
+ +
+ + Routines that write to a file descriptor or call malloc set errstr.
+ +
+

BUGS
+ +
+ + The formatting is close to that specified for ANSI fprintf(3); + the main difference is that b and r are not in ANSI and u is a + flag here instead of a verb. Also, and distinctly not a bug, print + and friends generate UTF rather than ASCII. +
+ + There is no runeprint, runefprint, etc. because runes are byte-order + dependent and should not be written directly to a file; use the + UTF output of print or fprint instead. Also, sprint is deprecated + for safety reasons; use snprint, seprint, or smprint instead. + Safety also precludes the existence of runesprint. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/proto.html b/man/man3/proto.html new file mode 100644 index 00000000..59e4fccd --- /dev/null +++ b/man/man3/proto.html @@ -0,0 +1,140 @@ + +proto(3) - Plan 9 from User Space + + + + +
+
+
PROTO(3)PROTO(3) +
+
+

NAME
+ +
+ + rdproto – parse and process a proto file listing
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <disk.h>
+ +
+ + typedef void Protoenum(char *new, char *old, Dir *d, void *a)
+ +
+ + typedef void Protowarn(char *msg, void *a)
+ +
+ + int rdproto(char *proto, char *root, Protoenum *enm,
+ +
+ + +
+ + Protowarn *warn, void *a)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + Rdproto reads and interprets the named proto file relative to + the root directory root. +
+ + Each line of the proto file specifies a file to copy. Blank lines + and lines beginning with # are ignored. Indentation (usually tabs) + is significant, with each level of indentation corresponding to + a level in the file tree. Fields within a line are separated by + white space. The first field is the last path element in the destination + file tree. The second field specifies the permissions. The third + field is the owner of the file, and the fourth is the group owning + the file. The fifth field is the name of the file from which to + copy; this file is read from the current name space, not the source + file tree. All fields except the first are optional. Specifying + − for + permissions, owner, or group causes rdproto to fetch the corresponding + information from the file rather than override it. (This is the + default behavior when the fields are not present; explicitly specifying + − is useful when one wishes to set, say, the file owner without + setting the permissions.) +
+ + Names beginning with a $ are expanded as environment variables. + If the first file specified in a directory is *, all of the files + in that directory are considered listed. If the first file is + +, all of the files are copied, and all subdirectories are recursively + considered listed. All files are considered relative to root. + +
+ + For each file named by the proto, enm is called with new pointing + at the name of the file (without the root prefix), old pointing + at the name of the source file (with the root prefix, when applicable), + and Dir at the desired directory information for the new file. + Only the name, uid, gid, mode, mtime, and length fields + are guaranteed to be valid. The argument a is the same argument + passed to rdproto; typically it points at some extra state used + by the enumeration function. +
+ + When files or directories do not exist or cannot be read by rdproto, + it formats a warning message, calls warn, and continues processing; + if warn is nil, rdproto prints the warning message to standard + error. +
+ + Rdproto returns zero if proto was processed, –1 if it could not + be opened.
+ +
+

FILES
+ +
+ + /sys/lib/sysconfig/proto/           directory of prototype files.
+ /sys/lib/sysconfig/proto/portproto   generic prototype file.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdisk/proto.c
+ +
+

SEE ALSO
+ +
+ + mk9660(8), Plan 9’s mkfs(8)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/pushtls.html b/man/man3/pushtls.html new file mode 100644 index 00000000..ee806701 --- /dev/null +++ b/man/man3/pushtls.html @@ -0,0 +1,261 @@ + +pushtls(3) - Plan 9 from User Space + + + + +
+
+
PUSHTLS(3)PUSHTLS(3) +
+
+

NAME
+ +
+ + pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, + okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption + to a communication channel
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int             pushtls(int fd, char *hashalg, char *encalg,
+ +
+ + +
+ + int isclient, char *secret, char *dir) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ #include <mp.h>
+ #include <libsec.h> +
+ + int             tlsClient(int fd, TLSconn *conn) +
+ + int             tlsServer(int fd, TLSconn *conn) +
+ + uchar           *readcert(char *filename, int *pcertlen) +
+ + PEMchain         *readcertchain(char *filename) +
+ + Thumbprint*      initThumbprints(char *ok, char *crl) +
+ + void            freeThumbprints(Thumbprint *table) +
+ + int             okThumbprint(uchar *hash, Thumbprint *table)
+ +
+

DESCRIPTION
+ +
+ + Transport Layer Security (TLS) comprises a record layer protocol, + doing message digesting and encrypting in the kernel, and a handshake + protocol, doing initial authentication and secret creation at + user level and then starting a data channel in the record protocol. + TLS is nearly the same as SSL 3.0, and the software + should interoperate with implementations of either standard. +
+ + To use just the record layer, as described in Plan 9’s tls(3), + call pushtls to open the record layer device, connect to the communications + channel fd, and start up encryption and message authentication + as specified in hashalg, encalg, and secret. These parameters + must have been arranged at the two ends of the + conversation by other means. For example, hashalg could be sha1, + encalg could be rc4_128, and secret could be the base-64 encoding + of two (client-to-server and server-to-client) 20-byte digest + keys and two corresponding 16-byte encryption keys. Pushtls returns + a file descriptor for the TLS data channel. + Anything written to this descriptor will get encrypted and authenticated + and then written to the file descriptor, fd. If dir is non-zero, + the path name of the connection directory is copied into dir. + This path name is guaranteed to be less than 40 bytes long. +
+ + Alternatively, call tlsClient to speak the full handshake protocol, + negotiate the algorithms and secrets, and return a new data file + descriptor for the data channel. Conn points to a (caller-allocated) + struct
+ +
+ + typedef struct TLSconn{
+ +
+ + char dir[40];       // OUT      connection directory
+ uchar *cert;        // IN/OUT certificate
+ uchar *sessionID; // IN/OUT sessionID
+ int certlen, sessionIDlen;
+ void (*trace)(char*fmt, ...);
+ PEMChain *chain;
+ +
+ } TLSconn;
+ +
+ defined in tls.h. On input, the caller can provide options such + as cert, the local certificate, and sessionID, used by a client + to resume a previously negotiated security association. On output, + the connection directory is set, as with listen (see dial(3)). + The input cert is freed and a freshly allocated copy of the remote’s + certificate is returned in conn, to be checked by the caller according + to its needs. One mechanism is supplied by initThumbprints and + freeThumbprints which allocate and free, respectively, a table + of hashes from files of known trusted and revoked certificates. + okThumbprint confirms that a particular hash is in the + table, as computed by +
+ + +
+ + uchar hash[SHA1dlen];
+ conn = (TLSconn*)mallocz(sizeof *conn, 1);
+ fd = tlsClient(fd, conn);
+ sha1(conn−>cert, conn−>certlen, hash, nil);
+ if(!okThumbprint(hash,table))
+ +
+ + exits("suspect server");
+ +
+ ...application begins...
+ +
+ + +
+ Call tlsServer to perform the corresponding function on the server + side: +
+ + +
+ + fd = accept(lcfd, ldir);
+ conn = (TLSconn*)mallocz(sizeof *conn, 1);
+ conn−>cert = readcert("cert.pem", &conn−>certlen);
+ fd = tlsServer(fd, conn);
+ ...application begins...
+ +
+ The private key corresponding to cert.pem should have been previously + loaded into factotum. (See rsa(3) for more about key generation.) + By setting
+ +
+ + conn−>chain = readcertchain("intermediate−certs.pem");
+ +
+ the server can present extra certificate evidence to establish + the chain of trust to a root authority known to the client. +
+ + Conn is not required for the ongoing conversation and may be freed + by the application whenever convenient.
+ +
+

FILES
+ +
+ + /sys/lib/tls
+ +
+ + thumbprints of trusted services
+ +
+ /sys/lib/ssl
+ +
+ + PEM certificate files
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec/port
+ +
+

SEE ALSO
+ +
+ + dial(3), thumbprint(7); Plan 9’s factotum(4) and tls(3)
+ +
+

DIAGNOSTICS
+ +
+ + return –1 on failure.
+ +
+

BUGS
+ +
+ + Pushtls is not implemented. +
+ + Client certificates and client sessionIDs are not yet implemented. + +
+ + Note that in the TLS protocol sessionID itself is public; it is + used as a pointer to secrets stored in factotum.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/qball.html b/man/man3/qball.html new file mode 100644 index 00000000..b1403336 --- /dev/null +++ b/man/man3/qball.html @@ -0,0 +1,111 @@ + +qball(3) - Plan 9 from User Space + + + + +
+
+
QBALL(3)QBALL(3) +
+
+

NAME
+ +
+ + qball – 3-d rotation controller
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + void qball(Rectangle r, Mouse *mousep,
+ +
+ + Quaternion *orientation,
+ void (*redraw)(void), Quaternion *ap)
+ +
+ +
+

DESCRIPTION
+ +
+ + Qball is an interactive controller that allows arbitrary 3-space + rotations to be specified with the mouse. Imagine a sphere with + its center at the midpoint of rectangle r, and diameter the smaller + of r’s dimensions. Dragging from one point on the sphere to another + specifies the endpoints of a great-circle arc. (Mouse + points outside the sphere are projected to the nearest point on + the sphere.) The axis of rotation is normal to the plane of the + arc, and the angle of rotation is twice the angle of the arc. + +
+ + Argument mousep is a pointer to the mouse event that triggered + the interaction. It should have some button set. Qball will read + more events into mousep, and return when no buttons are down. + +
+ + While qball is reading mouse events, it calls out to the caller-supplied + routine redraw, which is expected to update the screen to reflect + the changing orientation. Argument orientation is the orientation + that redraw should examine, represented as a unit Quaternion (see + quaternion(9.2)). The caller may set it to any + orientation. It will be updated before each call to redraw (and + on return) by multiplying by the rotation specified with the mouse. + +
+ + It is possible to restrict qball’s attention to rotations about + a particular axis. If ap is null, the rotation is unconstrained. + Otherwise, the rotation will be about the same axis as *ap. This + is accomplished by projecting points on the sphere to the nearest + point also on the plane through the sphere’s center and normal + to + the axis.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/qball.c
+ +
+

SEE ALSO
+ +
+ + quaternion(3)
+ Ken Shoemake, “Animating Rotation with Quaternion Curves”, SIGGRAPH + ’85 Conference Proceedings.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/quaternion.html b/man/man3/quaternion.html new file mode 100644 index 00000000..257ebe52 --- /dev/null +++ b/man/man3/quaternion.html @@ -0,0 +1,163 @@ + +quaternion(3) - Plan 9 from User Space + + + + +
+
+
QUATERNION(3)QUATERNION(3) +
+
+

NAME
+ +
+ + qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, + qmid, qsqrt – Quaternion arithmetic
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + Quaternion qadd(Quaternion q, Quaternion r) +
+ + Quaternion qsub(Quaternion q, Quaternion r) +
+ + Quaternion qneg(Quaternion q) +
+ + Quaternion qmul(Quaternion q, Quaternion r) +
+ + Quaternion qdiv(Quaternion q, Quaternion r) +
+ + Quaternion qinv(Quaternion q) +
+ + double qlen(Quaternion p) +
+ + Quaternion qunit(Quaternion q) +
+ + void qtom(Matrix m, Quaternion q) +
+ + Quaternion mtoq(Matrix mat) +
+ + Quaternion slerp(Quaternion q, Quaternion r, double a) +
+ + Quaternion qmid(Quaternion q, Quaternion r) +
+ + Quaternion qsqrt(Quaternion q)
+ +
+

DESCRIPTION
+ +
+ + The Quaternions are a non-commutative extension field of the Real + numbers, designed to do for rotations in 3-space what the complex + numbers do for rotations in 2-space. Quaternions have a real component + r and an imaginary vector component v=(i,j,k). Quaternions add + componentwise and multiply according to + the rule (r,v)(s,w)=(rs-v.w, rw+vs+vxw), where . and x are the ordinary + vector dot and cross products. The multiplicative inverse of a + non-zero quaternion (r,v) is (r,-v)/(r2-v.v). +
+ + The following routines do arithmetic on quaternions, represented + as
+ +
+ + typedef struct Quaternion Quaternion;
+ struct Quaternion{
+ +
+ + double r, i, j, k;
+ +
+ };
+ +
+ Name    Description
+ qadd    Add two quaternions.
+ qsub    Subtract two quaternions.
+ qneg    Negate a quaternion.
+ qmul    Multiply two quaternions.
+ qdiv    Divide two quaternions.
+ qinv    Return the multiplicative inverse of a quaternion.
+ qlen    Return sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k), the length of + a quaternion.
+ qunit   Return a unit quaternion (length=1) with components proportional + to q’s. +
+ + A rotation by angle θ about axis A (where A is a unit vector) + can be represented by the unit quaternion q=(cos θ/2, Asin θ/2). + The same rotation is represented by -q; a rotation by -θ about -A + is the same as a rotation by θ about A. The quaternion q transforms + points by (0,x’,y’,z’) = q-1(0,x,y,z)q. Quaternion + multiplication composes rotations. The orientation of an object + in 3-space can be represented by a quaternion giving its rotation + relative to some ‘standard’ orientation. +
+ + The following routines operate on rotations or orientations represented + as unit quaternions:
+ mtoq    Convert a rotation matrix (see matrix(3)) to a unit quaternion.
+ qtom    Convert a unit quaternion to a rotation matrix.
+ slerp   Spherical lerp. Interpolate between two orientations. The + rotation that carries q to r is q-1r, so slerp(q, r, t) is q(q-1r)t.
+ qmid    slerp(q, r, .5)
+ qsqrt   The square root of q. This is just a rotation about the same + axis by half the angle.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/quaternion.c
+ +
+

SEE ALSO
+ +
+ + matrix(3), qball(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/quote.html b/man/man3/quote.html new file mode 100644 index 00000000..433c5bfc --- /dev/null +++ b/man/man3/quote.html @@ -0,0 +1,164 @@ + +quote(3) - Plan 9 from User Space + + + + +
+
+
QUOTE(3)QUOTE(3) +
+
+

NAME
+ +
+ + quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, + quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote + – quoted character strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char *quotestrdup(char *s) +
+ + Rune *quoterunestrdup(Rune *s) +
+ + char *unquotestrdup(char *s) +
+ + Rune *unquoterunestrdup(Rune *s) +
+ + int quotestrfmt(Fmt*) +
+ + int quoterunestrfmt(Fmt*) +
+ + void quotefmtinstall(void) +
+ + int (*doquote)(int c) +
+ + int needsrcquote(int c) +
+ + +
+

DESCRIPTION
+ +
+ + These routines manipulate character strings, either adding or + removing quotes as necessary. In the quoted form, the strings + are in the style of rc(1), with single quotes surrounding the + string. Embedded single quotes are indicated by a doubled single + quote. For instance,
+ +
+ + Don't worry!
+ +
+ + +
+ when quoted becomes
+ +
+ + 'Don''t worry!'
+ +
+ + +
+ The empty string is represented by two quotes, ''. +
+ + The first four functions act as variants of strdup (see strcat(3)). + Each returns a freshly allocated copy of the string, created using + malloc(3). Quotestrdup returns a quoted copy of s, while unquotestrdup + returns a copy of s with the quotes evaluated. The rune versions + of these functions do the same for strings (see + runestrcat(3)). +
+ + The string returned by quotestrdup or quoterunestrdup has the + following properties:
+ 1.    If the original string s is empty, the returned string is ''.
+ 2.    If s contains no quotes, blanks, or control characters, the + returned string is identical to s.
+ 3.    If s needs quotes to be added, the first character of the returned + string will be a quote. For example, hello world becomes 'hello + world' not hello' 'world. +
+ + The function pointer doquote is nil by default. If it is non-nil, + characters are passed to that function to see if they should be + quoted. This mechanism allows programs to specify that characters + other than blanks, control characters, or quotes be quoted. Regardless + of the return value of *doquote, blanks, control + characters, and quotes are always quoted. Needsrcquote is provided + as a doquote function that flags any character special to rc(1). + +
+ + Quotestrfmt and quoterunestrfmt are print(3) formatting routines + that produce quoted strings as output. They may be installed by + hand, but quotefmtinstall installs them under the standard format + characters q and Q. (They are not installed automatically.) If + the format string includes the alternate format character #, + for example %#q, the printed string will always be quoted; otherwise + quotes will only be provided if necessary to avoid ambiguity. + In <libc.h> there are #pragma statements so the compiler can type-check + uses of %q and %Q in print(3) format strings.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/quote.c
+ /usr/local/plan9/src/lib9/fmt/fmtquote.c
+ +
+

SEE ALSO
+ +
+ + rc(1), malloc(3), print(3), strcat(3)
+ +
+

BUGS
+ +
+ + Because it is provided by the format library, doquote is a preprocessor + macro defined as fmtdoquote; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rand.html b/man/man3/rand.html new file mode 100644 index 00000000..0601c6bf --- /dev/null +++ b/man/man3/rand.html @@ -0,0 +1,190 @@ + +rand(3) - Plan 9 from User Space + + + + +
+
+
RAND(3)RAND(3) +
+
+

NAME
+ +
+ + rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, + fastrand, nfastrand – random number generator
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      rand(void) +
+ + long     lrand(void) +
+ + double frand(void) +
+ + int      nrand(int val) +
+ + long     lnrand(long val) +
+ + void     srand(long seed) +
+ + ulong    truerand(void) +
+ + ulong    ntruerand(ulong val)
+ #include <mp.h>
+ #include <libsec.h> +
+ + void     genrandom(uchar *buf, int nbytes) +
+ + void     prng(uchar *buf, int nbytes) +
+ + ulong    fastrand(void) +
+ + ulong    nfastrand(ulong val)
+ +
+

DESCRIPTION
+ +
+ + Rand returns a uniform pseudo-random number x, 0≤x<215. +
+ + Lrand returns a uniform long x, 0≤x<231. +
+ + Frand returns a uniform double x, 0.0≤x<1.0, This function calls + lrand twice to generate a number with as many as 62 significant + bits of mantissa. +
+ + Nrand returns a uniform integer x, 0≤x<val. Lnrand is the same, + but returns a long. +
+ + The algorithm is additive feedback with:
+ +
+ + x[n] = (x[n-273] + x[n-607]) mod 231 +
+ + +
+ giving a period of 230 × (2607 – 1). +
+ + The generators are initialized by calling srand with whatever + you like as argument. To get a different starting value each time,
+ +
+ + srand(time(0)) +
+ + +
+ will work as long as it is not called more often than once per + second. Calling
+ +
+ + srand(1) +
+ + +
+ will initialize the generators to their starting state. +
+ + Truerand returns a random unsigned long read from /dev/random. + Due to the nature of /dev/random, truerand can only return a few + hundred bits a second. +
+ + Ntruerand returns a uniform random integer x, 0≤x<val≤232-1. +
+ + Genrandom fills a buffer with bytes from the X9.17 pseudo-random + number generator. The X9.17 generator is seeded by 24 truly random + bytes read from /dev/random. +
+ + Prng uses the native rand(3) pseudo-random number generator to + fill the buffer. Used with srand, this function can produce a + reproducible stream of pseudo random numbers useful in testing. + +
+ + Both genrandom and prng may be passed to mprand (see mp(3)). +
+ + Fastrand uses genrandom to return a uniform unsigned long x, 0≤x<232-1. + +
+ + Nfastrand uses genrandom to return a uniform unsigned long x, + 0≤x<val≤232-1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ /usr/local/plan9/src/libsec/port
+ +
+

SEE ALSO
+ +
+ + mp(3)
+ +
+

BUGS
+ +
+ + Truerand and ntruerand maintain a static file descriptor. +
+ + To avoid name conflicts with the underlying system, rand, lrand, + frand, nrand, lnrand, and srand are preprocessor macros defined + as p9rand, p9lrand, and so on; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rc4.html b/man/man3/rc4.html new file mode 100644 index 00000000..8c0d374b --- /dev/null +++ b/man/man3/rc4.html @@ -0,0 +1,86 @@ + +rc4(3) - Plan 9 from User Space + + + + +
+
+
RC4(3)RC4(3) +
+
+

NAME
+ +
+ + setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupRC4state(RC4state *s, uchar *seed, int slen) +
+ + void rc4(RC4state *s, uchar *data, int dlen) +
+ + void rc4skip(RC4state *s, int nbytes) +
+ + void rc4back(RC4state *s, int nbytes)
+ +
+

DESCRIPTION
+ +
+ + +
+ + This is an algorithm alleged to be Rivest’s RC4 encryption function. + It is a pseudo-random number generator with a 256 byte state and + a long cycle. The input buffer is XOR’d with the output of the + generator both to encrypt and to decrypt. The seed, entered using + setupRC4state, can be any length. The generator can + be run forward using rc4, skip over bytes using rc4skip to account + lost transmissions, or run backwards using rc4back to cover retransmitted + data. The RC4state structure keeps track of the algorithm.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), elgamal(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/read.html b/man/man3/read.html new file mode 100644 index 00000000..515c3f77 --- /dev/null +++ b/man/man3/read.html @@ -0,0 +1,109 @@ + +read(3) - Plan 9 from User Space + + + + +
+
+
READ(3)READ(3) +
+
+

NAME
+ +
+ + read, readn, write, pread, pwrite – read or write file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long read(int fd, void *buf, long nbytes) +
+ + long readn(int fd, void *buf, long nbytes) +
+ + long write(int fd, void *buf, long nbytes) +
+ + long pread(int fd, void *buf, long nbytes, vlong offset) +
+ + long pwrite(int fd, void *buf, long nbytes, vlong offset)
+ +
+

DESCRIPTION
+ +
+ + Read reads nbytes bytes of data from the offset in the file associated + with fd into memory at buf. The offset is advanced by the number + of bytes read. It is not guaranteed that all nbytes bytes will + be read; for example if the file refers to the console, at most + one line will be returned. In any event the number of bytes + read is returned. A return value of 0 is conventionally interpreted + as end of file. +
+ + Readn is just like read, but does successive read calls until + nbytes have been read, or a read system call returns a non-positive + count. +
+ + Write writes nbytes bytes of data starting at buf to the file + associated with fd at the file offset. The offset is advanced + by the number of bytes written. The number of characters actually + written is returned. It should be regarded as an error if this + is not the same as requested. +
+ + Pread and Pwrite equivalent to a seek(3) to offset followed by + a read or write. By combining the operations in a single atomic + call, they more closely match the 9P protocol (see intro(9p)) + and, more important, permit multiprocess programs to execute multiple + concurrent read and write operations on the same file + descriptor without interference.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/readn.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3), dup(3), pipe(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/regexp.html b/man/man3/regexp.html new file mode 100644 index 00000000..21e1849b --- /dev/null +++ b/man/man3/regexp.html @@ -0,0 +1,178 @@ + +regexp(3) - Plan 9 from User Space + + + + +
+
+
REGEXP(3)REGEXP(3) +
+
+

NAME
+ +
+ + regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, + regerror – regular expression
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <regexp.h> +
+ + Reprog    *regcomp(char *exp) +
+ + Reprog    *regcomplit(char *exp) +
+ + Reprog    *regcompnl(char *exp) +
+ + int    regexec(Reprog *prog, char *string, Resub *match, int msize)
+ +
+ + void regsub(char *source, char *dest, int dlen, Resub *match, + int msize)
+ +
+ + int    rregexec(Reprog *prog, Rune *string, Resub *match, int msize)
+ +
+ + void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, + int msize)
+ +
+ + void regerror(char *msg)
+ +
+

DESCRIPTION
+ +
+ + Regcomp compiles a regular expression and returns a pointer to + the generated description. The space is allocated by malloc(3) + and may be released by free. Regular expressions are exactly as + in regexp(7). +
+ + Regcomplit is like regcomp except that all characters are treated + literally. Regcompnl is like regcomp except that the . metacharacter + matches all characters, including newlines. +
+ + Regexec matches a null-terminated string against the compiled + regular expression in prog. If it matches, regexec returns 1 and + fills in the array match with character pointers to the substrings + of string that correspond to the parenthesized subexpressions + of exp: match[i].sp points to the beginning and + match[i].ep points just beyond the end of the ith substring. (Subexpression + i begins at the ith left parenthesis, counting from 1.) Pointers + in match[0] pick out the substring that corresponds to the whole + regular expression. Unused elements of match are filled with zeros. + Matches involving *, +, and ? are + extended as far as possible. The number of array elements in match + is given by msize. The structure of elements of match is:
+ +
+ + typedef struct {
+ +
+ + union {
+ char *sp;
+ Rune *rsp;
+ } s;
+ union {
+ char *ep;
+ Rune *rep;
+ } e;
+ +
+ } Resub;
+ +
+ + +
+ If match[0].s.sp is nonzero on entry, regexec starts matching + at that point within string. If match[0].e.ep is nonzero on entry, + the last character matched is the one preceding that point. +
+ + Regsub places in dest a substitution instance of source in the + context of the last regexec performed using match. Each instance + of \n, where n is a digit, is replaced by the string delimited + by match[n].sp and match[n].ep. Each instance of & is replaced + by the string delimited by match[0].sp and + match[0].ep. The substitution will always be null terminated and + trimmed to fit into dlen bytes. +
+ + Regerror, called whenever an error is detected in regcomp, writes + the string msg on the standard error file and exits. Regerror + can be replaced to perform special error processing. If the user + supplied regerror returns rather than exits, regcomp will return + 0. +
+ + Rregexec and rregsub are variants of regexec and regsub that use + strings of Runes instead of strings of chars. With these routines, + the rsp and rep fields of the match array elements should be used.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libregexp
+ +
+

SEE ALSO
+ +
+ + grep(1)
+ +
+

DIAGNOSTICS
+ +
+ + Regcomp returns 0 for an illegal expression or other failure. + Regexec returns 0 if string is not matched.
+ +
+

BUGS
+ +
+ + There is no way to specify or match a NUL character; NULs terminate + patterns and strings.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rfork.html b/man/man3/rfork.html new file mode 100644 index 00000000..f76a61fd --- /dev/null +++ b/man/man3/rfork.html @@ -0,0 +1,118 @@ + +rfork(3) - Plan 9 from User Space + + + + +
+
+
RFORK(3)RFORK(3) +
+
+

NAME
+ +
+ + rfork – manipulate process state
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int rfork(int flags)
+ +
+

DESCRIPTION
+ +
+ + Rfork is a partial implementation of the Plan 9 system call. It + can be used to manipulate some process state and to create new + processes a la fork(2). It cannot be used to create shared-memory + processes (Plan 9’s RFMEM flag); for that functionality use proccreate + (see thread(3)). +
+ + The flags argument to rfork selects which resources of the invoking + process (parent) are shared by the new process (child) or initialized + to their default values. Flags is the logical OR of some subset + of
+ RFPROC     If set a new process is created; otherwise changes affect + the current process.
+ RFNOWAIT   If set, the child process will be dissociated from the + parent. Upon exit the child will leave no Waitmsg (see wait(3)) + for the parent to collect.
+ RFNOTEG    Each process is a member of a group of processes that all + receive notes when a note is sent to the group (see postnote(3) + and signal(2)). The group of a new process is by default the same + as its parent, but if RFNOTEG is set (regardless of RFPROC), the + process becomes the first in a new group, isolated + +
+ + +
+ + from previous processes. In Plan 9, a process can call rfork(RFNOTEG) + and then be sure that it will no longer receive console interrupts + or other notes. Unix job-control shells put each command in its + own process group and then relay notes to the current foreground + command, making the idiom + less useful.
+ +
+ +
+ RFFDG      If set, the invoker’s file descriptor table (see intro()) + is copied; otherwise the two processes share a single table. +
+ + File descriptors in a shared file descriptor table are kept open + until either they are explicitly closed or all processes sharing + the table exit. +
+ + If RFPROC is set, the value returned in the parent process is + the process id of the child process; the value returned in the + child is zero. Without RFPROC, the return value is zero. Process + ids range from 1 to the maximum integer (int) value. Rfork will + sleep, if necessary, until required process resources are available. + +
+ + Calling rfork(RFFDG|RFPROC) is equivalent to calling fork(2).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/rfork.c
+ +
+

DIAGNOSTICS
+ +
+ + Rfork sets errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rsa.html b/man/man3/rsa.html new file mode 100644 index 00000000..0cfd2949 --- /dev/null +++ b/man/man3/rsa.html @@ -0,0 +1,262 @@ + +rsa(3) - Plan 9 from User Space + + + + +
+
+
RSA(3)RSA(3) +
+
+

NAME
+ +
+ + asn1dump, asn1toRSApriv, decodepem, decodepemchain, rsadecrypt, + rsaencrypt, rsafill,, rsagen, rsaprivalloc, rsaprivfree, rsaprivtopub, + rsapuballoc, rsapubfree, X509toRSApub, X509dump, X509gen, X509req, + X509verify – RSA encryption algorithm
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + RSApriv*    rsagen(int nlen, int elen, int nrep) +
+ + RSApriv*    rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint + *q) +
+ + mpint*      rsaencrypt(RSApub *k, mpint *in, mpint *out) +
+ + mpint*      rsadecrypt(RSApriv *k, mpint *in, mpint *out) +
+ + RSApub*     rsapuballoc(void) +
+ + void        rsapubfree(RSApub*) +
+ + RSApriv*    rsaprivalloc(void) +
+ + void        rsaprivfree(RSApriv*) +
+ + RSApub*     rsaprivtopub(RSApriv*) +
+ + RSApub*     X509toRSApub(uchar *cert, int ncert, char *name, int nname) + +
+ + RSApriv*    asn1toRSApriv(uchar *priv, int npriv) +
+ + void        asn1dump(uchar *der, int len) +
+ + uchar*      decodepem(char *s, char *type, int *len) +
+ + PEMChain* decodepemchain(char *s, char *type) +
+ + void        X509dump(uchar *cert, int ncert) +
+ + uchar*      X509gen(RSApriv *priv, char *subj, ulong valid[2], int + *certlen); +
+ + uchar*      X509req(RSApriv *priv, char *subj, int *certlen); +
+ + char* X509verify(uchar *cert, int ncert, RSApub *pk)
+ +
+

DESCRIPTION
+ +
+ + +
+ + RSA is a public key encryption algorithm. The owner of a key publishes + the public part of the key:
+ +
+ + +
+ + struct RSApub
+ {
+ mpint*n;// modulus
+ mpint*ek;// exp (encryption key)
+ };
+ +
+ +
+ This part can be used for encrypting data (with rsaencrypt) to + be sent to the owner. The owner decrypts (with rsadecrypt) using + his private key:
+ +
+ + +
+ + struct RSApriv
+ {
+ RSApubpub;
+ mpint*dk;// exp (decryption key)
+
+ // precomputed crt values
+ mpint*p;
+ mpint*q;
+ mpint*kp;// k mod p−1
+ mpint*kq;// k mod q−1
+ mpint*c2;// for converting residues to number
+ };
+ +
+ + +
+ +
+ Keys are generated using rsagen. Rsagen takes both bit length + of the modulus, the bit length of the public key exponent, and + the number of repetitions of the Miller-Rabin primality test to + run. If the latter is 0, it does the default number of rounds. + Rsagen returns a newly allocated structure containing both public + and + private keys. Rsaprivtopub returns a newly allocated copy of the + public key corresponding to the private key. +
+ + Rsafill takes as input the bare minimum pieces of an RSA private + key and computes the rest (kp, kq, and c2). It returns a new private + key. All the mpints in the key, even the ones that correspond + directly to rsafill’s input parameters, are freshly allocated, + +
+ + The routines rsaalloc, rsafree, rsapuballoc, rsapubfree, rsaprivalloc, + and rsaprivfree are provided to aid in user provided key I/O. + +
+ + Given a binary X.509 cert, the routine X509toRSApub returns the + public key and, if name is not nil, the CN part of the Distinguished + Name of the certificate’s Subject. (This is conventionally a userid + or a host DNS name.) No verification is done of the certificate + signature; the caller should check the fingerprint, + sha1(cert), against a table or check the certificate by other + means. X.509 certificates are often stored in PEM format; use + dec64 to convert to binary before computing the fingerprint or + calling X509toRSApub. For the special case of certificates signed + by a known trusted key (in a single step, without certificate + chains) + X509verify checks the signature on cert. It returns nil if successful, + else an error string. +
+ + X509dump prints an X.509 certificate to standard ouptut. +
+ + X509gen creates a self-signed X.509 certificate, given an RSA + keypair priv, a issuer/subject string subj, and the starting and + ending validity dates, valid. Length of the allocated binary certificate + is stored in certlen. The subject line is conventionally of the + form
+ +
+ + "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric"
+ +
+ using the quoting conventions of tokenize (see getfields(3)). + +
+ + X509req creates an X.509 certification request. +
+ + Asn1toRSApriv converts an ASN1 formatted RSA private key into + the corresponding RSApriv structure. +
+ + Asn1dump prints an ASN1 object to standard output. +
+ + Decodepem takes a zero terminated string, s, and decodes the PEM + (privacy-enhanced mail) formatted section for type within it. + If successful, it returns the decoded section and sets *len to + its decoded length. If not, it returns nil, and *len is undefined. + +
+ + Decodepemchain is similar but expects a sequence of PEM-formatted + sections and returns a linked list of the decodings:
+ +
+ + typedef struct PEMChain PEMChain
+ struct PEMChain
+ {
+ +
+ + PEMChain *next;
+ uchar *pem;
+ int pemlen;
+ +
+ };
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), elgamal(3), rc4(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rune.html b/man/man3/rune.html new file mode 100644 index 00000000..2fed11f3 --- /dev/null +++ b/man/man3/rune.html @@ -0,0 +1,157 @@ + +rune(3) - Plan 9 from User Space + + + + +
+
+
RUNE(3)RUNE(3) +
+
+

NAME
+ +
+ + runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, + utflen, utfnlen, utfrune, utfrrune, utfutf – rune/UTF conversion
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      runetochar(char *s, Rune *r) +
+ + int      chartorune(Rune *r, char *s) +
+ + int      runelen(long r) +
+ + int      runenlen(Rune *r, int n) +
+ + int      fullrune(char *s, int n) +
+ + char*    utfecpy(char *s1, char *es1, char *s2) +
+ + int      utflen(char *s) +
+ + int      utfnlen(char *s, long n) +
+ + char*    utfrune(char *s, long c) +
+ + char*    utfrrune(char *s, long c) +
+ + char*    utfutf(char *s1, char *s2)
+ +
+

DESCRIPTION
+ +
+ + These routines convert to and from a UTF byte stream and runes. + +
+ + Runetochar copies one rune at r to at most UTFmax bytes starting + at s and returns the number of bytes copied. UTFmax, defined as + 3 in <libc.h>, is the maximum number of bytes required to represent + a rune. +
+ + Chartorune copies at most UTFmax bytes starting at s to one rune + at r and returns the number of bytes copied. If the input is not + exactly in UTF format, chartorune will convert to 0x80 and return + 1. +
+ + Runelen returns the number of bytes required to convert r into + UTF. +
+ + Runenlen returns the number of bytes required to convert the n + runes pointed to by r into UTF. +
+ + Fullrune returns 1 if the string s of length n is long enough + to be decoded by chartorune and 0 otherwise. This does not guarantee + that the string contains a legal UTF encoding. This routine is + used by programs that obtain input a byte at a time and need to + know when a full rune has arrived. +
+ + The following routines are analogous to the corresponding string + routines with utf substituted for str and rune substituted for + chr. +
+ + Utfecpy copies UTF sequences until a null sequence has been copied, + but writes no sequences beyond es1. If any sequences are copied, + s1 is terminated by a null sequence, and a pointer to that sequence + is returned. Otherwise, the original s1 is returned. +
+ + Utflen returns the number of runes that are represented by the + UTF string s. +
+ + Utfnlen returns the number of complete runes that are represented + by the first n bytes of UTF string s. If the last few bytes of + the string contain an incompletely coded rune, utfnlen will not + count them; in this way, it differs from utflen, which includes + every byte of the string. +
+ + Utfrune (utfrrune) returns a pointer to the first (last) occurrence + of rune c in the UTF string s, or 0 if c does not occur in the + string. The NUL byte terminating a string is considered to be + part of the string s. +
+ + Utfutf returns a pointer to the first occurrence of the UTF string + s2 as a UTF substring of s1, or 0 if there is none. If s2 is the + null string, utfutf returns s1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/utf/rune.c
+ /usr/local/plan9/src/lib9/utf/utfrune.c
+ +
+

SEE ALSO
+ +
+ + utf(7), tcs(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/runestrcat.html b/man/man3/runestrcat.html new file mode 100644 index 00000000..4774265c --- /dev/null +++ b/man/man3/runestrcat.html @@ -0,0 +1,107 @@ + +runestrcat(3) - Plan 9 from User Space + + + + +
+
+
RUNESTRCAT(3)RUNESTRCAT(3) +
+
+

NAME
+ +
+ + runestrcat, runestrncat, runestrcmp, runestrncmp, runestrcpy, + runestrncpy, runestrecpy, runestrlen, runestrchr, runestrrchr, + runestrdup, runestrstr – rune string operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + Rune* runestrcat(Rune *s1, Rune *s2) +
+ + Rune* runestrncat(Rune *s1, Rune *s2, long n) +
+ + int     runestrcmp(Rune *s1, Rune *s2) +
+ + int     runestrncmp(Rune *s1, Rune *s2, long n) +
+ + Rune* runestrcpy(Rune *s1, Rune *s2) +
+ + Rune* runestrncpy(Rune *s1, Rune *s2, long n) +
+ + Rune* runestrecpy(Rune *s1, Rune *es1, Rune *s2) +
+ + long    runestrlen(Rune *s) +
+ + Rune* runestrchr(Rune *s, Rune c) +
+ + Rune* runestrrchr(Rune *s, Rune c) +
+ + Rune* runestrdup(Rune *s) +
+ + Rune* runestrstr(Rune *s1, Rune *s2)
+ +
+

DESCRIPTION
+ +
+ + These functions are rune string analogues of the corresponding + functions in strcat(3).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + memory(3), rune(3), strcat(3)
+ +
+

BUGS
+ +
+ + The outcome of overlapping moves varies among implementations.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sechash.html b/man/man3/sechash.html new file mode 100644 index 00000000..2e055465 --- /dev/null +++ b/man/man3/sechash.html @@ -0,0 +1,195 @@ + +sechash(3) - Plan 9 from User Space + + + + +
+
+
SECHASH(3)SECHASH(3) +
+
+

NAME
+ +
+ + md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, + sha1unpickle – cryptographically secure hashes
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + DigestState*     md4(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + DigestState*     md5(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + char*           md5pickle(MD5state *state) +
+ + MD5state*        md5unpickle(char *p); +
+ + DigestState*     sha1(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + char*           sha1pickle(MD5state *state) +
+ + MD5state*        sha1unpickle(char *p); +
+ + DigestState*     hmac_md5(uchar *data, ulong dlen,
+ +
+ + +
+ + uchar *key, ulong klen,
+ uchar *digest, DigestState *state) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ DigestState*     hmac_sha1(uchar *data, ulong dlen,
+ +
+ + +
+ + uchar *key, ulong klen,
+ uchar *digest, DigestState *state)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + +
+ + These functions implement the cryptographic hash functions MD4, + MD5, and SHA1. The output of the hash is called a digest. A hash + is secure if, given the hashed data and the digest, it is difficult + to predict the change to the digest resulting from some change + to the data without rehashing the whole data. Therefore, if + a secret is part of the hashed data, the digest can be used as + an integrity check of the data by anyone possessing the secret. + +
+ + The routines md4, md5, sha1, hmac_md5, and hmac_sha1 differ only + in the length of the resulting digest and in the security of the + hash. Usage for each is the same. The first call to the routine + should have nil as the state parameter. This call returns a state + which can be used to chain subsequent calls. The last call + should have digest non-nil. Digest must point to a buffer of at + least the size of the digest produced. This last call will free + the state and copy the result into digest. For example, to hash + a single buffer using md5:
+ +
+ + uchar digest[MD5dlen];
+ md5(data, len, digest, nil);
+ +
+ + +
+ To chain a number of buffers together, bounded on each end by + some secret:
+ +
+ + char buf[256];
+ uchar digest[MD5dlen];
+ DigestState *s;
+ s = md5("my password", 11, nil, nil);
+ while((n = read(fd, buf, 256)) > 0)
+ +
+ + md5(buf, n, nil, s);
+ +
+ md5("drowssap ym", 11, digest, s);
+ +
+ + +
+ The constants MD4dlen, MD5dlen, and SHA1dlen define the lengths + of the digests. +
+ + Hmac_md5 and hmac_sha1 are used slightly differently. These hash + algorithms are keyed and require a key to be specified on every + call. The digest lengths for these hashes are MD5dlen and SHA1dlen + respectively. +
+ + The functions md5pickle and sha1pickle marshal the state of a + digest for transmission. Md5unpickle and sha1unpickle unmarshal + a pickled digest. All four routines return a pointer to a newly + malloc(3)’d object.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + aes(3), blowfish(3), des(3), elgamal(3), rc4(3), rsa(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/seek.html b/man/man3/seek.html new file mode 100644 index 00000000..a2c19651 --- /dev/null +++ b/man/man3/seek.html @@ -0,0 +1,96 @@ + +seek(3) - Plan 9 from User Space + + + + +
+
+
SEEK(3)SEEK(3) +
+
+

NAME
+ +
+ + seek – change file offset
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + vlong seek(int fd, vlong n, int type)
+ +
+

DESCRIPTION
+ +
+ + Seek sets the offset for the file associated with fd as follows:
+ +
+ + If type is 0, the offset is set to n bytes.
+ If type is 1, the pointer is set to its current location plus + n.
+ If type is 2, the pointer is set to the size of the file plus + n. +
+ + +
+ The new file offset value is returned. +
+ + Seeking in a directory is not allowed. Seeking in a pipe is a + no-op.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/seek.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, seek is a + preprocessor macro defined as p9seek; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sendfd.html b/man/man3/sendfd.html new file mode 100644 index 00000000..37007603 --- /dev/null +++ b/man/man3/sendfd.html @@ -0,0 +1,85 @@ + +sendfd(3) - Plan 9 from User Space + + + + +
+
+
SENDFD(3)SENDFD(3) +
+
+

NAME
+ +
+ + sendfd, recvfd – pass file descriptors along Unix domain sockets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int    sendfd(int socket, int fd) +
+ + int    recvfd(int socket)
+ +
+

DESCRIPTION
+ +
+ + Recvfd and sendfd can be used to pass an open file descriptor + over a Unix domain socket from one process to another. Since pipe(3) + is implemented with socketpair(2) instead of pipe(2), socket can + be a file descriptor obtained from pipe(3). +
+ + Sendfd sends the file descriptor fd along the socket to a process + calling recvfd on the other end. +
+ + It is assumed that the two sides have coordinated and agreed to + transfer a file descriptor already, so that the sendfd is met + with a recvfd instead of an ordinary read. +
+ + The file descriptor number may change on its way between processes, + but the kernel structure it represents will not.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sendfd.c
+ +
+

SEE ALSO
+ +
+ + socketpair(2), sendmsg in send(2)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/setjmp.html b/man/man3/setjmp.html new file mode 100644 index 00000000..b22431fd --- /dev/null +++ b/man/man3/setjmp.html @@ -0,0 +1,110 @@ + +setjmp(3) - Plan 9 from User Space + + + + +
+
+
SETJMP(3)SETJMP(3) +
+
+

NAME
+ +
+ + setjmp, longjmp, notejmp – non-local goto
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    setjmp(jmp_buf env) +
+ + void longjmp(jmp_buf env, int val) +
+ + void notejmp(void *uregs, jmp_buf env, int val)
+ +
+

DESCRIPTION
+ +
+ + These routines are useful for dealing with errors and interrupts + encountered in a low-level subroutine of a program. +
+ + Setjmp saves its stack environment in env for later use by longjmp. + It returns value 0. +
+ + Longjmp restores the environment saved by the last call of setjmp. + It then causes execution to continue as if the call of setjmp + had just returned with value val. The invoker of setjmp must not + itself have returned in the interim. All accessible data have + values as of the time longjmp was called. +
+ + Notejmp is the same as longjmp except that it is to be called + from within a note handler (see notify(3)). The uregs argument + should be the first argument passed to the note handler. +
+ + Setjmp and longjmp can also be used to switch stacks.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/jmp.c
+ +
+

SEE ALSO
+ +
+ + notify(3)
+ +
+

BUGS
+ +
+ + +
+ + Notejmp cannot recover from an address trap or bus error (page + fault) on the 680x0 architectures. +
+ + To avoid name conflicts with the underlying system, setjmp, longjmp, + notejmp, and jmp_buf are preprocessor macros defined as p9setjmp, + p9longjmp, p9notejmp, and p9jmp_buf; see intro(3). +
+ + P9setjmp is implemented as a preprocessor macro that calls sigsetjmp + (see Unix’s setjmp(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sleep.html b/man/man3/sleep.html new file mode 100644 index 00000000..6614f33a --- /dev/null +++ b/man/man3/sleep.html @@ -0,0 +1,95 @@ + +sleep(3) - Plan 9 from User Space + + + + +
+
+
SLEEP(3)SLEEP(3) +
+
+

NAME
+ +
+ + sleep, alarm – delay, ask for delayed note
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int sleep(long millisecs) +
+ + long alarm(unsigned long millisecs)
+ +
+

DESCRIPTION
+ +
+ + Sleep suspends the current process for the number of milliseconds + specified by the argument. The actual suspension time may be a + little more or less than the requested time. If millisecs is 0, + the process gives up the CPU if another process is waiting to + run, returning immediately if not. Sleep returns –1 if interrupted, + 0 otherwise. +
+ + Alarm causes an alarm note (see notify(3)) to be sent to the invoking + process after the number of milliseconds given by the argument. + Successive calls to alarm reset the alarm clock. A zero argument + clears the alarm. The return value is the amount of time previously + remaining in the alarm clock. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sleep.c
+ +
+

SEE ALSO
+ +
+ + intro(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, sleep and + alarm are preprocessor macros defined as p9sleep and p9alarm; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/stat.html b/man/man3/stat.html new file mode 100644 index 00000000..fb79a647 --- /dev/null +++ b/man/man3/stat.html @@ -0,0 +1,244 @@ + +stat(3) - Plan 9 from User Space + + + + +
+
+
STAT(3)STAT(3) +
+
+

NAME
+ +
+ + stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, + nulldir – get and put file status
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int stat(char *name, uchar *edir, int nedir) +
+ + int fstat(int fd, uchar *edir, int nedir) +
+ + int wstat(char *name, uchar *edir, int nedir) +
+ + int fwstat(int fd, uchar *edir, int nedir) +
+ + Dir* dirstat(char *name) +
+ + Dir* dirfstat(int fd) +
+ + int dirwstat(char *name, Dir *dir) +
+ + int dirfwstat(int fd, Dir *dir) +
+ + void nulldir(Dir *d)
+ +
+

DESCRIPTION
+ +
+ + Given a file’s name, or an open file descriptor fd, these routines + retrieve or modify file status information. Stat, fstat, wstat, + and fwstat are the system calls; they deal with machine-independent + directory entries. Their format is defined by stat(9p). Stat and + fstat retrieve information about name or fd into edir, a buffer + of length nedir, defined in <libc.h>. Wstat and fwstat write information + back, thus changing file attributes according to the contents + of edir. The data returned from the kernel includes its leading + 16-bit length field as described in intro(9p). For symmetry, this + field must also be present when passing data to the + kernel in a call to wstat and fwstat, but its value is ignored. + +
+ + Dirstat, dirfstat, dirwstat, and dirfwstat are similar to their + counterparts, except that they operate on Dir structures:
+ +
+ + typedef
+ struct Dir {
+ +
+ + /* system−modified data */
+ uint    type;      /* server type */
+ uint    dev;       /* server subtype */
+ /* file data */
+ Qid     qid;       /* unique id from server */
+ ulong mode;      /* permissions */
+ ulong atime;     /* last read time */
+ ulong mtime;     /* last write time */
+ vlong length;    /* file length: see <u.h> */
+ char    *name;     /* last element of path */
+ char    *uid;      /* owner name */
+ char    *gid;      /* group name */
+ char    *muid;     /* last modifier name */
+ +
+ } Dir;
+ +
+ + +
+ The returned structure is allocated by malloc(3); freeing it also + frees the associated strings. +
+ + This structure and the Qid structure are defined in <libc.h>. If + the file resides on permanent storage and is not a directory, + the length returned by stat is the number of bytes in the file. + For directories, the length returned is zero. For files that are + streams (e.g., pipes and network connections), the length is the + number of bytes that can be read without blocking. +
+ + Each file is the responsibility of some server: it could be a + file server, a kernel device, or a user process. Type identifies + the server type, and dev says which of a group of servers of the + same type is the one responsible for this file. Qid is a structure + containing path and vers fields: path is guaranteed to be + unique among all path names currently on the file server, and + vers changes each time the file is modified. The path is a long + long (64 bits, vlong) and the vers is an unsigned long (32 bits, + ulong). Thus, if two files have the same type, dev, and qid they + are the same file. +
+ + The bits in mode are defined by +
+ + +
+ + 0x80000000     directory
+ 0x40000000     append only
+ 0x20000000     exclusive use (locked)
+ +
+ + 0400     read permission by owner
+ 0200     write permission by owner
+ 0100     execute permission (search on directory) by owner
+ 0070     read, write, execute (search) by group
+ 0007     read, write, execute (search) by others
+ +
+ + +
+ +
+ There are constants defined in <libc.h> for these bits: DMDIR, DMAPPEND, + and DMEXCL for the first three; and DMREAD, DMWRITE, and DMEXEC + for the read, write, and execute bits for others. +
+ + The two time fields are measured in seconds since the epoch (Jan + 1 00:00 1970 GMT). Mtime is the time of the last change of content. + Similarly, atime is set whenever the contents are accessed; also, + it is set whenever mtime is set. +
+ + Uid and gid are the names of the owner and group of the file; + muid is the name of the user that last modified the file (setting + mtime). Groups are also users, but each server is free to associate + a list of users with any user name g, and that list is the set + of users in the group g. When an initial attachment is made to + a + server, the user string in the process group is communicated to + the server. Thus, the server knows, for any given file access, + whether the accessing process is the owner of, or in the group + of, the file. This selects which sets of three bits in mode is + used to check permissions. +
+ + Only some of the fields may be changed with the wstat calls. The + name can be changed by anyone with write permission in the parent + directory. The mode and mtime can be changed by the owner or the + group leader of the file’s current group. The gid can be changed: + by the owner if also a member of the new + group; or by the group leader of the file’s current group if also + leader of the new group (see intro(9p) for more information about + permissions, users, and groups). The length can be changed by + anyone with write permission, provided the operation is implemented + by the server. (See intro(9p) for permission, user, + and group information). +
+ + Special values in the fields of the Dir passed to wstat indicate + that the field is not intended to be changed by the call. The + values are the maximum unsigned integer of appropriate size for + integral values (usually ~0, but beware of conversions and size + mismatches when comparing values) and the empty or nil string + for string values. The routine nulldir initializes all the elements + of d to these “don’t care” values. Thus one may change the mode, + for example, by using nulldir to initialize a Dir, then setting + the mode, and then doing wstat; it is not necessary to use stat + to retrieve the initial values first. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dirstat.c
+ +
+

SEE ALSO
+ +
+ + intro(3), fcall(3), dirread(3), stat(9p)
+ +
+

DIAGNOSTICS
+ +
+ + The dir functions return a pointer to the data for a successful + call, or nil on error. The others return the number of bytes copied + on success, or –1 on error. All set errstr. +
+ + If the buffer for stat or fstat is too short for the returned + data, the return value will be BIT16SZ (see fcall(3)) and the + two bytes returned will contain the initial count field of the + returned data; retrying with nedir equal to that value plus BIT16SZ + (for the count itself) should succeed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/strcat.html b/man/man3/strcat.html new file mode 100644 index 00000000..542ebd25 --- /dev/null +++ b/man/man3/strcat.html @@ -0,0 +1,203 @@ + +strcat(3) - Plan 9 from User Space + + + + +
+
+
STRCAT(3)STRCAT(3) +
+
+

NAME
+ +
+ + strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, + strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, + strtok, strdup, strstr, cistrstr – string operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* strcat(char *s1, char *s2) +
+ + char* strncat(char *s1, char *s2, long n) +
+ + int     strcmp(char *s1, char *s2) +
+ + int     strncmp(char *s1, char *s2, long n) +
+ + int     cistrcmp(char *s1, char *s2) +
+ + int     cistrncmp(char *s1, char *s2, long n) +
+ + char* strcpy(char *s1, char *s2) +
+ + char* strecpy(char *s1, char *es1, char *s2) +
+ + char* strncpy(char *s1, char *s2, long n) +
+ + long    strlen(char *s) +
+ + char* strchr(char *s, char c) +
+ + char* strrchr(char *s, char c) +
+ + char* strpbrk(char *s1, char *s2) +
+ + long    strspn(char *s1, char *s2) +
+ + long    strcspn(char *s1, char *s2) +
+ + char* strtok(char *s1, char *s2) +
+ + char* strdup(char *s) +
+ + char* strstr(char *s1, char *s2) +
+ + char* cistrstr(char *s1, char *s2)
+ +
+

DESCRIPTION
+ +
+ + The arguments s1, s2 and s point to null-terminated strings. The + functions strcat, strncat, strcpy, strecpy, and strncpy all alter + s1. Strcat and strcpy do not check for overflow of the array pointed + to by s1. +
+ + Strcat appends a copy of string s2 to the end of string s1. Strncat + appends at most n bytes. Each returns a pointer to the null-terminated + result. +
+ + Strcmp compares its arguments and returns an integer less than, + equal to, or greater than 0, according as s1 is lexicographically + less than, equal to, or greater than s2. Strncmp makes the same + comparison but examines at most n bytes. Cistrcmp and cistrncmp + ignore ASCII case distinctions when comparing strings. + The comparisons are made with unsigned bytes. +
+ + Strcpy copies string s2 to s1, stopping after the null byte has + been copied. Strncpy copies exactly n bytes, truncating s2 or + adding null bytes to s1 if necessary. The result will not be null-terminated + if the length of s2 is n or more. Each function returns s1. +
+ + Strecpy copies bytes until a null byte has been copied, but writes + no bytes beyond es1. If any bytes are copied, s1 is terminated + by a null byte, and a pointer to that byte is returned. Otherwise, + the original s1 is returned. +
+ + Strlen returns the number of bytes in s, not including the terminating + null byte. +
+ + Strchr (strrchr) returns a pointer to the first (last) occurrence + of byte c in string s, or 0 if c does not occur in the string. + The null byte terminating a string is considered to be part of + the string. +
+ + Strpbrk returns a pointer to the first occurrence in string s1 + of any byte from string s2, 0 if no byte from s2 exists in s1. + +
+ + Strspn (strcspn) returns the length of the initial segment of + string s1 which consists entirely of bytes from (not from) string + s2. +
+ + Strtok considers the string s1 to consist of a sequence of zero + or more text tokens separated by spans of one or more bytes from + the separator string s2. The first call, with pointer s1 specified, + returns a pointer to the first byte of the first token, and will + have written a null byte into s1 immediately following the returned + token. The function keeps track of its position in the string + between separate calls; subsequent calls, signified by s1 being + 0, will work through the string s1 immediately following that + token. The separator string s2 may be different from call to call. + When no token remains in s1, 0 is returned. +
+ + Strdup returns a pointer to a distinct copy of the null-terminated + string s in space obtained from malloc(3) or 0 if no space can + be obtained. +
+ + Strstr returns a pointer to the first occurrence of s2 as a substring + of s1, or 0 if there is none. If s2 is the null string, strstr + returns s1. Cistrstr operates analogously, but ignores ASCII case + differences when comparing strings.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + memory(3), rune(3), runestrcat(3)
+ +
+

BUGS
+ +
+ + These routines know nothing about UTF. Use the routines in rune(3) + as appropriate. Note, however, that the definition of UTF guarantees + that strcmp compares UTF strings correctly. +
+ + The outcome of overlapping moves varies among implementations.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/string.html b/man/man3/string.html new file mode 100644 index 00000000..55a1673b --- /dev/null +++ b/man/man3/string.html @@ -0,0 +1,244 @@ + +string(3) - Plan 9 from User Space + + + + +
+
+
STRING(3)STRING(3) +
+
+

NAME
+ +
+ + s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, + s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, + s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, + s_getline, s_allocinstack, s_freeinstack, s_rdinstack – extensible + strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <String.h> +
+ + String*     s_new(void)
+ void        s_free(String *s)
+ String*     s_newalloc(int n)
+ String*     s_array(char *p, int n)
+ String*     s_grow(String *s, int n) +
+ + void        s_putc(String *s, int c)
+ void        s_terminate(String *s)
+ String*     s_reset(String *s)
+ String*     s_restart(String *s)
+ String*     s_append(String *s, char *p)
+ String*     s_nappend(String *s, char *p, int n)
+ String*     s_memappend(String *s, char *p, int n)
+ String*     s_copy(char *p)
+ String*     s_parse(String *s1, String *s2)
+ +
+ + void        s_tolower(String *s) +
+ + String*     s_incref(String *s)
+ String*     s_unique(String *s) +
+ + Sinstack* s_allocinstack(char *file)
+ void        s_freeinstack(Sinstack *stack)
+ char*       s_rdinstack(Sinstack *stack, String *s) +
+ + #include <bio.h> +
+ + int         s_read(Biobuf *b, String *s, int n)
+ char*       s_read_line(Biobuf *b, String *s)
+ char*       s_getline(Biobuf *b, String *s)
+ +
+

DESCRIPTION
+ +
+ + +
+ + These routines manipulate extensible strings. The basic type is + String, which points to an array of characters. The string maintains + pointers to the beginning and end of the allocated array. In addition + a finger pointer keeps track of where parsing will start (for + s_parse) or new characters will be added (for s_putc, + s_append, and s_nappend). The structure, and a few useful macros + are:
+ typedef struct String {
+ +
+ + +
+ + Lock;
+ char*base;/* base of String */
+ char*end;/* end of allocated space+1 */
+ char*ptr;/* ptr into String */
+ ...
+ +
+ +
+ } String;
+ #define s_to_c(s) ((s)−>base)
+ #define s_len(s) ((s)−>ptr−(s)−>base)
+ #define s_clone(s) s_copy((s)−>base)
+ +
+ + S_to_c is used when code needs a reference to the character array. + Using s−>base directly is frowned upon since it exposes too much + of the implementation.
+

Allocation and freeing
+ +
+ + A string must be allocated before it can be used. One normally + does this using s_new, giving the string an initial allocation + of 128 bytes. If you know that the string will need to grow much + longer, you can use s_newalloc instead, specifying the number + of bytes in the initial allocation. +
+ + S_free causes both the string and its character array to be freed. + +
+ + S_grow grows a string’s allocation by a fixed amount. It is useful + if you are reading directly into a string’s character array but + should be avoided if possible. +
+ + S_array is used to create a constant array, that is, one whose + contents won’t change. It points directly to the character array + given as an argument. Tread lightly when using this call.
+

Filling the string
+ After its initial allocation, the string points to the beginning + of an allocated array of characters starting with NUL. +
+ + S_putc writes a character into the string at the pointer and advances + the pointer to point after it. +
+ + S_terminate writes a NUL at the pointer but doesn’t advance it. + +
+ + S_restart resets the pointer to the begining of the string but + doesn’t change the contents. +
+ + S_reset is equivalent to s_restart followed by s_terminate. +
+ + S_append and s_nappend copy characters into the string at the + pointer and advance the pointer. They also write a NUL at the + pointer without advancing the pointer beyond it. Both routines + stop copying on encountering a NUL. S_memappend is like s_nappend + but doesn’t stop at a NUL. +
+ + If you know the initial character array to be copied into a string, + you can allocate a string and copy in the bytes using s_copy. + This is the equivalent of a s_new followed by an s_append. +
+ + S_parse copies the next white space terminated token from s1 to + the end of s2. White space is defined as space, tab, and newline. + Both single and double quoted strings are treated as a single + token. The bounding quotes are not copied. There is no escape + mechanism. +
+ + S_tolower converts all ASCII characters in the string to lower + case.
+

Multithreading
+ +
+ + S_incref is used by multithreaded programs to avoid having the + string memory released until the last user of the string performs + an s_free. S_unique returns a unique copy of the string: if the + reference count it 1 it returns the string, otherwise it returns + an s_clone of the string.
+

Bio interaction
+ +
+ + S_read reads the requested number of characters through a Biobuf + into a string. The string is grown as necessary. An eof or error + terminates the read. The number of bytes read is returned. The + string is null terminated. +
+ + S_read_line reads up to and including the next newline and returns + a pointer to the beginning of the bytes read. An eof or error + terminates the read. The string is null terminated. +
+ + S_getline reads up to the next newline, appends the input to s, + and returns a pointer to the beginning of the bytes read. Leading + spaces and tabs and the trailing newline are all discarded. S_getline + discards blank lines and lines beginning with #. S_getline ignores + newlines escaped by immediately-preceding + backslashes. +
+ + S_allocinstack allocates an input stack with the single file file + open for reading. S_freeinstack frees an input stack. S_rdinstack + reads a line from an input stack. It follows the same rules as + s_getline except that when it encounters a line of the form #include + newfile, s_getline pushes newfile onto the input stack, + postponing further reading of the current file until newfile has + been read. The input stack has a maximum depth of 32 nested include + files.
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libString
+ +
+

SEE ALSO
+ +
+ + bio(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/stringsize.html b/man/man3/stringsize.html new file mode 100644 index 00000000..1e8c4e91 --- /dev/null +++ b/man/man3/stringsize.html @@ -0,0 +1,116 @@ + +stringsize(3) - Plan 9 from User Space + + + + +
+
+
STRINGSIZE(3)STRINGSIZE(3) +
+
+

NAME
+ +
+ + stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, + runestringnwidth – graphical size of strings
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + Point stringsize(Font *f, char *s)
+ +
+ + int     stringwidth(Font *f, char *s)
+ +
+ + int     stringnwidth(Font *f, char *s, int n)
+ +
+ + Point runestringsize(Font *f, Rune *s)
+ +
+ + int     runestringwidth(Font *f, Rune *s)
+ +
+ + int     runestringnwidth(Font *f, Rune *s, int n)
+ +
+

DESCRIPTION
+ +
+ + These routines compute the geometrical extent of character strings + when drawn on the display. The most straightforward, stringsize, + returns a Point representing the vector from upper left to lower + right of the NUL-terminated string s drawn in font f. Stringwidth + returns just the x component. + Stringnwidth returns the width of the first n characters of s. + +
+ + The routines beginning with rune are analogous, but accept an + array of runes rather than UTF-encoded bytes.
+ +
+

FILES
+ +
+ + /lib/font/bit    directory of fonts
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + addpt(3), cachechars(3), subfont(3), draw(3), draw(3), image(7), + font(7)
+ +
+

DIAGNOSTICS
+ +
+ + Because strings are loaded dynamically, these routines may generate + I/O to the server and produce calls to the graphics error function.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/subfont.html b/man/man3/subfont.html new file mode 100644 index 00000000..16dc216d --- /dev/null +++ b/man/man3/subfont.html @@ -0,0 +1,260 @@ + +subfont(3) - Plan 9 from User Space + + + + +
+
+
SUBFONT(3)SUBFONT(3) +
+
+

NAME
+ +
+ + allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, + subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, + strsubfontwidth, mkfont – subfont manipulation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + Subfont* allocsubfont(char *name, int n, int height, int ascent,
+ +
+ + +
+ + Fontchar *info, Image *i) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void       freesubfont(Subfont *f) +
+ + void       installsubfont(char *name, Subfont *f) +
+ + Subfont* lookupsubfont(Subfont *f) +
+ + void       uninstallsubfont(Subfont *f) +
+ + Subfont* readsubfont(Display *d, char *name, int fd, int dolock) + +
+ + Subfont* readsubfonti(Display *d, char *name, int fd, Image *im,
+ +
+ + +
+ + int dolock) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int        writesubfont(int fd, Subfont *f) +
+ + Point      stringsubfont(Image *dst, Point p, Image *src,
+ +
+ + +
+ + Subfont *f, char *str) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ Point      strsubfontwidth(Subfont *f, char *s) +
+ + Font*      mkfont(Subfont *f, Rune min)
+ +
+

DESCRIPTION
+ +
+ + Subfonts are the components of fonts that hold the character images. + A font comprises an array of subfonts; see cachechars(3). A new + Subfont is allocated and initialized with allocsubfont. See cachechars(3) + for the meaning of n, height, ascent, and info, and the arrangement + of characters in image i. The name is + used to identify the subfont in the subfont cache; see the descriptions + lookupsubfont and installsubfont (q.v.). The appropriate fields + of the returned Subfont structure are set to the passed arguments, + and the image is registered as a subfont with the graphics device + draw(3). Allocsubfont returns 0 on failure. +
+ + Freesubfont frees a subfont and all its associated structure including + the associated image. Since freesbufont calls free on f−>info, + if f−>info was not allocated by malloc(3) it should be zeroed before + calling subffree. +
+ + A number of subfonts are kept in external files. The convention + for naming subfont files is:
+ +
+ + /usr/local/plan9/font/name/class.size.depth +
+ + +
+ where size is approximately the height in pixels of the lower + case letters (without ascenders or descenders). If there is only + one version of the subfont, the .depth extension is elided. Class + describes the range of runes encoded in the subfont: ascii, latin1, + greek, etc. +
+ + Subfonts are cached within the program, so a subfont shared between + fonts will be loaded only once. Installsubfont stores subfont + f under the given name, typically the file name from which it + was read. Uninstallsubfont removes the subfont from the cache. + Finally, lookupsubfont searches for a subfont with the given + name in the cache and returns it, or nil if no such subfont exists. + +
+ + Subfontname is used to locate subfonts given their names within + the fonts. The default version constructs a name given the cfname, + its name within the font, fname, the name of the font, and the + maximum depth suitable for this subfont. This interface allows + a partially specified name within a font to be resolved at + run-time to the name of a file holding a suitable subfont. Although + it is principally a routine internal to the library, subfontname + may be substituted by the application to provide a less file-oriented + subfont naming scheme. +
+ + The format of a subfont file is described in font(7). Briefly, + it contains a image with all the characters in it, followed by + a subfont header, followed by character information. Readsubfont + reads a subfont from the file descriptor fd. The name is used + to identify the font in the cache. The dolock argument specifies + whether + the routine should synchronize use of the Display with other processes; + for single-threaded applications it may always be zero. Readsubfonti + does the same for a subfont whose associated image is already + in memory; it is passed as the argument im. In other words, readsubfonti + reads only the header and character + information from the file descriptor. +
+ + Writesubfont writes on fd the part of a subfont file that comes + after the image. It should be preceded by a call to writeimage + (see allocimage(3)). +
+ + Stringsubfont is analogous to string (see draw(3)) for subfonts. + Rather than use the underlying font caching primitives, it calls + draw for each character. It is intended for stand-alone environments + such as operating system kernels. Strsubfontwidth returns the + width of the string s in as it would appear if drawn with + stringsubfont in Subfont f. +
+ + Mkfont takes as argument a Subfont s and returns a pointer to + a Font that maps the character images in s into the Runes min + to min+s−>n−1.
+ +
+

FILES
+ +
+ + /usr/local/plan9/font   bitmap font file tree
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), cachechars(3), image(7), + font(7)
+ +
+

DIAGNOSTICS
+ +
+ + All of the functions use the graphics error function (see graphics(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sysfatal.html b/man/man3/sysfatal.html new file mode 100644 index 00000000..15ceb0ca --- /dev/null +++ b/man/man3/sysfatal.html @@ -0,0 +1,71 @@ + +sysfatal(3) - Plan 9 from User Space + + + + +
+
+
SYSFATAL(3)SYSFATAL(3) +
+
+

NAME
+ +
+ + sysfatal – system error messages
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void sysfatal(char *fmt, ...)
+ +
+

DESCRIPTION
+ +
+ + Sysfatal prints to standard error the name of the running program, + a colon and a space, the message described by the print(3) format + string fmt and subsequent arguments, and a newline. It then calls + exits(3) with the formatted message as argument. The program’s + name is the value of argv0, which will be set if the + program uses the arg(3) interface to process its arguments. If + argv0 is null, it is ignored and the following colon and space + are suppressed.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sysfatal.c
+ +
+

SEE ALSO
+ +
+ + intro(3), errstr(3), the %r format in print(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/thread.html b/man/man3/thread.html new file mode 100644 index 00000000..b14d97e6 --- /dev/null +++ b/man/man3/thread.html @@ -0,0 +1,383 @@ + +thread(3) - Plan 9 from User Space + + + + +
+
+
THREAD(3)THREAD(3) +
+
+

NAME
+ +
+ + alt, chancreate, chanfree, chaninit, chanprint, chansetname, mainstacksize, + proccreate, procdata, recv, recvp, recvul, send, sendp, sendul, + nbrecv, nbrecvp, nbrecvul, nbsend, nbsendp, nbsendul, threadcreate, + threaddata, threadexec, threadexecl, threadexits, threadexitsall, + threadgetgrp, threadgetname, threadint, + threadintgrp, threadkill, threadkillgrp, threadmain, threadnotify, + threadid, threadpid, threadsetgrp, threadsetname, threadsetstate, + threadspawn, threadwaitchan, yield – thread and proc management
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ #define    CHANEND      0
+ #define    CHANSND      1
+ #define    CHANRCV      2
+ #define    CHANNOP      3
+ #define    CHANNOBLK    4
+ typedef struct Alt Alt;
+ struct Alt {
+ +
+ + Channel *c;
+ void      *v;
+ int       op;
+ Channel **tag;
+ int       entryno;
+ char      *name;
+ +
+ };
+ +
+ + void       threadmain(int argc, char *argv[])
+ int        mainstacksize
+ int        proccreate(void (*fn)(void*), void *arg, uint stacksize)
+ int        threadcreate(void (*fn)(void*), void *arg, uint stacksize)
+ void       threadexits(char *status)
+ void       threadexitsall(char *status)
+ void       yield(void)
+ int        threadid(void)
+ int        threadgrp(void)
+ int        threadsetgrp(int group)
+ int        threadpid(int id)
+ int        threadint(int id)
+ int        threadintgrp(int group)
+ int        threadkill(int id)
+ int        threadkillgrp(int group)
+ void       threadsetname(char *name)
+ char*      threadgetname(void)
+ void**     threaddata(void)
+ void**     procdata(void)
+ int        chaninit(Channel *c, int elsize, int nel)
+ Channel* chancreate(int elsize, int nel)
+ void       chanfree(Channel *c)
+ int        alt(Alt *alts)
+ int        recv(Channel *c, void *v)
+ void*      recvp(Channel *c)
+ ulong      recvul(Channel *c)
+ int        nbrecv(Channel *c, void *v)
+ void*      nbrecvp(Channel *c)
+ ulong      nbrecvul(Channel *c)
+ int        send(Channel *c, void *v)
+ int        sendp(Channel *c, void *v)
+ int        sendul(Channel *c, ulong v)
+ int        nbsend(Channel *c, void *v)
+ int        nbsendp(Channel *c, void *v)
+ int        nbsendul(Channel *c, ulong v)
+ int        chanprint(Channel *c, char *fmt, ...)
+ int        threadspawn(int fd[3], char *file, char *args[])
+ int        threadexecl(Channel *cpid, int fd[3], char *file, ...)
+ int        threadexec(Channel *cpid, int fd[3], char *file, char *args[])
+ Channel* threadwaitchan(void)
+ int        threadnotify(int (*f)(void*, char*), int in)
+ +
+

DESCRIPTION
+ +
+ + +
+ + The thread library provides parallel programming support similar + to that of the languages Alef and Newsqueak. Threads and procs + occupy a shared address space, communicating and synchronizing + through channels and shared variables. +
+ + A proc is a Plan 9 process that contains one or more cooperatively + scheduled threads. Programs using threads must replace main by + threadmain. The thread library provides a main function that sets + up a proc with a single thread executing threadmain on a stack + of size mainstacksize (default eight kilobytes). To set + mainstacksize, declare a global variable initialized to the desired + value (e.g., int mainstacksize = 1024). +
+ + Threadcreate creates a new thread in the calling proc, returning + a unique integer identifying the thread; the thread executes fn(arg) + on a stack of size stacksize. Thread stacks are allocated in shared + memory, making it valid to pass pointers to stack variables between + threads and procs. Proccreate creates a new proc, + and inside that proc creates a single thread as threadcreate would, + returning the id of the created thread. Be aware that the calling + thread may continue execution before the newly created proc and + thread are scheduled. Because of this, arg should not point to + data on the stack of a function that could return before the + new process is scheduled. +
+ + Threadexits terminates the calling thread. If the thread is the + last in its proc, threadexits also terminates the proc, using + status as the exit status. Threadexitsall terminates all procs + in the program, using status as the exit status. +
+ + When the last thread in threadmain’s proc exits, the program will + appear to its parent to have exited. The remaining procs will + still run together, but as a background program. +
+ + The threads in a proc are coroutines, scheduled nonpreemptively + in a round-robin fashion. A thread must explicitly relinquish + control of the processor before another thread in the same proc + is run. Calls that do this are yield, proccreate, threadexec, + threadexecl, threadexits, threadspawn, alt, send, and recv (and + the + calls related to send and recv--see their descriptions further on). + Procs are scheduled by the operating system. Therefore, threads + in different procs can preempt one another in arbitrary ways and + should synchronize their actions using qlocks (see lock(3)) or + channel communication. System calls such as read(3) + block the entire proc; all threads in a proc block until the system + call finishes. +
+ + As mentioned above, each thread has a unique integer thread id. + Thread ids are not reused; they are unique across the life of + the program. Threadid returns the id for the current thread. Each + thread also has a thread group id. The initial thread has a group + id of zero. Each new thread inherits the group id of the + thread that created it. Threadgrp returns the group id for the + current thread; threadsetgrp sets it. Threadpid returns the pid + of the Plan 9 process containing the thread identified by id, + or –1 if no such thread is found. +
+ + Threadint interrupts a thread that is blocked in a channel operation + or system call. Threadintgrp interrupts all threads with the given + group id. Threadkill marks a thread to die when it next relinquishes + the processor (via one of the calls listed above). If the thread + is blocked in a channel operation or system call, it is + also interrupted. Threadkillgrp kills all threads with the given + group id. Note that threadkill and threadkillgrp will not terminate + a thread that never relinquishes the processor. +
+ + Primarily for debugging, threads can have string names associated + with them. Threadgetname returns the current thread’s name; threadsetname + sets it. The pointer returned by threadgetname is only valid until + the next call to threadsetname. +
+ + Also for debugging, threads have a string state associated with + them. Threadsetstate sets the state string. There is no threadgetstate; + since the thread scheduler resets the state to Running every time + it runs the thread, it is only useful for debuggers to inspect + the state. +
+ + Threaddata returns a pointer to a per-thread pointer that may + be modified by threaded programs for per-thread storage. Similarly, + procdata returns a pointer to a per-proc pointer. +
+ + Threadexecl and threadexec are threaded analogues of exec and + execl (see exec(3)); on success, they replace the calling thread + and invoke the external program, never returning. (Unlike on Plan + 9, the calling thread need not be the only thread in its proc--the + other threads will continue executing.) On error, they return + –1. If cpid is not null, the pid of the invoked program will be + sent along cpid (using sendul) once the program has been started, + or –1 will be sent if an error occurs. Threadexec and threadexecl + will not access their arguments after sending a result along cpid. + Thus, programs that malloc the argv passed to threadexec + can safely free it once they have received the cpid response. + +
+ + Threadexecl and threadexec will duplicate (see dup(3)) the three + file descriptors in fd onto standard input, output, and error + for the external program and then close them in the calling thread. + Beware of code that sets
+ +
+ + fd[0] = 0;
+ fd[1] = 1;
+ fd[2] = 2;
+ +
+ + +
+ to use the current standard files. The correct code is
+ +
+ + fd[0] = dup(0, −1);
+ fd[1] = dup(1, −1);
+ fd[2] = dup(2, −1);
+ +
+ + +
+ Threadspawn is like threadexec but does not replace the current + thread. It returns the pid of the invoked program on success, + or –1 on error. +
+ + Threadwaitchan returns a channel of pointers to Waitmsg structures + (see wait(3)). When an exec’ed process exits, a pointer to a Waitmsg + is sent to this channel. These Waitmsg structures have been allocated + with malloc(3) and should be freed after use. +
+ + A Channel is a buffered or unbuffered queue for fixed-size messages. + Procs and threads send messages into the channel and recv messages + from the channel. If the channel is unbuffered, a send operation + blocks until the corresponding recv operation occurs and vice + versa. Chaninit initializes a Channel for + messages of size elsize and with a buffer holding nel messages. + If nel is zero, the channel is unbuffered. Chancreate allocates + a new channel and initializes it. Chanfree frees a channel that + is no longer used. Chanfree can be called by either sender or + receiver after the last item has been sent or received. Freeing + the + channel will be delayed if there is a thread blocked on it until + that thread unblocks (but chanfree returns immediately). +
+ + The name element in the Channel structure is a description intended + for use in debugging. Chansetname sets the name. +
+ + Send sends the element pointed at by v to the channel c. If v + is null, zeros are sent. Recv receives an element from c and stores + it in v. If v is null, the received value is discarded. Send and + recv return 1 on success, –1 if interrupted. Nbsend and nbrecv + behave similarly, but return 0 rather than blocking. +
+ + Sendp, nbsendp, sendul, and nbsendul send a pointer or an unsigned + long; the channel must have been initialized with the appropriate + elsize. Recvp, nbrecvp, recvul, and nbrecvul receive a pointer + or an unsigned long; they return zero when a zero is received, + when interrupted, or (for nbrecvp and nbrecvul) when the + operation would have blocked. To distinguish between these three + cases, use recv or nbrecv. +
+ + Alt can be used to recv from or send to one of a number of channels, + as directed by an array of Alt structures, each of which describes + a potential send or receive operation. In an Alt structure, c + is the channel; v the value pointer (which may be null); and op + the operation: CHANSND for a send operation, + CHANRECV for a recv operation; CHANNOP for no operation (useful + when alt is called with a varying set of operations). The array + of Alt structures is terminated by an entry with op CHANEND or + CHANNOBLK. If at least one Alt structure can proceed, one of them + is chosen at random to be executed. Alt returns the + index of the chosen structure. If no operations can proceed and + the list is terminated with CHANNOBLK, alt returns the index of + the terminating CHANNOBLK structure. Otherwise, alt blocks until + one of the operations can proceed, eventually returning the index + of the structure executes. Alt returns –1 when + interrupted. The tag and entryno fields in the Alt structure are + used internally by alt and need not be initialized. They are not + used between alt calls. +
+ + Chanprint formats its arguments in the manner of print(3) and + sends the result to the channel c. The string delivered by chanprint + is allocated with malloc(3) and should be freed upon receipt. + +
+ + Thread library functions do not return on failure; if errors occur, + the entire program is aborted. +
+ + Threaded programs should use threadnotify in place of atnotify + (see notify(3)). +
+ + It is safe to use sysfatal(3) in threaded programs. Sysfatal will + print the error string and call threadexitsall. +
+ + It is not safe to call rfork in a threaded program, except to + call rfork(RFNOTEG) from the main proc before any other procs + have been created. To create new processes, use proccreate.
+ +
+

FILES
+ +
+ + /usr/local/plan9/acid/thread contains useful acid(1) functions + for debugging threaded programs. +
+ + /usr/local/plan9/src/libthread/test contains some example programs.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + intro(3), ioproc(3)
+ +
+

BUGS
+ +
+ + To avoid name conflicts, alt, nbrecv, nbrecvp, nbrecvul, nbsend, + nbsendp, nbsendul, recv, recvp, recvul, send, sendp, and sendul + are defined as macros that expand to chanalt, channbrecv, and + so on. Yield is defined as a macro that expands to threadyield. + See intro(3). +
+ + The implementation of threadnotify may not be correct.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/time.html b/man/man3/time.html new file mode 100644 index 00000000..de0de468 --- /dev/null +++ b/man/man3/time.html @@ -0,0 +1,79 @@ + +time(3) - Plan 9 from User Space + + + + +
+
+
TIME(3)TIME(3) +
+
+

NAME
+ +
+ + time, nsec – time in seconds and nanoseconds since epoch
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long time(long *tp)
+ +
+ + vlong nsec(void)
+ +
+

DESCRIPTION
+ +
+ + Both time and nsec return the time since the epoch 00:00:00 GMT, + Jan. 1, 1970. The return value of the former is in seconds and + the latter in nanoseconds. For time, if tp is not zero then *tp + is also set to the answer.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/time.c
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, time and nsec + are preprocessor macros defined as p9time and p9nsec; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/udpread.html b/man/man3/udpread.html new file mode 100644 index 00000000..e8f0d37b --- /dev/null +++ b/man/man3/udpread.html @@ -0,0 +1,105 @@ + +udpread(3) - Plan 9 from User Space + + + + +
+
+
UDPREAD(3)UDPREAD(3) +
+
+

NAME
+ +
+ + udpread, udpwrite – read and write UDP packets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + #include <ip.h> +
+ + typedef struct Udphdr Udphdr;
+ struct Udphdr
+ {
+ +
+ + uchar    raddr[IPaddrlen];/* remote address and port */
+ uchar    laddr[IPaddrlen];/* local address and port */
+ uchar    rport[2];
+ uchar    lport[2];
+ +
+ };
+ +
+ + long      udpread(int fd, Udphdr *hdr, void *data, long n)
+ +
+ + long udpwrite(int fd, Udphdr *hdr, void *data, long n)
+ +
+

DESCRIPTION
+ +
+ + Udpread and udpwrite read and write UDP packets from the UDP network + connection established on file descriptor fd. +
+ + Udpread reads at most n bytes of packet body into data , stores + the header in hdr, and returns the number of bytes stored in data. + +
+ + Udpwrite writes the n bytes stored in data in a UDP packet with + header hdr. +
+ + Note that the Udphdr frames the addresses as local and remote + instead of source and destination. Thus the hdr filled in for + a packet read by udpread can be used unchanged in udpwrite to + send a response back to the sender of the original packet.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/udp.c
+ +
+

SEE ALSO
+ +
+ + ip(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/wait.html b/man/man3/wait.html new file mode 100644 index 00000000..84322bc2 --- /dev/null +++ b/man/man3/wait.html @@ -0,0 +1,170 @@ + +wait(3) - Plan 9 from User Space + + + + +
+
+
WAIT(3)WAIT(3) +
+
+

NAME
+ +
+ + await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid + – wait for a process to exit
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + Waitmsg*    wait(void) +
+ + Waitmsg*    waitnohang(void) +
+ + Waitmsg*    waitfor(int pid) +
+ + int         waitpid(void) +
+ + int         await(char *s, int n) +
+ + int         awaitnohang(char *s, int n) +
+ + int         awaitfor(int pid, char *s, int n)
+ +
+

DESCRIPTION
+ +
+ + Wait causes a process to wait for any child process (see fork(2) + and rfork(3)) to exit. It returns a Waitmsg holding information + about the exited child. A Waitmsg has this structure:
+ +
+ + typedef
+ struct Waitmsg
+ {
+ +
+ + int pid;               /* of loved one */
+ ulong time[3];          /* of loved one & descendants */
+ char *msg;
+ +
+ } Waitmsg;
+ +
+ + +
+ Pid is the child’s process id. The time array contains the time + the child and its descendants spent in user code, the time spent + in system calls, and the child’s elapsed real time, all in units + of milliseconds. Msg contains the message that the child specified + in exits(3). For a normal exit, msg[0] is zero, otherwise msg + is the exit string prefixed by the process name, a blank, the + process id, and a colon. +
+ + If there are no more children to wait for, wait returns immediately, + with return value nil. +
+ + The Waitmsg structure is allocated by malloc(3) and should be + freed after use. For programs that only need the pid of the exiting + program, waitpid returns just the pid and discards the rest of + the information. +
+ + Waitnohang is like wait but does not block if there are no more + children to wait for. Instead it returns immediately and sets + errstr. +
+ + Waitfor is like wait but waits for a particular pid. +
+ + The underlying calls are await, awaitnohang, and awaitfor, which + fill in the n-byte buffer s with a textual representation of the + pid, times, and exit string. There is no terminal NUL. The return + value is the length, in bytes, of the data. +
+ + The filled-in buffer may be parsed (after appending a NUL) using + tokenize (see getfields(3)); the resulting fields are, in order, + pid, the three times, and the exit string, which will be '' for + normal exit. If the representation is longer than n bytes, it + is truncated but, if possible, properly formatted. The information + that + does not fit in the buffer is discarded, so a subsequent call + to await will return the information about the next exiting child, + not the remainder of the truncated message. In other words, each + call to await returns the information about one child, blocking + if necessary if no child has exited. If the calling process has + no + living children, await returns −1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/wait.c +
+ + /usr/local/plan9/src/lib9/await.c
+ +
+

SEE ALSO
+ +
+ + rfork(3), exits(3),
+ +
+

DIAGNOSTICS
+ +
+ + These routines set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, wait, waitpid, + and waitfor are preprocessor macros defined as p9wait, p9waitpid, + and p9waitfor; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/wctl.html b/man/man3/wctl.html new file mode 100644 index 00000000..071217e2 --- /dev/null +++ b/man/man3/wctl.html @@ -0,0 +1,78 @@ + +wctl(3) - Plan 9 from User Space + + + + +
+
+
WCTL(3)WCTL(3) +
+
+

NAME
+ +
+ + drawresizewindow, drawsetlabel, drawtopwindow – window management
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + void drawresizewindow(Rectangle r) +
+ + int    drawsetlabel(Display *d, char *name) +
+ + void drawtopwindow(void)
+ +
+

DESCRIPTION
+ +
+ + These routines interact with a window manager to set the properties + of the window running the current program. They substitute for + interacting directly with the Plan 9 rio’s /dev/wctl. +
+ + Drawresizewindow requests that the program’s window be resized + to have the width and height of the rectangle r. Only the width + and height are important; the offset is ignored. +
+ + Drawsetlabel requests that the program’s window title be set to + name. +
+ + Drawtopwindow requests that the program’s window be moved above + all other windows and given the input focus.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/x11−init.c
+ /usr/local/plan9/src/libdraw/x11−wsys.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/window.html b/man/man3/window.html new file mode 100644 index 00000000..83355bdd --- /dev/null +++ b/man/man3/window.html @@ -0,0 +1,241 @@ + +window(3) - Plan 9 from User Space + + + + +
+
+
WINDOW(3)WINDOW(3) +
+
+

NAME
+ +
+ + Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, + bottomnwindows, topwindow, topnwindows, originwindow – window management
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + typedef
+ struct Screen
+ {
+ +
+ + Display     *display; /* display holding data */
+ int         id;         /* id of system−held Screen */
+ Image       *image;     /* unused; for reference only */
+ Image       *fill;      /* color to paint behind windows */
+ +
+ } Screen;
+ +
+ + Screen* allocscreen(Image *image, Image *fill, int public) +
+ + Screen* publicscreen(Display *d, int id, ulong chan) +
+ + int       freescreen(Screen *s) +
+ + Image*    allocwindow(Screen *s, Rectangle r, int ref, int val) +
+ + void      bottomwindow(Image *w) +
+ + void      bottomnwindows(Image **wp, int nw) +
+ + void      topwindow(Image *w) +
+ + void      topnwindows(Image **wp, int nw) +
+ + int       originwindow(Image *w, Point log, Point scr) +
+ + enum
+ {
+ +
+ + +
+ + /* refresh methods */
+ Refbackup= 0,
+ Refnone= 1,
+ Refmesg= 2
+ +
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + Windows are represented as Images and may be treated as regular + images for all drawing operations. The routines discussed here + permit the creation, deletion, and shuffling of windows, facilities + that do not apply to regular images. +
+ + To create windows, it is first necessary to allocate a Screen + data structure to gather them together. A Screen turns an arbitrary + image into something that may have windows upon it. It is created + by allocscreen, which takes an image upon which to place the windows + (typically display−>image), a fill image + to paint the background behind all the windows on the image, and + a flag specifying whether the result should be publicly visible. + If it is public, an arbitrary other program connected to the same + display may acquire a pointer to the same screen by calling publicscreen + with the Display pointer and the id of the + published Screen, as well as the expected channel descriptor, + as a safety check. It will usually require some out-of-band coordination + for programs to share a screen profitably. Freescreen releases + a Screen, although it may not actually disappear from view until + all the windows upon it have also been + deallocated. +
+ + Unlike allocwindow, allocscreen does not initialize the appearance + of the Screen. +
+ + Windows are created by allocwindow, which takes a pointer to the + Screen upon which to create the window, a rectangle r defining + its geometry, an integer pixel value val to color the window initially, + and a refresh method ref. The refresh methods are Refbackup, which + provides backing store and is the + method used by rio(1) for its clients; Refnone, which provides + no refresh and is designed for temporary uses such as sweeping + a display rectangle, for windows that are completely covered by + other windows, and for windows that are already protected by backing + store; and Refmesg, which causes messages to be + delivered to the owner of the window when it needs to be repainted. + Refmesg is not fully implemented. +
+ + The result of allocwindow is an Image pointer that may be treated + like any other image. In particular, it is freed by calling freeimage + (see allocimage(3)). The following functions, however, apply only + to windows, not regular images. +
+ + Bottomwindow pushes window w to the bottom of the stack of windows + on its Screen, perhaps obscuring it. Topwindow pulls window w + to the top, making it fully visible on its Screen. (This Screen + may itself be within a window that is not fully visible; topwindow + will not affect the stacking of this parent + window.) Bottomnwindows and Topnwindows are analogous, but push + or pull a group of nw windows listed in the array wp. The order + within wp is unaffected. +
+ + Each window is created as an Image whose Rectangle r corresponds + to the rectangle given to allocwindow when it was created. Thus, + a newly created window w resides on its Screen−>image at w−>r and + has internal coordinates w−>r. Both these may be changed by a call + to originwindow. The two + Point arguments to originwindow define the upper left corner of + the logical coordinate system (log) and screen position (scr). + Their usage is shown in the Examples section. +
+ + Rio(1) creates its client windows with backing store, Refbackup. + The graphics initialization routine, initdraw (see graphics(3)), + builds a Screen upon this, and then allocates upon that another + window indented to protect the border. That window is created + Refnone, since the backing store created by rio + protects its contents. That window is the one known in the library + by the global name screen (a historic but confusing choice).
+ +
+

EXAMPLES
+ +
+ + To move a window to the upper left corner of the display,
+ +
+ + +
+ + originwindow(w, w−>r.min, Pt(0, 0));
+ +
+ +
+ To leave a window where it is on the screen but change its internal + coordinate system so (0, 0) is the upper left corner of the window,
+ +
+ + +
+ + originwindow(w, Pt(0, 0), w−>r.min);
+ +
+ +
+ After this is done, w−>r is translated to the origin and there + will be no way to discover the actual screen position of the window + unless it is recorded separately.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), cachechars(3), draw(3)
+ +
+

BUGS
+ +
+ + The refresh method Refmesg should be finished.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3