-
Notifications
You must be signed in to change notification settings - Fork 198
/
doxymain.dox
122 lines (81 loc) · 4.84 KB
/
doxymain.dox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
/**
@mainpage The libsocket documentation
<b>This documentation is targeted at people who want to gain deeper insight into the libsocket source code.
Normal library users should use the documentation provided in the doc/libsocket and doc/libsocket++ directories!</b>
This is the documentation for the C and C++ library libsocket. libsocket is intended to simplify the use of internet and
UNIX sockets. Information about how to build libsocket are placed <a href="building.html">here</a>, and <a href="usage.html">this page</a>
tells you how to use libsocket in your applications.
@section libsocket libsocket for C
To get started with *libsocket for C*, take a look at [the hand-crafted documentation](https://github.com/dermesser/libsocket/blob/master/doc/libsocket/DOCUMENTATION.mkd).
Detailed documentation is available here: <a href="group__libinetsocket.html">libinetsocket</a>; <a
href="group__libunixsocket.html">libunixsocket</a>.
@section libsocketpp libsocket for C++
libsocket++ should also be easy to understand but it has a <a href="classlibsocket_1_1socket.html">quite sophisticated class hierarchy</a>.
libsocket++ consists of many C++ classes. Only the following are intended for use in external applications:
- inet_stream, inet_stream_server (TCP/IP client and server)
- inet_dgram_client, inet_dgram_server (UDP/IP client [unbound] and server [bound])
- unix_stream_client, unix_stream_server (UNIX domain; STREAM client and server)
- unix_dgram_client, unix_stream_client (UNIX domain; DGRAM unbound and bound sockets)
- selectset, epollset
If a function fails, it throws a `socket_exception` object containing the error. Look <a href="structlibsocket_1_1socket__exception.html">here</a>
for detailed information. *Therefore it's important to put libsocket++ operations inside `try {...} catch () {...}` blocks*.
Libsocket++ uses C++11 to delete the copy constructors of the socket classes. This enables the destructor to safely
close the socket; to pass a socket to other functions use *call-by-reference*, *call-by-pointer* or `std::move` and an rvalue-accepting function type:
@code{.cpp}
void f(xyzsocket&);
void f(xyzsocket*);
@endcode
Detailed documentation can be found in this doxygen documentation; easier documentation is available [here](https://github.com/dermesser/libsocket/blob/master/doc/libsocket%2B%2B/DOCUMENTATION%2B%2B.mkd)
*/
/************************************** BUILDING **********************************************/
/**
@page building Building libsocket
It should be rather simple to build and install libsocket.
@section targets Targets
- all (default): Build both shared objects (libsocket.so, libsocket++.so)
- libsocket: Build only libsocket
- libsocketpp: Build only libsocket++
- install: Install shared objects and header files
- install-headers: Install headers to (default) `/usr/include/libsocket/`
- clean: Remove object files and shared libraries from source tree
- deinstall: Remove all previously installed files (libraries, header files)
@section Customization
You may specify variables when invoking make: `$ make VARIABLE_DECLARATIONS TARGET`
Predefined vars are:
LIBPATH=/usr/lib
HEADERPATH=/usr/include/libsocket
CC=gcc
CPP=g++
CFLAGS=
If you want to have errors on STDERR from libsocket, simply say `$ make CFLAGS=-DVERBOSE`. If you want to
install the shared libraries to `/usr/local/lib`, use `$ make LIBPATH=/usr/local/lib`.
*/
/************************************ USAGE ************************************/
/**
@page usage Usage
As libsocket is built as shared library, it's not really hard to use.
@section headers Including the header files
The header files are placed by default to `/usr/include/libsocket` (you may want to change that, especially on BSD). This directory
should be contained in your compiler's include path, so just say (if you want to build an application using UNIX client stream sockets):
# include <libsocket/unixclientdgram.hpp>
The classes are contained in these header files:
CLASS HEADER FILE
----------------------------------------------------
inet_stream inetclientstream.hpp
inet_stream_server inetserverstream.hpp
inet_dgram_client inetclientdgram.hpp
inet_dgram_server inetserverdgram.hpp
unix_dgram_client unixclientdgram.hpp
unix_dgram_server unixserverdgram.hpp
unix_stream_client unixclientstream.hpp
unix_stream_server unixserverstream.hpp
selectset select.hpp
epollset epoll.hpp
[libinetsocket] libinetsocket.h
[libunixsocket] libunixsocket.h
@section linkage Linking your apps with libsocket
If you let the Makefile place the shared object to a default library path like `/usr/lib`, `/lib`, `/usr/local/lib`, you need to
link your programs with the following switches:
- For libsocket: `$CC -lsocket ...`
- For libsocket++: `$CXX -lsocket++ ...`
*/