1DC_PLUG_NEW(2)                     distcache                    DC_PLUG_NEW(2)
2
3
4

NAME

6       DC_PLUG_new, DC_PLUG_free, DC_PLUG_to_select, DC_PLUG_io - basic
7       DC_PLUG functions
8

SYNOPSIS

10        #include <distcache/dc_plug.h>
11
12        DC_PLUG *DC_PLUG_new(NAL_CONNECTION *conn, unsigned int flags);
13        int DC_PLUG_free(DC_PLUG *plug);
14        void DC_PLUG_to_select(DC_PLUG *plug, NAL_SELECTOR *sel);
15        int DC_PLUG_io(DC_PLUG *plug, NAL_SELECTOR *sel);
16

DESCRIPTION

18       DC_PLUG_new() allocates and initialises a DC_PLUG structure encapsulat‐
19       ing the specified connection. The flags parameter is zero or a bitmask
20       combining one or more of the following flags;
21
22        #define DC_PLUG_FLAG_TO_SERVER         (unsigned int)0x0001
23        #define DC_PLUG_FLAG_NOFREE_CONN       (unsigned int)0x0002
24
25       If the DC_PLUG_FLAG_TO_SERVER flag is specified, the plug object will
26       expect to be sending ``request'' messages and receiving ``response''
27       messages, otherwise will default to the opposite sense.
28
29       DC_PLUG_free() frees the DC_PLUG structure and, unless it had been cre‐
30       ated with the DC_PLUG_FLAG_NOFREE_CONN flag, will also destroy the con‐
31       nection object it encapsulates.
32
33       DC_PLUG_to_select() is used to add a plug object to the sel selector so
34       that it can be tested for network events it is waiting on. This will
35       automatically handle selection of flags depending on the plug object's
36       state. Ie. it will select for writability on its underlying connection
37       only if there is data waiting to be sent, and likewise will select for
38       readability only if it is ready to receive any data that may have
39       arrived.
40
41       DC_PLUG_io() is used to allow network I/O to be performed on a plug
42       object's underlying connection depending on the results of the last
43       select operation on sel.
44

RETURN VALUES

46       DC_PLUG_new() returns the new plug object on success, otherwise NULL
47       for failure.
48
49       DC_PLUG_free() should never fail and should only return non-zero
50       results.
51
52       DC_PLUG_to_select() has no return value.
53
54       DC_PLUG_io() return zero on an error, otherwise non-zero.
55
56       None of the DC_PLUG functions sets (or clears) errno because it is
57       implemented on top of the libnal library which in turn is an abstrac‐
58       tion layer for the system's networking interfaces. As such, any errno
59       codes set by failure in system libraries will not be overwritten by
60       these functions.
61

SEE ALSO

63       DC_PLUG_read(2) - Provides documentation for other DC_PLUG functions
64       also.
65
66       distcache(8) - Overview of the distcache architecture.
67
68       http://www.distcache.org/ - Distcache home page.
69

AUTHOR

71       This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
72       graphic Appliances Incorporated. Since the project was released into
73       open source, it has a home page and a project environment where devel‐
74       opment, mailing lists, and releases are organised. For problems with
75       the software or this man page please check for new releases at the
76       project web-site below, mail the users mailing list described there, or
77       contact the author at geoff@geoffthorpe.net.
78
79       Home Page: http://www.distcache.org
80
81
82
831.4.5                             2004.03.23                    DC_PLUG_NEW(2)
Impressum