1DC_CTX_NEW(2) distcache DC_CTX_NEW(2)
2
6 DC_CTX_new, DC_CTX_free, DC_CTX_add_session, DC_CTX_remove_session,
7 DC_CTX_get_session, DC_CTX_reget_session, DC_CTX_has_session - dist‐
8 cache blocking client API
9
11 #include <distcache/dc_client.h>
12 DC_CTX *DC_CTX_new(const char *target, unsigned int flags);
14 void DC_CTX_free(DC_CTX *ctx);
15 int DC_CTX_add_session(DC_CTX *ctx, const unsigned char *id_data,
16 unsigned int id_len, const unsigned char *sess_data,
17 unsigned int sess_len, unsigned long timeout_msecs);
18 int DC_CTX_remove_session(DC_CTX *ctx, const unsigned char *id_data,
19 unsigned int id_len);
20 int DC_CTX_get_session(DC_CTX *ctx, const unsigned char *id_data,
21 unsigned int id_len, unsigned char *result_storage,
22 unsigned int result_size, unsigned int *result_used);
23 int DC_CTX_reget_session(DC_CTX *ctx, const unsigned char *id_data,
24 unsigned int id_len, unsigned char *result_storage,
25 unsigned int result_size, unsigned int *result_used);
26 int DC_CTX_has_session(DC_CTX *ctx, const unsigned char *id_data,
27 unsigned int id_len);
28
30 DC_CTX_new() allocates and initialises a DC_CTX structure with an
31 address for sending session caching operation requests to, and flags
32 controlling the behaviour of the DC_CTX object. The address specified
33 by target should be compatible with the syntax defined by the libnal
34 API, see the "NOTES" section below. The flags parameter can be zero to
35 indicate that each cache operation should create and destroy a tempo‐
36 rary connection, otherwise a bitmask combining one or more of the fol‐
37 lowing flags;
38 #define DC_CTX_FLAG_PERSISTENT (unsigned int)0x0001
40 #define DC_CTX_FLAG_PERSISTENT_PIDCHECK (unsigned int)0x0002
41 #define DC_CTX_FLAG_PERSISTENT_RETRY (unsigned int)0x0004
42 #define DC_CTX_FLAG_PERSISTENT_LATE (unsigned int)0x0008
43 DC_CTX_free() frees the ctx object.
45 DC_CTX_add_session() attempts to add session data to the cache. id_data
47 and id_len define the unique session ID corresponding to the session
48 data - this is the ID used in DC_CTX_get_session() or
49 DC_CTX_remove_session() to refer to the session being added, and the
50 ``add'' operation will fail if there is already a session with a match‐
51 ing ID in the cache. sess_data and sess_len define the session data
52 itself to be stored in the cache. timeout_msecs specifies the expiry
53 period for the session - if this period of time passes without the cor‐
54 responding session being explicitly removed nor scrolled out of the
55 cache because of over-filling, then the cache server will remove the
56 session from the cache anyway.
57 DC_CTX_remove_session() provides a session ID with id_data and id_len
59 and requests that the corresponding session be removed from the cache.
60 DC_CTX_get_session() provides a session ID with id_data and id_len and
62 requests that the corresponding session data be retrieved from the
63 cache. result_storage and result_size specify a storage area for the
64 retrieved session data, and result_used points to a variable that will
65 be set to the length of the retrieved session data. Even if
66 DC_CTX_get_session() returns successfully, the caller should check the
67 value of result_used - if it is larger than result_size then the
68 requested session data was too big for the provided storage area and
69 only partial data will have been returned. In this case, the caller
70 should immediately call DC_CTX_reget_session().
71 DC_CTX_reget_session() is similar to DC_CTX_get_session() except that
73 it does not perform any network operations at all. It is designed to
74 return session data that had previously been retrieved by
75 DC_CTX_get_session(), so that a larger storage area can be provided if
76 the one first provided to DC_CTX_get_session() was too small. This
77 function will fail if the last operation on ctx was not DC_CTX_get_ses‐
78 sion() with an exact match for id_data and id_len.
79 DC_CTX_has_session() is similar to DC_CTX_get_session() except that it
81 does not ask for session data to be returned, merely to know whether
82 the session is in the cache or not. This should be used by any applica‐
83 tion that already has a copy of the required session but merely wishes
84 to verify that it hasn't already been explicitly invalidated. As dist‐
85 cache allows parallel use of a single cache from multiple clients
86 across potentially multiple machines, it is a security flaw for any
87 client (thread, process, or machine) to implement local session caching
88 and using its sessions whenever there is a cache-hit. If the session
89 was used and for any reason required invalidation (eg. renegotiation,
90 data corruption detected, etc) then another client should not use a
91 locally cached copy of the session without first verifying with the
92 shared cache that the session is still OK. This function should be used
93 in such cases as it provides the same check as DC_CTX_get_session() but
94 with less network overhead.
95
97 DC_CTX_new() returns a valid DC_CTX object on success, otherwise NULL
98 for failure.
99 DC_CTX_free() has no return type.
101 All other DC_CTX functions return zero on failure, otherwise non-zero.
103
105 The following code snippet attempts to create a session cache context
106 that uses a temporary connection for each operation to a local
107 dc_client agent running on a unix domain socket at /tmp/dc_client;
108 DC_CTX *ctx = DC_CTX_new("UNIX:/tmp/dc_client", 0);
110 The following code snippet attempts to create a session cache context
112 to communicate with a remote server listening on TCP/IPv4 port 9001. It
113 will attempt to use a persistent connection for all cache operations
114 (DC_CTX_FLAG_PERSISTENT), retry once for any cache operation that suf‐
115 fers a network I/O error (DC_CTX_FLAG_PERSISTENT_RETRY), will wait
116 until the first cache operation before trying to connect
117 (DC_CTX_FLAG_PERSISTENT_LATE), and will verify before any cache opera‐
118 tion whether it is running in a different process than it used to be
119 and if so will close then re-open a new connection (DC_CTX_FLAG_PERSIS‐
120 TENT_PIDCHECK).
121 DC_CTX *ctx = DC_CTX_new("IP:cacheserver.localnet",
123 DC_CTX_FLAG_PERSISTENT ⎪ DC_CTX_FLAG_PERSISTENT_PIDCHECK ⎪
124 DC_CTX_FLAG_PERSISTENT_RETRY ⎪ DC_CTX_FLAG_PERSISTENT_LATE);
125 The DC_CTX_FLAG_PERSISTENT_RETRY flag exists because of the -idle com‐
127 mand-line switch in the dc_client(1) tool. This switch allows dc_client
128 to automatically close client connections that have been idle for some
129 configurable length of time. However, this creates the possiblity for
130 race conditions if a persistent DC_CTX is used by an application to
131 request a cache operation at the same time or following a decision by
132 dc_client to close the connection. The most robust way to address this
133 is to have DC_CTX regard any first network error during the operation
134 as an idle-timeout from the peer and to immediately re-connect and
135 retry the operation. Any subsequent error (or initial error that can
136 not be timeout-related, such as connection failure) is considered a
137 failure and will not result in any retry.
138 The DC_CTX_FLAG_PERSISTENT_PIDCHECK flag exists for software like
140 Apache or Stunnel that use fork(2) or clone(2) to create child pro‐
141 cesses that inherit file-descriptors from the parent process. In such
142 circumstances, attempts by the parent and child processes to communi‐
143 cate over the same file-descriptor can have unpredictable results and
144 is, generally speaking, never useful. This flag will force a check
145 before each operation that the process ID is ``what it used to be'' and
146 if not, will close any persistent connection, reconnect with a new
147 file-descriptor, and reset the process ID in the DC_CTX. If a parent
148 process has a DC_CTX that has a connection open, this flag will ensure
149 that any subsequent child processes that attempt to perform cache oper‐
150 ations will transparently reconnect with their own connections.
151
153 DC_PLUG_new(2), DC_PLUG_read(2) - Lower-level asynchronous implementa‐
154 tion of the distcache protocol, useful for client and server operation.
155 This DC_CTX implementation is built on top of the DC_PLUG functional‐
156 ity.
157 distcache(8) - Overview of the distcache architecture.
159 http://www.distcache.org/ - Distcache home page.
161
163 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
164 graphic Appliances Incorporated. Since the project was released into
165 open source, it has a home page and a project environment where devel‐
166 opment, mailing lists, and releases are organised. For problems with
167 the software or this man page please check for new releases at the
168 project web-site below, mail the users mailing list described there, or
169 contact the author at geoff@geoffthorpe.net.
170 Home Page: http://www.distcache.org
1721.4.5 2004.03.23 DC_CTX_NEW(2)