.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DC_PLUG_READ 2" .TH DC_PLUG_READ 2 "2004.03.23" "1.4.5" "distcache" .SH "NAME" DC_PLUG_read, DC_PLUG_consume, DC_PLUG_write, DC_PLUG_write_more, DC_PLUG_commit, DC_PLUG_rollback \- DC_PLUG read/write functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include .Ve .PP .Vb 11 \& int DC_PLUG_read(DC_PLUG *plug, int resume, unsigned long *request_uid, \& DC_CMD *cmd, const unsigned char **payload_data, \& unsigned int *payload_len); \& int DC_PLUG_consume(DC_PLUG *plug); \& int DC_PLUG_write(DC_PLUG *plug, int resume, unsigned long request_uid, \& DC_CMD cmd, const unsigned char *payload_data, \& unsigned int payload_len); \& int DC_PLUG_write_more(DC_PLUG *plug, const unsigned char *data, \& unsigned int data_len); \& int DC_PLUG_commit(DC_PLUG *plug); \& int DC_PLUG_rollback(DC_PLUG *plug); .Ve .PP .Vb 7 \& typedef enum { \& DC_CMD_ERROR, \& DC_CMD_ADD, \& DC_CMD_GET, \& DC_CMD_REMOVE, \& DC_CMD_HAVE \& } DC_CMD; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIDC_PLUG_read()\fR will attempt to open the next distcache message received by \&\fBplug\fR for reading. This message will block the reading of any other received messages remain until \fIDC_PLUG_consume()\fR is called. If a message has already been opened for reading inside \fBplug\fR, then \fIDC_PLUG_read()\fR will fail unless \&\fBresume\fR is set to non-zero in which case it will simply re-open the message that was already being read. If \fIDC_PLUG_read()\fR succeeds, \fBrequest_uid\fR, \&\fBcmd\fR, \fBpayload_data\fR and \fBpayload_len\fR are populated with the message's data. Note that \fBpayload_data\fR points to the original data stored inside \&\fBplug\fR and this pointer is only valid until the next call to \&\fIDC_PLUG_consume()\fR. .PP \&\fIDC_PLUG_consume()\fR will close the message currently opened for reading in \&\fBplug\fR, and will allow a future call to \fIDC_PLUG_read()\fR to succeed if there any subsequent (complete) messages received from the plug object's connection. .PP \&\fIDC_PLUG_write()\fR will attempt to open a distcache message for writing in \&\fBplug\fR. If successful, this message will block the writing of any other messages until the message is committed with \fIDC_PLUG_commit()\fR or discarded with \&\fIDC_PLUG_rollback()\fR. If a message has already been opened for writing, \&\fIDC_PLUG_write()\fR will fail unless \fBresume\fR is non-zero in which case the message will be re-opened and will overwrite the settings from the previous \&\fIDC_PLUG_write()\fR call. This is equivalent to \fIDC_PLUG_rollback()\fR followed immediately by \fIDC_PLUG_write()\fR with a zero \fBresume\fR value. Note that \&\fBpayload_len\fR can be zero (and thus \fBpayload_data\fR can be \s-1NULL\s0) even if the message will eventually have payload data \- this can be supplemented afterwards using the \fIDC_PLUG_write_more()\fR function. \fBrequest_uid\fR and \fBcmd\fR, on the other hand, must be specified at once in \fIDC_PLUG_write()\fR. .PP \&\fIDC_PLUG_write_more()\fR will attempt to add more payload data to the message currently opened for writing in \fBplug\fR. This data will be concatenated to the end of any payload data already provided in prior calls to \fIDC_PLUG_write()\fR or \&\fIDC_PLUG_write_more()\fR. .PP \&\fIDC_PLUG_commit()\fR will close the message currently opened for writing, and queue it for serialisation out on the plug object's connection. .PP \&\fIDC_PLUG_rollback()\fR will discard the message currently opened for writing. .SH "RETURN VALUES" .IX Header "RETURN VALUES" All these \fB\s-1DC_PLUG\s0\fR functions return zero on failure, otherwise non\-zero. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIDC_PLUG_new\fR\|(2) \- Basic \fB\s-1DC_PLUG\s0\fR functions. .PP \&\fIdistcache\fR\|(8) \- Overview of the distcache architecture. .PP \&\fIhttp://www.distcache.org/\fR \- Distcache home page. .SH "AUTHOR" .IX Header "AUTHOR" This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at \fIgeoff@geoffthorpe.net\fR. .PP Home Page: \fIhttp://www.distcache.org\fR