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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
\function{socket}
\synopsis{Create a communications socket}
\usage{FD_Type socket (domain, type, protocol)}
\description
The \ifun{socket} function creates a communications socket of the
specified domain, type, and protocol. Currently supported domains
include \ivar{PF_UNIX} and \ivar{PF_INET}. The various socket types
may be specified by the symbolic constants
#v+
SOCK_STREAM
SOCK_DGRAM
SOCK_SEQPACKET
SOCK_RAW
SOCK_RDM
#v-
The \exmp{protocol} parameter specifies the protocol to be used.
Normally only one protocol is support for a particular domain. For
such cases, 0 should be passed for the \exmp{protocol} parameter.
If successful, the \ifun{socket} function will return a
file-descriptor that may be used with the \ifun{read} and
\ifun{write} function, or passed to other socket related functions.
Upon error, a \ivar{SocketError} exception will be thrown and
\ivar{errno} set accordingly.
When finished with the socket, it should be passed to the
\ifun{close} function.
\example
The following example illustrates the creation of a socket for use
in the internet domain:
#v+
try {
s = socket (PF_INET, SOCK_STREAM, 0);
}
catch SocketError: {
() = fprintf (stderr, "socket failed: %s", errno_string(errno));
exit (1);
}
#v-
\seealso{accept, bind, connect, listen, setsockopt, getsockopt}
\done
\function{connect}
\synopsis{Make a connection to a socket}
\usage{connect (FD_Type s, address-args)}
\description
The \ifun{connect} function may be used to connect a socket \exmp{s}
to the address specified by the address-arguments. The type and
number of the address arguments must be consistent with the domain
of the socket. For example, if the socket is in the Unix domain
(PF_UNIX), then a single string giving a filename must be passed as
the address-argument. Sockets in the internet domain (PF_INET) take two
address arguments: a hostname and a port.
Upon failure, the function may throw a \ivar{SocketError} exception and set
\ivar{errno}, or throw a \ivar{SocketHError} and set \ivar{h_error}.
It should be noted that \ivar{SocketHError} is a subclass of
\ivar{SocketError}.
\example
The following example creates an internet domain socket and connects
it to port 32100 of a specified host:
#v+
try {
s = socket (PF_INET, SOCK_STREAM, 0);
connect (s, "some.host.com", 32100);
}
catch SocketHError: {...}
catch SocketError: {...}
#v-
\seealso{accept, bind, listen, socket, setsockopt, getsockopt}
\done
\function{bind}
\synopsis{Bind a local address-name to a socket}
\usage{bind (FD_Type s, address-args)}
\description
The \ivar{bind} function may be used to assign a name to a specified
socket. The address-args parameters specify the name in a
domain-specific manner. For Unix domain sockets, the address is the
name of a file. For sockets in the internet domain, the address is
given by a hostname and port number.
Upon failure, the function will throw a \ivar{SocketError} or
\ivar{SocketHError} exception.
\example
The following example creates a \ivar{PF_UNIX} domain socket and
binds it to \exmp{"/tmp/mysock"}:
#v+
s = socket (PF_UNIX, SOCK_STREAM, 0);
bind (s, "/tmp/mysock");
#v-
The next example creates a \ivar{PF_INET} domain socket and binds it
to port 32000 of the local host \exmp{my.host.com}:
#v+
s = socket (PF_INET, SOCK_STREAM, 0);
bind (s, "my.host.com", 32000);
#v-
\seealso{accept, connect, listen, socket, setsockopt, getsockopt}
\done
\function{accept}
\synopsis{Accept a connection on a socket}
\usage{FD_Type accept (FD_Type s [,&address-args...]}
\description
The \ifun{accept} function accepts a connection on the specified
socket and returns a new socket that may be used to communicate with
the remote end. It can optionally return the address of the remote
end through reference arguments.
Upon error, \ifun{accept} will throw a \ivar{SocketError} exception.
\example
The following example accepts a remote connection on \ivar{PF_INET}
socket and returns the hostname and port used by the connected party:
#v+
s1 = accept (s, &hostip, &port);
vmessage ("Accepted connection from %s on port %d", hostip, port);
#v-
\seealso{bind, connect, listen, socket, setsockopt, getsockopt}
\done
\function{listen}
\synopsis{Listen for connections on a socket}
\usage{listen (FD_Type s, Int_Type max_pending)}
\description
The \ifun{listen} function may be used to wait for a connection to a
socket \exmp{s}. The second argument specified the maximum number
of pending connections to allow before refusing more. Upon error, a
\ivar{SocketError} exception will be thrown.
\seealso{accept, bind, connect, socket, setsockopt, getsockopt}
\seealso{}
\done
\function{getsockopt}
\synopsis{Get a socket option}
\usage{option = getsockopt (FD_Type s, Int_Type level, Int_Type optname)}
\description
The \ifun{getsockopt} function returns the value of the option
specified by the integer \exmp{optname} residing at the specified
level. The actual object returned depends upon the option
requested. Upon error, a \ivar{SocketError} exception will be
generated.
\example
The following example returns the SO_LINGER option of a socket. In
this case, the value returned will be a structure:
#v+
s = socket (PF_INET, SOCK_STREAM, 0);
linger = getsockopt (s, SOL_SOCKET, SO_LINGER);
#v-
\seealso{accept, bind, connect, listen, socket, getsockopt}
\done
\function{setsockopt}
\synopsis{Set an option on a socket}
\usage{setsockopt (FD_Type s, Int_Type level, Int_Type optname, value)}
\description
The \ifun{setsockopt} function sets the value of the option
specified by the integer \exmp{optname} residing at the specified
level. The value of the last parameter will vary with the option to
be set. Upon error, a \ivar{SocketError} exception will be
generated.
\example
The following example sets the SO_LINGER option of a socket. In
this case, the value is a structure:
#v+
s = socket (PF_INET, SOCK_STREAM, 0);
linger = struct { l_onoff, l_linger };
linger.l_onoff = 1; linger.l_linger = 10;
setsockopt (s, SOL_SOCKET, SO_LINGER, linger);
#v-
\seealso{accept, bind, connect, listen, socket, getsockopt}
\done
|
