diff options
| author | rsc <devnull@localhost> | 2005-01-03 06:40:20 +0000 |
|---|---|---|
| committer | rsc <devnull@localhost> | 2005-01-03 06:40:20 +0000 |
| commit | 058b0118a52061ad57694c01fc8763b22b789c4d (patch) | |
| tree | 6685f04dea5ed68edaa34998c976aed34c55fe94 /man/man3 | |
| parent | 2600337aa704efbeba8201e88147a764b4fd2b90 (diff) | |
| download | plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.tar.gz plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.tar.bz2 plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.zip | |
Some man pages.
Diffstat (limited to 'man/man3')
106 files changed, 6016 insertions, 1828 deletions
diff --git a/man/man3/9p.3 b/man/man3/9p.3 index 9e755735..9d8967eb 100644 --- a/man/man3/9p.3 +++ b/man/man3/9p.3 @@ -10,8 +10,9 @@ postmountsrv, readbuf, readstr, respond, +srv, threadpostmountsrv, -srv \- 9P file service +walkandclone \- 9P file service .SH SYNOPSIS .ft L .nf @@ -176,9 +177,7 @@ as .BI /srv/ name . .IP Fork a child process via -.I rfork -(see -.IR fork (3)) +.IR rfork (3) or .I procrfork (see @@ -214,9 +213,7 @@ The parent returns to the caller. .LP If any error occurs during this process, the entire process is terminated by calling -.I sysfatal -(see -.IR perror (3)). +.IR sysfatal (3). .SS Service functions The functions in a .B Srv @@ -603,12 +600,12 @@ consults in changing the metadata for .IB r -> fid as described in -.IR stat (5). +.IR stat (9p). When using file trees, .I srv will take care to check that the request satisfies the permissions outlined in -.IR stat (5). +.IR stat (9p). Otherwise .I wstat should take care to enforce permissions @@ -720,19 +717,16 @@ accept the option to increment .BR chatty9p . .SH EXAMPLES -.IR Archfs (4), -.IR cdfs (4), -.IR nntpfs (4), -.IR snap (4), -and -.B /usr/local/plan9/src/lib9p/ramfs.c -are good examples of simple single-threaded file servers. -.IR Webfs (4) +/usr/local/plan9/src/lib9p/ramfs.c +is an example of simple single-threaded file servers. +On Plan 9, see +.IR archfs , +.IR cdfs , +.IR nntpfs , +.IR webfs , and .I sshnet -(see -.IR ssh (1)) -are good examples of multithreaded file servers. +for more examples. .PP In general, the .B File @@ -752,9 +746,4 @@ or is maintained elsewhere. .SH SEE ALSO .IR 9pfid (3), .IR 9pfile (3), -.IR srv (3), -.IR intro (5) -.SH BUGS -The switch to 9P2000 was taken as an opportunity to tidy -much of the interface; we promise to avoid such gratuitous change -in the future. +.IR intro (9p) diff --git a/man/man3/9pclient.3 b/man/man3/9pclient.3 new file mode 100644 index 00000000..1c7e76ad --- /dev/null +++ b/man/man3/9pclient.3 @@ -0,0 +1,342 @@ +.TH 9PCLIENT 3 +.SH 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 +.SH SYNOPSIS +.B #include <u.h> +.PP +.B #include <libc.h> +.PP +.B #include <fcall.h> +.PP +.B #include <9pclient.h> +.PP +.ta +'\fLCFsys* 'u +.B +CFsys* fsmount(int fd, char *aname) +.PP +.B +CFsys* nsmount(char *name, char *aname) +.PP +.B +CFid* fsroot(CFsys *fsys) +.PP +.B +void fsunmount(CFsys *fsys) +.PP +.B +CFsys* fsinit(int fd) +.PP +.B +int fsversion(CFsys *fsys, int msize, char *version, int nversion) +.PP +.B +CFid *fsauth(CFsys *fsys, char *uname, char *aname) +.PP +.B +CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) +.PP +.B +void fssetroot(CFsys *fsys, CFid *fid) +.PP +.B +void fsclose(CFid *fid) +.PP +.B +CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm) +.PP +.B +CFid* fsopen(CFsys *fs, char *path, int mode) +.PP +.B +long fspread(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fspwrite(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fsread(CFid *fid, void *buf, long n) +.PP +.B +long fsreadn(CFid *fid, void *buf, long n) +.PP +.B +long fswrite(CFid *fid, void *buf, long n) +.PP +.B +long fsdirread(CFid *fid, Dir **d) +.PP +.B +long fsdirreadall(CFid *fid, Dir **d) +.PP +.B +Dir* fsdirstat(CFsys *fs, char *path) +.PP +.B +Dir* fsdirfstat(CFid *fid) +.PP +.B +int fsdirwstat(CFsys *fs, char *path, Dir *d) +.PP +.B +int fsdirfwstat(CFid *fid, Dir *d) +.PP +.B +int fsopenfd(CFsys *fs, char *path, int mode) +.SH DESCRIPTION +The +.I 9pclient +library helps client programs interact with 9P servers. +.PP +A +.B CFsys* +represents a connection to a 9P server. +A +.B CFid* +represents an active fid on some connection; +see +.IR intro (9p). +.PP +A new connection to a 9P server is typically established by +.I fsmount +or +.IR nsmount . +.I Fsmount +initializes a new 9P conversation on the open file descriptor +.IR fd ; +.I nsmount +connects to a service named +.I name +in the current name space directory +(see +.IR intro (4)). +Both attach to the root of the file system +using the attach name +.IR aname . +.I Fsroot +returns the +.B CFid* +corresponding to this root. +.PP +.IR Fsinit , +.IR fsversion , +.IR fsauth , +.IR fsattach , +and +.I fssetroot +provide more detailed control over the file system connection +than +.I fsmount +and +.IR nsmount . +.I Fsinit +allocates a new +.B CFsys* +corresponding to a 9P conversation on the file descriptor +.IR fd . +.I Fsversion +executes a +.IR version (9p) +transaction to establish +maximum message size and 9P version. +.I Fsauth +executes an +.IR auth (9p) +transaction, returning the new auth fid. +.RI ( Fsread +and +.I fswrite +can then be used to run the authentication protocol over the fid.) +.I Fsattach +executes an +.IR attach (9p) +transaction to connect to the root of a file tree served by the server. +It presents +.I afid +(which may be nil) +to establish identity. +.I Fssetroot +sets the root fid used by +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +and +.IR fsdirwstat , +which evaluate rooted path names. +.PP +When a fid +is no longer needed, it should be clunked by calling +.I fsclose +and then considered freed. +Similarly, when the connection to the server is no longer needed, +it should be closed by calling +.IR fsunmount , +which will take care of calling +.I fsclose +on the current root fid. +Once all fids have been clunked +.I 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 +.IR close (2)). +Fids are not reference counted: when +.I fsclose +is called, the clunk transaction and freeing of storage +happen immediately. +.PP +.I Fscreate +and +.I fsopen +establish new fids using the +.IR walk , +.I create +and +.I open +transactions +(see +.IR walk (9p) +and +.IR open (9p)). +The +.I path +argument is evaluated relative to the +.B CFsys +root +(see +.I fsroot +and +.I 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 +.B ( . ) +are ignored. +.PP +Once opened, these fids can be read and written using +.I fspread +and +.IR fspwrite , +which execute +.I read +and +.I write +transactions +(see +.IR read (9p)). +The library maintains an offset for each fid, +analagous to the offset maintained by the kernel for each open file descriptor. +.I Fsread +and +.I fswrite +read and write from this offset, and update it after successful calls. +Calling +.I fspread +or +.I fspwrite +with an +.I offset +of \-1 +is identical to calling +.I fsread +or +.IR fswrite . +.I Fsreadn +calls +.I fsread +repeatedly to obtain exactly +.I n +bytes of data, unless it encounters end-of-file or an error. +.PP +Reading an open a directory returns directory entries encoded as described in +.IR stat (9p). +.I Fsdirread +calls +.I fsread +and then parses the encoded entries into an array of +.B Dir* +data structures, +storing a pointer to the array in +.BI *d +and returning the number of entries. +.I Fsdirreadall +is similar but reads the entire directory. +The returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirfstat +and +.I fsdirfwstat +execute +.I stat +and +.I wstat +(see +.IR stat (9p)) +transactions. +The +.B Dir +structure returned by +.I fsdirfstat +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirstat +and +.I fsdirwstat +are similar to +.I fsdirfstat +and +.I fsdirfwstat +but operate on paths relative to the file system root +(see +.I fsopen +and +.I fscreate +above). +.PP +.I 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 +.IR 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 +.B CFsys +is unmounted. +.SH SOURCE +.B /usr/local/plan9/src/lib9pclient +.SH SEE ALSO +.IR intro (4), +.IR intro (9p) +.SH BUGS +The implementation +should use a special version string to distinguish between +servers that support +.IR openfd (9p) +and servers that do not. +.PP +The interface does not provide access to the +.IR walk (9p) +transaction, or to +.I open +and +.I create +on already-established fids. +.PP +There is no +.IR fsseek . diff --git a/man/man3/9pcmdbuf.3 b/man/man3/9pcmdbuf.3 index d6a78b92..e961422f 100644 --- a/man/man3/9pcmdbuf.3 +++ b/man/man3/9pcmdbuf.3 @@ -42,7 +42,9 @@ bytes at .I p (which need not be NUL-terminated) as a UTF string and splits it using -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). It returns a .B Cmdbuf structure holding pointers to each field in the message. diff --git a/man/man3/9pfile.3 b/man/man3/9pfile.3 index 083b6550..1bb3038e 100644 --- a/man/man3/9pfile.3 +++ b/man/man3/9pfile.3 @@ -94,7 +94,7 @@ and the permissions of .I dir are used to calculate the permission bits for the file as described in -.IR open (5). +.IR open (9p). It is permissible for .I name to be a slash-separated path rather than a single element. @@ -162,7 +162,7 @@ consume the passed reference. .PP Directories may be read, yielding a directory entry structure (see -.IR stat (5)) +.IR stat (9p)) for each file in the directory. In order to allow concurrent reading of directories, clients must obtain a diff --git a/man/man3/INDEX b/man/man3/INDEX new file mode 100644 index 00000000..9c067d00 --- /dev/null +++ b/man/man3/INDEX @@ -0,0 +1,1163 @@ +9p 9p.3 +Srv 9p.3 +dirread9p 9p.3 +emalloc9p 9p.3 +erealloc9p 9p.3 +estrdup9p 9p.3 +postfd 9p.3 +postmountsrv 9p.3 +readbuf 9p.3 +readstr 9p.3 +respond 9p.3 +srv 9p.3 +threadpostmountsrv 9p.3 +walkandclone 9p.3 +9pclient 9pclient.3 +CFid 9pclient.3 +CFsys 9pclient.3 +fsattach 9pclient.3 +fsauth 9pclient.3 +fsclose 9pclient.3 +fscreate 9pclient.3 +fsdirfstat 9pclient.3 +fsdirfwstat 9pclient.3 +fsdirread 9pclient.3 +fsdirreadall 9pclient.3 +fsdirstat 9pclient.3 +fsdirwstat 9pclient.3 +fsinit 9pclient.3 +fsmount 9pclient.3 +fsopen 9pclient.3 +fsopenfd 9pclient.3 +fspread 9pclient.3 +fspwrite 9pclient.3 +fsread 9pclient.3 +fsreadn 9pclient.3 +fsroot 9pclient.3 +fssetroot 9pclient.3 +fsunmount 9pclient.3 +fsversion 9pclient.3 +fswrite 9pclient.3 +nsmount 9pclient.3 +9pcmdbuf 9pcmdbuf.3 +Cmdbuf 9pcmdbuf.3 +lookupcmd 9pcmdbuf.3 +parsecmd 9pcmdbuf.3 +respondcmderror 9pcmdbuf.3 +9pfid 9pfid.3 +Fid 9pfid.3 +Fidpool 9pfid.3 +Req 9pfid.3 +Reqpool 9pfid.3 +allocfid 9pfid.3 +allocfidpool 9pfid.3 +allocreq 9pfid.3 +allocreqpool 9pfid.3 +closefid 9pfid.3 +closereq 9pfid.3 +freefidpool 9pfid.3 +freereqpool 9pfid.3 +lookupfid 9pfid.3 +lookupreq 9pfid.3 +removefid 9pfid.3 +removereq 9pfid.3 +9pfile 9pfile.3 +File 9pfile.3 +Tree 9pfile.3 +alloctree 9pfile.3 +closedirfile 9pfile.3 +closefile 9pfile.3 +createfile 9pfile.3 +freetree 9pfile.3 +hasperm 9pfile.3 +opendirfile 9pfile.3 +readdirfile 9pfile.3 +removefile 9pfile.3 +walkfile 9pfile.3 +Dx addpt.3 +Dy addpt.3 +Pt addpt.3 +Rect addpt.3 +Rpt addpt.3 +addpt addpt.3 +canonrect addpt.3 +combinerect addpt.3 +divpt addpt.3 +eqpt addpt.3 +eqrect addpt.3 +insetrect addpt.3 +mulpt addpt.3 +ptinrect addpt.3 +rectXrect addpt.3 +rectaddpt addpt.3 +rectclip addpt.3 +rectinrect addpt.3 +rectsubpt addpt.3 +subpt addpt.3 +aes aes.3 +aesCBCdecrypt aes.3 +aesCBCencrypt aes.3 +setupAESstate aes.3 +allocimage allocimage.3 +allocimagemix allocimage.3 +bytesperline allocimage.3 +cloadimage allocimage.3 +freeimage allocimage.3 +loadimage allocimage.3 +namedimage allocimage.3 +nameimage allocimage.3 +readimage allocimage.3 +setalpha allocimage.3 +unloadimage allocimage.3 +wordsperline allocimage.3 +writeimage allocimage.3 +ARGBEGIN arg.3 +ARGC arg.3 +ARGEND arg.3 +ARGF arg.3 +EARGF arg.3 +arg arg.3 +arginit arg.3 +argopt arg.3 +add3 arith3.3 +add4 arith3.3 +arith3 arith3.3 +closept3 arith3.3 +cross3 arith3.3 +dist3 arith3.3 +div3 arith3.3 +dot3 arith3.3 +eqpt3 arith3.3 +fff2p3 arith3.3 +len3 arith3.3 +lerp3 arith3.3 +midpt3 arith3.3 +mul3 arith3.3 +nearseg3 arith3.3 +neg3 arith3.3 +pdiv4 arith3.3 +pldist3 arith3.3 +pn2f3 arith3.3 +ppp2f3 arith3.3 +reflect3 arith3.3 +sub3 arith3.3 +sub4 arith3.3 +unit3 arith3.3 +vdiv3 arith3.3 +vrem3 arith3.3 +atof atof.3 +atoi atof.3 +atol atof.3 +atoll atof.3 +charstod atof.3 +strtod atof.3 +strtol atof.3 +strtoll atof.3 +strtoul atof.3 +strtoull atof.3 +bin bin.3 +binalloc bin.3 +binfree bin.3 +bingrow bin.3 +Bbuffered bio.3 +Bfdopen bio.3 +Bfildes bio.3 +Bflush bio.3 +Bgetc bio.3 +Bgetd bio.3 +Bgetrune bio.3 +Binit bio.3 +Binits bio.3 +Blinelen bio.3 +Boffset bio.3 +Bopen bio.3 +Bprint bio.3 +Bputc bio.3 +Bputrune bio.3 +Brdline bio.3 +Brdstr bio.3 +Bread bio.3 +Bseek bio.3 +Bterm bio.3 +Bungetc bio.3 +Bungetrune bio.3 +Bvprint bio.3 +Bwrite bio.3 +bio bio.3 +bfCBCdecrypt blowfish.3 +bfCBCencrypt blowfish.3 +bfECBdecrypt blowfish.3 +bfECBencrypt blowfish.3 +blowfish blowfish.3 +setupBFstate blowfish.3 +Font cachechars.3 +Fontchar cachechars.3 +Subfont cachechars.3 +agefont cachechars.3 +cachechars cachechars.3 +loadchar cachechars.3 +cleanname cleanname.3 +cmap2rgb color.3 +cmap2rgba color.3 +color color.3 +rgb2cmap color.3 +complete complete.3 +freecompletion complete.3 +cputime cputime.3 +times cputime.3 +asctime ctime.3 +ctime ctime.3 +gmtime ctime.3 +localtime ctime.3 +timezone ctime.3 +tm2sec ctime.3 + +block_cipher des.3 +des des.3 +des3CBCdecrypt des.3 +des3CBCencrypt des.3 +des3ECBdecrypt des.3 +des3ECBencrypt des.3 +des56to64 des.3 +des64to56 des.3 +desCBCdecrypt des.3 +desCBCencrypt des.3 +desECBdecrypt des.3 +desECBencrypt des.3 +des_key_setup des.3 +key_setup des.3 +setupDES3state des.3 +setupDESstate des.3 +triple_block_cipher des.3 +accept dial.3 +announce dial.3 +dial dial.3 +dialparse dial.3 +hangup dial.3 +listen dial.3 +netmkaddr dial.3 +reject dial.3 +dirread dirread.3 +dirreadall dirread.3 +Disk disk.3 +disk disk.3 +opendisk disk.3 +ARROW draw.3 +Image draw.3 +_string draw.3 +arc draw.3 +arcop draw.3 +bezier draw.3 +bezierop draw.3 +bezspline draw.3 +bezsplineop draw.3 +bezsplinepts draw.3 +border draw.3 +draw draw.3 +drawop draw.3 +drawrepl draw.3 +drawreplxy draw.3 +drawsetdebug draw.3 +ellipse draw.3 +ellipseop draw.3 +fillarc draw.3 +fillarcop draw.3 +fillbezier draw.3 +fillbezierop draw.3 +fillbezspline draw.3 +fillbezsplineop draw.3 +fillellipse draw.3 +fillellipseop draw.3 +fillpoly draw.3 +fillpolyop draw.3 +gendraw draw.3 +gendrawop draw.3 +icossin draw.3 +icossin2 draw.3 +line draw.3 +lineop draw.3 +poly draw.3 +polyop draw.3 +replclipr draw.3 +runestring draw.3 +runestringbg draw.3 +runestringbgop draw.3 +runestringn draw.3 +runestringnbg draw.3 +runestringnbgop draw.3 +runestringnop draw.3 +runestringop draw.3 +string draw.3 +stringbg draw.3 +stringbgop draw.3 +stringn draw.3 +stringnbg draw.3 +stringnbgop draw.3 +stringnop draw.3 +stringop draw.3 +dsa dsa.3 +dsagen dsa.3 +dsaprivalloc dsa.3 +dsaprivfree dsa.3 +dsaprivtopub dsa.3 +dsapuballoc dsa.3 +dsapubfree dsa.3 +dsasigalloc dsa.3 +dsasigfree dsa.3 +dsasign dsa.3 +dsaverify dsa.3 +dup dup.3 +egdecrypt elgamal.3 +egencrypt elgamal.3 +eggen elgamal.3 +egprivalloc elgamal.3 +egprivfree elgamal.3 +egprivtopub elgamal.3 +egpuballoc elgamal.3 +egpubfree elgamal.3 +egsigalloc elgamal.3 +egsigfree elgamal.3 +egsign elgamal.3 +egverify elgamal.3 +elgamal elgamal.3 +dec16 encode.3 +dec32 encode.3 +dec64 encode.3 +enc16 encode.3 +enc32 encode.3 +enc64 encode.3 +encode encode.3 +encodefmt encode.3 +errstr errstr.3 +rerrstr errstr.3 +werrstr errstr.3 +Event event.3 +Menu event.3 +Mouse event.3 +eatomouse event.3 +ecankbd event.3 +ecanmouse event.3 +ecanread event.3 +edrawgetrect event.3 +egetrect event.3 +einit event.3 +ekbd event.3 +emenuhit event.3 +emouse event.3 +emoveto event.3 +eread event.3 +ereadmouse event.3 +eresized event.3 +esetcursor event.3 +estart event.3 +estartfn event.3 +etimer event.3 +event event.3 +exec exec.3 +execl exec.3 +_exits exits.3 +atexit exits.3 +atexitdont exits.3 +exits exits.3 +terminate exits.3 +Fcall fcall.3 +convD2M fcall.3 +convM2D fcall.3 +convM2S fcall.3 +convS2M fcall.3 +dirfmt fcall.3 +dirmodefmt fcall.3 +fcall fcall.3 +fcallfmt fcall.3 +read9pmsg fcall.3 +sizeD2M fcall.3 +sizeS2M fcall.3 +statcheck fcall.3 +adler32 flate.3 +blockcrc flate.3 +deflate flate.3 +deflateblock flate.3 +deflateinit flate.3 +deflatezlib flate.3 +deflatezlibblock flate.3 +flate flate.3 +flateerr flate.3 +inflate flate.3 +inflateblock flate.3 +inflateinit flate.3 +inflatezlib flate.3 +inflatezlibblock flate.3 +mkcrctab flate.3 +dofmt fmtinstall.3 +dorfmt fmtinstall.3 +errfmt fmtinstall.3 +fmtfdflush fmtinstall.3 +fmtfdinit fmtinstall.3 +fmtinstall fmtinstall.3 +fmtprint fmtinstall.3 +fmtrune fmtinstall.3 +fmtrunestrcpy fmtinstall.3 +fmtstrcpy fmtinstall.3 +fmtstrflush fmtinstall.3 +fmtstrinit fmtinstall.3 +fmtvprint fmtinstall.3 +runefmtstrflush fmtinstall.3 +runefmtstrinit fmtinstall.3 +frame frame.3 +frcharofpt frame.3 +frclear frame.3 +frdelete frame.3 +frdrawsel frame.3 +frdrawsel0 frame.3 +frgetmouse frame.3 +frinit frame.3 +frinittick frame.3 +frinsert frame.3 +frptofchar frame.3 +frselect frame.3 +frselectpaint frame.3 +frsetrects frame.3 +frtick frame.3 +genrandom genrandom.3 +prng genrandom.3 +get9root get9root.3 +unsharp get9root.3 +getcallerpc getcallerpc.3 +getenv getenv.3 +putenv getenv.3 +getfields getfields.3 +gettokens getfields.3 +tokenize getfields.3 +getns getns.3 +getsnarf getsnarf.3 +putsnarf getsnarf.3 +getuser getuser.3 +sysname getuser.3 +getwd getwd.3 +Cursor graphics.3 +Display graphics.3 +Pfmt graphics.3 +Point graphics.3 +Rectangle graphics.3 +Rfmt graphics.3 +bufimage graphics.3 +buildfont graphics.3 +chantodepth graphics.3 +chantostr graphics.3 +closedisplay graphics.3 +cursorset graphics.3 +cursorswitch graphics.3 +drawerror graphics.3 +flushimage graphics.3 +freefont graphics.3 +gengetwindow graphics.3 +geninitdraw graphics.3 +getdefont graphics.3 +getwindow graphics.3 +graphics graphics.3 +initdisplay graphics.3 +initdraw graphics.3 +lockdisplay graphics.3 +openfont graphics.3 +strtochan graphics.3 +unlockdisplay graphics.3 +dimenkind html.3 +dimenspec html.3 +freedocinfo html.3 +freeitems html.3 +fromStr html.3 +html html.3 +parsehtml html.3 +printitems html.3 +targetid html.3 +targetname html.3 +toStr html.3 +validitems html.3 +Intmap intmap.3 +allocmap intmap.3 +caninsertkey intmap.3 +deletekey intmap.3 +freemap intmap.3 +insertkey intmap.3 +intmap intmap.3 +lookupkey intmap.3 +closeioproc ioproc.3 +iocall ioproc.3 +ioclose ioproc.3 +iodial ioproc.3 +iointerrupt ioproc.3 +ioopen ioproc.3 +ioproc ioproc.3 +ioread ioproc.3 +ioread9pmsg ioproc.3 +ioreadn ioproc.3 +iorecvfd ioproc.3 +iosendfd ioproc.3 +iosleep ioproc.3 +iowrite ioproc.3 +defmask ip.3 +eipfmt ip.3 +equivip ip.3 +hnputl ip.3 +hnputs ip.3 +hnputv ip.3 +ip ip.3 +isv4 ip.3 +maskip ip.3 +myetheraddr ip.3 +myipaddr ip.3 +nhgetl ip.3 +nhgets ip.3 +nhgetv ip.3 +parseether ip.3 +parseip ip.3 +parseipmask ip.3 +ptclbsum ip.3 +readipifc ip.3 +v4parsecidr ip.3 +v4parseip ip.3 +v4tov6 ip.3 +v6tov4 ip.3 +isalpharune isalpharune.3 +islowerrune isalpharune.3 +isspacerune isalpharune.3 +istitlerune isalpharune.3 +isupperrune isalpharune.3 +tolowerrune isalpharune.3 +totitlerune isalpharune.3 +toupperrune isalpharune.3 +closekeyboard keyboard.3 +ctlkeyboard keyboard.3 +initkeyboard keyboard.3 +keyboard keyboard.3 +canlock lock.3 +canqlock lock.3 +canrlock lock.3 +canwlock lock.3 +decref lock.3 +incref lock.3 +lock lock.3 +qlock lock.3 +qunlock lock.3 +rlock lock.3 +rsleep lock.3 +runlock lock.3 +rwakeup lock.3 +rwakeupall lock.3 +unlock lock.3 +wlock lock.3 +wunlock lock.3 +attachargs mach-cmd.3 +attachcore mach-cmd.3 +attachdynamic mach-cmd.3 +attachproc mach-cmd.3 +mach-cmd mach-cmd.3 +proctextfile mach-cmd.3 +crackhdr mach-file.3 +ctlproc mach-file.3 +detachproc mach-file.3 +mach-file mach-file.3 +mapfile mach-file.3 +mapproc mach-file.3 +procnotes mach-file.3 +uncrackhdr mach-file.3 +unmapfile mach-file.3 +unmapproc mach-file.3 +addrtoseg mach-map.3 +addrtosegafter mach-map.3 +addseg mach-map.3 +allocmap mach-map.3 +findseg mach-map.3 +fpformat mach-map.3 +freemap mach-map.3 +get1 mach-map.3 +get2 mach-map.3 +get4 mach-map.3 +get8 mach-map.3 +lget1 mach-map.3 +lget2 mach-map.3 +lget4 mach-map.3 +lget8 mach-map.3 +locaddr mach-map.3 +loccmp mach-map.3 +locconst mach-map.3 +loceval mach-map.3 +locfmt mach-map.3 +locindir mach-map.3 +locnone mach-map.3 +locreg mach-map.3 +locsimplify mach-map.3 +lput1 mach-map.3 +lput2 mach-map.3 +lput4 mach-map.3 +lput8 mach-map.3 +mach-map mach-map.3 +put1 mach-map.3 +put2 mach-map.3 +put4 mach-map.3 +put8 mach-map.3 +removeseg mach-map.3 +rget mach-map.3 +rput mach-map.3 +localaddr mach-stack.3 +mach-stack mach-stack.3 +stacktrace mach-stack.3 +unwindframe mach-stack.3 +windindex mach-stack.3 +windreglocs mach-stack.3 +beieeeftoa32 mach-swap.3 +beieeeftoa64 mach-swap.3 +beieeeftoa80 mach-swap.3 +beload2 mach-swap.3 +beload4 mach-swap.3 +beload8 mach-swap.3 +beswap2 mach-swap.3 +beswap4 mach-swap.3 +beswap8 mach-swap.3 +ieeeftoa32 mach-swap.3 +ieeeftoa64 mach-swap.3 +leieeeftoa32 mach-swap.3 +leieeeftoa64 mach-swap.3 +leieeeftoa80 mach-swap.3 +leload2 mach-swap.3 +leload4 mach-swap.3 +leload8 mach-swap.3 +leswap2 mach-swap.3 +leswap4 mach-swap.3 +leswap8 mach-swap.3 +mach-swap mach-swap.3 +ffindsym mach-symbol.3 +file2pc mach-symbol.3 +fileline mach-symbol.3 +findexsym mach-symbol.3 +findhdr mach-symbol.3 +findlsym mach-symbol.3 +findsym mach-symbol.3 +flookupsym mach-symbol.3 +fnbound mach-symbol.3 +indexlsym mach-symbol.3 +indexsym mach-symbol.3 +line2pc mach-symbol.3 +lookuplsym mach-symbol.3 +lookupsym mach-symbol.3 +mach-symbol mach-symbol.3 +pc2file mach-symbol.3 +pc2line mach-symbol.3 +symclose mach-symbol.3 +symoff mach-symbol.3 +symopen mach-symbol.3 +mach mach.3 +machbyname mach.3 +machbytype mach.3 +calloc malloc.3 +free malloc.3 +getmalloctag malloc.3 +getrealloctag malloc.3 +malloc malloc.3 +mallocz malloc.3 +realloc malloc.3 +setmalloctag malloc.3 +setrealloctag malloc.3 +adjoint matrix.3 +determinant matrix.3 +ident matrix.3 +invertmat matrix.3 +ixform matrix.3 +look matrix.3 +matmul matrix.3 +matmulr matrix.3 +matrix matrix.3 +move matrix.3 +persp matrix.3 +popmat matrix.3 +pushmat matrix.3 +qrot matrix.3 +rot matrix.3 +scale matrix.3 +viewport matrix.3 +xform matrix.3 +xformplane matrix.3 +xformpoint matrix.3 +xformpointd matrix.3 +Memdata memdraw.3 +Memdrawparam memdraw.3 +Memimage memdraw.3 +allocmemimage memdraw.3 +allocmemimaged memdraw.3 +allocmemsubfont memdraw.3 +byteaddr memdraw.3 +cloadmemimage memdraw.3 +creadmemimage memdraw.3 +drawclip memdraw.3 +freememimage memdraw.3 +freememsubfont memdraw.3 +getmemdefont memdraw.3 +hwdraw memdraw.3 +iprint memdraw.3 +loadmemimage memdraw.3 +memarc memdraw.3 +memdraw memdraw.3 +memellipse memdraw.3 +memfillcolor memdraw.3 +memfillpoly memdraw.3 +memimagedraw memdraw.3 +memimageinit memdraw.3 +memimageline memdraw.3 +memimagemove memdraw.3 +memimagestring memdraw.3 +memlinebbox memdraw.3 +memlineendsize memdraw.3 +mempoly memdraw.3 +memsetchan memdraw.3 +memsubfontwidth memdraw.3 +openmemsubfont memdraw.3 +readmemimage memdraw.3 +unloadmemimage memdraw.3 +wordaddr memdraw.3 +writememimage memdraw.3 +memdraw memlayer.3 +memlalloc memlayer.3 +memlayer memlayer.3 +memldelete memlayer.3 +memlexpose memlayer.3 +memlfree memlayer.3 +memlhide memlayer.3 +memline memlayer.3 +memlnorefresh memlayer.3 +memload memlayer.3 +memlorigin memlayer.3 +memlsetrefresh memlayer.3 +memltofront memlayer.3 +memltofrontn memlayer.3 +memltorear memlayer.3 +memltorearn memlayer.3 +memunload memlayer.3 +memccpy memory.3 +memchr memory.3 +memcmp memory.3 +memcpy memory.3 +memmove memory.3 +memory memory.3 +memset memory.3 +closemouse mouse.3 +cursorswitch mouse.3 +drawgetrect mouse.3 +getrect mouse.3 +initmouse mouse.3 +menuhit mouse.3 +mouse mouse.3 +moveto mouse.3 +readmouse mouse.3 +setcursor mouse.3 +mousescrollsize mousescrollsize.3 +betomp mp.3 +crtin mp.3 +crtout mp.3 +crtpre mp.3 +crtprefree mp.3 +crtresfree mp.3 +itomp mp.3 +letomp mp.3 +mp mp.3 +mpadd mp.3 +mpassign mp.3 +mpbits mp.3 +mpcmp mp.3 +mpcopy mp.3 +mpdigdiv mp.3 +mpdiv mp.3 +mpexp mp.3 +mpextendedgcd mp.3 +mpfactorial mp.3 +mpfmt mp.3 +mpfree mp.3 +mpinvert mp.3 +mpleft mp.3 +mplowbits0 mp.3 +mpmagadd mp.3 +mpmagcmp mp.3 +mpmagsub mp.3 +mpmod mp.3 +mpmul mp.3 +mpnew mp.3 +mpnorm mp.3 +mprand mp.3 +mpright mp.3 +mpsetminbits mp.3 +mpsignif mp.3 +mpsub mp.3 +mptoa mp.3 +mptobe mp.3 +mptoi mp.3 +mptole mp.3 +mptoui mp.3 +mptouv mp.3 +mptov mp.3 +mpvecadd mp.3 +mpveccmp mp.3 +mpvecdigmuladd mp.3 +mpvecdigmulsub mp.3 +mpvecmul mp.3 +mpvecsub mp.3 +strtomp mp.3 +uitomp mp.3 +uvtomp mp.3 +vtomp mp.3 +muldiv muldiv.3 +umuldiv muldiv.3 +Mux mux.3 +mux mux.3 +muxinit mux.3 +muxrpc mux.3 +muxthreads mux.3 +Inf nan.3 +NaN nan.3 +isInf nan.3 +isNaN nan.3 +nan nan.3 +needstack needstack.3 +atnotify notify.3 +noted notify.3 +notedisable notify.3 +noteenable notify.3 +notify notify.3 +notifyoff notify.3 +notifyon notify.3 +close open.3 +create open.3 +open open.3 +opentemp opentemp.3 +pipe pipe.3 +Plumbmsg plumb.3 +eplumb plumb.3 +plumb plumb.3 +plumbaddattr plumb.3 +plumbdelattr plumb.3 +plumbfree plumb.3 +plumblookup plumb.3 +plumbopen plumb.3 +plumbopenfid plumb.3 +plumbpack plumb.3 +plumbpackattr plumb.3 +plumbrecv plumb.3 +plumbrecvfid plumb.3 +plumbsend plumb.3 +plumbsendtext plumb.3 +plumbsendtofid plumb.3 +plumbunpack plumb.3 +plumbunpackattr plumb.3 +plumbunpackpartial plumb.3 +post9pservice post9pservice.3 +postnote postnote.3 +DSAprimes prime.3 +genprime prime.3 +gensafeprime prime.3 +genstrongprime prime.3 +prime prime.3 +probably_prime prime.3 +smallprimetest prime.3 +fprint print.3 +print print.3 +runeseprint print.3 +runesmprint print.3 +runesnprint print.3 +runesprint print.3 +runevseprint print.3 +runevsmprint print.3 +runevsnprint print.3 +seprint print.3 +smprint print.3 +snprint print.3 +sprint print.3 +vfprint print.3 +vseprint print.3 +vsmprint print.3 +vsnprint print.3 +proto proto.3 +rdproto proto.3 +freeThumbprints pushtls.3 +initThumbprints pushtls.3 +okThumbprint pushtls.3 +pushtls pushtls.3 +readcert pushtls.3 +readcertchain pushtls.3 +tlsClient pushtls.3 +tlsServer pushtls.3 +qball qball.3 +mtoq quaternion.3 +qadd quaternion.3 +qdiv quaternion.3 +qinv quaternion.3 +qlen quaternion.3 +qmid quaternion.3 +qmul quaternion.3 +qneg quaternion.3 +qsqrt quaternion.3 +qsub quaternion.3 +qtom quaternion.3 +quaternion quaternion.3 +qunit quaternion.3 +slerp quaternion.3 +doquote quote.3 +needsrcquote quote.3 +quote quote.3 +quotefmtinstall quote.3 +quoterunestrdup quote.3 +quoterunestrfmt quote.3 +quotestrdup quote.3 +quotestrfmt quote.3 +unquoterunestrdup quote.3 +unquotestrdup quote.3 +fastrand rand.3 +frand rand.3 +lnrand rand.3 +lrand rand.3 +nfastrand rand.3 +nrand rand.3 +ntruerand rand.3 +rand rand.3 +srand rand.3 +truerand rand.3 +rc4 rc4.3 +rc4back rc4.3 +rc4skip rc4.3 +setupRC4state rc4.3 +pread read.3 +pwrite read.3 +read read.3 +readn read.3 +write read.3 +RGB readcolmap.3 +readcolmap readcolmap.3 +writecolmap readcolmap.3 +regcomp regexp.3 +regcomplit regexp.3 +regcompnl regexp.3 +regerror regexp.3 +regexec regexp.3 +regexp regexp.3 +regsub regexp.3 +rregexec regexp.3 +rregsub regexp.3 +regcomp regexp9.3 +regcomplit regexp9.3 +regcompnl regexp9.3 +regerror regexp9.3 +regexec regexp9.3 +regexp9 regexp9.3 +regsub regexp9.3 +rregexec regexp9.3 +rregsub regexp9.3 +rfork rfork.3 + +X509dump rsa.3 +X509gen rsa.3 +X509req rsa.3 +X509toRSApub rsa.3 +X509verify rsa.3 +asn1dump rsa.3 +asn1toRSApriv rsa.3 +decodepem rsa.3 +decodepemchain rsa.3 +rsa rsa.3 +rsadecrypt rsa.3 +rsaencrypt rsa.3 +rsafill rsa.3 +rsagen rsa.3 +rsaprivalloc rsa.3 +rsaprivfree rsa.3 +rsaprivtopub rsa.3 +rsapuballoc rsa.3 +rsapubfree rsa.3 +chartorune rune.3 +fullrune rune.3 +rune rune.3 +runelen rune.3 +runenlen rune.3 +runetochar rune.3 +utfecpy rune.3 +utflen rune.3 +utfnlen rune.3 +utfrrune rune.3 +utfrune rune.3 +utfutf rune.3 +runestrcat runestrcat.3 +runestrchr runestrcat.3 +runestrcmp runestrcat.3 +runestrcpy runestrcat.3 +runestrdup runestrcat.3 +runestrecpy runestrcat.3 +runestrlen runestrcat.3 +runestrncat runestrcat.3 +runestrncmp runestrcat.3 +runestrncpy runestrcat.3 +runestrrchr runestrcat.3 +runestrstr runestrcat.3 +openscsi scsi.3 +scsi scsi.3 +scsicmd scsi.3 +scsierror scsi.3 +scsiready scsi.3 +hmac_md5 sechash.3 +hmac_sha1 sechash.3 +md4 sechash.3 +md5 sechash.3 +md5pickle sechash.3 +md5unpickle sechash.3 +sechash sechash.3 +sha1 sechash.3 +sha1pickle sechash.3 +sha1unpickle sechash.3 +seek seek.3 +recvfd sendfd.3 +sendfd sendfd.3 +longjmp setjmp.3 +notejmp setjmp.3 +setjmp setjmp.3 +alarm sleep.3 +sleep sleep.3 +dirfstat stat.3 +dirfwstat stat.3 +dirstat stat.3 +dirwstat stat.3 +fstat stat.3 +fwstat stat.3 +nulldir stat.3 +stat stat.3 +wstat stat.3 +cistrcmp strcat.3 +cistrncmp strcat.3 +cistrstr strcat.3 +strcat strcat.3 +strchr strcat.3 +strcmp strcat.3 +strcpy strcat.3 +strcspn strcat.3 +strdup strcat.3 +strecpy strcat.3 +strlen strcat.3 +strncat strcat.3 +strncmp strcat.3 +strncpy strcat.3 +strpbrk strcat.3 +strrchr strcat.3 +strspn strcat.3 +strstr strcat.3 +strtok strcat.3 +s_alloc string.3 +s_allocinstack string.3 +s_append string.3 +s_array string.3 +s_copy string.3 +s_error string.3 +s_free string.3 +s_freeinstack string.3 +s_getline string.3 +s_grow string.3 +s_incref string.3 +s_memappend string.3 +s_nappend string.3 +s_new string.3 +s_newalloc string.3 +s_parse string.3 +s_putc string.3 +s_rdinstack string.3 +s_read string.3 +s_read_line string.3 +s_reset string.3 +s_restart string.3 +s_terminate string.3 +s_tolower string.3 +s_unique string.3 +string string.3 +runestringnwidth stringsize.3 +runestringsize stringsize.3 +runestringwidth stringsize.3 +stringnwidth stringsize.3 +stringsize stringsize.3 +stringwidth stringsize.3 +allocsubfont subfont.3 +freesubfont subfont.3 +installsubfont subfont.3 +lookupsubfont subfont.3 +mkfont subfont.3 +readsubfont subfont.3 +readsubfonti subfont.3 +stringsubfont subfont.3 +strsubfontwidth subfont.3 +subfont subfont.3 +subfontname subfont.3 +uninstallsubfont subfont.3 +writesubfont subfont.3 +sysfatal sysfatal.3 +alt thread.3 +chancreate thread.3 +chanfree thread.3 +chaninit thread.3 +chanprint thread.3 +chansetname thread.3 +mainstacksize thread.3 +nbrecv thread.3 +nbrecvp thread.3 +nbrecvul thread.3 +nbsend thread.3 +nbsendp thread.3 +nbsendul thread.3 +proccreate thread.3 +procdata thread.3 +recv thread.3 +recvp thread.3 +recvul thread.3 +send thread.3 +sendp thread.3 +sendul thread.3 +thread thread.3 +threadcreate thread.3 +threaddata thread.3 +threadexec thread.3 +threadexecl thread.3 +threadexits thread.3 +threadexitsall thread.3 +threadgetgrp thread.3 +threadgetname thread.3 +threadid thread.3 +threadint thread.3 +threadintgrp thread.3 +threadkill thread.3 +threadkillgrp thread.3 +threadlinklibrary thread.3 +threadmain thread.3 +threadnotify thread.3 +threadpid thread.3 +threadsetgrp thread.3 +threadsetname thread.3 +threadsetstate thread.3 +threadspawn thread.3 +threadwaitchan thread.3 +yield thread.3 +nsec time.3 +time time.3 +udpread udpread.3 +udpwrite udpread.3 +await wait.3 +awaitfor wait.3 +awaitnohang wait.3 +wait wait.3 +waitfor wait.3 +waitnohang wait.3 +waitpid wait.3 +drawresizewindow wctl.3 +drawsetlabel wctl.3 +drawtopwindow wctl.3 +wctl wctl.3 +Screen window.3 +allocscreen window.3 +allocwindow window.3 +bottomnwindows window.3 +bottomwindow window.3 +freescreen window.3 +originwindow window.3 +publicscreen window.3 +topnwindows window.3 +topwindow window.3 +window window.3 diff --git a/man/man3/abs.3 b/man/man3/abs.3 deleted file mode 100644 index 46dbd929..00000000 --- a/man/man3/abs.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH ABS 3 -.SH NAME -abs, labs \- integer absolute values -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -int abs(int a) -.PP -.B -long labs(long a) -.SH DESCRIPTION -.I Abs -returns -the absolute value of integer -.IR a , -and -.I labs -does the same for a long. -.SH SOURCE -.B /usr/local/plan9/src/libc/port/abs.c -.SH SEE ALSO -.IR floor (3) -for -.I fabs -.SH DIAGNOSTICS -.I Abs -and -.I labs -return -the most negative integer or long when the true result is unrepresentable. diff --git a/man/man3/allocimage.3 b/man/man3/allocimage.3 index 26365dce..e9da53a5 100644 --- a/man/man3/allocimage.3 +++ b/man/man3/allocimage.3 @@ -148,7 +148,7 @@ The field will be set to the number of bits per pixel specified by the channel descriptor (see -.IR image (6)). +.IR image (7)). .I Allocimage returns 0 if the server has run out of image memory. .PP @@ -214,7 +214,7 @@ values between image and user space or external files. There is a fixed format for the exchange and storage of image data (see -.IR image (6)). +.IR image (7)). .PP .I Unloadimage reads a rectangle of pixels from image @@ -271,7 +271,7 @@ but for bytes of compressed image .I data (see -.IR image (6)). +.IR image (7)). On each call to .IR cloadimage, the @@ -289,7 +289,7 @@ return the number of bytes copied. .PP .I Readimage creates an image from data contained in an external file (see -.IR image (6) +.IR image (7) for the file format); .I fd is a file descriptor obtained by opening such a file for reading. @@ -336,7 +336,7 @@ To allocate a single-pixel replicated image that may be used to paint a region r .IR graphics (3), .IR draw (3), .IR draw (3), -.IR image (6) +.IR image (7) .SH DIAGNOSTICS These functions return pointer 0 or integer \-1 on failure, usually due to insufficient memory. diff --git a/man/man3/arg.3 b/man/man3/arg.3 index 35e5914d..6f7bb929 100644 --- a/man/man3/arg.3 +++ b/man/man3/arg.3 @@ -121,4 +121,4 @@ prog -bffile1 -r -f file2 arg1 arg2 prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2' .PP .SH SOURCE -.B /sys/include/libc.h +.B /usr/local/plan9/include/libc.h diff --git a/man/man3/arith3.3 b/man/man3/arith3.3 new file mode 100644 index 00000000..faba4aa5 --- /dev/null +++ b/man/man3/arith3.3 @@ -0,0 +1,269 @@ +.TH ARITH3 3 +.SH 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 +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +Point3 add3(Point3 a, Point3 b) +.PP +.B +Point3 sub3(Point3 a, Point3 b) +.PP +.B +Point3 neg3(Point3 a) +.PP +.B +Point3 div3(Point3 a, double b) +.PP +.B +Point3 mul3(Point3 a, double b) +.PP +.B +int eqpt3(Point3 p, Point3 q) +.PP +.B +int closept3(Point3 p, Point3 q, double eps) +.PP +.B +double dot3(Point3 p, Point3 q) +.PP +.B +Point3 cross3(Point3 p, Point3 q) +.PP +.B +double len3(Point3 p) +.PP +.B +double dist3(Point3 p, Point3 q) +.PP +.B +Point3 unit3(Point3 p) +.PP +.B +Point3 midpt3(Point3 p, Point3 q) +.PP +.B +Point3 lerp3(Point3 p, Point3 q, double alpha) +.PP +.B +Point3 reflect3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +Point3 nearseg3(Point3 p0, Point3 p1, Point3 testp) +.PP +.B +double pldist3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +double vdiv3(Point3 a, Point3 b) +.PP +.B +Point3 vrem3(Point3 a, Point3 b) +.PP +.B +Point3 pn2f3(Point3 p, Point3 n) +.PP +.B +Point3 ppp2f3(Point3 p0, Point3 p1, Point3 p2) +.PP +.B +Point3 fff2p3(Point3 f0, Point3 f1, Point3 f2) +.PP +.B +Point3 pdiv4(Point3 a) +.PP +.B +Point3 add4(Point3 a, Point3 b) +.PP +.B +Point3 sub4(Point3 a, Point3 b) +.SH DESCRIPTION +These routines do arithmetic on points and planes in affine or projective 3-space. +Type +.B Point3 +is +.IP +.EX +.ta 6n +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +Routines whose names end in +.B 3 +operate on vectors or ordinary points in affine 3-space, represented by their Euclidean +.B (x,y,z) +coordinates. +(They assume +.B w=1 +in their arguments, and set +.B w=1 +in their results.) +.TF reflect3 +.TP +Name +Description +.TP +.B add3 +Add the coordinates of two points. +.TP +.B sub3 +Subtract coordinates of two points. +.TP +.B neg3 +Negate the coordinates of a point. +.TP +.B mul3 +Multiply coordinates by a scalar. +.TP +.B div3 +Divide coordinates by a scalar. +.TP +.B eqpt3 +Test two points for exact equality. +.TP +.B closept3 +Is the distance between two points smaller than +.IR eps ? +.TP +.B dot3 +Dot product. +.TP +.B cross3 +Cross product. +.TP +.B len3 +Distance to the origin. +.TP +.B dist3 +Distance between two points. +.TP +.B unit3 +A unit vector parallel to +.IR p . +.TP +.B midpt3 +The midpoint of line segment +.IR pq . +.TP +.B lerp3 +Linear interpolation between +.I p +and +.IR q . +.TP +.B reflect3 +The reflection of point +.I p +in the segment joining +.I p0 +and +.IR p1 . +.TP +.B nearseg3 +The closest point to +.I testp +on segment +.IR "p0 p1" . +.TP +.B pldist3 +The distance from +.I p +to segment +.IR "p0 p1" . +.TP +.B vdiv3 +Vector divide \(em the length of the component of +.I a +parallel to +.IR b , +in units of the length of +.IR b . +.TP +.B vrem3 +Vector remainder \(em the component of +.I a +perpendicular to +.IR b . +Ignoring roundoff, we have +.BR "eqpt3(add3(mul3(b, vdiv3(a, b)), vrem3(a, b)), a)" . +.PD +.PP +The following routines convert amongst various representations of points +and planes. Planes are represented identically to points, by duality; +a point +.B p +is on a plane +.B q +whenever +.BR 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 +.BR p.w=1 , +we can't make the same assumption for planes. +The names of these routines are extra-cryptic. They contain an +.B f +(for `face') to indicate a plane, +.B p +for a point and +.B n +for a normal vector. +The number +.B 2 +abbreviates the word `to.' +The number +.B 3 +reminds us, as before, that we're dealing with affine points. +Thus +.B pn2f3 +takes a point and a normal vector and returns the corresponding plane. +.TF reflect3 +.TP +Name +Description +.TP +.B pn2f3 +Compute the plane passing through +.I p +with normal +.IR n . +.TP +.B ppp2f3 +Compute the plane passing through three points. +.TP +.B fff2p3 +Compute the intersection point of three planes. +.PD +.PP +The names of the following routines end in +.B 4 +because they operate on points in projective 4-space, +represented by their homogeneous coordinates. +.TP +pdiv4 +Perspective division. Divide +.B p.w +into +.IR p 's +coordinates, converting to affine coordinates. +If +.B p.w +is zero, the result is the same as the argument. +.TP +add4 +Add the coordinates of two points. +.PD +.TP +sub4 +Subtract the coordinates of two points. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry +.SH "SEE ALSO +.IR matrix (3) diff --git a/man/man3/atof.3 b/man/man3/atof.3 index f242036e..f8d7c608 100644 --- a/man/man3/atof.3 +++ b/man/man3/atof.3 @@ -127,7 +127,7 @@ Therefore, it may be necessary to back up the input stream one character after calling .IR charstod . .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR fscanf (3) .SH DIAGNOSTICS diff --git a/man/man3/auth.3 b/man/man3/auth.3 deleted file mode 100644 index 1fe81f97..00000000 --- a/man/man3/auth.3 +++ /dev/null @@ -1,395 +0,0 @@ -.TH AUTH 3 -.SH NAME -amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users -.SH SYNOPSIS -.nf -.PP -.ft L -#include <u.h> -#include <libc.h> -#include <auth.h> -.fi -.ta 11n +4n +4n +4n +4n +4n +4n -.PP -.B -int newns(char *user, char *nsfile); -.PP -.B -int addns(char *user, char *nsfile); -.PP -.B -int amount(int fd, char *old, int flag, char *aname); -.PP -.B -int login(char *user, char *password, char *namespace); -.PP -.B -int noworld(char *user); -.PP -.B -AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey, -.br -.B char *params); -.PP -.B -AuthRpc* auth_allocrpc(int afd); -.PP -.B -void auth_freerpc(AuthRpc *rpc); -.PP -.B -uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n); -.PP -.B -int auth_getkey(char *proto, char *dom); -.PP -.B -int (*amount_getkey)(char*, char*); -.PP -.B -void auth_freeAI(AuthInfo *ai); -.PP -.B -int auth_chuid(AuthInfo *ai, char *ns); -.PP -.B -Chalstate* auth_challenge(char *fmt, ...); -.PP -.B -AuthInfo* auth_response(Chalstate*); -.PP -.B -void auth_freechal(Chalstate*); -.PP -.B -int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* auth_userpasswd(char*user, char*password); -.PP -.B -UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); -.PP -.B -AuthInfo* auth_getinfo(int fd); -.SH DESCRIPTION -.PP -This library, in concert with -.IR factotum (4), -is used to authenticate users. -It provides the primary interface to -.IR factotum . -.PP -.I Newns -builds a name space for -.IR user . -It opens the file -.I nsfile -.RB ( /lib/namespace -is used if -.I nsfile -is null), -copies the old environment, erases the current name space, -sets the environment variables -.B user -and -.BR home , -and interprets the commands in -.IR nsfile . -The format of -.I nsfile -is described in -.IR namespace (6). -.PP -.I Addns -also interprets and executes the commands in -.IR nsfile . -Unlike -.I newns -it applies the command to the current name space -rather than starting from scratch. -.PP -.I Amount -is like -.I mount -but performs any authentication required. -It should be used instead of -.I mount -whenever the file server being mounted requires authentication. -See -.IR bind (3) -for a definition of the arguments to -.I mount -and -.IR amount . -.PP -.I Login -changes the user id of the process -.I user -and recreates the namespace using the file -.I namespace -(default -.BR /lib/nnamespace ). -It uses -.I auth_userpassword -and -.IR auth_chuid . -.PP -.I Noworld -returns 1 if the user is in the group -.B noworld -in -.BR /adm/users . -Otherwise, it returns 0. -.I Noworld -is used by telnetd and ftpd to provide sandboxed -access for some users. -.PP -The following routines use the -.B AuthInfo -structure returned after a successful authentication by -.IR factotum (4). -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct -{ - char *cuid; /* caller id */ - char *suid; /* server id */ - char *cap; /* capability */ - int nsecret; /* length of secret */ - uchar *secret; /* secret */ -} AuthInfo; -.EE -.sp -The fields -.B cuid -and -.B suid -point to the authenticated ids of the client and server. -.B Cap -is a capability returned only to the server. -It can be passed to the -.IR cap (3) -device to change the user id of the process. -.B Secret -is an -.BR nsecret -byte -shared secret that can be used by the client and server to -create encryption and hashing keys for the rest of the -conversation. -.PP -.I Auth_proxy -proxies an authentication conversation between a remote -server reading and writing -.I fd -and a -.I factotum -file. The -.I factotum -file used is -.BR /mnt/factotum/rpc . -An -.B sprint -(see -.IR print (3)) -of -.I fmt -and the variable arg list yields a key template (see -.IR factotum (4)) -specifying the key to use. -The template must specify at least the protocol ( -.BI proto= xxx ) -and the role (either -.B role=client -or -.BR role=server ). -.I Auth_proxy -either returns an allocated -.B AuthInfo -structure, or sets the error string and -returns nil. -.PP -.I Fauth_proxy -can be used instead of -.I auth_proxy -if a single connection to -.I factotum -will be used for multiple authentications. -This is necessary, for example, for -.I newns -which must open the -.I factotum -file before wiping out the namespace. -.I Fauth_proxy -takes as an argument a pointer to an -.B AuthRPC -structure which contains an fd for an open connection to -.I factotum -in addition to storage and state information for -the protocol. -An -.B AuthRPC -structure is obtained by calling -.I auth_allocrpc -with the fd of an open -.I factotum -connection. -It is freed using -.IR auth_freerpc . -Individual commands can be sent to -.IR factotum (4) -by invoking -.IR auth_rpc . -.PP -Both -.I auth_proxy -and -.I fauth_proxy -take a pointer to a routine, -.IR getkey , -to invoke should -.I factotum -not posess a key for the authentication. If -.I getkey -is nil, the authentication fails. -.I Getkey -is called with a key template for the desired -key. -We have provided a generic routine, -.IR auth_getkey , -which queries the user for -the key information and passes it to -.IR factotum . -This is the default for the global variable, -.IR amount_getkey , -which holds a pointer to the key prompting routine used by -.IR amount . -.PP -.I Auth_chuid -uses the -.B cuid -and -.B cap -fields of an -.B AuthInfo -structure to change the user id of the current -process and uses -.IR ns , -default -.BR /lib/namespace , -to build it a new name space. -.PP -.I Auth_challenge -and -.I auth_response -perform challenge/response protocols with -.IR factotum . -State between the challenge and response phase are -kept in the -.B Chalstate -structure: -.sp -.EX -struct Chalstate -{ - char *user; - char chal[MAXCHLEN]; - int nchal; - void *resp; - int nresp; - -/* for implementation only */ - int afd; - AuthRpc *rpc; - char userbuf[MAXNAMELEN]; - int userinchal; -}; -.EE -.sp -.I Auth_challenge -requires a key template generated by an -.B sprint -of -.I fmt -and the variable arguments. It must contain the protocol -(\fBproto=\fIxxx\fR) -and depending on the protocol, the user name ( -.BI user= xxx \fR).\fP -.B P9cr -and -.B vnc -expect the user specified as an attribute in -the key template and -.BR apop , -.BR cram , -and -.BR chap -expect it in the -.B user -field of the arg to -.IR auth_response . -For all protocols, the response is returned -to -.I auth_response -in the -.I resp -field of the -.BR Chalstate . -.I Chalstate.nresp -must be the length of the response. -.PP -Supply to -.I auth_respond -a challenge string and the fmt and args specifying a key, -and it will use -.I factotum -to return the proper user and response. -.PP -.I Auth_userpasswd -verifies a simple user/password pair. -.I Auth_getuserpasswd -retrieves a user/password pair from -.I factotum -if permitted. -.PP -.I Auth_getinfo -reads an -.B AuthInfo -message from -.I fd -and converts it into a structure. It is only -used by the other routines in this library when -communicating with -.IR factotum . -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct UserPasswd { - char *user; - char *passwd; -} UserPasswd; -.EE -.sp -.PP -.I Auth_freeAI -is used to free an -.B AuthInfo -structure returned by one of these routines. -Similary -.I auth_freechal -frees a challenge/response state. -.SH SOURCE -.B /usr/local/plan9/src/libauth -.SH SEE ALSO -.IR factotum (4), -.IR authsrv (3), -.IR bind (3) -.SH DIAGNOSTICS -These routines set -.IR errstr . diff --git a/man/man3/authsrv.3 b/man/man3/authsrv.3 deleted file mode 100644 index c8f3330d..00000000 --- a/man/man3/authsrv.3 +++ /dev/null @@ -1,223 +0,0 @@ -.TH AUTHSRV 3 -.SH NAME -authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers -.SH SYNOPSIS -.nf -.PP -.ft L -#include <u.h> -#include <libc.h> -#include <authsrv.h> -.fi -.ta 8n +4n +4n +4n +4n +4n +4n -.PP -.B -int authdial(char *netroot, char *ad); -.PP -.B -int passtokey(char key[DESKEYLEN], char *password) -.PP -.B -uchar nvcsum(void *mem, int len) -.PP -.B -int readnvram(Nvrsafe *nv, int flag); -.PPP -.B -int convT2M(Ticket *t, char *msg, char *key) -.PP -.B -void convM2T(char *msg, Ticket *t, char *key) -.PP -.B -int convA2M(Authenticator *a, char *msg, char *key) -.PP -.B -void convM2A(char *msg, Authenticator *a, char *key) -.PP -.B -int convTR2M(Ticketreq *tr, char *msg) -.PP -.B -void convM2TR(char *msg, Ticketreq *tr) -.PP -.B -int convPR2M(Passwordreq *pr, char *msg, char *key) -.PP -.B -void convM2PR(char *msg, Passwordreq *pr, char *key) -.PP -.B -int _asgetticket(int fd, char *trbuf, char *tbuf); -.PP -.B -int _asrdresp(int fd, char *buf, int len); -.SH DESCRIPTION -.PP -.I Authdial -dials an authentication server over the -network rooted at -.IR net , -default -.BR /net . -The authentication domain, -.IR ad , -specifies which server to call. -If -.I ad -is non-nil, -the connection server -.B cs -(see -.IR ndb (8)) -is queried for an entry which contains -.B authdom=\fIad\fP -or -.BR dom=\fIad\fP , -the former having precedence, -and which also contains an -.B auth -attribute. -The string dialed is then -.I netroot\fP!\fIserver\fP!ticket -where -.I server -is the value of the -.B auth -attribute. -If no entry is found, the error string is -set to ``no authentication server found'' -and -1 is returned. -If -.I authdom -is nil, the string -.IB netroot !$auth! ticket -is used to make the call. -.PP -.I Passtokey -converts -.I password -into a DES key and stores the result in -.IR key . -It returns 0 if -.I password -could not be converted, -and 1 otherwise. -.PP -.I Readnvram -reads authentication information into the structure: -.EX -.ta 4n +4n +8n +4n +4n +4n +4n - struct Nvrsafe - { - char machkey[DESKEYLEN]; - uchar machsum; - char authkey[DESKEYLEN]; - uchar authsum; - char config[CONFIGLEN]; - uchar configsum; - char authid[ANAMELEN]; - uchar authidsum; - char authdom[DOMLEN]; - uchar authdomsum; - }; -.EE -.PP -On Sparc, MIPS, and SGI machines this information is -in non-volatile ram, accessible in the file -.BR #r/nvram . -On x86s and Alphas -.I readnvram -successively opens the following areas stopping with the -first to succeed: -.PP -\- the partition named by the -.B $nvram -environment variable -(commonly set via -.IR plan9.ini (8)) -.br -\- the partition -.B #S/sdC0/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sdC0/9fat -.br -\- the partition -.B #S/sd00/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sd00/9fat -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 0 -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 1 -.PP -The -.IR nvcsum s -of the fields -.BR machkey , -.BR authid , -and -.B authdom -must match their respective checksum or that field is zeroed. -If -.I flag -is -.B NVwrite -or at least one checksum fails and -.I flag -is -.BR NVwriteonerr , -.I readnvram -will prompt for new values on -.B #c/cons -and then write them back to the storage area. -.PP -.IR ConvT2M , -.IR convA2M , -.IR convTR2M , -and -.I convPR2M -convert tickets, authenticators, ticket requests, and password change request -structures into transmittable messages. -.IR ConvM2T , -.IR convM2A , -.IR convM2TR , -and -.I convM2PR -are used to convert them back. -.I Key -is used for encrypting the message before transmission and decrypting -after reception. -.PP -The routine -.I _asgetresp -receives either a character array or an error string. -On error, it sets errstr and returns -1. If successful, -it returns the number of bytes received. -.PP -The routine -.I _asgetticket -sends a ticket request message and then uses -.I _asgetresp -to recieve an answer. -.SH SOURCE -.B /usr/local/plan9/src/libauthsrv -.SH SEE ALSO -.IR passwd (1), -.IR cons (3), -.IR dial (3), -.IR authsrv (6), -.SH DIAGNOSTICS -These routines set -.IR errstr . -Integer-valued functions return -1 on error. diff --git a/man/man3/bio.3 b/man/man3/bio.3 index 7f6c05f3..8228dada 100644 --- a/man/man3/bio.3 +++ b/man/man3/bio.3 @@ -1,6 +1,6 @@ .TH BIO 3 .SH NAME -Bopen, 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 +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 .SH SYNOPSIS .ta \w'Biobuf* 'u .B #include <u.h> @@ -10,7 +10,10 @@ Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetru .B #include <bio.h> .PP .B -Biobuf* Bopen(char *file, int mode) +Biobuf* Bopen(char *file, int mode) +.PP +.B +Biobuf* Bfdopen(int fd, int mode) .PP .B int Binit(Biobuf *bp, int fd, int mode) @@ -93,6 +96,17 @@ It calls .IR malloc (3) to allocate a buffer. .PP +.I Bfdopen +allocates a buffer for the already-open file descriptor +.I fd +for mode +.B OREAD +or +.BR OWRITE . +It calls +.IR malloc (3) +to allocate a buffer. +.PP .I Binit initializes a standard size buffer, type .IR Biobuf , @@ -312,7 +326,7 @@ written. .IR open (3), .IR print (3), .IR exits (3), -.IR utf (6), +.IR utf (7), .SH DIAGNOSTICS .I Bio routines that return integers yield diff --git a/man/man3/cachechars.3 b/man/man3/cachechars.3 index 46bff616..bb7a475d 100644 --- a/man/man3/cachechars.3 +++ b/man/man3/cachechars.3 @@ -4,7 +4,7 @@ cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities .SH SYNOPSIS .B #include <u.h> .br -.B #include <draw.h> +.B #include <libc.h> .br .B #include <draw.h> .PP @@ -127,7 +127,7 @@ A .B Font consists of an overall height and ascent and a collection of subfonts together with the ranges of runes (see -.IR utf (6)) +.IR utf (7)) they represent. Fonts are described by the following structures. .IP @@ -306,8 +306,8 @@ for replacement when the cache is full. .IR allocimage (3), .IR draw (3), .IR subfont (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)). diff --git a/man/man3/cleanname.3 b/man/man3/cleanname.3 index 27818ef2..5568880e 100644 --- a/man/man3/cleanname.3 +++ b/man/man3/cleanname.3 @@ -29,6 +29,6 @@ Therefore .I filename must contain room for at least two bytes. .SH SOURCE -.B /usr/local/plan9/src/libc/port/cleanname.c +.B /usr/local/plan9/src/lib9/cleanname.c .SH SEE ALSO .IR cleanname (1) diff --git a/man/man3/color.3 b/man/man3/color.3 index 7d772b5e..aac61bd7 100644 --- a/man/man3/color.3 +++ b/man/man3/color.3 @@ -19,7 +19,7 @@ int cmap2rgba(int col) .SH DESCRIPTION These routines convert between `true color' red/green/blue triples and the Plan 9 color map. See -.IR color (6) +.IR color (7) for a description of RGBV, the standard color map. .PP .I Rgb2cmap @@ -52,5 +52,5 @@ take colors as arguments. .IR graphics (3), .IR allocimage (3), .IR draw (3), -.IR image (6), -.IR color (6) +.IR image (7), +.IR color (7) diff --git a/man/man3/complete.3 b/man/man3/complete.3 index b1478ddc..dc74050d 100644 --- a/man/man3/complete.3 +++ b/man/man3/complete.3 @@ -1,6 +1,6 @@ .TH COMPLETE 3 .SH NAME -complete \- file name completion +complete, freecompletion \- file name completion .SH SYNOPSIS .B #include <u.h> .br diff --git a/man/man3/cputime.3 b/man/man3/cputime.3 index 5acf671a..c88340d8 100644 --- a/man/man3/cputime.3 +++ b/man/man3/cputime.3 @@ -24,11 +24,5 @@ child processes in user code, and child processes in system calls. returns the sum of those same times, converted to seconds. .I Times returns the elapsed real time, in milliseconds, that the process has been running. -.PP -These functions read -.BR /dev/cputime , -opening that file when they are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 00000000..ef3ae111 --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,98 @@ +.TH CTIME 3 +.SH NAME +ctime, localtime, gmtime, asctime, tm2sec, timezone \- convert date and time +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.ta \w'\fLchar* 'u +.B +char* ctime(long clock) +.PP +.B +Tm* localtime(long clock) +.PP +.B +Tm* gmtime(long clock) +.PP +.B +char* asctime(Tm *tm) +.PP +.B +long tm2sec(Tm *tm) +.SH DESCRIPTION +.I Ctime +converts a time +.I clock +such as returned by +.IR time (3) +into +.SM ASCII +(sic) +and returns a pointer to a +30-byte string +in the following form. +All the fields have constant width. +.PP +.B + Wed Aug 5 01:07:47 EST 1973\en\e0 +.PP +.I Localtime +and +.I gmtime +return pointers to structures containing +the broken-down time. +.I Localtime +corrects for the time zone and possible daylight savings time; +.I gmtime +converts directly to GMT. +.I Asctime +converts a broken-down time to +.SM ASCII +and returns a pointer +to a 30-byte string. +.IP +.EX +.ta 6n +\w'char 'u +\w'zone[4]; 'u +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; +.EE +.PP +.I Tm2sec +converts a broken-down time to +seconds since the start of the epoch. +It ignores +.BR wday , +and assumes the local time zone +if +.B zone +is not +.BR GMT . +.SH SOURCE +.B /usr/local/plan9/src/lib9/date.c +.br +.B /usr/local/plan9/src/lib9/ctime.c +.SH "SEE ALSO" +.IR date (1), +.IR time (3) +.SH BUGS +The return values point to static data +whose content is overwritten by each call. +.br +Daylight Savings Time is ``normal'' in the Southern hemisphere. +.br +These routines are not equipped to handle non-\c +.SM ASCII +text, and are provincial anyway. diff --git a/man/man3/dial.3 b/man/man3/dial.3 index b26e65c6..51102273 100644 --- a/man/man3/dial.3 +++ b/man/man3/dial.3 @@ -1,6 +1,6 @@ .TH DIAL 3 .SH NAME -dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections +dial, hangup, announce, listen, accept, reject, netmkaddr, dialparse \- make and break network connections .SH SYNOPSIS .B #include <u.h> .br @@ -10,9 +10,6 @@ dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetcon int dial(char *addr, char *local, char *dir, int *cfdp) .PP .B -int hangup(int ctl) -.PP -.B int announce(char *addr, char *dir) .PP .B @@ -26,15 +23,18 @@ int reject(int ctl, char *dir, char *cause) .PP .B char* netmkaddr(char *addr, char *defnet, char *defservice) +.\" .PP +.\" .B +.\" void setnetmtpt(char *to, int tolen, char *from) +.\" .PP +.\" .B +.\" NetConnInfo* getnetconninfo(char *conndir, int fd) +.\" .PP +.\" .B +.\" void freenetconninfo(NetConnINfo*) .PP .B -void setnetmtpt(char *to, int tolen, char *from) -.PP -.B -NetConnInfo* getnetconninfo(char *conndir, int fd) -.PP -.B -void freenetconninfo(NetConnINfo*) +int dialparse(char *addr, char **net, char **unix, u32int *host, int *port) .SH DESCRIPTION For these routines, .I addr @@ -44,8 +44,10 @@ is a network address of the form or simply .IR netaddr . .I Network -is any directory listed in -.B /net +is +.BR tcp , +.BR udp , +.BR unix , or the special token, .BR net . .B Net @@ -53,45 +55,28 @@ is a free variable that stands for any network in common between the source and the host .IR netaddr . .I Netaddr -can be a host name, a domain name, a network address, -or a meta-name of the form -.BI $ attribute\f1, -which -is replaced by -.I value -from the value-attribute pair -.IB attribute = value -most closely associated with the source host in the -network data base (see -.IR ndb (6)). +can be a host name, a domain name, or a network address. +.\" or a meta-name of the form +.\" .BI $ attribute\f1, +.\" which +.\" is replaced by +.\" .I value +.\" from the value-attribute pair +.\" .IB attribute = value +.\" most closely associated with the source host in the +.\" network data base (see +.\" .IR ndb (6)). .PP -If a connection attempt is successful and +On Plan 9, the .I dir -is non-zero, -the path name of a +argument is a path name to a .I line directory -that has files for accessing the connection -is copied into -.IR dir . -The path name is guaranteed to be less than 40 -bytes long. -One line directory exists for each possible connection. -The -.B data -file in the line directory should be used to communicate with the destination. -The -.B ctl -file in the line directory can be used to send commands to the line. -See -.IR ip (3) -for messages that can be written to the -.B ctl -file. -The last close of the -.B data -or -.B ctl -file will close the connection. +that has files for accessing the connection. +To keep the same function signatures, +the Unix port of these routines uses strings of the form +.BI /dev/fd/ n +instead of line directory paths. +These strings should be treated as opaque data and ignored. .PP .I Dial makes a call to destination @@ -111,26 +96,19 @@ file in the line directory. The .B addr file in the line directory contains the address called. -If the network allows the local address to be set, -as is the case with UDP and TCP port numbers, and -.IR local -is non-zero, the local address will be set to -.IR local . -If +.\" If the network allows the local address to be set, +.\" as is the case with UDP and TCP port numbers, and +.\" .IR local +.\" is non-zero, the local address will be set to +.\" .IR local . +.IR Dial 's +.IR local , +.IR dir , +and .I cfdp -is non-zero, -.BI * cfdp -is set to a file descriptor open for reading and -writing the control file. +arguments +are not supported and must be zero. .PP -.I Hangup -is a means of forcing a connection to hang up without -closing the -.B ctl -and -.B data -files. -.P .I Announce and .I listen @@ -181,73 +159,78 @@ 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. .PP -.I Getnetconninfo -returns a structure containing information about a -network connection. The structure is: -.EX - typedef struct NetConnInfo NetConnInfo; - struct NetConnInfo - { - char *dir; /* connection directory */ - char *root; /* network root */ - char *spec; /* binding spec */ - char *lsys; /* local system */ - char *lserv; /* local service */ - char *rsys; /* remote system */ - char *rserv; /* remote service */ - }; -.EE -.PP -The information is obtained from the connection directory, -.IR conndir . -If -.I conndir -is nil, the directory is obtained by performing -.IR fd2path (3) -on -.IR fd . -.I Getnetconninfo -returns either a completely specified structure, or -nil if either the structure can't be allocated or the -network directory can't be determined. -The structure -is freed using -.IR freenetconninfo . -.PP -.I Setnetmtpt -copies the name of the network mount point into -the buffer -.IR to , -whose length is -.IR tolen . -It exists to merge two pre-existing conventions for specifying -the mount point. -Commands that take a network mount point as a parameter -(such as -.BR dns , -.BR cs -(see -.IR ndb (8)), -and -.IR ipconfig (8)) -should now call -.IR setnetmtpt . -If -.I from -is -.BR nil , -the mount point is set to the default, -.BR /net . -If -.I from -points to a string starting with a slash, -the mount point is that path. -Otherwise, the mount point is the string pointed to by -.I from -appended to the string -.BR /net . -The last form is obsolete and is should be avoided. -It exists only to aid in conversion. +.I 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. +.\" .PP +.\" .I Getnetconninfo +.\" returns a structure containing information about a +.\" network connection. The structure is: +.\" .EX +.\" typedef struct NetConnInfo NetConnInfo; +.\" struct NetConnInfo +.\" { +.\" char *dir; /* connection directory */ +.\" char *root; /* network root */ +.\" char *spec; /* binding spec */ +.\" char *lsys; /* local system */ +.\" char *lserv; /* local service */ +.\" char *rsys; /* remote system */ +.\" char *rserv; /* remote service */ +.\" }; +.\" .EE +.\" .PP +.\" The information is obtained from the connection directory, +.\" .IR conndir . +.\" If +.\" .I conndir +.\" is nil, the directory is obtained by performing +.\" .IR fd2path (3) +.\" on +.\" .IR fd . +.\" .I Getnetconninfo +.\" returns either a completely specified structure, or +.\" nil if either the structure can't be allocated or the +.\" network directory can't be determined. +.\" The structure +.\" is freed using +.\" .IR freenetconninfo . +.\" .PP +.\" .I Setnetmtpt +.\" copies the name of the network mount point into +.\" the buffer +.\" .IR to , +.\" whose length is +.\" .IR tolen . +.\" It exists to merge two pre-existing conventions for specifying +.\" the mount point. +.\" Commands that take a network mount point as a parameter +.\" (such as +.\" .BR dns , +.\" .BR cs +.\" (see +.\" .IR ndb (8)), +.\" and +.\" .IR ipconfig (8)) +.\" should now call +.\" .IR setnetmtpt . +.\" If +.\" .I from +.\" is +.\" .BR nil , +.\" the mount point is set to the default, +.\" .BR /net . +.\" If +.\" .I from +.\" points to a string starting with a slash, +.\" the mount point is that path. +.\" Otherwise, the mount point is the string pointed to by +.\" .I from +.\" appended to the string +.\" .BR /net . +.\" The last form is obsolete and is should be avoided. +.\" It exists only to aid in conversion. .SH EXAMPLES Make a call and return an open file descriptor to use for communications: @@ -259,12 +242,13 @@ int callkremvax(void) } .EE .PP -Call the local authentication server: +Connect to a Unix socket served by +.IR acme (4): .IP .EX -int dialauth(char *service) +int dialacme(void) { - return dial(netmkaddr("$auth", 0, service), 0, 0, 0); + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0); } .EE .PP @@ -315,17 +299,14 @@ bekremvax(void) } .EE .SH SOURCE -.BR /usr/local/plan9/src/libc/9sys , -.B /usr/local/plan9/src/libc/port -.SH "SEE ALSO" -.IR auth (3), -.IR ip (3), -.IR ndb (8) +.B /usr/local/plan9/src/lib9/dial.c +.br +.B /usr/local/plan9/src/lib9/announce.c +.br +.B /usr/local/plan9/src/lib9/_p9dialparse.c .SH DIAGNOSTICS .IR Dial , .IR announce , and .I listen return \-1 if they fail. -.I Hangup -returns nonzero if it fails. diff --git a/man/man3/dirread.3 b/man/man3/dirread.3 index 4258509a..ac83edf1 100644 --- a/man/man3/dirread.3 +++ b/man/man3/dirread.3 @@ -62,7 +62,7 @@ always returns complete .B Dir structures. See -.IR read (5) +.IR read (9p) for more information. .PP The constant @@ -83,7 +83,7 @@ structures filled in .BR buf . The file offset is advanced by the number of bytes actually read. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/dirread.c +.B /usr/local/plan9/src/lib9/dirread.c .SH SEE ALSO .IR intro (3), .IR open (3), diff --git a/man/man3/disk.3 b/man/man3/disk.3 new file mode 100644 index 00000000..30e4440a --- /dev/null +++ b/man/man3/disk.3 @@ -0,0 +1,177 @@ +.TH DISK 3 +.SH NAME +opendisk, Disk \- generic disk device interface +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.ft L +typedef struct Disk { + char *prefix; + char part[NAMELEN]; + int fd, wfd, ctlfd, rdonly; + int type; + vlong secs, secsize, size, offset; + int c, h, s; +} Disk; +.ft +.PP +.B +Disk* opendisk(char *file, int rdonly, int noctl) +.SH DESCRIPTION +These routines provide a simple way to gather +and use information about +disks and disk partitions, +as well as plain files. +.PP +.I Opendisk +opens +.I file +for reading and stores the file descriptor in +the +.B fd +field of the +.B Disk +structure. +If +.I rdonly +is not set, +.I opendisk +also opens +.I file +for writing and stores that file descriptor in +.BR wfd . +The two file descriptors are kept separate to +help prevent accidents. +.PP +If +.I noctl +is not set, +.I opendisk +looks for a +.B ctl +file in the same directory as the +disk file; +if it finds one, it declares +the disk to be +an +.I sd +device, +setting the +.B type +field in the +.B Disk +structure +to +.BR Tsd . +If the passed +.I file +is named +.BI fd n disk \fR, +it looks for a file +.BI fd n ctl \fR, +and if it finds that, +declares the disk to be +a floppy disk, of type +.BR Tfloppy . +If either +control +file is found, it is opened for reading +and writing, and the resulting file descriptor +is saved as +.BR ctlfd . +Otherwise the returned disk +has type +.BR Tfile . +.PP +.I Opendisk +then stats the file and stores its length in +.BR size . +If the disk is an +.I sd +partition, +.I opendisk +reads the sector size from the +control +file and stores it in +.BR secsize ; +otherwise the sector size is assumed to be 512, +as is the case for floppy disks. +.I Opendisk +then stores the disk size measured in sectors in +.BR secs . +.PP +If the disk is an +.I sd +partition, +.I opendisk +parses the +control +file to find the partition's offset +within its disk; +otherwise it sets +.B offset +to zero. +If the disk is an ATA disk, +.I opendisk +reads +the disk geometry (number of cylinders, heads, and sectors) +from the +.B geometry +line in the +.I sd +control file; +otherwise it sets these to zero as well. +.B Name +is initialized with the base name of +the disk partition, and is useful for forming messages to the +.I sd +control file. +.B Prefix +is set to the passed filename without +the +.B name +suffix. +.PP +The IBM PC BIOS interface allocates +10 bits for the number of cylinders, 8 for +the number of heads, and 6 for the number of sectors per track. +Disk geometries are not quite so simple +anymore, but to keep the interface useful, +modern disks and BIOSes present geometries +that still fit within these constraints. +These numbers are still used when partitioning +and formatting disks. +.I Opendisk +employs a number of heuristics to discover this +supposed geometry and store it in the +.BR c , +.BR h , +and +.B s +fields. +Disk offsets in partition tables and +in FAT descriptors are stored in a form +dependent upon these numbers, so +.I opendisk +works hard to report numbers that +agree with those used by other operating +systems; the numbers bear little or no resemblance +to reality. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/disk.c +.SH SEE ALSO +Plan 9's +\fIfloppy\fR(3) and \fIsd\fR(3) +.SH BUGS +Disks on Unix systems do not present the interface +that +.I opendisk +expects, so +.I opendisk +will give them type +.BR Tfile . diff --git a/man/man3/draw.3 b/man/man3/draw.3 index 6ad6d375..be5e6c64 100644 --- a/man/man3/draw.3 +++ b/man/man3/draw.3 @@ -1,10 +1,14 @@ .TH DRAW 3 .SH NAME -Image, draw, gendraw, drawreplxy, drawrepl, -replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse, -fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn, -runestring, runestringn, stringbg, stringnbg, runestringbg, -runestringnbg, _string, ARROW, drawsetdebug \- graphics functions +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 .de PB .PP .ft L @@ -252,7 +256,7 @@ The clipping region may be modified dynamically using .TP .B chan The pixel channel format descriptor, as described in -.IR image (6). +.IR image (7). The value should not be modified after the image is created. .TP .B depth @@ -805,8 +809,8 @@ is non-zero. .SH SEE ALSO .IR graphics (3), .IR stringsize (3), -.IR color (6), -.IR utf (6), +.IR color (7), +.IR utf (7), .IR addpt (3) .PP T. Porter, T. Duff. diff --git a/man/man3/dsa.3 b/man/man3/dsa.3 index b1af55e0..f95ca771 100644 --- a/man/man3/dsa.3 +++ b/man/man3/dsa.3 @@ -79,7 +79,9 @@ a key is created using a new and .B q generated by -.IR DSAprimes (3). +.IR DSAprimes +(see +.IR prime (3)). Otherwise, .B p and diff --git a/man/man3/dup.3 b/man/man3/dup.3 index e3cee43b..3c7312d7 100644 --- a/man/man3/dup.3 +++ b/man/man3/dup.3 @@ -25,18 +25,14 @@ will use for the new file descriptor (closing any old file associated with .IR newfd ). -File descriptors are allocated dynamically, -so to prevent unwarranted growth of the file descriptor table, -.I dup -requires that -.I newfd -be no greater than 20 more than the highest file descriptor ever used by -the program. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR intro (3), -.IR dup (3) +.B /usr/local/plan9/src/lib9/dup.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +.I Dup +is a macro for +.I p9dup +to avoid name conflicts with the Unix function; see +.IR intro (3). diff --git a/man/man3/encode.3 b/man/man3/encode.3 index 1a93e37b..44c6afd5 100644 --- a/man/man3/encode.3 +++ b/man/man3/encode.3 @@ -80,6 +80,6 @@ For example, to display a 15 byte array as hex: .EE .SH SOURCE -.B /usr/local/plan9/src/libc/port/u32.c +.B /usr/local/plan9/src/lib9/u32.c .br -.B /usr/local/plan9/src/libc/port/u64.c +.B /usr/local/plan9/src/lib9/u64.c diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 deleted file mode 100644 index 50d00bfb..00000000 --- a/man/man3/encrypt.3 +++ /dev/null @@ -1,76 +0,0 @@ -.TH ENCRYPT 3 -.SH NAME -encrypt, decrypt, netcrypt \- DES encryption -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -int encrypt(void *key, void *data, int len) -.PP -.B -int decrypt(void *key, void *data, int len) -.PP -.B -int netcrypt(void *key, void *data) -.SH DESCRIPTION -.I Encrypt -and -.I decrypt -perform DES encryption and decryption. -.I Key -is an array of -.B DESKEYLEN -(defined as 7 in -.BR <auth.h> ) -bytes containing the encryption key. -.I Data -is an array of -.I len -bytes; -it must be at least 8 bytes long. -The bytes are encrypted or decrypted in place. -.PP -The DES algorithm encrypts an individual 8-byte block of data. -.I Encrypt -uses the following method to encrypt data longer than 8 bytes. -The first 8 bytes are encrypted as usual. -The last byte of the encrypted result -is prefixed to the next 7 unencrypted bytes to make the next 8 -bytes to encrypt. -This is repeated until fewer than 7 bytes remain unencrypted. -Any remaining unencrypted bytes are encrypted with enough of the preceding -encrypted bytes to make a full 8-byte block. -.I Decrypt -uses the inverse algorithm. -.PP -.I Netcrypt -performs the same encryption as a SecureNet Key. -.I Data -points to an -.SM ASCII -string of decimal digits with numeric value between 0 and 10000. -These digits are copied into an 8-byte buffer with trailing binary zero fill -and encrypted as one DES block. -The first four bytes are each formatted as two digit -.SM ASCII -hexadecimal numbers, -and the string is copied into -.IR data . -.SH SOURCE -.B /usr/local/plan9/src/libc/port -.SH DIAGNOSTICS -These routines return 1 if the data was encrypted, -and 0 if the encryption fails. -.I Encrypt -and -.I decrypt -fail if the data passed is less than 8 bytes long. -.I Netcrypt -can fail if it is passed invalid data. -.SH SEE ALSO -.IR securenet (8) -.SH BUGS -The implementation is broken in a way that makes -it unsuitable for anything but authentication. diff --git a/man/man3/errstr.3 b/man/man3/errstr.3 index 1a888978..a0e6d3f0 100644 --- a/man/man3/errstr.3 +++ b/man/man3/errstr.3 @@ -73,13 +73,35 @@ a string to pass to The string returned from .I errstr is discarded. +.PP +The error string is maintained in parallel with the Unix +error number +.IR errno . +Changing +.I errno +will reset the error string, +and changing the error string via +.I errstr +or +.I werrstr +will reset +.IR errno . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/werrstr.c +.B /usr/local/plan9/src/lib9/errstr.c .SH DIAGNOSTICS .I Errstr always returns 0. .SH SEE ALSO .IR intro (3), .IR perror (3) +.SH BUGS +The implementation sets +.I errno +to the (somewhat arbitrary) +constant 0x19283745 when +the error string is valid. +When +.I errno +is set to other values, the error string +is synthesized using +.IR strerror (3). diff --git a/man/man3/event.3 b/man/man3/event.3 index 7982b70a..e0299811 100644 --- a/man/man3/event.3 +++ b/man/man3/event.3 @@ -138,9 +138,9 @@ event mechanism and put in a queue. .I Ekbd returns the next rune from the queue, blocking until the queue is non-empty. -The characters are read in raw mode -(see -.IR cons (3)), +The characters are read in raw mode, +.\" (see +.\" .IR cons (3)), so they are available as soon as a complete rune is typed. .PP When the mouse moves or a mouse button is pressed or released, @@ -380,5 +380,5 @@ is nil, it restores the image to the default arrow. .IR rio (1), .IR graphics (3), .IR plumb (3), -.IR cons (3), +.\" .IR cons (3), .IR draw (3) diff --git a/man/man3/exec.3 b/man/man3/exec.3 index 48868616..285af111 100644 --- a/man/man3/exec.3 +++ b/man/man3/exec.3 @@ -1,6 +1,6 @@ .TH EXEC 3 .SH NAME -exec, execl, _clock, _privates, _nprivates \- execute a file +exec, execl \- execute a file .SH SYNOPSIS .B #include <u.h> .br @@ -12,15 +12,6 @@ int exec(char *name, char* argv[]) .PP .B int execl(char *name, ...) -.PP -.B -long *_clock; -.PP -.B -void **_privates; -.PP -.B -int _nprivates; .fi .SH DESCRIPTION .I Exec @@ -35,10 +26,8 @@ to be executed; it must not be a directory, and the permissions must allow the current user to execute it (see .IR stat (3)). -It should also be a valid binary image, as defined in the -.IR a.out (6) -for the current machine architecture, -or a shell script +It should also be a valid binary image, as defined by the local +operating system, or a shell script (see .IR rc (1)). The first line of a @@ -106,45 +95,17 @@ into the open mode; see .IR open (3)); and the working directory and environment (see -.IR env (3)) +.IR getenv (3)) remain the same. However, a newly .I exec'ed -process has no notification handler +process has no notification handlers (see .IR notify (3)). -.PP -When the new program begins, the global cell -.B _clock -is set to the address of a cell that keeps approximate time -expended by the process at user level. -The time is measured in milliseconds but is updated at -a system-dependent lower rate. -This clock is typically used by the profiler but is available -to all programs. -.PP -The global cell -.B _privates -points to an array of -.B _nprivates -elements of per-process private data. -This storage is private for each process, even if the processes share data segments. -.PP -The above conventions apply to C programs; the raw system -interface to the new image is as follows: -the word pointed to by the stack pointer is -.BR argc ; -the words beyond that are the zeroth and subsequent elements -of -.BR argv , -followed by a terminating null pointer; and -the return register (e.g. -.B R0 -on the 68020) contains the address of the clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/exec.c .br -.B /usr/local/plan9/src/libc/port/execl.c +.B /usr/local/plan9/src/lib9/execl.c .SH SEE ALSO .IR prof (1), .IR intro (3), @@ -157,3 +118,13 @@ There can be no return from a successful or .IR execl ; the calling image is lost. +.SH BUGS +On Unix, unlike on Plan 9, +.I exec +and +.I execl +use the user's current path to locate +.IR prog . +This is a clumsy way to deal with Unix's lack of +a union directory for +.BR /bin . diff --git a/man/man3/exits.3 b/man/man3/exits.3 index 2591ff11..95e2b935 100644 --- a/man/man3/exits.3 +++ b/man/man3/exits.3 @@ -22,7 +22,10 @@ void atexitdont(void(*)(void)) .I Exits is the conventional way to terminate a process. .I _Exits -is the underlying system call. +also terminates a process but does not call the registered +.I atexit +handlers +.RI ( q.v. ). They can never return. .PP @@ -75,7 +78,18 @@ returns 0 if that limit has been reached. .I Atexitdont cancels a previous registration of an exit function. .SH SOURCE -.B /usr/local/plan9/src/libc/port/atexit.c +.B /usr/local/plan9/src/lib9/atexit.c +.br +.B /usr/local/plan9/src/lib9/_exits.c .SH "SEE ALSO" -.IR fork (3), +.IR fork (2), .IR wait (3) +.SH 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. +.PP +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. diff --git a/man/man3/fcall.3 b/man/man3/fcall.3 index 2e09ddac..1143217d 100644 --- a/man/man3/fcall.3 +++ b/man/man3/fcall.3 @@ -303,7 +303,7 @@ and .I buf should include the second two-byte (16-bit) length field that precedes the entry when formatted in a 9P message (see -.IR stat (5)); +.IR stat (9p)); in other words, .I nbuf is 2 plus the sum of the sizes of the entry itself. @@ -349,9 +349,9 @@ multiple times, if necessary, to read an entire 9P message into The return value is 0 for end of file, or -1 for error; it does not return partial messages. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), .IR 9p (3), .IR stat (3), -.IR intro (5) +.IR intro (9p) diff --git a/man/man3/fmtinstall.3 b/man/man3/fmtinstall.3 index cc4884a8..8a437f10 100644 --- a/man/man3/fmtinstall.3 +++ b/man/man3/fmtinstall.3 @@ -297,12 +297,12 @@ 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. -.PP -.IR 2c (1) -describes the C directive -.B #pragma -.B varargck -that can be used to provide type-checking for custom print verbs and output routines. +.\" .PP +.\" .IR 2c (1) +.\" describes the C directive +.\" .B #pragma +.\" .B varargck +.\" that can be used to provide type-checking for custom print verbs and output routines. .SH EXAMPLES This function prints an error message with a variable number of arguments and then quits. @@ -362,10 +362,10 @@ main(...) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/fmt +.B /usr/local/plan9/src/lib9/fmt .SH SEE ALSO .IR print (3), -.IR utf (6), +.IR utf (7), .IR errstr (3) .SH DIAGNOSTICS These routines return negative numbers or nil for errors and set diff --git a/man/man3/fork.3 b/man/man3/fork.3 deleted file mode 100644 index e17f0d67..00000000 --- a/man/man3/fork.3 +++ /dev/null @@ -1,166 +0,0 @@ -.TH FORK 3 -.SH NAME -fork, rfork \- manipulate process resources -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.nf -.B -int fork(void) -.PP -.B -int rfork(int flags) -.fi -.SH DESCRIPTION -Forking is the only way new processes are created. -The -.I flags -argument to -.I rfork -selects which resources of the -invoking process (parent) are shared -by the new process (child) or initialized to -their default values. -The resources include -the file name space, -the open file descriptor table (which, when shared, permits processes -to open and close files for other processes), -the set of environment variables -(see -.IR env (3)), -the note group -(the set of processes that receive notes written to a member's -.B notepg -file; -see -.IR proc (3)), -the set of rendezvous tags -(see -.IR rendezvous (3)); -and open files. -.I Flags -is the logical OR of some subset of -.TF RFCNAMEG -.TP -.B RFPROC -If set a new process is created; otherwise changes affect the -current process. -.TP -.B RFNOWAIT -If set, the child process will be dissociated from the parent. Upon -exit the child will leave no -.B Waitmsg -(see -.IR wait (3)) -for the parent to collect. -.TP -.B RFNAMEG -If set, the new process inherits a copy of the parent's name space; -otherwise the new process shares the parent's name space. -Is mutually exclusive with -.BR RFCNAMEG . -.TP -.B RFCNAMEG -If set, the new process starts with a clean name space. A new -name space must be built from a mount of an open file descriptor. -Is mutually exclusive with -.BR RFNAMEG . -.TP -.B RFNOMNT -If set, subsequent mounts into the new name space and dereferencing -of pathnames starting with -.B # -are disallowed. -.TP -.B RFENVG -If set, the environment variables are copied; -otherwise the two processes share environment variables. -Is mutually exclusive with -.BR RFCENVG . -.TP -.B RFCENVG -If set, the new process starts with an empty environment. -Is mutually exclusive with -.BR RFENVG . -.TP -.B RFNOTEG -Each process is a member of a group of processes that all -receive notes when a note is written to any of their -.B notepg -files (see -.IR proc (3)). -The group of a new process is by default the same as its parent, but if -.B RFNOTEG -is set (regardless of -.BR RFPROC ), -the process becomes the first in a new group, isolated from -previous processes. -.TP -.B RFFDG -If set, the invoker's file descriptor table (see -.IR intro (3)) -is copied; otherwise the two processes share a -single table. -.TP -.B RFCFDG -If set, the new process starts with a clean file descriptor table. -Is mutually exclusive with -.BR RFFDG . -.TP -.B RFREND -If set, the process will be unable to -.IR rendezvous (3) -with any of its ancestors; its children will, however, be able to -.B rendezvous -with it. In effect, -.B RFREND -makes the process the first in a group of processes that share a space for -.B rendezvous -tags. -.TP -.B RFMEM -If set, the child and the parent will share -.B data -and -.B bss -segments. -Otherwise, the child inherits a copy of those segments. -Other segment types, in particular stack segments, will be unaffected. -May be set only with -.BR RFPROC . -.PD -.PP -File descriptors in a shared file descriptor table are kept -open until either they are explicitly closed -or all processes sharing the table exit. -.PP -If -.B 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 -.BR RFPROC , -the return value is zero. -Process ids range from 1 to the maximum integer -.RB ( int ) -value. -.I Rfork -will sleep, if necessary, until required process resources are available. -.PP -.I Fork -is just a call of -.BR rfork(RFFDG|RFREND|RFPROC) . -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/fork.c -.SH SEE ALSO -.IR intro (3), -.IR proc (3), -.SH DIAGNOSTICS -These functions set -.IR errstr . diff --git a/man/man3/genrandom.3 b/man/man3/genrandom.3 index f8952e45..761df867 100644 --- a/man/man3/genrandom.3 +++ b/man/man3/genrandom.3 @@ -16,7 +16,6 @@ void genrandom(uchar *buf, int nbytes) .B void prng(uchar *buf, int nbytes) .SH DESCRIPTION -.PP Most security software requires a source of random or, at the very least, unguessable numbers. .PP diff --git a/man/man3/get9root.3 b/man/man3/get9root.3 new file mode 100644 index 00000000..134f3054 --- /dev/null +++ b/man/man3/get9root.3 @@ -0,0 +1,75 @@ +.TH GET9ROOT 3 +.SH NAME +get9root, unsharp \- get path to root of Plan 9 tree +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +char* get9root(void) +.PP +.B +char* unsharp(char *path) +.SH DESCRIPTION +This tree of Plan 9 software is conventionally installed in +.B /usr/local/plan9 +but may be installed in other places (for example, users without +the ability to write to +.B /usr/local +may with to install it in their own home directories). +The environment variable +.B $PLAN9 +should contain the path to the root. +.I Get9root +returns a static pointer to the pathname of root, first checking +.B $PLAN9 +and defaulting to +.BR /usr/local/plan9 . +.PP +The lack of a fixed location for the Plan 9 tree +makes it difficult to hard-code paths +to files. +.I Unsharp +replaces a leading +.B #9 +in +.I path +with the root of the tree. +.I Unsharp +also replaces a leading +.B #d +with the path to the underlying system's file descriptor dup device, +typically +.BR /dev/fd . +The string returned from +.IR unsharp , +if different from +.IR path , +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +As a convention, programs should never +.I unsharp +paths obtained from user input. +.SH EXAMPLE +The +.IR plumber (4) +uses this code to find unrooted file names included by plumb rules. +.IP +.EX +snprint(buf, sizeof buf, "#9/plumb/%s", name); +fd = open(unsharp(buf), OREAD); +.EE +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4) +.SH BUGS +.I Get9root +could be smarter about finding the tree when +.B $PLAN9 +is not set. diff --git a/man/man3/getcallerpc.3 b/man/man3/getcallerpc.3 index c275fb50..8ad95a36 100644 --- a/man/man3/getcallerpc.3 +++ b/man/man3/getcallerpc.3 @@ -31,7 +31,7 @@ main(int argc, char *argv[]) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/getcallerpc.[cs] +.B /usr/local/plan9/src/lib9/ .SH BUGS The .I firstarg diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 index 315407c6..4be92ece 100644 --- a/man/man3/getenv.3 +++ b/man/man3/getenv.3 @@ -15,10 +15,8 @@ int putenv(char *name, char *val) .fi .SH DESCRIPTION .I Getenv -reads the contents of -.BI /env/ name -(see -.IR env (3)) +fetches the environment value associated with +.I name into memory allocated with .IR malloc (3), 0-terminates it, @@ -27,18 +25,18 @@ If no file exists, 0 is returned. .PP .I Putenv -creates the file -.BI /env/ name -and writes the string -.I val -to it. The terminating -.B 0 -is not written. -If the file value cannot be written, \-1 is returned. +sets the environment value associated with +.I name +to +.IR val . .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR env (3) +.B /usr/local/plan9/src/lib9/getenv.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +Defined as macros for +.I p9getenv +and +.I p9putenv +to avoid name conflicts with Unix library calls. diff --git a/man/man3/getfields.3 b/man/man3/getfields.3 index e39c775b..78052906 100644 --- a/man/man3/getfields.3 +++ b/man/man3/getfields.3 @@ -87,7 +87,7 @@ with .I delims set to \f5"\et\er\en "\fP. .SH SOURCE -.B /usr/local/plan9/src/libc/port/tokenize.c +.B /usr/local/plan9/src/lib9/tokenize.c .SH SEE ALSO .I strtok in diff --git a/man/man3/getns.3 b/man/man3/getns.3 new file mode 100644 index 00000000..cc76f2bf --- /dev/null +++ b/man/man3/getns.3 @@ -0,0 +1,22 @@ +.TH GETNS 3 +.SH NAME +getns \- get path to name space directory +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +char* getns(void) +.SH DESCRIPTION +.I 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 +.IR intro (4) +for details. +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4) diff --git a/man/man3/getpid.3 b/man/man3/getpid.3 deleted file mode 100644 index 44837f69..00000000 --- a/man/man3/getpid.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH GETPID 3 -.SH NAME -getpid, getppid \- get process ids -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -int getpid(void) -.PP -.B -int getppid(void) -.SH DESCRIPTION -.I Getpid -reads -.B /dev/pid -(see -.IR cons (3)) -and converts it to get the process id of the current process, -a number guaranteed to be unique among all running processes on the machine -executing -.IR getpid . -.PP -.I Getppid -reads -.B /dev/ppid -(see -.IR cons (3)) -and converts it to get the id of the parent of the current process. -.SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR intro (3), -.IR cons (3), -.IR proc (3) -.SH DIAGNOSTICS -Returns 0 and -sets -.I errstr -if unsuccessful. diff --git a/man/man3/getsnarf.3 b/man/man3/getsnarf.3 new file mode 100644 index 00000000..a90d5950 --- /dev/null +++ b/man/man3/getsnarf.3 @@ -0,0 +1,37 @@ +.TH GETSNARF 3 +.SH NAME +getsnarf, putsnarf \- window system snarf (cut and paste) buffer +.SH SYNOPSIS +.B #include <draw.h> +.PP +.B +char *getsnarf(void) +.PP +.B +void putsnarf(char *text) +.SH DESCRIPTION +.I Getsnarf +and +.I putsnarf +access the window system's snarf (cut and paste) buffer. +.PP +.I Getsnarf +returns a copy of the current buffer; +the returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Putsnarf +sets the buffer to the text string +.IR text . +.PP +Callers should assume that the snarf buffer is UTF. +If the window system does not keep the buffer in UTF, +.I getsnarf +and +.I putsnarf +will convert as necessary. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-itrans.c diff --git a/man/man3/getuser.3 b/man/man3/getuser.3 index e09c4a49..a7ada46f 100644 --- a/man/man3/getuser.3 +++ b/man/man3/getuser.3 @@ -18,20 +18,35 @@ null-terminated name of the user who owns the current process. .I Getuser -reads -.B /dev/user -to find the name. +calls +.IR getuid (2) +and then reads +.B /etc/passwd +to find the corresponding name. .PP .I Sysname -provides the same service for the file -.BR #c/sysname , -which contains the name of the machine. +returns a pointer to static data which contains the name +of the machine on which the current process is running. +.I Sysname +looks first for an environment variable +.BR $sysname . +If there is no such variable, +.I sysname +calls +.IR gethostname (2) +and truncates the returned name at the first dot. +If +.I gethostname +fails, +.I sysname +returns the default name +.LR gnot . +.PP Unlike .IR getuser , .I sysname -caches the string, reading the file only once. +caches the string, deriving the host name only once. .SH SOURCE -.B /usr/local/plan9/src/libc/port/getuser.c -.SH SEE ALSO -.IR intro (3), -.IR cons (3) +.B /usr/local/plan9/src/lib9/getuser.c +.br +.B /usr/local/plan9/src/lib9/sysname.c diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 index 6b053fda..d9aa02b1 100644 --- a/man/man3/getwd.3 +++ b/man/man3/getwd.3 @@ -21,17 +21,10 @@ places no more than .I size bytes in the buffer provided. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/getwd.c +.B /usr/local/plan9/src/lib9/getwd.c .SH "SEE ALSO" .IR pwd (1), -.IR fd2path (3) .SH DIAGNOSTICS On error, zero is returned. .IR Errstr (3) may be consulted for more information. -.SH BUGS -Although the name returned by -.I getwd -is guaranteed to be the path used to reach the directory, -if the name space has changed underfoot, the name may be -incorrect. diff --git a/man/man3/graphics.3 b/man/man3/graphics.3 index 68245377..971303e9 100644 --- a/man/man3/graphics.3 +++ b/man/man3/graphics.3 @@ -189,7 +189,7 @@ data structure is defined in A .B Font is a set of character images, indexed by runes (see -.IR utf (6)). +.IR utf (7)). The images are organized into .BR Subfonts , each containing the images for a small, contiguous set of runes. @@ -376,24 +376,24 @@ specifies the refresh function to be used to create the window, if running under .IR rio (1) (see .IR window (3)). -.PP -The function -.I newwindow -may be called before -.I initdraw -or -.IR geninitdraw -to cause the program to occupy a newly created window rather than take over the one in -which it is running when it starts. -The -.I str -argument, if non-null, is concatenated to the string \f5\&"new\ "\fP -that is used to create the window (see -.IR rio (4)). -For example, -.B newwindow("-hide -dy 100") -will cause the program to run in a newly created, hidden window -100 pixels high. +.\" .PP +.\" The function +.\" .I newwindow +.\" may be called before +.\" .I initdraw +.\" or +.\" .IR geninitdraw +.\" to cause the program to occupy a newly created window rather than take over the one in +.\" which it is running when it starts. +.\" The +.\" .I str +.\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP +.\" that is used to create the window (see +.\" .IR rio (4)). +.\" For example, +.\" .B newwindow("-hide -dy 100") +.\" will cause the program to run in a newly created, hidden window +.\" 100 pixels high. .PP .I Initdisplay is part of @@ -484,15 +484,15 @@ point to the portion of the window inside the border; sophisticated clients may use .B _screen to make further subwindows. -Programs desiring multiple independent windows -may use the mechanisms of -.IR rio (4) -to create more windows (usually by a fresh mount of the window sytem -in a directory other than -.BR /dev ), -then use -.I gengetwindow -to connect to them. +.\" Programs desiring multiple independent windows +.\" may use the mechanisms of +.\" .IR rio (4) +.\" to create more windows (usually by a fresh mount of the window sytem +.\" in a directory other than +.\" .BR /dev ), +.\" then use +.\" .I gengetwindow +.\" to connect to them. .IR Gengetwindow 's extra arguments are the full path of the window's .B winname @@ -552,7 +552,7 @@ and .I chantostr convert between the channel descriptor strings used by -.IR image (6) +.IR image (7) and the internal .B ulong representation @@ -630,9 +630,9 @@ if(gengetwindow(display, "/tmp/winname", .IR print (3), .IR window (3), .IR draw (3), -.IR rio (4), -.IR image (6), -.IR font (6) +.\" .IR rio (4), +.IR image (7), +.IR font (7) .SH DIAGNOSTICS An error function may call .IR errstr (3) diff --git a/man/man3/ioproc.3 b/man/man3/ioproc.3 index ae21758e..5c3ebda4 100644 --- a/man/man3/ioproc.3 +++ b/man/man3/ioproc.3 @@ -8,7 +8,11 @@ iodial, ioopen, ioproc, ioread, +ioread9pmsg, ioreadn, +iorecvfd, +iosendfd, +iosleep, iowrite \- slave I/O processes for threaded programs .SH SYNOPSIS .PP @@ -26,12 +30,16 @@ typedef struct Ioproc Ioproc; .sp Ioproc* ioproc(void); .XX -int ioopen(Ioproc *io, char *file, int omode); 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); -int iodial(Ioproc *io, char *addr, char *local, char *dir, char *cdfp); .XX void iointerrupt(Ioproc *io); void closeioproc(Ioproc *io); @@ -58,20 +66,28 @@ if either fails, it calls .I sysfatal rather than return an error. .PP -.IR Ioopen , -.IR ioclose , +.IR Ioclose , +.IR iodial , +.IR ioopen , .IR ioread , +.IR ioread9pmsg , .IR ioreadn , -.IR iowrite , +.IR iorecvfd , +.IR iosendfd , +.IR iosleep , and -.IR iodial -are execute the +.I iowrite +execute the similarly named library or system calls (see +.IR close (2), +.IR dial (3), .IR open (3), .IR read (3), +.IR fcall (3), +.IR sendfd (3), and -.IR dial (3)) +.IR sleep (3)) in the slave process associated with .IR io . It is an error to execute more than one call @@ -144,7 +160,6 @@ instances were running in different procs, the common access to .I tot would be unsafe. -.EE .PP Implement .IR ioread : @@ -170,10 +185,12 @@ ioread(Ioproc *io, int fd, void *a, long n) } .EE .SH SOURCE -.B /usr/local/plan9/src/libthread/io*.c +.B /usr/local/plan9/src/libthread .SH SEE ALSO .IR dial (3), .IR open (3), .IR read (3), .IR thread (3) - +.SH BUGS +.I Iointerrupt +is currently unimplemented. diff --git a/man/man3/ip.3 b/man/man3/ip.3 index b133adf8..c31c294f 100644 --- a/man/man3/ip.3 +++ b/man/man3/ip.3 @@ -1,6 +1,6 @@ .TH IP 3 .SH NAME -eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc \- Internet protocol +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, readipifc \- Internet protocol .SH SYNOPSIS .B #include <u.h> .br @@ -57,12 +57,18 @@ ushort nhgets(void *p) uint nhgetl(void *p) .PP .B +uvlong nhgetv(void *p) +.PP +.B void hnputs(void *p, ushort v) .PP .B void hnputl(void *p, uint v) .PP .B +void hnputv(void *p, uvlong v) +.PP +.B ushort ptclbsum(uchar *a, int n) .PP .B @@ -211,14 +217,16 @@ converts the V6 address, to a V4 address and puts the result in .IR v4ip . .PP -.I Hnputs +.IR Hnputs , +.IR hnputl , and -.I hnputl -are used to store 16-bit and 32-bit integers into IP big-endian form. -.I Nhgets +.I hnputv +are used to store 16-, 32-, and 64-bit integers into IP big-endian form. +.IR Nhgets , +.IR nhgetl , and -.I nhgetl -convert big-endian 2 and 4 byte quantities into integers. +.I nhgetv +convert big-endian 2-, 4-, and 8-byte quantities into integers. .PP .I Pctlbsum returns the one's complement checksum used in IP protocols, typically invoked as diff --git a/man/man3/isalpharune.3 b/man/man3/isalpharune.3 index 07d99554..78bc4e63 100644 --- a/man/man3/isalpharune.3 +++ b/man/man3/isalpharune.3 @@ -35,7 +35,7 @@ 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 -.IR ctype (3) +.IR isalpha (3) for .SM ASCII\c , @@ -45,7 +45,7 @@ The names are self-explanatory. .PP The case-conversion routines return the character unchanged if it has no case. .SH SOURCE -.B /usr/local/plan9/src/libc/port/runetype.c +.B /usr/local/plan9/src/lib9/utf/runetype.c .SH "SEE ALSO -.IR ctype (3) , +.IR isalpha (3) , .IR "The Unicode Standard" . diff --git a/man/man3/keyboard.3 b/man/man3/keyboard.3 index b90f18b6..f341e50e 100644 --- a/man/man3/keyboard.3 +++ b/man/man3/keyboard.3 @@ -53,16 +53,8 @@ struct Keyboardctl .PP The argument to .I initkeyboard -is a -.I file -naming the device file from which characters may be read, -typically -.BR /dev/cons . -If -.I file -is nil, -.B /dev/cons -is assumed. +is ignored +(on Plan 9, it is the name of the keyboard device). .PP Once the .B Keyboardctl @@ -75,9 +67,9 @@ will be sent on the to report each character read from the device. .PP .I Ctlkeyboard -is used to set the state of the interface, typically to turn raw mode on and off -(see -.IR cons (3)). +is used to set the state of the interface, typically to turn raw mode on and off. +.\" (see +.\" .IR cons (3)). It writes the string .I msg to the control file associated with the device, which is assumed to be the regular device file name diff --git a/man/man3/lock.3 b/man/man3/lock.3 index d989d18c..9034229d 100644 --- a/man/man3/lock.3 +++ b/man/man3/lock.3 @@ -72,22 +72,16 @@ are spin locks, .B QLocks and .B RWLocks -are different types of queueing rendezvous locks, +are different types of queueing locks, and .B Rendezes are rendezvous points. .PP -Locks and rendezvous points work in regular programs as -well as programs that use the thread library +Locks and rendezvous points have trivial implementations in programs +not using the thread library (see -.IR thread (3)). -The thread library replaces the -.IR rendezvous (3) -system call -with its own implementation, -.IR threadrendezvous , -so that threads as well as processes may be synchronized by locking calls -in threaded programs. +.IR thread (3)), +since such programs have no concurrency. .PP Used carelessly, spin locks can be expensive and can easily generate deadlocks. Their use is discouraged, especially in programs that use the @@ -105,7 +99,7 @@ releases a lock. .B QLocks have the same interface but are not spin locks; instead if the lock is taken .I qlock -will suspend execution of the calling task until it is released. +will suspend execution of the calling thread until it is released. .PP Although .B Locks @@ -199,18 +193,39 @@ atomically decrements the .B Ref and returns zero if the resulting value is zero, non-zero otherwise. .SH SOURCE -.B /usr/local/plan9/src/libc/port/lock.c +.B /usr/local/plan9/src/lib9/qlock.c .br -.B /usr/local/plan9/src/libc/9sys/qlock.c -.br -.B /usr/local/plan9/src/libthread/ref.c -.SH SEE ALSO -.I rfork -in -.IR fork (3) +.B /usr/local/plan9/src/libthread .SH BUGS .B Locks -are not strictly spin locks. +are not always spin locks. +Instead they are usually implemented using the +.I pthreads +library's +.BR pthread_mutex_t , +whose implementation method is not defined. +.PP +On +.IR pthreads -based +systems, the implementation of +.B Lock +never calls +.I pthread_mutex_destroy +to free the +.BR pthread_mutex_t 's. +This leads to resource leaks on FreeBSD 5 +(though not on Linux 2.6, where +.I pthread_mutex_destroy +is a no-op). +.BR +.PP +On systems that do not have a usable +.I pthreads +implementation, the +.B Lock +implementation provided by +.I libthread +is still not exactly a spin lock. After each unsuccessful attempt, .I lock calls diff --git a/man/man3/mach-cmd.3 b/man/man3/mach-cmd.3 new file mode 100644 index 00000000..202ca395 --- /dev/null +++ b/man/man3/mach-cmd.3 @@ -0,0 +1,141 @@ +.TH MACH-CMD 3 +.SH NAME +attachargs, attachcore, attachdynamic, attachproc, proctextfile \- debugging processes and core files +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <mach.h> +.PP +.ta +\w'\fLextern 'u +\w'\fLchar *'u +.B +int attachcore(Fhdr *hdr) +.PP +.B +int attachproc(int pid) +.PP +.B +int attachdynamic(void) +.PP +.B +char* proctextfile(int pid) +.PP +.B +int attachargs(int argc, char **argv, int omode) +.PP +.B +.nf +extern Fhdr* symhdr; +extern char* symfil; +extern Map* symmap; +extern Fhdr* fhdrlist; +.ift .sp .5 +.ifn .sp +extern Fhdr* corhdr; +extern char* corfil; +extern Map* cormap; +.ift .sp .5 +.ifn .sp +extern int corpid; +extern Regs* correg; +.SH 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. +.PP +The maintained state is: +.TP +.I symhdr +The file header for the main binary. +.TP +.I symfil +The file name of the main binary. +.TP +.I symmap +The memory map of the main binary. +.TP +.I fhdrlist +A linked list (via the +.B Fhdr.next +fields) of all currently open headers +(see +.I symopen +in +.IR mach-symbol (3)). +When dynamically linked objects have been attached, +they are present in this linked list, +and therefore included in searches by +.IR indexsym , +.IR lookupsym , +and +.I findsym +(see +.IR mach-symbol (3)). +.TP +.I corhdr +The file header for the core dump, if any. +.TP +.I corfil +The file name of the core dump, if any. +.TP +.I cormap +The memory map of the core dump or attached process. +.TP +.I corpid +The process id of the attached process, if any. +.TP +.I correg +The register set of the core dump or attached process. +.PD +If these fields are not valid, they are zeroed. +.PP +.I Attachcore +and +.I attachproc +attach to an opened core file or an executing process. +They set +.IR corhdr , +.IR corfil , +.IR cormap , +.IR corpid , +and +.IR correg . +.PP +.I Proctextfile +returns the name of the main binary for the process with id +.IR pid . +.PP +.I 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. +.PP +.I Attachargs +uses all of these functions while +parsing an argument vector as would be passed to +a debugger like +.IR db (1) +or +.IR 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), +.I attachargs +fills them in as best it can. +.SH SOURCE +.B /usr/local/plan9/src/libmach +.SH "SEE ALSO +.IR mach (3), +.IR mach-file (3), +.IR mach-map (3) +.SH BUGS +The interface needs to be changed to support +multiple threads, each with its own register set. diff --git a/man/man3/mach-file.3 b/man/man3/mach-file.3 index f235815e..17911ec1 100644 --- a/man/man3/mach-file.3 +++ b/man/man3/mach-file.3 @@ -1,6 +1,6 @@ .TH MACH-FILE 3 .SH NAME -crackhdr, uncrackhdr, mapfile, mapproc, detachproc, ctlproc, +crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc, procnotes \- machine-independent access to exectuable files and running processes .SH SYNOPSIS .B #include <u.h> @@ -16,9 +16,13 @@ int crackhdr(int fd, Fhdr *hdr) void uncrackhdr(Fhdr *hdr) .PP .ft B -int mapfile(Map *map, ulong base, Fhdr *hdr) +int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs) .br -int mapproc(Map *map, int pid) +void unmapfile(Fhdr *hdr, Map *map) +.br +int mapproc(int pid, Map *map, Regs **regs) +.br +void unmapproc(Map *map) .br int detachproc(int pid) .br @@ -95,6 +99,12 @@ 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. .PP +.I Unmapfile +removes the mappings in +.I map +corresponding to +.IR hdr . +.PP .I Mapproc attaches to a running program and adds its segments to the given map. It adds one segment for each contiguous section of @@ -103,8 +113,14 @@ 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. +.PP +.I Unmapproc +removes the mappings in +.I map +corresponding to +.IR pid . .I Detachproc -detaches from a previously-attached program. +detaches from all previously attached processes. .PP .I Ctlproc manipulates the process with id @@ -143,7 +159,9 @@ returns the number of pending notes. The memory at .BI * notes should be freed via -.IR free (3) +.I free +(see +.IR malloc (3)) when no longer needed. .SH SOURCE .B /usr/local/plan9/src/libmach diff --git a/man/man3/mach-map.3 b/man/man3/mach-map.3 index 8175e138..2fc8cc72 100644 --- a/man/man3/mach-map.3 +++ b/man/man3/mach-map.3 @@ -4,10 +4,9 @@ allocmap, addseg, findseg, addrtoseg, addrtosegafter, removeseg, freemap, get1, get2, get4, get8, put1, put2, put4, put8, -rget1, rget2, rget4, rget8, -rput1, rput2, rput4, rput8, -locaddr, locconst, locreg, locindir, -loccmp, loceval, locfmt, locredir, +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 @@ -80,26 +79,16 @@ int put4(Map *map, ulong addr, u32int u) int put8(Map *map, ulong addr, u64int u) .PP .ft B -int rget1(Map *map, char *reg, u8int *u) -.br -int rget2(Map *map, char *reg, u16int *u) -.br -int rget4(Map *map, char *reg, u32int *u) -.br -int rget8(Map *map, char *reg, u64int *u) +int rget(Regs *regs, char *reg, ulong *u) .br int fpformat(Map *map, char *reg, char *a, uint n, char code); .PP .ft B -int rput1(Map *map, char *reg, u8int u) -.br -int rput2(Map *map, char *reg, u16int u) -.br -int rput4(Map *map, char *reg, u32int u) -.br -int rput8(Map *map, char *reg, u64int u) +int rput(Regs *regs, char *name, ulong u) .PP .ft B +Loc locnone(void) +.br Loc locaddr(ulong addr) .br Loc locconst(ulong con) @@ -115,7 +104,7 @@ int loceval(Map *map, Loc loc, ulong *addr) .br int locfmt(Fmt *fmt) .br -int locredir(Map *map, Loc *regs, Loc loc, Loc *newloc) +int locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc) .PP .ft B int lget1(Map *map, Loc loc, uchar *a, uint n) @@ -297,20 +286,15 @@ A \-1 return value indicates an error. .PP When representing core files or running programs, maps also provide access to the register set. -.IR Rget1 , -.IR rget2 , -.IR rget4 , -.IR rget8 , -.IR rput1 , -.IR rput2 , -.IR rput4 , -and -.IR rput8 -read or write the 1-, 2-, 4-, or 8-byte register +.IR Rget +and +.IR rput +read or write the register named by .IR reg . -If the register is not the requested size, the -behavior is undefined. +If the register is smaller than a +.BR ulong , +the high bits are ignored. .PP .I Fpformat converts the contents of a floating-point register to a string. @@ -418,3 +402,8 @@ function families as necessary. .SH DIAGNOSTICS These routines set .IR errstr . +.SH BUGS +This man page needs to describe +.B Regs +and +.B Regdesc diff --git a/man/man3/mach-stack.3 b/man/man3/mach-stack.3 index e17c6cb0..caae6bf8 100644 --- a/man/man3/mach-stack.3 +++ b/man/man3/mach-stack.3 @@ -1,7 +1,6 @@ .TH MACH-STACK 3 .SH NAME -stacktrace, -localaddr, +stacktrace, localaddr, unwindframe, windindex, windreglocs \- stack traces .SH SYNOPSIS .B #include <u.h> .br @@ -14,7 +13,16 @@ localaddr, int stacktrace(Map *map, Rgetter rget, Tracer trace) .PP .ft B -int localvar(Map *map, char *fn, char *val, Loc *loc) +int localaddr(Map *map, Regs *regs, char *fn, char *val, ulong *val) +.PP +.ft B +int unwindframe(Map *map, Regs *regs, ulong *next, Symbol *sym) +.PP +.ft B +int windindex(char *regname) +.PP +.ft B +Loc* windreglocs(void) .SH DESCRIPTION .I Stacktrace provides machine-independent @@ -80,7 +88,7 @@ is as an argument to .IR lget4 , etc., when evaluating the locations of local variables. .PP -.I Localvar +.I Localaddr uses .I stacktrace to walk up the stack looking for the innermost instance of a function named @@ -88,8 +96,46 @@ to walk up the stack looking for the innermost instance of a function named once it finds the function, it looks for the parameter or local variable .IR var , -storing the location of the variable in -.IR loc . +storing the address of the variable in +.IR val . +.PP +.I Unwindframe +is the low-level function on which +.I stacktrace +is built. +Given the current memory image in +.I map +and the current register set in +.I regs , +.I unwindframe +fills in +.I next +with the values of the register set +at the time of the call to the function in the current program counter. +.I Sym +should be the symbol corresponding to the current function, +if available. +.PP +The +.I next +array holds only the +.IR "winding registers" , +typically the caller-save registers and the program counter and stack pointer. +The order of registers in the array is called the +.IR "winding order" . +The winding set can be found in the array +.IB mach -> windreg \fR, +which has +.IB mach -> nwindreg +entries. +.I Windindex +returns the index of the named register +in the winding order. +.I Windreglocs +returns an array of +.I Loc +structures corresponding to the winding registers, +in the winding order. .SH EXAMPLE The following code writes a simple stack trace to standard output, stopping after at most 20 stack frames. @@ -135,3 +181,5 @@ trace(Map *map, ulong pc, ulong callerpc, .B /usr/local/plan9/src/libmach .SH SEE ALSO .IR mach (3) +.SH BUGS +Need to talk about Regs diff --git a/man/man3/mach-symbol.3 b/man/man3/mach-symbol.3 index ad208ce0..c74ae8e5 100644 --- a/man/man3/mach-symbol.3 +++ b/man/man3/mach-symbol.3 @@ -1,6 +1,7 @@ .TH MACH-SYMBOL 3 .SH NAME -symopen, symclose, indexsym, lookupsym, findsym, +symopen, symclose, findhdr, indexsym, lookupsym, findsym, +findexsym, flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, pc2file, file2pc, line2pc, fnbound, fileline, pc2line \- symbol table access functions @@ -11,11 +12,15 @@ pc2line \- symbol table access functions .br .B #include <mach.h> .PP -.ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u +.ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u .ft B int symopen(Fhdr *hdr) .br void symclose(Fhdr *hdr) +.br +Fhdr *findhdr(char *name) +.br +extern Fhdr* fhdrlist; .PP .ft B int indexsym(uint n, Symbol *s) @@ -25,6 +30,13 @@ int lookupsym(char *fn, char *var, Symbol *s) int findsym(Loc loc, uint class, Symbol *s) .PP .ft B +int findexsym(Fhdr *hdr, uint n, Symbol *s) +.br +Symbol *flookupsym(Fhdr *hdr, char *name) +.br +Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +.PP +.ft B int indexlsym(Symbol *s1, uint n, Symbol *s2) .br int lookuplsym(Symbol *s1, char *name, Symbol *s2) @@ -70,6 +82,25 @@ frees the structures. The rest of the functions described here access a composite symbol table made up of all currently open tables. .PP +The set of all currently open +.BR Fhdr s +is maintained as a linked list starting at +.I fhdrlist +(chained via +.BR Fhdr.next ). +.PP +.I Findhdr +searches the currently open +.BR Fhdr s +for one whose file name ends with the path +.I name +(that is, +.B libc.so +matches +.B /usr/lib/libc.so +but not +.BR mylibc.so ). +.PP The .B Symbol data structure: @@ -190,10 +221,28 @@ Class specification .B CANY searches the text table first, then the global table. .PP +.IR Findexsym , +.IR flookupsym , +and +.I ffindsym +are similar to +.IR indexsym , +.IR lookupsym , +and +.IR findsym , +but operate only on the symbols from +.IR hdr . +.I Flookupsym +and +.I ffindsym +return pointers to data stored in the +.IR hdr , +which must not be modified or freed. +.PP .IR Indexlsym , .IR lookuplsym , and -.IR findlsym +.I findlsym are similar to .IR indexsym , .IR lookupsym , diff --git a/man/man3/mach.3 b/man/man3/mach.3 index 38918523..18147891 100644 --- a/man/man3/mach.3 +++ b/man/man3/mach.3 @@ -54,24 +54,37 @@ the various file parsers deduce the operating system from information in the binary files themselves and adjust accordingly. .PP +The supported architectures are +.B 386 +(Intel 32-bit x86) +386 and later) +and +.B power +(IBM PowerPC, typically running +Mac OS X). +.PP Other manual pages describe the library functions in detail. .PP -.I Mach-file (3) +.IR Mach-cmd (3) +describes some convenience routines for attaching to +processes and core files. +.PP +.IR Mach-file (3) describes the manipulation of binary files. .PP -.I Mach-map (3) +.IR Mach-map (3) describes the interface to address spaces and register sets in executable files and executing programs. .PP -.I Mach-stack (3) +.IR Mach-stack (3) describes support for unwinding the stack. .PP -.I Mach-swap (3) +.IR Mach-swap (3) describes helper functions for accessing data in a particular byte order. .PP -.I Mach-symbol (3) +.IR Mach-symbol (3) describes the interface to debugging symbol information. .SH SOURCE .B /usr/local/plan9/src/libmach diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 index 54e9ecc8..01493c75 100644 --- a/man/man3/malloc.3 +++ b/man/man3/malloc.3 @@ -1,6 +1,6 @@ .TH MALLOC 3 .SH NAME -malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- memory allocator .SH SYNOPSIS .B #include <u.h> .br @@ -23,23 +23,16 @@ void* realloc(void *ptr, ulong size) void* calloc(ulong nelem, ulong elsize) .PP .B -ulong msize(void *ptr) -.PP -.B void setmalloctag(void *ptr, ulong tag) .PP .B -ulong getmalloctag(void *ptr, ulong tag) +ulong getmalloctag(void *ptr) .PP .B void setrealloctag(void *ptr, ulong tag) .PP .B -ulong getrealloctag(void *ptr, ulong tag) -.PP -.B -void* malloctopoolblock(void*) -.PP +ulong getrealloctag(void *ptr) .SH DESCRIPTION .I Malloc and @@ -109,12 +102,7 @@ The space is initialized to zeros. .I Free frees such a block. .PP -When a block is allocated, sometimes there is some extra unused space at the end. -.I Msize -grows the block to encompass this unused space and returns the new number -of bytes that may be used. -.PP -The memory allocator maintains two word-sized fields +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. @@ -137,24 +125,15 @@ to .IR setmalloctag ) to provide more useful information about the source of allocation. -.PP -.I Malloctopoolblock -takes the address of a block returned by -.I malloc -and returns the address of the corresponding -block allocated by the -.IR pool (3) -routines. .SH SOURCE -.B /usr/local/plan9/src/libc/port/malloc.c +.B /usr/local/plan9/src/lib9/malloc.c +.br +.B /usr/local/plan9/src/lib9/malloctag.c .SH SEE ALSO -.IR leak (1), .I trump (in .IR acid (1)), -.IR brk (3), -.IR getcallerpc (3), -.IR pool (3) +.IR getcallerpc (3) .SH DIAGNOSTICS .I Malloc, realloc and @@ -169,22 +148,6 @@ and return .BR ~0 . .PP -After including -.BR pool.h , -the call -.B poolcheck(mainmem) -can be used to scan the storage arena for inconsistencies -such as data written beyond the bounds of allocated blocks. -It is often useful to combine this with with setting -.EX - mainmem->flags |= POOL_NOREUSE; -.EE -at the beginning of your program. -This will cause malloc not to reallocate blocks even -once they are freed; -.B poolcheck(mainmem) -will then detect writes to freed blocks. -.PP The .I trump library for @@ -198,7 +161,7 @@ is bizarre. .PP User errors can corrupt the storage arena. The most common gaffes are (1) freeing an already freed block, -(3) storing beyond the bounds of an allocated block, and (3) +(2) storing beyond the bounds of an allocated block, and (3) freeing data that was not obtained from the allocator. When .I malloc diff --git a/man/man3/matrix.3 b/man/man3/matrix.3 new file mode 100644 index 00000000..87ba34c5 --- /dev/null +++ b/man/man3/matrix.3 @@ -0,0 +1,350 @@ +.TH MATRIX 3 +.SH NAME +ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport \- Geometric transformations +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +void ident(Matrix m) +.PP +.B +void matmul(Matrix a, Matrix b) +.PP +.B +void matmulr(Matrix a, Matrix b) +.PP +.B +double determinant(Matrix m) +.PP +.B +void adjoint(Matrix m, Matrix madj) +.PP +.B +double invertmat(Matrix m, Matrix inv) +.PP +.B +Point3 xformpoint(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformpointd(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformplane(Point3 p, Space *to, Space *from) +.PP +.B +Space *pushmat(Space *t) +.PP +.B +Space *popmat(Space *t) +.PP +.B +void rot(Space *t, double theta, int axis) +.PP +.B +void qrot(Space *t, Quaternion q) +.PP +.B +void scale(Space *t, double x, double y, double z) +.PP +.B +void move(Space *t, double x, double y, double z) +.PP +.B +void xform(Space *t, Matrix m) +.PP +.B +void ixform(Space *t, Matrix m, Matrix inv) +.PP +.B +int persp(Space *t, double fov, double n, double f) +.PP +.B +void look(Space *t, Point3 eye, Point3 look, Point3 up) +.PP +.B +void viewport(Space *t, Rectangle r, double aspect) +.SH DESCRIPTION +These routines manipulate 3-space affine and projective transformations, +represented as 4\(mu4 matrices, thus: +.IP +.EX +.ta 6n +typedef double Matrix[4][4]; +.EE +.PP +.I Ident +stores an identity matrix in its argument. +.I Matmul +stores +.I a\(mub +in +.IR a . +.I Matmulr +stores +.I b\(mua +in +.IR b . +.I Determinant +returns the determinant of matrix +.IR m . +.I Adjoint +stores the adjoint (matrix of cofactors) of +.I m +in +.IR madj . +.I Invertmat +stores the inverse of matrix +.I m +in +.IR minv , +returning +.IR m 's +determinant. +Should +.I m +be singular (determinant zero), +.I invertmat +stores its +adjoint in +.IR minv . +.PP +The rest of the routines described here +manipulate +.I Spaces +and transform +.IR Point3s . +A +.I Point3 +is a point in three-space, represented by its +homogeneous coordinates: +.IP +.EX +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +The homogeneous coordinates +.RI ( x , +.IR y , +.IR z , +.IR w ) +represent the Euclidean point +.RI ( x / w , +.IR y / w , +.IR z / w ) +if +.IR w ≠0, +and a ``point at infinity'' if +.IR w =0. +.PP +A +.I Space +is just a data structure describing a coordinate system: +.IP +.EX +typedef struct Space Space; +struct Space{ + Matrix t; + Matrix tinv; + Space *next; +}; +.EE +.PP +It contains a pair of transformation matrices and a pointer +to the +.IR Space 's +parent. The matrices transform points to and from the ``root +coordinate system,'' which is represented by a null +.I Space +pointer. +.PP +.I Pushmat +creates a new +.IR Space . +Its argument is a pointer to the parent space. Its result +is a newly allocated copy of the parent, but with its +.B next +pointer pointing at the parent. +.I Popmat +discards the +.B Space +that is its argument, returning a pointer to the stack. +Nominally, these two functions define a stack of transformations, +but +.B pushmat +can be called multiple times +on the same +.B Space +multiple times, creating a transformation tree. +.PP +.I Xformpoint +and +.I Xformpointd +both transform points from the +.B Space +pointed to by +.I from +to the space pointed to by +.IR to . +Either pointer may be null, indicating the root coordinate system. +The difference between the two functions is that +.B xformpointd +divides +.IR x , +.IR y , +.IR z , +and +.I w +by +.IR w , +if +.IR w ≠0, +making +.RI ( x , +.IR y , +.IR z ) +the Euclidean coordinates of the point. +.PP +.I Xformplane +transforms planes or normal vectors. A plane is specified by the +coefficients +.RI ( a , +.IR b , +.IR c , +.IR d ) +of its implicit equation +.IR ax+by+cz+d =0. +Since this representation is dual to the homogeneous representation of points, +.B libgeometry +represents planes by +.B Point3 +structures, with +.RI ( a , +.IR b , +.IR c , +.IR d ) +stored in +.RI ( x , +.IR y , +.IR z , +.IR w ). +.PP +The remaining functions transform the coordinate system represented +by a +.BR Space . +Their +.B Space * +argument must be non-null \(em you can't modify the root +.BR Space . +.I Rot +rotates by angle +.I theta +(in radians) about the given +.IR axis , +which must be one of +.BR XAXIS , +.B YAXIS +or +.BR ZAXIS . +.I Qrot +transforms by a rotation about an arbitrary axis, specified by +.B Quaternion +.IR q . +.PP +.I Scale +scales the coordinate system by the given scale factors in the directions of the three axes. +.IB Move +translates by the given displacement in the three axial directions. +.PP +.I Xform +transforms the coordinate system by the given +.BR Matrix . +If the matrix's inverse is known +.I a +.IR priori , +calling +.I ixform +will save the work of recomputing it. +.PP +.I Persp +does a perspective transformation. +The transformation maps the frustum with apex at the origin, +central axis down the positive +.I y +axis, and apex angle +.I fov +and clipping planes +.IR y = n +and +.IR y = f +into the double-unit cube. +The plane +.IR y = n +maps to +.IR y '=-1, +.IR y = f +maps to +.IR y '=1. +.PP +.I Look +does a view-pointing transformation. The +.B eye +point is moved to the origin. +The line through the +.I eye +and +.I look +points is aligned with the y axis, +and the plane containing the +.BR eye , +.B look +and +.B up +points is rotated into the +.IR x - y +plane. +.PP +.I Viewport +maps the unit-cube window into the given screen viewport. +The viewport rectangle +.I r +has +.IB r .min +at the top left-hand corner, and +.IB r .max +just outside the lower right-hand corner. +Argument +.I aspect +is the aspect ratio +.RI ( 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 +.I y +axis, with +.I x +to the left and +.I z +up. The viewport +has +.I x +increasing to the right and +.I y +increasing down. The window's +.I y +coordinates are mapped, unchanged, into the viewport's +.I z +coordinates. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/matrix.c +.SH "SEE ALSO +.IR arith3 (3) diff --git a/man/man3/memdraw.3 b/man/man3/memdraw.3 index 78c4859c..4b59428f 100644 --- a/man/man3/memdraw.3 +++ b/man/man3/memdraw.3 @@ -231,9 +231,9 @@ element of .B Memdata points back at the .B Memdata -structure, so that the +structure, so that in the Plan 9 kernel, the memory allocator (see -.IR pool (3)) +Plan 9's \fIpool\fR(3)) can compact image memory using .IR memimagemove . @@ -294,7 +294,7 @@ writes a compressed representation of to file descriptor .IR fd . For more on bitmap formats, see -.IR image (6). +.IR image (7). .I Freememimage frees images returned by any of these routines. The @@ -433,7 +433,7 @@ In the kernel, .I iprint prints to a serial line rather than the screen, for obvious reasons. .SH SOURCE -.B /usr/local/plan9/src/libmemdraw +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR addpt (3), .IR color (3), @@ -442,9 +442,14 @@ prints to a serial line rather than the screen, for obvious reasons. .IR memlayer (3), .IR stringsize (3), .IR subfont (3), -.IR color (6), -.IR utf (6) +.IR color (7), +.IR utf (7) .SH BUGS .I Memimagestring is unusual in using a subfont rather than a font, and in having no parameter to align the source. +.PP +.I Libmemdraw +is archived into +.IR libdraw . + diff --git a/man/man3/memlayer.3 b/man/man3/memlayer.3 index 523253a8..90e63e50 100644 --- a/man/man3/memlayer.3 +++ b/man/man3/memlayer.3 @@ -294,12 +294,16 @@ bytes of data in .I buf are in compressed image format (see -.IR image (6)). +.IR image (7)). .SH SOURCE -.B /usr/local/plan9/src/libmemlayer +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR graphics (3), .IR memdraw (3), .IR stringsize (3), .IR window (3), .IR draw (3) +.SH BUGS +.I Libmemlayer +is archived into +.IR libdraw . diff --git a/man/man3/memory.3 b/man/man3/memory.3 new file mode 100644 index 00000000..746dc7d9 --- /dev/null +++ b/man/man3/memory.3 @@ -0,0 +1,126 @@ +.TH MEMORY 3 +.SH NAME +memccpy, memchr, memcmp, memcpy, memmove, memset \- memory operations +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.ta \w'\fLvoid* 'u +.B +void* memccpy(void *s1, void *s2, int c, long n) +.PP +.B +void* memchr(void *s, int c, long n) +.PP +.B +int memcmp(void *s1, void *s2, long n) +.PP +.B +void* memcpy(void *s1, void *s2, long n) +.PP +.B +void* memmove(void *s1, void *s2, long n) +.PP +.B +void* memset(void *s, int c, long n) +.SH 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. +.PP +.I Memccpy +copies bytes from memory area +.I s2 +into +.IR s1 , +stopping after the first occurrence of byte +.I c +has been copied, or after +.I n +bytes have been copied, whichever comes first. +It returns a pointer to the byte after +the copy of +.I c +in +.IR s1 , +or zero if +.I c +was not found in the first +.I n +bytes of +.IR s2 . +.PP +.I Memchr +returns a pointer to the first +occurrence of byte +.I c +in the first +.I n +bytes of memory area +.IR s, +or zero if +.I c +does not occur. +.PP +.I Memcmp +compares its arguments, looking at the first +.I n +bytes only, and returns an integer +less than, equal to, or greater than 0, +according as +.I s1 +is lexicographically less than, equal to, or +greater than +.IR s2 . +The comparison is bytewise unsigned. +.PP +.I Memcpy +copies +.I n +bytes from memory area +.I s2 +to +.IR s1 . +It returns +.IR s1 . +.PP +.I Memmove +works like +.IR memcpy , +except that it is guaranteed to work if +.I s1 +and +.IR s2 +overlap. +.PP +.I Memset +sets the first +.I n +bytes in memory area +.I s +to the value of byte +.IR c . +It returns +.IR s . +.SH SOURCE +All these routines have portable C implementations in +.BR /usr/local/plan9/src/lib9 . +.\" Most also have machine-dependent assembly language implementations in +.\" .BR /usr/local/plan9/lib9/$objtype . +.SH SEE ALSO +.IR strcat (3) +.SH BUGS +ANSI C does not require +.I memcpy +to handle overlapping source and destination; on Plan 9, it does, so +.I memmove +and +.I memcpy +behave identically. +.PP +If +.I memcpy +and +.I memmove +are handed a negative count, they abort. diff --git a/man/man3/mousescrollsize.3 b/man/man3/mousescrollsize.3 new file mode 100644 index 00000000..915a6bb1 --- /dev/null +++ b/man/man3/mousescrollsize.3 @@ -0,0 +1,62 @@ +.TH MOUSESCROLLSIZE 3 +.SH NAME +mousescrollsize \- compute mouse scroll increment +.SH SYNOPSIS +.B #include <draw.h> +.PP +int mousescrollsize(int maxlines) +.SH DESCRIPTION +.I Mousescrollsize +computes the number of lines of text that should be scrolled +in response to a mouse scroll wheel click. +.I Maxlines +is the number of lines visible in the text window. +.PP +The default scroll increment is one line. +This default can be overridden by setting the +.B $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 +.B $mousescrollsize +to +.B 50% +causes a half-window scroll increment. +.PP +.I Mousescrollsize +is used by +.IR 9term (1) +and +.IR acme (1) +to set their scrolling behavior. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/scroll.c +.SH SEE ALSO +.IR 9term (1), +.IR acme (1) +.SH BUGS +.I 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 +.B InputDevice +section of +.B XF86Config-4 +to look like: +.IP +.EX +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 +.EE diff --git a/man/man3/mp.3 b/man/man3/mp.3 index 420f0ba6..9a4ed848 100644 --- a/man/man3/mp.3 +++ b/man/man3/mp.3 @@ -1,7 +1,6 @@ .TH MP 3 .SH 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, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree \- extended precision arithmetic +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, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree, mpfactorial \- extended precision arithmetic .SH SYNOPSIS .B #include <u.h> .br @@ -163,6 +162,9 @@ void crtprefree(CRTpre *cre) void crtresfree(CRTres *res) .PP .B +mpint* mpfactorial(ulong n) +.PP +.B mpint *mpzero, *mpone, *mptwo .SH DESCRIPTION .PP @@ -573,5 +575,9 @@ free and .I CRTres structures respectively. +.PP +.I Mpfactorial +returns the factorial of +.IR n . .SH SOURCE .B /usr/local/plan9/src/libmp diff --git a/man/man3/mux.3 b/man/man3/mux.3 new file mode 100644 index 00000000..cc8de4d2 --- /dev/null +++ b/man/man3/mux.3 @@ -0,0 +1,154 @@ +.TH MUX 3 +.SH NAME +Mux, muxinit, muxrpc, muxthreads \- protocol multiplexor +.SH SYNOPSIS +.B #include <mux.h> +.PP +.nf +.B +.ta +4n +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 */ +}; +.ta +\w'\fLvoid* 'u +.PP +.B +void muxinit(Mux *mux); +.PP +.B +void* muxrpc(Mux *mux, void *request); +.PP +.B +void muxprocs(Mux *mux); +.SH DESCRIPTION +.I Libmux +is a generic protocol multiplexor. +A client program initializes a +.B Mux +structure with information about the protocol +(mainly in the form of helper functions) +and can then use +.I muxrpc +to execute individual RPCs without worrying +about details of multiplexing requests +and demultiplexing responses. +.PP +.I Libmux +assumes that the protocol messages contain a +.I tag +(or message ID) field that exists for the sole purpose of demultiplexing messages. +.I Libmux +chooses the tags and then calls a helper function +to put them in the outgoing messages. +.I Libmux +calls another helper function to retrieve tags +from incoming messages. +It also calls helper functions to send and receive packets. +.PP +A client should allocate a +.B Mux +structure and then call +.I muxinit +to initialize the library's private elements. +The client must initialize the following elements: +.TP +.I mintag\fR, \fPmaxtag +The range of valid tags; +.I maxtag +is the maximum valid tag plus one, so that +.IR maxtag \- mintag +is equal to the number of valid tags. +If +.I libmux +runs out of tags +(all tags are being used for RPCs currently in progress), +a new call to +.IR muxrpc +will block until an executing call finishes. +.TP +.I settag\fR, \fPgettag +Set or get the tag value in a message. +.TP +.I send\fR, \fPrecv +Send or receive protocol messages on the connection. +.I Recv +should block until a message is available and +should return nil if the connection is closed. +.I Libmux +will arrange that only one call to +.I recv +is active at a time. +.TP +.I aux +An auxiliary pointer for use by the client. +.PD +Once a client has initialized the +.B Mux +structure, it can call +.I muxrpc +to execute RPCs. +The +.I request +is the message passed to +.I settag +and +.IR send . +The return value is the response packet, +as provided by +.IR recv , +or +nil if an error occurred. +.I Muxprocs +allocates new procs +(see +.IR thread (3)) +in which to run +.I send +and +.IR recv . +After a call to +.IR muxprocs , +.I muxrpc +will run +.I send +and +.I recv +in these procs instead of in the calling proc. +This is useful if the implementation of +either (particularly +.IR recv ) +blocks an entire proc +and there are other threads in the calling proc +that need to remain active. +.SH EXAMPLE +See +.B /usr/local/plan9/src/lib9pclient/fs.c +for an example of using +.I libmux +with +9P +(see +.IR intro (9p)). +.SH SOURCE +.B /usr/local/plan9/src/libmux +.SH SEE ALSO +.IR thread (3), +.IR intro (9p) +.SH BUGS +.I Libmux +does not know how to free protocol messages, +so message arriving with unexpected or invalid +tags are leaked. +.PP +Using +.I mintag +other than zero is not well tested and probably buggy. diff --git a/man/man3/nan.3 b/man/man3/nan.3 index 2c77af00..69777e52 100644 --- a/man/man3/nan.3 +++ b/man/man3/nan.3 @@ -41,4 +41,4 @@ else negative infinity. returns true if its first argument is infinity with the same sign as the second argument. .SH SOURCE -.B /usr/local/plan9/src/libc/port/nan.c +.B /usr/local/plan9/src/lib9/nan.c diff --git a/man/man3/needstack.3 b/man/man3/needstack.3 new file mode 100644 index 00000000..31588f68 --- /dev/null +++ b/man/man3/needstack.3 @@ -0,0 +1,69 @@ +.TH NEEDSTACK 3 +.SH NAME +needstack \- check for execution stack overflow +.SH SYNOPSIS +.B +#include <u.h> +.PP +.B +#include <libc.h> +.PP +.B +int needstack(int n) +.SH 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 +.I needstack +indicates to the thread library that an external routine is about +to be called that will require +.I 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 +.B needstack(0) +can be used to check whether the stack is +currently overflowed. +.PP +.I Needstack +is defined in +.B libc.h +so that library functions used in threaded and non-threaded contexts +can call it. +The implementation of +.I needstack +in +.B lib9 +is a no-op. +.PP +.I Needstack +should be thought of as a comment checked at run time, +like +.IR assert (3). +.SH EXAMPLE +The X Window library implementation of +.I XLookupString +allocates some very large buffers on the stack, so +.B /usr/local/plan9/src/libdraw/x11-itrans.c +calls +.B needstack(20*1024) +before making calls to +.IR XLookupString . +If a thread (in this case, the keyboard-reading thread used +inside the +.IR draw (3) +library) +does not allocate a large enough stack, the problem is diagnosed +immediately rather than left to corrupt memory. +.SH SOURCE +.B /usr/local/plan9/src/lib9/needstack.c +.br +.B /usr/local/plan9/src/libthread +.SH SEE ALSO +.IR thread (3) diff --git a/man/man3/notify.3 b/man/man3/notify.3 index 0286ea8f..41b84521 100644 --- a/man/man3/notify.3 +++ b/man/man3/notify.3 @@ -1,6 +1,6 @@ .TH NOTIFY 3 .SH NAME -notify, noted, atnotify \- handle asynchronous process notification +notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff \- handle asynchronous process notification .SH SYNOPSIS .B #include <u.h> .br @@ -14,36 +14,34 @@ int noted(int v) .PP .B int atnotify(int (*f)(void*, char*), int in) +.PP +.B +int noteenable(char *msg) +.br +.B +int notedisable(char *msg) +.PP +.B +int notifyon(char *msg) +.br +.B +int notifyoff(char *msg) .SH DESCRIPTION When a process raises an exceptional condition such as dividing by zero or writing on a closed pipe, a .I note is posted to communicate the exception. -A note may also be posted by a -.I write -(see -.IR read (3)) -to the process's -.BI /proc/ n /note -file or to the -.BI /proc/ m /notepg -file of a process in the same process group (see -.IR proc (3)). -When the note is received -the behavior of the process depends on the origin of the note. -If the note was posted by an external process, -the process receiving the note exits; -if generated by the system the note string, -preceded by the name -and id of the process and the string -\fL"suicide: "\fP, -is printed on the process's standard error file -and the -process is suspended in the -.B Broken -state for debugging. -.PP -These default actions may be overridden. +A note may also be posted by another process +via +.IR postnote (3). +On Unix, notes are implemented as signals. +.PP +When a note is received, the action taken depends on the note. +See +.IR signal (7) +for the full description of the defaults. +.PP +The default actions may be overridden. The .I notify function registers a @@ -55,7 +53,7 @@ replaces the previous handler, if any. An argument of zero cancels a previous handler, restoring the default action. A -.IR fork (3) +.IR fork (2) system call leaves the handler registered in both the parent and the child; .IR exec (3) @@ -64,20 +62,19 @@ Handlers may not perform floating point operations. .PP After a note is posted, the handler is called with two arguments: -the first is a pointer to a +the first is unimplemented and should not be used +(on Plan 9 +it is a .B Ureg -structure (defined in -.BR /$objtype/include/ureg.h ) -giving the current values of registers; +structure +giving the current values of registers); the second is a pointer to the note itself, -a null-terminated string with no more than -.L ERRLEN -characters in it including the terminal NUL. -The -.B Ureg -argument is usually not needed; it is provided to help recover from traps such -as floating point exceptions. -Its use and layout are machine- and system-specific. +a null-terminated string. +.\" The +.\" .B Ureg +.\" argument is usually not needed; it is provided to help recover from traps such +.\" as floating point exceptions. +.\" Its use and layout are machine- and system-specific. .PP A notification handler must finish either by exiting the program or by calling .IR noted ; @@ -115,14 +112,32 @@ set up with using the .I notejmp function (see -.IR setjmp (3)), -which is implemented by modifying the saved state and calling -.BR noted(NCONT) . +.IR setjmp (3)). +.PP +Unix provides a fixed set of notes (typically there are 32) called +.IR signals . +It also allows a process to block certain notes from being delivered +(see +.IR sigprocmask (2)) +and to ignore certain notes by setting the signal hander to the special value +.B SIG_IGN +(see +.IR signal (2)). +.I Noteenable +and +.I 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. +.I Notifyon +and +.I 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. .PP Regardless of the origin of the note or the presence of a handler, if the process is being debugged (see -.IR proc (3)) +.IR ptrace (2)) the arrival of a note puts the process in the .B Stopped state and awakens the debugger. @@ -158,87 +173,67 @@ calls .I noted with argument .BR NDFLT . -.PP -.I Noted -has two other possible values for its argument. -.B NSAVE -returns from the handler and clears the note, enabling the receipt of another, -but does not return to the program. -Instead it starts a new handler with the same stack, stack pointer, -and arguments as the -original, at the address recorded in the program counter of the -.B Ureg -structure. Typically, the program counter will be overridden by the -first note handler to be the address of a separate function; -.B NSAVE -is then a `trampoline' to that handler. -That handler may executed -.B noted(NRSTR) -to return to the original program, usually after restoring the original program -counter. -.B NRSTR -is identical to -.BR NCONT -except that it can only be executed after an -.BR NSAVE . -.B NSAVE -and -.B NRSTR -are designed to improve the emulation of signals by the ANSI C/POSIX -environment; their use elsewhere is discouraged. +.\" .PP +.\" .I Noted +.\" has two other possible values for its argument. +.\" .B NSAVE +.\" returns from the handler and clears the note, enabling the receipt of another, +.\" but does not return to the program. +.\" Instead it starts a new handler with the same stack, stack pointer, +.\" and arguments as the +.\" original, at the address recorded in the program counter of the +.\" .B Ureg +.\" structure. Typically, the program counter will be overridden by the +.\" first note handler to be the address of a separate function; +.\" .B NSAVE +.\" is then a `trampoline' to that handler. +.\" That handler may executed +.\" .B noted(NRSTR) +.\" to return to the original program, usually after restoring the original program +.\" counter. +.\" .B NRSTR +.\" is identical to +.\" .BR NCONT +.\" except that it can only be executed after an +.\" .BR NSAVE . +.\" .B NSAVE +.\" and +.\" .B NRSTR +.\" are designed to improve the emulation of signals by the ANSI C/POSIX +.\" environment; their use elsewhere is discouraged. .PP The set of notes a process may receive is system-dependent, but there is a common set that includes: .PP .RS 3n .nf -.ta \w'\fLsys: write on closed pipe \fP'u -\fINote\fP \fIMeaning\fP -\fLinterrupt\fP user interrupt (DEL key) -\fLhangup\fP I/O connection closed -\fLalarm\fP alarm expired -\fLsys: breakpoint\fP breakpoint instruction -\fLsys: bad address\fP system call address argument out of range -\fLsys: odd address\fP system call address argument unaligned -\fLsys: bad sys call\fP system call number out of range -\fLsys: odd stack\fP system call user stack unaligned -\fLsys: write on closed pipe\fP write on closed pipe -\fLsys: fp: \fIfptrap\f1 floating point exception -\fLsys: trap: \fItrap\f1 other exception (see below) +.ta \w'\fLsys: write on closed pipe \fP'u \w'system call address argument out of range 'u +\fINote\fP \fIMeaning\fP \fIUnix signal\fP +\fLinterrupt\fP user interrupt (DEL key) SIGINTR +\fLhangup\fP I/O connection closed SIGHUP +\fLalarm\fP alarm expired SIGLARM +\fLquit\fP quit from keyboard SIGQUIT +\fLkill\fP process requested to exit SIGTERM +\fLsys: kill\fP process forced to exit SIGKILL +\fLsys: bus error\fP bus error SIGBUS +\fLsys: segmentation violation\fP segmentation violation SIGSEGV .fi .RE .PP +See +.B /usr/local/plan9/src/lib9/await.c +(sic) +for the full list. +.PP The notes prefixed .B sys: -are generated by the operating system. -They are suffixed by the user program counter in format -.BR pc=0x1234 . -If the note is due to a floating point exception, just before the -.BR pc -is the address of the offending instruction in format -.BR fppc=0x1234 . -Notes are limited to -.B ERRLEN -bytes; if they would be longer they are truncated but the -.B pc -is always reported correctly. -.PP -The types and syntax of the -.I trap -and -.I fptrap -portions of the notes are machine-dependent. +are usually generated by the operating system. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/notify.c .br -.B /usr/local/plan9/src/libc/port/atnotify.c +.B /usr/local/plan9/src/lib9/atnotify.c .SH SEE ALSO .IR intro (3), .I notejmp in .IR setjmp (3) -.SH BUGS -Since -.IR exec (3) -discards the notification handler, there is a window -of vulnerability to notes in a new process. diff --git a/man/man3/open.3 b/man/man3/open.3 index 46b4fe58..b964cc9a 100644 --- a/man/man3/open.3 +++ b/man/man3/open.3 @@ -94,7 +94,7 @@ 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 -.IR open (5). +.IR open (9p). .PP .I Create fails if the path up to the last element of @@ -106,12 +106,12 @@ does not permit the access defined by of if there there are no free file descriptors. In the last case, the file may be created even when an error is returned. -If the file is new and the directory in which it is created is -a union directory (see -.IR intro (3)) -then the constituent directory where the file is created -depends on the structure of the union: see -.IR bind (3). +.\" If the file is new and the directory in which it is created is +.\" a union directory (see +.\" .IR intro (3)) +.\" then the constituent directory where the file is created +.\" depends on the structure of the union: see +.\" .IR bind (3). .PP Since .I create @@ -126,7 +126,7 @@ for a .IR create, the call succeeds only if the file does not already exist; see -.IR open (5) +.IR open (9p) for details. .PP .I Close @@ -138,10 +138,9 @@ Files are closed automatically upon termination of a process; .I close allows the file descriptor to be reused. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), -.IR bind (3), .IR stat (3) .SH DIAGNOSTICS These functions set diff --git a/man/man3/opentemp.3 b/man/man3/opentemp.3 new file mode 100644 index 00000000..23e77d3d --- /dev/null +++ b/man/man3/opentemp.3 @@ -0,0 +1,48 @@ +.TH OPENTEMP 3 +.SH NAME +opentemp \- create a uniquely-named file +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int opentemp(char *template) +.SH DESCRIPTION +.I Opentemp +replaces +.I template +by a unique file name, and returns the +address of the template. +The template should look like a file name with eleven trailing +.LR X s. +The +.LR X s +are replaced by a letter followed by the current process id. +Letters from +.L a +to +.L z +are tried until the name of a file that does not yet exist +(see +.IR access (2)) +is generated. +.I Opentemp +then creates the file for reading and writing +and returns the file descriptor. +.PP +If no such name can be generated, +.I opentemp +returns \-1. +.PP +.I Opentemp +avoids races. +Two simultaneous calls to +.I opentemp +will never return the same name. +.SH SOURCE +.B /usr/local/plan9/src/lib9/opentemp.c +.SH "SEE ALSO +.I create +in +.IR open (3) diff --git a/man/man3/pipe.3 b/man/man3/pipe.3 index 06d37694..993e33ab 100644 --- a/man/man3/pipe.3 +++ b/man/man3/pipe.3 @@ -25,50 +25,76 @@ is available for reading from After the pipe has been established, cooperating processes created by subsequent -.IR fork (3) +.IR fork (2) calls may pass data through the pipe with .I read and .I write calls. -The bytes placed on a pipe -by one -.I write -are contiguous even if many processes are writing. -Write boundaries are preserved: each read terminates -when the read buffer is full or after reading the last byte -of a write, whichever comes first. -.PP -The number of bytes available to a -.IR read (3) -is reported -in the -.B Length -field returned by -.I fstat -or -.I dirfstat -on a pipe (see -.IR stat (3)). +.\" The bytes placed on a pipe +.\" by one +.\" .I write +.\" are contiguous even if many processes are writing. +.\" Write boundaries are preserved: each read terminates +.\" when the read buffer is full or after reading the last byte +.\" of a write, whichever comes first. +.\" .PP +.\" The number of bytes available to a +.\" .IR read (3) +.\" is reported +.\" in the +.\" .B Length +.\" field returned by +.\" .I fstat +.\" or +.\" .I dirfstat +.\" on a pipe (see +.\" .IR stat (3)). .PP When all the data has been read from a pipe and the writer has closed the pipe or exited, .IR read (3) will return 0 bytes. Writes to a pipe with no reader will generate a note .BR "sys: write on closed pipe" . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/pipe.c .SH SEE ALSO .IR intro (3), -.IR read (3), -.IR pipe (3) +.IR read (3) .SH DIAGNOSTICS Sets .IR errstr . .SH BUGS If a read or a write of a pipe is interrupted, some unknown number of bytes may have been transferred. -.br -When a read from a pipe returns 0 bytes, it usually means end of file -but is indistinguishable from reading the result of an explicit -write of zero bytes. +.PP +.I Pipe +is a macro defined as +.I p9pipe +to avoid name conflicts with Unix's +.I pipe +system call. +.PP +Unix pipes are not guaranteed to be bidirectional. +In order to ensure a bidirectional channel, +.I p9pipe +creates Unix domain sockets via the +.IR socketpair (2) +instead of Unix pipes. +.PP +The implementation of pipes as Unix domain sockets +causes problems with some Unix implementations of +.BR /dev/fd , +Unix's dup device. If a Unix domain socket is open as file +descriptor 0, some implementations disallow the opening of +.BR /dev/fd/0 ; +instead one must +.IR connect (2) +to it. +If this functionality is important +(as it is for +.IR rc (1)), +one must +.B #undef +.B pipe +and fall back on the (possibly unidirectional) Unix pipes. diff --git a/man/man3/plumb.3 b/man/man3/plumb.3 index f75acb39..c988bbab 100644 --- a/man/man3/plumb.3 +++ b/man/man3/plumb.3 @@ -1,6 +1,6 @@ .TH PLUMB 3 .SH NAME -eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages +eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages .SH SYNOPSIS .B #include <u.h> .br @@ -51,9 +51,21 @@ Plumbattr* plumbdelattr(Plumbattra *a, char *name) .PP .B int eplumb(int key, char *port) +.PP +.B +#include <9pclient.h> +.PP +.B +CFid *plumbopenfid(char *port, int omode) +.PP +.B +Plumbmsg* plumbrecvfid(CFid *fid) +.PP +.B +int plumbsendtofid(CFid *fid, Plumbmsg *m) .SH DESCRIPTION These routines manipulate -.IR plumb (6) +.IR plumb (7) messages, transmitting them, receiving them, and converting them between text and these data structures: .IP @@ -141,7 +153,7 @@ or nil for error. encodes message .I m as a character string in the format of -.IR plumb (6) , +.IR plumb (7) , setting .BI * np to the length in bytes of the string. @@ -226,15 +238,49 @@ for the first attribute with name and deletes it from the list, returning the resulting list. .I Plumbdelattr is a no-op if no such attribute exists. +.PP +The file descriptor returned by +.I plumbopen +is created with +.I fsopenfd +(see +.IR 9pclient (3)), +which masks information about read and write errors. +This is acceptable for use in +.I plumbrecv +but not for +.IR plumbsend , +which depends on seeing details of write errors. +.IR Plumbopenfid , +.IR plumbrecvfid , +and +.IR plumbsendtofid +provide an explicit interface to +.I lib9pclient +that preserves the exact error details. .SH SOURCE .B /usr/local/plan9/src/libplumb .SH SEE ALSO .IR plumb (1), .IR event (3), .IR plumber (4), -.IR plumb (6) +.IR plumb (7) .SH DIAGNOSTICS When appropriate, including when a .I plumbsend fails, these routine set .IR errstr . +.SH BUGS +To avoid rewriting clients that use +.IR plumbsend , +the call +.B plumbopen("send", +.B OWRITE) +returns a useless file descriptor +(it is opened to +.BR /dev/null ). +.I Plumbsend +looks for this particular file descriptor +and uses a static copy of the +.B CFid +instead. diff --git a/man/man3/post9pservice.3 b/man/man3/post9pservice.3 new file mode 100644 index 00000000..74404c17 --- /dev/null +++ b/man/man3/post9pservice.3 @@ -0,0 +1,29 @@ +.TH POST9PSERVICE 3 +.SH NAME +post9pservice \- post 9P service for use by clients +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int post9pservice(int fd, char *name) +.SH DESCRIPTION +.I Post9pservice +invokes +.IR 9pserve (4) +to post a new 9P service in the current +``name space'' +(see +.IR intro (4)) +named +.IR name . +Clients connecting to the posted service +are multiplexed onto a single 9P conversation with the server +on file descriptor +.IR fd . +.SH "SEE ALSO +.IR intro (4), +.IR 9pserve (4) +.SH SOURCE +.B /usr/local/plan9/src/lib9/post9p.c diff --git a/man/man3/postnote.3 b/man/man3/postnote.3 index fed339bd..535c7e6c 100644 --- a/man/man3/postnote.3 +++ b/man/man3/postnote.3 @@ -19,17 +19,16 @@ is .BR PNPROC , then .I note -is written to -.BI /proc/ pid /note\f1. +is sent to the process with id +.IR pid . If .I who is .BI PNGROUP , the note is delivered to the -process group by writing -.I note -to -.BI /proc/ pid /notepg\f1. +process group which has the process with id +.I pid +as a member. For .B PNGROUP only, if the calling process is in the target group, the note is @@ -39,11 +38,10 @@ delivered to that process. If the write is successful, zero is returned. Otherwise \-1 is returned. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/postnote.c +.B /usr/local/plan9/src/lib9/postnote.c .SH "SEE ALSO" .IR notify (3), -.IR intro (3), -.IR proc (3) +.IR intro (3) .SH DIAGNOSTICS Sets .IR errstr . diff --git a/man/man3/print.3 b/man/man3/print.3 index 1fab0ad8..b1c8545f 100644 --- a/man/man3/print.3 +++ b/man/man3/print.3 @@ -8,7 +8,7 @@ .ft R .. .SH NAME -print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output +print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output .SH SYNOPSIS .B #include <utf.h> .PP diff --git a/man/man3/proto.3 b/man/man3/proto.3 new file mode 100644 index 00000000..ab8d304c --- /dev/null +++ b/man/man3/proto.3 @@ -0,0 +1,131 @@ +.TH PROTO 3 +.SH NAME +rdproto \- parse and process a proto file listing +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.B +typedef void Protoenum(char *new, char *old, Dir *d, void *a) +.PP +.B +typedef void Protowarn(char *msg, void *a) +.PP +.B +int rdproto(char *proto, char *root, Protoenum *enm, +.br +.B + Protowarn *warn, void *a) +.SH DESCRIPTION +.I Rdproto +reads and interprets the named +.I proto +file relative to the +root directory +.IR root . +.PP +Each line of the +.I proto +file specifies a file to copy. +Blank lines and lines beginning with +.B # +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 +.B - +for permissions, owner, or group +causes +.I 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 +.B - +is useful when one wishes to set, say, +the file owner without setting the permissions.) +.PP +Names beginning with a +.L $ +are expanded as environment variables. +If the first file specified in a directory is +.LR * , +all of the files in that directory are considered listed. +If the first file is +.LR + , +all of the files are copied, and all subdirectories +are recursively considered listed. +All files are considered relative to +.IR root . +.PP +For each file named by the +.IR proto , +.I enm +is called with +.I new +pointing at the name of the file (without the root prefix), +.I old +pointing at the name of the source file (with the root prefix, +when applicable), +and +.I Dir +at the desired directory information for the new file. +Only the +.BR name , +.BR uid , +.BR gid , +.BR mode , +.BR mtime , +and +.B length +fields are guaranteed to be valid. +The argument +.I a +is the same argument passed to +.IR rdproto ; +typically it points at some extra state +used by the enumeration function. +.PP +When files or directories do not exist or +cannot be read by +.IR rdproto , +it formats a warning message, calls +.IR warn , +and continues processing; +if +.I warn +is nil, +.I rdproto +prints the warning message to standard error. +.PP +.I Rdproto +returns zero +if +.I proto +was processed, \-1 if it could not be opened. +.SH FILES +.TF /sys/lib/sysconfig/proto/portproto +.TP +.B /sys/lib/sysconfig/proto/ +directory of prototype files. +.TP +.B /sys/lib/sysconfig/proto/portproto +generic prototype file. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/proto.c +.SH SEE ALSO +.IR mk9660 (8), +Plan 9's \fImkfs\fR(8) diff --git a/man/man3/pushtls.3 b/man/man3/pushtls.3 new file mode 100644 index 00000000..b92dcb6e --- /dev/null +++ b/man/man3/pushtls.3 @@ -0,0 +1,196 @@ +.TH PUSHTLS 3 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int pushtls(int fd, char *hashalg, char *encalg, +.br +.B + int isclient, char *secret, char *dir) +.PP +.B #include <mp.h> +.br +.B #include <libsec.h> +.PP +.B +int tlsClient(int fd, TLSconn *conn) +.PP +.B +int tlsServer(int fd, TLSconn *conn) +.PP +.B +uchar *readcert(char *filename, int *pcertlen) +.PP +.B +PEMchain *readcertchain(char *filename) +.PP +.B +Thumbprint* initThumbprints(char *ok, char *crl) +.PP +.B +void freeThumbprints(Thumbprint *table) +.PP +.B +int okThumbprint(uchar *hash, Thumbprint *table) +.SH 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. +.PP +To use just the record layer, as described in Plan 9's +\fItls\fR(3), +call +.I pushtls +to open the record layer device, connect to the communications channel +.IR fd , +and start up encryption and message authentication as specified +in +.IR hashalg , +.IR encalg , +and +.IR secret . +These parameters must have been arranged at the two ends of the +conversation by other means. +For example, +.I hashalg +could be +.BR sha1 , +.I encalg +could be +.BR rc4_128 , +and +.I 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. +.I 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, +.IR fd . +If +.I dir +is non-zero, the path name of the connection directory is copied into +.IR dir . +This path name is guaranteed to be less than 40 bytes long. +.PP +Alternatively, call +.I tlsClient +to speak the full handshake protocol, +negotiate the algorithms and secrets, +and return a new data file descriptor for the data channel. +.I Conn +points to a (caller-allocated) struct +.EX + 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; +.EE +defined in +.IR tls.h . +On input, the caller can provide options such as +.IR cert , +the local certificate, and +.IR sessionID , +used by a client to resume a previously negotiated security association. +On output, the connection directory is set, as with +.B listen +(see +.IR dial (3)). +The input +.I cert +is freed and a freshly allocated copy of the remote's certificate +is returned in +.IR conn , +to be checked by the caller +according to its needs. One mechanism is supplied by +.I initThumbprints +and +.I freeThumbprints +which allocate and free, respectively, a table of hashes +from files of known trusted and revoked certificates. +.I okThumbprint +confirms that a particular hash is in the table, as computed by +.PP +.EX + 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... +.EE +.PP +Call +.I tlsServer +to perform the corresponding function on the server side: +.PP +.EX + fd = accept(lcfd, ldir); + conn = (TLSconn*)mallocz(sizeof *conn, 1); + conn->cert = readcert("cert.pem", &conn->certlen); + fd = tlsServer(fd, conn); + ...application begins... +.EE +The private key corresponding to +.I cert.pem +should have been previously loaded into factotum. +(See +.IR rsa (3) +.\" XXX should be rsa(8) +for more about key generation.) +By setting +.EX + conn->chain = readcertchain("intermediate-certs.pem"); +.EE +the server can present extra certificate evidence +to establish the chain of trust to a root authority +known to the client. +.PP +.I Conn +is not required for the ongoing conversation and may +be freed by the application whenever convenient. +.SH FILES +.TP +.B /sys/lib/tls +thumbprints of trusted services +.TP +.B /sys/lib/ssl +PEM certificate files +.SH SOURCE +.\" .B /sys/src/libc/9sys/pushtls.c +.\" .br +.B /usr/local/plan9/src/libsec/port +.SH "SEE ALSO" +.IR dial (3), +.IR thumbprint (7); +Plan 9's +\fIfactotum\fR(4) +and +\fItls\fR(3) +.SH DIAGNOSTICS +return \-1 on failure. +.SH BUGS +.I Pushtls +is not implemented. +.PP +Client certificates and client sessionIDs are not yet +implemented. +.PP +Note that in the TLS protocol +.I sessionID +itself is public; it is used as a pointer to +secrets stored in factotum. diff --git a/man/man3/qball.3 b/man/man3/qball.3 new file mode 100644 index 00000000..8d27f21a --- /dev/null +++ b/man/man3/qball.3 @@ -0,0 +1,76 @@ +.TH QBALL 3 +.SH NAME +qball \- 3-d rotation controller +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +void qball(Rectangle r, Mouse *mousep, +.br +.B + Quaternion *orientation, +.br +.B + void (*redraw)(void), Quaternion *ap) +.SH DESCRIPTION +.I 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 +.IR r , +and diameter the smaller of +.IR 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. +.PP +Argument +.I mousep +is a pointer to the mouse event that triggered the interaction. It should +have some button set. +.I Qball +will read more events into +.IR mousep , +and return when no buttons are down. +.PP +While +.I qball +is reading mouse events, it calls out to the caller-supplied routine +.IR redraw , +which is expected to update the screen to reflect the changing orientation. +Argument +.I orientation +is the orientation that +.I redraw +should examine, represented as a unit Quaternion (see +.IR quaternion(9.2)). +The caller may set it to any orientation. +It will be updated before each call to +.I redraw +(and on return) by multiplying by the rotation specified with the mouse. +.PP +It is possible to restrict +.I qball's +attention to rotations about a particular axis. +If +.I ap +is null, the rotation is unconstrained. +Otherwise, the rotation will be about the same axis as +.IR *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. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/qball.c +.SH SEE ALSO +.IR quaternion (3) +.br +Ken Shoemake, +``Animating Rotation with Quaternion Curves'', +.I +SIGGRAPH '85 Conference Proceedings. diff --git a/man/man3/quaternion.3 b/man/man3/quaternion.3 new file mode 100644 index 00000000..31f4ab50 --- /dev/null +++ b/man/man3/quaternion.3 @@ -0,0 +1,152 @@ +.TH QUATERNION 3 +.SH NAME +qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt \- Quaternion arithmetic +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +Quaternion qadd(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsub(Quaternion q, Quaternion r) +.PP +.B +Quaternion qneg(Quaternion q) +.PP +.B +Quaternion qmul(Quaternion q, Quaternion r) +.PP +.B +Quaternion qdiv(Quaternion q, Quaternion r) +.PP +.B +Quaternion qinv(Quaternion q) +.PP +.B +double qlen(Quaternion p) +.PP +.B +Quaternion qunit(Quaternion q) +.PP +.B +void qtom(Matrix m, Quaternion q) +.PP +.B +Quaternion mtoq(Matrix mat) +.PP +.B +Quaternion slerp(Quaternion q, Quaternion r, double a) +.PP +.B +Quaternion qmid(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsqrt(Quaternion q) +.SH 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 +.I r +and an imaginary vector component \fIv\fP=(\fIi\fP,\fIj\fP,\fIk\fP). +Quaternions add componentwise and multiply according to the rule +(\fIr\fP,\fIv\fP)(\fIs\fP,\fIw\fP)=(\fIrs\fP-\fIv\fP\v'-.3m'.\v'.3m'\fIw\fP, \fIrw\fP+\fIvs\fP+\fIv\fP×\fIw\fP), +where \v'-.3m'.\v'.3m' and × are the ordinary vector dot and cross products. +The multiplicative inverse of a non-zero quaternion (\fIr\fP,\fIv\fP) +is (\fIr\fP,\fI-v\fP)/(\fIr\^\fP\u\s-22\s+2\d-\fIv\fP\v'-.3m'.\v'.3m'\fIv\fP). +.PP +The following routines do arithmetic on quaternions, represented as +.IP +.EX +.ta 6n +typedef struct Quaternion Quaternion; +struct Quaternion{ + double r, i, j, k; +}; +.EE +.TF qunit +.TP +Name +Description +.TP +.B qadd +Add two quaternions. +.TP +.B qsub +Subtract two quaternions. +.TP +.B qneg +Negate a quaternion. +.TP +.B qmul +Multiply two quaternions. +.TP +.B qdiv +Divide two quaternions. +.TP +.B qinv +Return the multiplicative inverse of a quaternion. +.TP +.B qlen +Return +.BR sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k) , +the length of a quaternion. +.TP +.B qunit +Return a unit quaternion +.RI ( length=1 ) +with components proportional to +.IR q 's. +.PD +.PP +A rotation by angle \fIθ\fP about axis +.I A +(where +.I A +is a unit vector) can be represented by +the unit quaternion \fIq\fP=(cos \fIθ\fP/2, \fIA\fPsin \fIθ\fP/2). +The same rotation is represented by \(mi\fIq\fP; a rotation by \(mi\fIθ\fP about \(mi\fIA\fP is the same as a rotation by \fIθ\fP about \fIA\fP. +The quaternion \fIq\fP transforms points by +(0,\fIx',y',z'\fP) = \%\fIq\fP\u\s-2-1\s+2\d(0,\fIx,y,z\fP)\fIq\fP. +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. +.PP +The following routines operate on rotations or orientations represented as unit quaternions: +.TF slerp +.TP +.B mtoq +Convert a rotation matrix (see +.IR matrix (3)) +to a unit quaternion. +.TP +.B qtom +Convert a unit quaternion to a rotation matrix. +.TP +.B slerp +Spherical lerp. Interpolate between two orientations. +The rotation that carries +.I q +to +.I r +is \%\fIq\fP\u\s-2-1\s+2\d\fIr\fP, so +.B slerp(q, r, t) +is \fIq\fP(\fIq\fP\u\s-2-1\s+2\d\fIr\fP)\u\s-2\fIt\fP\s+2\d. +.TP +.B qmid +.B slerp(q, r, .5) +.TP +.B qsqrt +The square root of +.IR q . +This is just a rotation about the same axis by half the angle. +.PD +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/quaternion.c +.SH SEE ALSO +.IR matrix (3), +.IR qball (3) diff --git a/man/man3/quote.3 b/man/man3/quote.3 index 286cdd90..5a4c8d19 100644 --- a/man/man3/quote.3 +++ b/man/man3/quote.3 @@ -157,9 +157,9 @@ in .IR print (3) format strings. .SH SOURCE -.B /usr/local/plan9/src/libc/port/quote.c +.B /usr/local/plan9/src/lib9/quote.c .br -.B /usr/local/plan9/src/libc/fmt/fmtquote.c +.B /usr/local/plan9/src/lib9/fmt/fmtquote.c .SH "SEE ALSO .IR rc (1), .IR malloc (3), diff --git a/man/man3/rand.3 b/man/man3/rand.3 index 3f3e0061..25ea8a43 100644 --- a/man/man3/rand.3 +++ b/man/man3/rand.3 @@ -156,18 +156,12 @@ to return a uniform .IR x , .RI 0≤ x < val ≤ 2\u\s732\s10\d-1. .SH SOURCE -.B /usr/local/plan9/src/libc/port/*rand.c +.B /usr/local/plan9/src/lib9/ .br -.B /usr/local/plan9/src/libc/9sys/truerand.c -.br -.B /usr/local/plan9/src/libsec/port/genrandom.c -.br -.B /usr/local/plan9/src/libsec/port/prng.c -.br -.B /usr/local/plan9/src/libsec/port/*fastrand.c +.B /usr/local/plan9/src/libsec/port/ .SH "SEE ALSO -.IR cons (3), -.IR mp (3), +.\" .IR cons (3), +.IR mp (3) .SH BUGS .I Truerand and diff --git a/man/man3/read.3 b/man/man3/read.3 index aa35c659..34e65c6e 100644 --- a/man/man3/read.3 +++ b/man/man3/read.3 @@ -75,21 +75,18 @@ or By combining the operations in a single atomic call, they more closely match the 9P protocol (see -.IR intro (5)) +.IR intro (9p)) and, more important, permit multiprocess programs to execute multiple concurrent read and write operations on the same file descriptor without interference. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/port/readn.c +.B /usr/local/plan9/src/lib9/readn.c .SH SEE ALSO .IR intro (3), .IR open (3), .IR dup (3), -.IR pipe (3), -.IR readv (3) +.IR pipe (3) .SH DIAGNOSTICS These functions set .IR errstr . diff --git a/man/man3/readcolmap.3 b/man/man3/readcolmap.3 new file mode 100644 index 00000000..51753c57 --- /dev/null +++ b/man/man3/readcolmap.3 @@ -0,0 +1,76 @@ +.TH READCOLMAP 3 +.SH NAME +RGB, readcolmap, writecolmap \- access display color map +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <draw.h> +.PP +.PP +.ta \w'\fLvoid 'u +.PP +.B +int readcolmap(Display *d, RGB *map) +.PP +.B +int writecolmap(Display *d, RGB *map) +.fi +.SH DESCRIPTION +Colors are described by their red, green, and blue +light intensities, in an +.B RGB +datum: +.IP +.EX +.ta 6n +typedef +struct RGB { + ulong red; + ulong green; + ulong blue; +} RGB; +.EE +.PP +Black is represented by zero in all three positions and +white has the maximum +.B unsigned +.B long +value in all three positions. +.PP +A color map is an array of +.BR RGB s, +of length +.if t \x'-.8n'2\u\s-1\fIdepth\fP\s+1\d, +.if n 2^\fIdepth\fP, +giving the colors for pixels 0, 1, 2, etc. +On displays with color mapped pixels +(typically 8-bit displays), +one retrieves RGB color information +by treating the pixel data as an offset +into the color map. +.PP +.I Readcolmap +reads the color map for the given display into the provided +.IR map , +which must have enough space to hold it. +.I Writecolmap +associates the given color map with the given display, if possible. +(The hardware might not allow this.) +Both return 0 on success, or \-1 on error, setting +.IR errstr . +.PP +Changing the hardware color map does not change +the color map used by the +.IR draw (3) +operator to convert between +mapped and true color or greyscale images, +which is described in +.IR color (7). +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH "SEE ALSO" +.IR graphics (3), +.IR draw (3), +.IR color (7) diff --git a/man/man3/regexp.3 b/man/man3/regexp.3 index 92f07015..2d3c1a21 100644 --- a/man/man3/regexp.3 +++ b/man/man3/regexp.3 @@ -46,7 +46,7 @@ The space is allocated by and may be released by .IR free . Regular expressions are exactly as in -.IR regexp (6). +.IR regexp (7). .PP .I Regcomplit is like diff --git a/man/man3/regexp9.3 b/man/man3/regexp9.3 new file mode 100644 index 00000000..dc5e4340 --- /dev/null +++ b/man/man3/regexp9.3 @@ -0,0 +1,212 @@ +.TH REGEXP9 3 +.SH NAME +regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror \- regular expression +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <regexp.h> +.PP +.ta \w'\fLRegprog 'u +.B +Reprog *regcomp(char *exp) +.PP +.B +Reprog *regcomplit(char *exp) +.PP +.B +Reprog *regcompnl(char *exp) +.PP +.nf +.B +int regexec(Reprog *prog, char *string, Resub *match, int msize) +.PP +.nf +.B +void regsub(char *source, char *dest, int dlen, Resub *match, int msize) +.PP +.nf +.B +int rregexec(Reprog *prog, Rune *string, Resub *match, int msize) +.PP +.nf +.B +void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize) +.PP +.B +void regerror(char *msg) +.SH DESCRIPTION +.I Regcomp +compiles a +regular expression and returns +a pointer to the generated description. +The space is allocated by +.IR malloc (3) +and may be released by +.IR free . +Regular expressions are exactly as in +.IR regexp9 (7). +.PP +.I Regcomplit +is like +.I regcomp +except that all characters are treated literally. +.I Regcompnl +is like +.I regcomp +except that the +.B . +metacharacter matches all characters, including newlines. +.PP +.I Regexec +matches a null-terminated +.I string +against the compiled regular expression in +.IR prog . +If it matches, +.I regexec +returns +.B 1 +and fills in the array +.I match +with character pointers to the substrings of +.I string +that correspond to the +parenthesized subexpressions of +.IR exp : +.BI match[ i ].sp +points to the beginning and +.BI match[ i ].ep +points just beyond +the end of the +.IR i th +substring. +(Subexpression +.I i +begins at the +.IR i th +left parenthesis, counting from 1.) +Pointers in +.B match[0] +pick out the substring that corresponds to +the whole regular expression. +Unused elements of +.I match +are filled with zeros. +Matches involving +.LR * , +.LR + , +and +.L ? +are extended as far as possible. +The number of array elements in +.I match +is given by +.IR msize . +The structure of elements of +.I match +is: +.IP +.EX +typedef struct { + union { + char *sp; + Rune *rsp; + }; + union { + char *ep; + Rune *rep; + }; +} Resub; +.EE +.LP +If +.B match[0].sp +is nonzero on entry, +.I regexec +starts matching at that point within +.IR string . +If +.B match[0].ep +is nonzero on entry, +the last character matched is the one +preceding that point. +.PP +.I Regsub +places in +.I dest +a substitution instance of +.I source +in the context of the last +.I regexec +performed using +.IR match . +Each instance of +.BI \e n\f1, +where +.I n +is a digit, is replaced by the +string delimited by +.BI match[ n ].sp +and +.BI match[ n ].ep\f1. +Each instance of +.L & +is replaced by the string delimited by +.B match[0].sp +and +.BR match[0].ep . +The substitution will always be null terminated and +trimmed to fit into dlen bytes. +.PP +.IR Regerror , +called whenever an error is detected in +.IR regcomp , +writes the string +.I msg +on the standard error file and exits. +.I Regerror +can be replaced to perform +special error processing. +If the user supplied +.I regerror +returns rather than exits, +.I regcomp +will return 0. +.PP +.I Rregexec +and +.I rregsub +are variants of +.I regexec +and +.I regsub +that use strings of +.B Runes +instead of strings of +.BR chars . +With these routines, the +.I rsp +and +.I rep +fields of the +.I match +array elements should be used. +.SH SOURCE +.B /usr/local/plan9/src/libregexp +.SH "SEE ALSO" +.IR grep (1) +.SH DIAGNOSTICS +.I Regcomp +returns +.B 0 +for an illegal expression +or other failure. +.I Regexec +returns 0 +if +.I string +is not matched. +.SH BUGS +There is no way to specify or match a NUL character; NULs terminate patterns and strings. diff --git a/man/man3/rendezvous.3 b/man/man3/rendezvous.3 deleted file mode 100644 index 97128ce1..00000000 --- a/man/man3/rendezvous.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH RENDEZVOUS 3 -.SH NAME -rendezvous \- user level process synchronization -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -ulong rendezvous(ulong tag, ulong value) -.SH DESCRIPTION -The rendezvous system call allows two processes to synchronize and -exchange a value. -In conjunction with the shared memory system calls -(see -.IR segattach (3) -and -.IR fork (3)), -it enables parallel programs to control their scheduling. -.PP -Two processes wishing to synchronize call -.I rendezvous -with a common -.IR tag , -typically an address in -memory they share. -One process will arrive at the rendezvous first; -it suspends execution until a second arrives. -When a second process meets the rendezvous -the -.I value -arguments are exchanged between the processes and returned -as the result of the respective -.I rendezvous -system calls. -Both processes are awakened when -the rendezvous succeeds. -.PP -The set of tag values which two processes may use to rendezvous\(emtheir tag space\(emis -inherited when a process forks, unless -.B RFREND -is set in the argument to -.BR rfork ; -see -.IR fork (3). -.PP -If a rendezvous is interrupted the return value is -.BR ~0 , -so that value should not be used in normal communication. -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR segattach (3), -.IR fork (3) -.SH DIAGNOSTICS -Sets -.IR errstr . diff --git a/man/man3/rfork.3 b/man/man3/rfork.3 new file mode 100644 index 00000000..12cedda3 --- /dev/null +++ b/man/man3/rfork.3 @@ -0,0 +1,163 @@ +.TH RFORK 3 +.SH NAME +rfork \- manipulate process state +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.nf +.B +int rfork(int flags) +.fi +.SH DESCRIPTION +.I 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 +.IR fork (2). +It cannot be used to create shared-memory processes +(Plan 9's +.B RFMEM +flag); for that functionality use +.I proccreate +(see +.IR thread (3)). +.PP +The +.I flags +argument to +.I rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +.I Flags +is the logical OR of some subset of +.TF RFCNAMEG +.TP +.B RFPROC +If set a new process is created; otherwise changes affect the +current process. +.TP +.B RFNOWAIT +If set, the child process will be dissociated from the parent. Upon +exit the child will leave no +.B Waitmsg +(see +.IR wait (3)) +for the parent to collect. +.\" .TP +.\" .B RFNAMEG +.\" If set, the new process inherits a copy of the parent's name space; +.\" otherwise the new process shares the parent's name space. +.\" Is mutually exclusive with +.\" .BR RFCNAMEG . +.\" .TP +.\" .B RFCNAMEG +.\" If set, the new process starts with a clean name space. A new +.\" name space must be built from a mount of an open file descriptor. +.\" Is mutually exclusive with +.\" .BR RFNAMEG . +.\" .TP +.\" .B RFNOMNT +.\" If set, subsequent mounts into the new name space and dereferencing +.\" of pathnames starting with +.\" .B # +.\" are disallowed. +.\" .TP +.\" .B RFENVG +.\" If set, the environment variables are copied; +.\" otherwise the two processes share environment variables. +.\" Is mutually exclusive with +.\" .BR RFCENVG . +.\" .TP +.\" .B RFCENVG +.\" If set, the new process starts with an empty environment. +.\" Is mutually exclusive with +.\" .BR RFENVG . +.TP +.B RFNOTEG +Each process is a member of a group of processes that all +receive notes when a note is sent to the group +(see +.IR postnote (3) +and +.IR signal (2)). +The group of a new process is by default the same as its parent, but if +.B RFNOTEG +is set (regardless of +.BR RFPROC ), +the process becomes the first in a new group, isolated from +previous processes. +In Plan 9, a process can call +.B 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. +.TP +.B RFFDG +If set, the invoker's file descriptor table (see +.IR intro ( )) +is copied; otherwise the two processes share a +single table. +.\" .TP +.\" .B RFCFDG +.\" If set, the new process starts with a clean file descriptor table. +.\" Is mutually exclusive with +.\" .BR RFFDG . +.\" .TP +.\" .B RFREND +.\" If set, the process will be unable to +.\" .IR rendezvous (3) +.\" with any of its ancestors; its children will, however, be able to +.\" .B rendezvous +.\" with it. In effect, +.\" .B RFREND +.\" makes the process the first in a group of processes that share a space for +.\" .B rendezvous +.\" tags. +.\" .TP +.\" .B RFMEM +.\" If set, the child and the parent will share +.\" .B data +.\" and +.\" .B bss +.\" segments. +.\" Otherwise, the child inherits a copy of those segments. +.\" Other segment types, in particular stack segments, will be unaffected. +.\" May be set only with +.\" .BR RFPROC . +.PD +.PP +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.PP +If +.B 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 +.BR RFPROC , +the return value is zero. +Process ids range from 1 to the maximum integer +.RB ( int ) +value. +.I Rfork +will sleep, if necessary, until required process resources are available. +.PP +Calling +.B rfork(RFFDG|RFPROC) +is equivalent to calling +.IR fork (2). +.SH SOURCE +.B /usr/local/plan9/src/lib9/rfork.c +.SH DIAGNOSTICS +.I Rfork +sets +.IR errstr . diff --git a/man/man3/rsa.3 b/man/man3/rsa.3 index 56ad4c7e..c0b0fe9f 100644 --- a/man/man3/rsa.3 +++ b/man/man3/rsa.3 @@ -3,8 +3,10 @@ asn1dump, asn1toRSApriv, decodepem, +decodepemchain, rsadecrypt, rsaencrypt, +rsafill,, rsagen, rsaprivalloc, rsaprivfree, @@ -12,7 +14,9 @@ rsaprivtopub, rsapuballoc, rsapubfree, X509toRSApub, +X509dump, X509gen, +X509req, X509verify \- RSA encryption algorithm .SH SYNOPSIS .B #include <u.h> @@ -24,9 +28,13 @@ X509verify \- RSA encryption algorithm .B #include <libsec.h> .PP .B +.ta +\w'\fLPEMChain* 'u RSApriv* rsagen(int nlen, int elen, int nrep) .PP .B +RSApriv* rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint *q) +.PP +.B mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) .PP .B @@ -60,6 +68,12 @@ void asn1dump(uchar *der, int len) uchar* decodepem(char *s, char *type, int *len) .PP .B +PEMChain* decodepemchain(char *s, char *type) +.PP +.B +void X509dump(uchar *cert, int ncert) +.PP +.B uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); .PP .B @@ -113,6 +127,22 @@ public and private keys. returns a newly allocated copy of the public key corresponding to the private key. .PP +.I Rsafill +takes as input the bare minimum pieces of an RSA private key +and computes the rest +.RB ( kp , +.BR kq , +and +.BR c2 ). +It returns a new private key. +All the +.BR mpint s +in the key, +even the ones that correspond directly to +.IR rsafill 's +input parameters, +are freshly allocated, +.PP The routines .IR rsaalloc , .IR rsafree , @@ -148,6 +178,9 @@ checks the signature on .IR cert . It returns nil if successful, else an error string. .PP +.I X509dump +prints an X.509 certificate to standard ouptut. +.PP .I X509gen creates a self-signed X.509 certificate, given an RSA keypair .IR priv , @@ -162,7 +195,12 @@ The subject line is conventionally of the form "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric" .EE using the quoting conventions of -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). +.PP +.I X509req +creates an X.509 certification request. .PP .I Asn1toRSApriv converts an ASN1 formatted RSA private key into the corresponding @@ -186,6 +224,20 @@ If not, it returns and .BI * len is undefined. +.PP +.I Decodepemchain +is similar but expects a sequence of PEM-formatted sections +and returns a linked list of the decodings: +.IP +.EX +typedef struct PEMChain PEMChain +struct PEMChain +{ + PEMChain *next; + uchar *pem; + int pemlen; +}; +.EE .SH SOURCE .B /usr/local/plan9/src/libsec .SH SEE ALSO @@ -198,5 +250,5 @@ is undefined. .IR rc4 (3), .IR sechash (3), .IR prime (3), -.IR rand (3), -.IR x509 (8) +.IR rand (3) +.\" .IR pem (8) diff --git a/man/man3/rune.3 b/man/man3/rune.3 index 46895307..bc3dbe87 100644 --- a/man/man3/rune.3 +++ b/man/man3/rune.3 @@ -182,9 +182,9 @@ is the null string, returns .IR s1 . .SH SOURCE -.B /usr/local/plan9/src/libc/port/rune.c +.B /usr/local/plan9/src/lib9/utf/rune.c .br -.B /usr/local/plan9/src/libc/port/utfrune.c +.B /usr/local/plan9/src/lib9/utf/utfrune.c .SH SEE ALSO -.IR utf (6), +.IR utf (7), .IR tcs (1) diff --git a/man/man3/runestrcat.3 b/man/man3/runestrcat.3 index f5210c2a..dadcbcd2 100644 --- a/man/man3/runestrcat.3 +++ b/man/man3/runestrcat.3 @@ -58,7 +58,7 @@ These functions are rune string analogues of the corresponding functions in .IR strcat (3). .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3), diff --git a/man/man3/scsi.3 b/man/man3/scsi.3 new file mode 100644 index 00000000..5b6f24ce --- /dev/null +++ b/man/man3/scsi.3 @@ -0,0 +1,188 @@ +.TH SCSI 3 +.SH NAME +openscsi, scsiready, scsi, scsicmd, scsierror \- SCSI device operations +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.ft L +typedef struct Scsi { + char *inquire; + int rawfd; + int nchange; + ulong changetime; +}; +.ft +.PP +.B +Scsi* openscsi(char *devdir) +.PP +.B +void closescsi(Scsi *s) +.PP +.B +int scsiready(Scsi *s) +.PP +.B +int scsi(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +int scsicmd(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +char* scsierror(int asc, int ascq) +.PP +.B +int scsiverbose; +.SH DESCRIPTION +These routines provide an interface +to a SCSI or ATAPI device via Plan 9's +\fIsd\fR(3). +.PP +.I Openscsi +attempts to open the file +.IB devdir /raw +and use it to send raw SCSI commands. +On success, it reads the device's inquiry +string and stores it in in returned +.B Scsi +structure. +.I Closescsi +closes the connection and frees the +.B Scsi +structure. +.PP +.I Scsiready +sends the ``unit ready'' command up to three times, +returning zero if the unit responds that it is ready, +or \-1 on error. +.PP +.I Scsierror +returns a textual description of the SCSI status +denoted by the ASC and ASCQ sense codes. +The description is found by consulting +.BR /sys/lib/scsicodes . +The returned string will be overwritten by +the next call to +.IR scsierror . +.PP +.I Scsi +and +.I scsicmd +execute a single SCSI command on the named device. +There should be +.I ncmd +bytes of +command data in +.IR cmd ; +if +.I dir +is +.BR Sread , +a successful operation +will store up to +.I ndata +bytes into +.IR data , +returning the number of bytes stored. +If +.I dir +is +.BR Swrite , +the +.I ndata +bytes beginning at +.I data +are transmitted as the data argument to +the command, and the +number of bytes written is returned. +If +.I dir +is +.BR Snone , +.I data +and +.I ndata +are ignored. +On error, +.I scsi +and +.I scsicmd +return \-1. +.I Scsicmd +simply issues the command and +returns the result; +.I scsi +works a bit harder and +is the more commonly used routine. +.I Scsi +attempts to send the command; +if it is successful, +.I scsi +returns what +.I scsicmd +returned. +Otherwise, +.I scsi +sends a request sense command to +obtain the reason for the failure, +sends a unit ready command in +an attempt to bring the unit out of any +inconsistent states, and tries again. +If the second try fails, +.I scsi +sends the request +sense and unit ready commands +again +and then uses +.I scsierror +to set +.I errstr +with a reason for failure. +.PP +The +.B nchange +and +.B changetime +fields +in the +.B Scsi +structure +record the number of times a media +change has been detected, and the +time when the current media was +inserted into the drive (really the +first time a SCSI command was issued +after it was inserted). +They are maintained by +.IR scsi . +.PP +If +.I scsiverbose +is set, +these commands will produce a fair +amount of debugging output on file descriptor 2 +when SCSI commands fail. +.SH FILES +.TP +.B /sys/lib/scsicodes +List of textual messages corresponding to SCSI error codes; +consulted by +.BR scsierror . +.SH SOURCE +.B /usr/local/plan9/src/libdisk/scsi.c +.SH SEE ALSO +Plan 9's +\fIsd\fR(3) and +\fIscuzz\fR(8) +.SH BUGS +SCSI devices on Unix do not present the interface expected by +these routines. diff --git a/man/man3/seek.3 b/man/man3/seek.3 index 33966385..2ce4cff0 100644 --- a/man/man3/seek.3 +++ b/man/man3/seek.3 @@ -37,7 +37,7 @@ The new file offset value is returned. Seeking in a directory is not allowed. Seeking in a pipe is a no-op. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/seek.c .SH SEE ALSO .IR intro (3), .IR open (3) diff --git a/man/man3/sendfd.3 b/man/man3/sendfd.3 new file mode 100644 index 00000000..8090dfce --- /dev/null +++ b/man/man3/sendfd.3 @@ -0,0 +1,57 @@ +.TH SENDFD 3 +.SH NAME +sendfd, recvfd \- pass file descriptors along Unix domain sockets +.SH SYNOPSIS +.B +#include <u.h> +.PP +.B +#include <libc.h> +.PP +.B +int sendfd(int socket, int fd) +.PP +.B +int recvfd(int socket) +.SH DESCRIPTION +.I Recvfd +and +.I sendfd +can be used to pass an open file descriptor over +a Unix domain socket from one process to another. +Since +.IR pipe (3) +is implemented with +.IR socketpair (2) +instead of +.IR pipe (2), +.I socket +can be a file descriptor obtained from +.IR pipe (3). +.PP +.I Sendfd +sends the file descriptor +.I fd +along the socket to a process calling +.I recvfd +on the other end. +.PP +It is assumed that the two sides have coordinated +and agreed to transfer a file descriptor already, so +that the +.I sendfd +is met with a +.I recvfd +instead of an ordinary +.IR read . +.PP +The file descriptor number may change on its way +between processes, but the kernel structure it represents +will not. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sendfd.c +.SH SEE ALSO +.IR socketpair (2), +.I sendmsg +in +.IR send (2) diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 index b451c296..0ed7845f 100644 --- a/man/man3/setjmp.3 +++ b/man/man3/setjmp.3 @@ -86,9 +86,7 @@ setlabel(void) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/setjmp.s -.br -.B /usr/local/plan9/src/libc/$objtype/notejmp.c +.B /usr/local/plan9/src/lib9/jmp.c .SH SEE ALSO .IR notify (3) .SH BUGS diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 index 1872ab51..da2e6956 100644 --- a/man/man3/sleep.3 +++ b/man/man3/sleep.3 @@ -37,7 +37,7 @@ A zero argument clears the alarm. The return value is the amount of time previously remaining in the alarm clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/sleep.c .SH SEE ALSO .IR intro (3) .SH DIAGNOSTICS diff --git a/man/man3/stat.3 b/man/man3/stat.3 index a815550e..03f3abea 100644 --- a/man/man3/stat.3 +++ b/man/man3/stat.3 @@ -46,7 +46,7 @@ and are the system calls; they deal with machine-independent .IR "directory entries" . Their format is defined by -.IR stat (5). +.IR stat (9p). .I Stat and .I fstat @@ -67,7 +67,7 @@ write information back, thus changing file attributes according to the contents .IR edir . The data returned from the kernel includes its leading 16-bit length field as described in -.IR intro (5). +.IR intro (9p). For symmetry, this field must also be present when passing data to the kernel in a call to .I wstat and @@ -242,19 +242,15 @@ 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 -.IR intro (5) -for more information about permissions and -.IR users (6) -for users and groups). +.IR intro (9p) +for more information about permissions, users, and groups). The .B length can be changed by anyone with write permission, provided the operation is implemented by the server. (See -.IR intro (5) -for permission information, and -.IR users (6) -for user and group information). +.IR intro (9p) +for permission, user, and group information). .PP Special values in the fields of the .B Dir @@ -281,21 +277,12 @@ it is not necessary to use .I stat to retrieve the initial values first. .SH SOURCE -.TF /usr/local/plan9/src/libc/9syscall -.TP -.B /usr/local/plan9/src/libc/9syscall -for the -.RB non- dir -routines -.TP -.B /usr/local/plan9/src/libc/9sys -for the routines prefixed -.B dir +.B /usr/local/plan9/src/lib9/dirstat.c .SH SEE ALSO .IR intro (3), .IR fcall (3), .IR dirread (3), -.IR stat (5) +.IR stat (9p) .SH DIAGNOSTICS The .I dir diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 index 6e16158d..8fcf2ca6 100644 --- a/man/man3/strcat.3 +++ b/man/man3/strcat.3 @@ -242,11 +242,7 @@ returns .I Cistrstr operates analogously, but ignores ASCII case differences when comparing strings. .SH SOURCE -All these routines have portable C implementations in -.BR /usr/local/plan9/src/libc/port . -Many also have machine-dependent assembly language -implementations in -.BR /usr/local/plan9/src/libc/$objtype . +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3), diff --git a/man/man3/string.3 b/man/man3/string.3 index 0782b260..0b39d5c8 100644 --- a/man/man3/string.3 +++ b/man/man3/string.3 @@ -1,6 +1,6 @@ .TH STRING 3 .SH 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 \- extensible strings +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 .SH SYNOPSIS .B #include <u.h> .br @@ -8,6 +8,7 @@ s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_na .br .B #include <String.h> .PP +.ta +\w'\fLSinstack* 'u .B String* s_new(void) .br @@ -61,6 +62,15 @@ String* s_incref(String *s) String* s_unique(String *s) .PP .B +Sinstack* s_allocinstack(char *file) +.br +.B +void s_freeinstack(Sinstack *stack) +.br +.B +char* s_rdinstack(Sinstack *stack, String *s) +.PP +.B #include <bio.h> .PP .B @@ -222,14 +232,39 @@ An eof or error terminates the read. The string is null terminated. .PP .I S_getline -reads up to the next newline and returns +reads up to the next newline, appends the input to +.IR s , +and returns a pointer to the beginning of the bytes read. Leading spaces and tabs and the trailing newline are all discarded. .I S_getline -will recursively read through files included with +discards blank lines and lines beginning with +.LR # . +.I S_getline +ignores +newlines escaped by immediately-preceding backslashes. +.PP +.I S_allocinstack +allocates an input stack with the single file +.I file +open for reading. +.I S_freeinstack +frees an input stack. +.I S_rdinstack +reads a line from an input stack. +It follows the same rules as +.I s_getline +except that when it encounters a line of the form .B #include -and discard all other lines beginning with -.BR # . +.IR newfile , +.I s_getline +pushes +.I newfile +onto the input stack, postponing further reading of the current +file until +.I newfile +has been read. +The input stack has a maximum depth of 32 nested include files. .SH SOURCE .B /usr/local/plan9/src/libString .SH SEE ALSO diff --git a/man/man3/stringsize.3 b/man/man3/stringsize.3 index ac57f4a8..448df993 100644 --- a/man/man3/stringsize.3 +++ b/man/man3/stringsize.3 @@ -62,8 +62,8 @@ are analogous, but accept an array of runes rather than .IR subfont (3), .IR draw (3), .IR draw (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS Because strings are loaded dynamically, these routines may generate I/O to the server and produce calls to the graphics error function. diff --git a/man/man3/subfont.3 b/man/man3/subfont.3 index 980b93b2..4933c0d6 100644 --- a/man/man3/subfont.3 +++ b/man/man3/subfont.3 @@ -150,7 +150,7 @@ Although it is principally a routine internal to the library, may be substituted by the application to provide a less file-oriented subfont naming scheme. .PP The format of a subfont file is described in -.IR font (6). +.IR font (7). Briefly, it contains a image with all the characters in it, followed by a subfont header, followed by character information. .I Readsubfont @@ -228,8 +228,8 @@ bitmap font file tree .IR allocimage (3), .IR draw (3), .IR cachechars (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)). diff --git a/man/man3/sysfatal.3 b/man/man3/sysfatal.3 new file mode 100644 index 00000000..ea1a3df8 --- /dev/null +++ b/man/man3/sysfatal.3 @@ -0,0 +1,39 @@ +.TH SYSFATAL 3 +.SH NAME +sysfatal \- system error messages +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +void sysfatal(char *fmt, ...) +.SH DESCRIPTION +.I Sysfatal +prints to standard error the name of the running program, +a colon and a space, +the message described by the +.IR print (3) +format string +.I fmt +and subsequent arguments, and a newline. +It then calls +.IR exits (3) +with the formatted message as argument. +The program's name is the value of +.BR argv0 , +which will be set if the program uses the +.IR arg (3) +interface to process its arguments. +If +.B argv0 +is null, it is ignored and the following colon and space are suppressed. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sysfatal.c +.SH "SEE ALSO" +.IR intro (3), +.IR errstr (3), +the +.B %r +format in +.IR print (3) diff --git a/man/man3/thread.3 b/man/man3/thread.3 index 84ca69f8..05c19022 100644 --- a/man/man3/thread.3 +++ b/man/man3/thread.3 @@ -5,12 +5,10 @@ chancreate, chanfree, chaninit, chanprint, +chansetname, mainstacksize, proccreate, procdata, -procexec, -procexecl, -procrfork, recv, recvp, recvul, @@ -25,6 +23,8 @@ nbsendp, nbsendul, threadcreate, threaddata, +threadexec, +threadexecl, threadexits, threadexitsall, threadgetgrp, @@ -33,12 +33,15 @@ threadint, threadintgrp, threadkill, threadkillgrp, +threadlinklibrary, threadmain, threadnotify, threadid, threadpid, threadsetgrp, threadsetname, +threadsetstate, +threadspawn, threadwaitchan, yield \- thread and proc management .SH SYNOPSIS @@ -71,6 +74,7 @@ struct Alt { int op; Channel **tag; int entryno; + char *name; }; .fi .de XX @@ -126,8 +130,9 @@ int nbsendp(Channel *c, void *v) int nbsendul(Channel *c, ulong v) int chanprint(Channel *c, char *fmt, ...) .XX -int procexecl(Channel *cpid, char *file, ...) -int procexec(Channel *cpid, char *file, char *args[]) +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) .XX int threadnotify(int (*f)(void*, char*), int in) @@ -179,31 +184,31 @@ on a stack of size .IR stacksize . Thread stacks are allocated in shared memory, making it valid to pass pointers to stack variables between threads and procs. -.I Procrfork +.I Proccreate creates a new proc, and inside that proc creates a single thread as .I threadcreate would, returning the id of the created thread. -.I Procrfork -creates the new proc by calling -.B rfork -(see -.IR fork (3)) -with flags -.BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. -(The thread library depends on all its procs -running in the same rendezvous group. -Do not include -.B RFREND -in -.IR rforkflag .) -.I Proccreate -is identical to -.I procrfork -with -.I rforkflag -set to zero. +.\" .I Procrfork +.\" creates the new proc by calling +.\" .B rfork +.\" (see +.\" .IR fork (3)) +.\" with flags +.\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. +.\" (The thread library depends on all its procs +.\" running in the same rendezvous group. +.\" Do not include +.\" .B RFREND +.\" in +.\" .IR rforkflag .) +.\" .I Proccreate +.\" is identical to +.\" .I procrfork +.\" with +.\" .I rforkflag +.\" set to zero. Be aware that the calling thread may continue execution before the newly created proc and thread @@ -226,6 +231,11 @@ using .I status as the exit status. .PP +When the last thread in +.IR 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. +.PP The threads in a proc are coroutines, scheduled nonpreemptively in a round-robin fashion. A thread must explicitly relinquish control of the processor @@ -233,9 +243,10 @@ before another thread in the same proc is run. Calls that do this are .IR yield , .IR proccreate , -.IR procexec , -.IR procexecl , +.IR threadexec , +.IR threadexecl , .IR threadexits , +.IR threadspawn , .IR alt , .IR send , and @@ -307,6 +318,17 @@ The pointer returned by is only valid until the next call to .IR threadsetname . .PP +Also for debugging, +threads have a string state associated with them. +.I Threadsetstate +sets the state string. +There is no +.IR threadgetstate ; +since the thread scheduler resets the state to +.B Running +every time it runs the thread, +it is only useful for debuggers to inspect the state. +.PP .I Threaddata returns a pointer to a per-thread pointer that may be modified by threaded programs for @@ -315,9 +337,9 @@ Similarly, .I procdata returns a pointer to a per-proc pointer. .PP -.I Procexecl +.I Threadexecl and -.I procexec +.I threadexec are threaded analogues of .I exec and @@ -325,30 +347,67 @@ and (see .IR exec (3)); on success, -they replace the calling thread (which must be the only thread in its proc) +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\(emthe other +threads will continue executing.) On error, they return \-1. If .I cpid is not null, the pid of the invoked program will be sent along .I cpid +(using +.IR sendul ) once the program has been started, or \-1 will be sent if an error occurs. -.I Procexec +.I Threadexec and -.I procexecl +.I threadexecl will not access their arguments after sending a result along .IR cpid . Thus, programs that malloc the .I argv passed to -.I procexec +.I threadexec can safely free it once they have received the .I cpid response. +.PP +.I Threadexecl +and +.I threadexec +will duplicate +(see +.IR dup (3)) +the three file descriptors in +.I fd +onto standard input, output, and error for the external program +and then close them in the calling thread. +Beware of code that sets +.IP +.EX +fd[0] = 0; +fd[1] = 1; +fd[2] = 2; +.EE +to use the current standard files. The correct code is +.IP +.EX +fd[0] = dup(0, -1); +fd[1] = dup(1, -1); +fd[2] = dup(2, -1); +.EE +.PP +.I Threadspawn +is like +.I threadexec +but does not replace the current thread. +It returns the pid of the invoked program on success, or +\-1 on error. +.PP .I Threadwaitchan returns a channel of pointers to .B Waitmsg @@ -398,6 +457,14 @@ blocked on it until that thread unblocks (but .I chanfree returns immediately). .PP +The +.B name +element in the +.B Channel +structure is a description intended for use in debugging. +.I Chansetname +sets the name. +.PP .I Send sends the element pointed at by .I v @@ -536,49 +603,97 @@ in place of .IR notify (3)). .PP It is safe to use -.B sysfatal -(see -.IR perror (3)) +.IR sysfatal (3) in threaded programs. .I Sysfatal will print the error string and call .IR threadexitsall . .PP -It is safe to use +It is not safe to call .IR rfork -(see -.IR fork (3)) -to manage the namespace, file descriptors, note group, and environment of a -single process. -That is, it is safe to call -.I rfork -with the flags -.BR RFNAMEG , -.BR RFFDG , -.BR RFCFDG , -.BR RFNOTEG , -.BR RFENVG , -and -.BR RFCENVG. -(To create new processes, use -.I proccreate -and -.IR procrfork .) -As mentioned above, -the thread library depends on all procs being in the -same rendezvous group; do not change the rendezvous -group with -.IR rfork . +in a threaded program, except to call +.B rfork(RFNOTEG) +from the main proc before any other procs have been created. +To create new processes, use +.IR proccreate . +.\" .PP +.\" It is safe to use +.\" .IR rfork +.\" (see +.\" .IR fork (3)) +.\" to manage the namespace, file descriptors, note group, and environment of a +.\" single process. +.\" That is, it is safe to call +.\" .I rfork +.\" with the flags +.\" .BR RFNAMEG , +.\" .BR RFFDG , +.\" .BR RFCFDG , +.\" .BR RFNOTEG , +.\" .BR RFENVG , +.\" and +.\" .BR RFCENVG. +.\" (To create new processes, use +.\" .I proccreate +.\" and +.\" .IR procrfork .) +.\" As mentioned above, +.\" the thread library depends on all procs being in the +.\" same rendezvous group; do not change the rendezvous +.\" group with +.\" .IR rfork . .SH FILES .B /usr/local/plan9/acid/thread contains useful .IR acid (1) functions for debugging threaded programs. .PP -.B /usr/local/plan9/src/libthread/example.c -contains a full example program. +.B /usr/local/plan9/src/libthread/test +contains some example programs. .SH SOURCE .B /usr/local/plan9/src/libthread .SH SEE ALSO .IR intro (3), .IR ioproc (3) +.SH BUGS +A program that intends to use the thread library +but does not call any of its functions will not cause Unix linkers +to link the thread library, resulting in the unintelligible error: +.IP +.EX +/usr/local/plan9/lib/lib9.a(main.o)(.text+0x17): In function `main': +/usr/local/plan9/src/lib9/main.c:10: undefined reference to `p9main' +.EE +.LP +or similar. To force the thread library to be linked properly in such cases, +insert a call to the no-op function +.I threadlinklibrary +somewhere in your program. +.PP +To avoid name conflicts, +.IR alt , +.IR nbrecv , +.IR nbrecvp , +.IR nbrecvul , +.IR nbsend , +.IR nbsendp , +.IR nbsendul , +.IR recv , +.IR recvp , +.IR recvul , +.IR send , +.IR sendp , +and +.IR sendul +are defined as macros that expand to +.IR chanalt , +.IR channbrecv , +and so on. +Similarly, +.I yield +is defined as a macro that expands to +.IR threadyield . +.PP +The implementation of +.I threadnotify +may not be correct. diff --git a/man/man3/time.3 b/man/man3/time.3 index 90ec7311..6f3cbcd2 100644 --- a/man/man3/time.3 +++ b/man/man3/time.3 @@ -26,20 +26,8 @@ if is not zero then .BI * tp is also set to the answer. -.PP -These functions work by reading -.BR /dev/bintime , -opening that file when -.I they -are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/time.c -.br -.B /usr/local/plan9/src/libc/9sys/nsec.c -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c .SH DIAGNOSTICS -Sets +These functions set .IR errstr . -.SH BUGS -These routines maintain a static file descriptor. diff --git a/man/man3/udpread.3 b/man/man3/udpread.3 new file mode 100644 index 00000000..3a0a7ea6 --- /dev/null +++ b/man/man3/udpread.3 @@ -0,0 +1,68 @@ +.TH UDPREAD 3 +.SH NAME +udpread, udpwrite \- read and write UDP packets +.SH SYNOPSIS +.B #include <u.h> +.PP +.B #include <libc.h> +.PP +.B #include <ip.h> +.PP +.B +.nf +.ta +4n +8n +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]; +}; +.PP +.B +long udpread(int fd, Udphdr *hdr, void *data, long n) +.PP +.B +long udpwrite(int fd, Udphdr *hdr, void *data, long n) +.SH DESCRIPTION +.I Udpread +and +.I udpwrite +read and write UDP packets from the UDP network connection +established on file descriptor +.IR fd . +.PP +.I Udpread +reads at most +.I n +bytes of packet body into +.I data , +stores the header in +.IR hdr , +and returns the number of bytes stored in +.IR data . +.PP +.I Udpwrite +writes the +.I n +bytes stored in +.I data +in a UDP packet with header +.IR hdr . +.PP +Note that the +.B Udphdr +frames the addresses as local and remote +instead of source and destination. +Thus the +.I hdr +filled in for a packet read by +.I udpread +can be used unchanged in +.I udpwrite +to send a response back to the sender of the original packet. +.SH SOURCE +.B /usr/local/plan9/src/lib9/udp.c +.SH SEE ALSO +.IR ip (3) diff --git a/man/man3/wait.3 b/man/man3/wait.3 index b8b5c7fd..03b55bf2 100644 --- a/man/man3/wait.3 +++ b/man/man3/wait.3 @@ -1,6 +1,6 @@ .TH WAIT 3 .SH NAME -await, wait, waitpid \- wait for a process to exit +await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid \- wait for a process to exit .SH SYNOPSIS .B #include <u.h> .br @@ -10,14 +10,28 @@ await, wait, waitpid \- wait for a process to exit Waitmsg* wait(void) .PP .B +Waitmsg* waitnohang(void) +.PP +.B +Waitmsg* waitfor(int pid) +.PP +.B int waitpid(void) .PP .B int await(char *s, int n) +.PP +.B +int awaitnohang(char *s, int n) +.PP +.B +int awaitfor(int pid, char *s, int n) .SH DESCRIPTION .I Wait causes a process to wait for any child process (see -.IR fork (3)) +.IR fork (2) +and +.IR rfork (3)) to exit. It returns a .B Waitmsg @@ -70,16 +84,33 @@ For programs that only need the pid of the exiting program, .I waitpid returns just the pid and discards the rest of the information. .PP -The underlying system call is +.I Waitnohang +is like +.I wait +but does not block if there are no more children to wait for. +Instead it returns immediately and sets +.IR errstr . +.PP +.I Waitfor +is like +.I wait +but waits for a particular +.IR pid . +.PP +The underlying calls are .IR await , -which fills in the n-byte buffer +.IR awaitnohang , +and +.IR awaitfor , +which fill in the +.IR n -byte +buffer .I 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. .PP -The buffer filled in by -.I await +The filled-in buffer may be parsed (after appending a NUL) using .IR tokenize (see @@ -104,14 +135,12 @@ If the calling process has no living children, returns .BR -1 . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/wait.c +.PP +.B /usr/local/plan9/src/lib9/await.c .SH "SEE ALSO" -.IR fork (3), +.IR rfork (3), .IR exits (3), -the -.B wait -file in -.IR proc (3) .SH DIAGNOSTICS These routines set .IR errstr . diff --git a/man/man3/wctl.3 b/man/man3/wctl.3 new file mode 100644 index 00000000..dfed6fcb --- /dev/null +++ b/man/man3/wctl.3 @@ -0,0 +1,39 @@ +.TH WCTL 3 +.SH NAME +drawresizewindow, drawsetlabel, drawtopwindow \- window management +.SH SYNOPSIS +.B #include <draw.h> +.PP +.B +void drawresizewindow(Rectangle r) +.PP +.B +int drawsetlabel(Display *d, char *name) +.PP +.B +void drawtopwindow(void) +.SH 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 +.IR rio 's +.BR /dev/wctl . +.PP +.I Drawresizewindow +requests that the program's window be resized to have the +width and height of the rectangle +.IR r . +Only the width and height +are important; the offset is ignored. +.PP +.I Drawsetlabel +requests that the program's window title be set to +.IR name . +.PP +.I Drawtopwindow +requests that the program's window be moved +above all other windows and given the input focus. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-init.c +.br +.B /usr/local/plan9/src/libdraw/x11-wsys.c diff --git a/man/man3/window.3 b/man/man3/window.3 new file mode 100644 index 00000000..6f140603 --- /dev/null +++ b/man/man3/window.3 @@ -0,0 +1,244 @@ +.TH WINDOW 3 +.SH NAME +Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow \- window management +.SH SYNOPSIS +.nf +.B +#include <u.h> +.B +#include <libc.h> +.B +#include <draw.h> +.PP +.ft L +.nf +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; +.fi +.ta \w'\fLScreen* 'u +.PP +.B +Screen* allocscreen(Image *image, Image *fill, int public) +.PP +.B +Screen* publicscreen(Display *d, int id, ulong chan) +.PP +.B +int freescreen(Screen *s) +.PP +.B +Image* allocwindow(Screen *s, Rectangle r, int ref, int val) +.PP +.B +void bottomwindow(Image *w) +.PP +.B +void bottomnwindows(Image **wp, int nw) +.PP +.B +void topwindow(Image *w) +.PP +.B +void topnwindows(Image **wp, int nw) +.PP +.B +int originwindow(Image *w, Point log, Point scr) +.PP +.ft L +.nf +enum +{ + /* refresh methods */ + Refbackup = 0, + Refnone = 1, + Refmesg = 2 +}; +.fi +.ft P +.SH DESCRIPTION +Windows are represented as +.B 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. +.PP +To create windows, it is first necessary to allocate a +.B Screen +data structure to gather them together. +A +.B Screen +turns an arbitrary image into something that may have windows upon it. +It is created by +.BR allocscreen , +which takes an +.I image +upon which to place the windows (typically +.BR display->image ), +a +.I 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 +.B publicscreen +with the +.B Display +pointer and the +.I id +of the published +.BR 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. +.B Freescreen +releases a +.BR Screen , +although it may not actually disappear from view until all the windows upon it have also been deallocated. +.PP +Unlike +.BR allocwindow , +.B allocscreen +does +.I not +initialize the appearance of the +.BR Screen . +.PP +Windows are created by +.BR allocwindow , +which takes a pointer to the +.B Screen +upon which to create the window, a rectangle +.I r +defining its geometry, an integer pixel value +.I val +to color the window initially, and a refresh method +.BR ref . +The refresh methods are +.BR Refbackup , +which provides backing store and is the method used by +.IR rio (1) +for its clients; +.BR 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 +.BR Refmesg , +which causes messages to be delivered to the owner of the window +when it needs to be repainted. +.B Refmesg +is not fully implemented. +.PP +The result of +.B allocwindow +is an +.B Image +pointer that may be treated like any other image. +In particular, it is freed by calling +.B freeimage +(see +.IR allocimage (3)). +The following functions, however, apply only to windows, not regular images. +.PP +.B Bottomwindow +pushes window +.I w +to the bottom of the stack of windows on its +.BR Screen , +perhaps obscuring it. +.B Topwindow +pulls window +.I w +to the top, making it fully visible on its +.BR Screen . +(This +.B Screen +may itself be within a window that is not fully visible; +.B topwindow +will not affect the stacking of this parent window.) +.B Bottomnwindows +and +.B Topnwindows +are analogous, but push or pull a group of +.I nw +windows listed in the array +.IR wp . +The order within +.IR wp +is unaffected. +.PP +Each window is created as an +.B Image +whose +.B Rectangle +.B r +corresponds to the rectangle given to +.B allocwindow +when it was created. Thus, a newly created window +.I w +resides on its +.B Screen->image +at +.IB w ->r +and has internal coordinates +.IB w ->r . +Both these may be changed by a call to +.BR originwindow . +The two +.B Point +arguments to +.B originwindow +define the upper left corner of the logical coordinate system +.RI ( log ) +and screen position +.RI ( scr ). +Their usage is shown in the Examples section. +.PP +.IR Rio (1) +creates its client windows with backing store, +.BR Refbackup . +The graphics initialization routine, +.B initdraw +(see +.IR graphics (3)), +builds a +.B Screen +upon this, and then allocates upon that another window indented +to protect the border. That window is created +.BR Refnone , +since the backing store created by +.B rio +protects its contents. That window is the one known in the +library by the global name +.B screen +(a historic but confusing choice). +.SH EXAMPLES +To move a window to the upper left corner of the display, +.EX + originwindow(w, w->r.min, Pt(0, 0)); +.EE +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, +.EX + originwindow(w, Pt(0, 0), w->r.min); +.EE +After this is done, +.B 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. +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH SEE ALSO +.IR graphics (3), +.IR draw (3), +.IR cachechars (3), +.IR draw (3) +.SH BUGS +The refresh method +.B Refmesg +should be finished. |