.\" 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_CTX_NEW 2" .TH DC_CTX_NEW 2 "2004.03.23" "1.4.5" "distcache" .SH "NAME" DC_CTX_new, DC_CTX_free, DC_CTX_add_session, DC_CTX_remove_session, DC_CTX_get_session, DC_CTX_reget_session, DC_CTX_has_session \- distcache blocking client API .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include .Ve .PP .Vb 15 \& DC_CTX *DC_CTX_new(const char *target, unsigned int flags); \& void DC_CTX_free(DC_CTX *ctx); \& int DC_CTX_add_session(DC_CTX *ctx, const unsigned char *id_data, \& unsigned int id_len, const unsigned char *sess_data, \& unsigned int sess_len, unsigned long timeout_msecs); \& int DC_CTX_remove_session(DC_CTX *ctx, const unsigned char *id_data, \& unsigned int id_len); \& int DC_CTX_get_session(DC_CTX *ctx, const unsigned char *id_data, \& unsigned int id_len, unsigned char *result_storage, \& unsigned int result_size, unsigned int *result_used); \& int DC_CTX_reget_session(DC_CTX *ctx, const unsigned char *id_data, \& unsigned int id_len, unsigned char *result_storage, \& unsigned int result_size, unsigned int *result_used); \& int DC_CTX_has_session(DC_CTX *ctx, const unsigned char *id_data, \& unsigned int id_len); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIDC_CTX_new()\fR allocates and initialises a \fB\s-1DC_CTX\s0\fR structure with an address for sending session caching operation requests to, and flags controlling the behaviour of the \fB\s-1DC_CTX\s0\fR object. The address specified by \fBtarget\fR should be compatible with the syntax defined by the \fIlibnal\fR \s-1API\s0, see the \*(L"\s-1NOTES\s0\*(R" section below. The \fBflags\fR parameter can be zero to indicate that each cache operation should create and destroy a temporary connection, otherwise a bitmask combining one or more of the following flags; .PP .Vb 4 \& #define DC_CTX_FLAG_PERSISTENT (unsigned int)0x0001 \& #define DC_CTX_FLAG_PERSISTENT_PIDCHECK (unsigned int)0x0002 \& #define DC_CTX_FLAG_PERSISTENT_RETRY (unsigned int)0x0004 \& #define DC_CTX_FLAG_PERSISTENT_LATE (unsigned int)0x0008 .Ve .PP \&\fIDC_CTX_free()\fR frees the \fBctx\fR object. .PP \&\fIDC_CTX_add_session()\fR attempts to add session data to the cache. \fBid_data\fR and \&\fBid_len\fR define the unique session \s-1ID\s0 corresponding to the session data \- this is the \s-1ID\s0 used in \fIDC_CTX_get_session()\fR or \fIDC_CTX_remove_session()\fR to refer to the session being added, and the ``add'' operation will fail if there is already a session with a matching \s-1ID\s0 in the cache. \fBsess_data\fR and \fBsess_len\fR define the session data itself to be stored in the cache. \fBtimeout_msecs\fR specifies the expiry period for the session \- if this period of time passes without the corresponding session being explicitly removed nor scrolled out of the cache because of over\-filling, then the cache server will remove the session from the cache anyway. .PP \&\fIDC_CTX_remove_session()\fR provides a session \s-1ID\s0 with \fBid_data\fR and \fBid_len\fR and requests that the corresponding session be removed from the cache. .PP \&\fIDC_CTX_get_session()\fR provides a session \s-1ID\s0 with \fBid_data\fR and \fBid_len\fR and requests that the corresponding session data be retrieved from the cache. \&\fBresult_storage\fR and \fBresult_size\fR specify a storage area for the retrieved session data, and \fBresult_used\fR points to a variable that will be set to the length of the retrieved session data. Even if \fIDC_CTX_get_session()\fR returns successfully, the caller should check the value of \fBresult_used\fR \- if it is larger than \fBresult_size\fR then the requested session data was too big for the provided storage area and only partial data will have been returned. In this case, the caller should immediately call \fIDC_CTX_reget_session()\fR. .PP \&\fIDC_CTX_reget_session()\fR is similar to \fIDC_CTX_get_session()\fR except that it does not perform any network operations at all. It is designed to return session data that had previously been retrieved by \fIDC_CTX_get_session()\fR, so that a larger storage area can be provided if the one first provided to \&\fIDC_CTX_get_session()\fR was too small. This function will fail if the last operation on \fBctx\fR was not \fIDC_CTX_get_session()\fR with an exact match for \&\fBid_data\fR and \fBid_len\fR. .PP \&\fIDC_CTX_has_session()\fR is similar to \fIDC_CTX_get_session()\fR except that it does not ask for session data to be returned, merely to know whether the session is in the cache or not. This should be used by any application that already has a copy of the required session but merely wishes to verify that it hasn't already been explicitly invalidated. As distcache allows parallel use of a single cache from multiple clients across potentially multiple machines, it is a security flaw for any client (thread, process, or machine) to implement local session caching and using its sessions whenever there is a cache\-hit. If the session was used and for any reason required invalidation (eg. renegotiation, data corruption detected, etc) then another client should not use a locally cached copy of the session without first verifying with the shared cache that the session is still \s-1OK\s0. This function should be used in such cases as it provides the same check as \fIDC_CTX_get_session()\fR but with less network overhead. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fIDC_CTX_new()\fR returns a valid \fB\s-1DC_CTX\s0\fR object on success, otherwise \s-1NULL\s0 for failure. .PP \&\fIDC_CTX_free()\fR has no return type. .PP All other \fB\s-1DC_CTX\s0\fR functions return zero on failure, otherwise non\-zero. .SH "NOTES" .IX Header "NOTES" The following code snippet attempts to create a session cache context that uses a temporary connection for each operation to a local \fBdc_client\fR agent running on a unix domain socket at /tmp/dc_client; .PP .Vb 1 \& DC_CTX *ctx = DC_CTX_new("UNIX:/tmp/dc_client", 0); .Ve .PP The following code snippet attempts to create a session cache context to communicate with a remote server listening on TCP/IPv4 port 9001. It will attempt to use a persistent connection for all cache operations (\s-1DC_CTX_FLAG_PERSISTENT\s0), retry once for any cache operation that suffers a network I/O error (\s-1DC_CTX_FLAG_PERSISTENT_RETRY\s0), will wait until the first cache operation before trying to connect (\s-1DC_CTX_FLAG_PERSISTENT_LATE\s0), and will verify before any cache operation whether it is running in a different process than it used to be and if so will close then re-open a new connection (\s-1DC_CTX_FLAG_PERSISTENT_PIDCHECK\s0). .PP .Vb 3 \& DC_CTX *ctx = DC_CTX_new("IP:cacheserver.localnet", \& DC_CTX_FLAG_PERSISTENT | DC_CTX_FLAG_PERSISTENT_PIDCHECK | \& DC_CTX_FLAG_PERSISTENT_RETRY | DC_CTX_FLAG_PERSISTENT_LATE); .Ve .PP The \s-1DC_CTX_FLAG_PERSISTENT_RETRY\s0 flag exists because of the \fB\-idle\fR command-line switch in the \fIdc_client\fR\|(1) tool. This switch allows \fBdc_client\fR to automatically close client connections that have been idle for some configurable length of time. However, this creates the possiblity for race conditions if a persistent \fB\s-1DC_CTX\s0\fR is used by an application to request a cache operation at the same time or following a decision by \fBdc_client\fR to close the connection. The most robust way to address this is to have \s-1DC_CTX\s0 regard any first network error during the operation as an idle-timeout from the peer and to immediately re-connect and retry the operation. Any subsequent error (or initial error that can not be timeout\-related, such as connection failure) is considered a failure and will not result in any retry. .PP The \s-1DC_CTX_FLAG_PERSISTENT_PIDCHECK\s0 flag exists for software like Apache or Stunnel that use \fIfork\fR\|(2) or \fIclone\fR\|(2) to create child processes that inherit file-descriptors from the parent process. In such circumstances, attempts by the parent and child processes to communicate over the same file-descriptor can have unpredictable results and is, generally speaking, never useful. This flag will force a check before each operation that the process \s-1ID\s0 is ``what it used to be'' and if not, will close any persistent connection, reconnect with a new file\-descriptor, and reset the process \s-1ID\s0 in the \fB\s-1DC_CTX\s0\fR. If a parent process has a \fB\s-1DC_CTX\s0\fR that has a connection open, this flag will ensure that any subsequent child processes that attempt to perform cache operations will transparently reconnect with their own connections. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIDC_PLUG_new\fR\|(2), \fIDC_PLUG_read\fR\|(2) \- Lower-level asynchronous implementation of the distcache protocol, useful for client and server operation. This \&\fB\s-1DC_CTX\s0\fR implementation is built on top of the \fB\s-1DC_PLUG\s0\fR functionality. .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