KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
socket.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  sys/socket.h
4  Copyright (C)2006, 2010, 2012 Lawrence Sebald
5 
6 */
7 
8 /** \file sys/socket.h
9  \brief Main sockets header.
10 
11  This file contains the standard definitions (as directed by the POSIX 2008
12  standard) for socket-related functionality in the AF_INET address family.
13  This does not include anything related to AF_INET6 (as IPv6 is not currently
14  implemented in KOS) nor UNIX domain sockets, and is not guaranteed to have
15  everything that one might have in a fully-standard compliant implementation
16  of the POSIX standard.
17 
18  \author Lawrence Sebald
19 */
20 
21 #ifndef __SYS_SOCKET_H
22 #define __SYS_SOCKET_H
23 
24 #include <sys/cdefs.h>
25 #include <sys/types.h>
26 
27 __BEGIN_DECLS
28 
29 /** \brief Socket length type. */
30 typedef __uint32_t socklen_t;
31 
32 /** \brief Socket address family type. */
33 typedef __uint8_t sa_family_t;
34 
35 /** \brief Socket address structure.
36  \headerfile sys/socket.h
37 */
38 struct sockaddr {
39  /** \brief Address family. */
41  /** \brief Address data. */
42  char sa_data[];
43 };
44 
45 /** \brief Size of the struct sockaddr_storage.
46  The size here is chosen for compatibility with anything that may expect the
47  struct sockaddr_storage to be of size 128. Technically, since there are no
48  current plans to support AF_UNIX sockets, this could be smaller, but most
49  implementations make it 128 bytes.
50 */
51 #define _SS_MAXSIZE 128
52 
53 /** \brief Desired alignment of struct sockaddr_storage. */
54 #define _SS_ALIGNSIZE (sizeof(__uint64_t))
55 
56 /** \brief First padding size used within struct sockaddr_storage. */
57 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
58 
59 /** \brief Second padding size used within struct sockaddr_storage. */
60 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t) + \
61  _SS_PAD1SIZE + _SS_ALIGNSIZE))
62 
63 /** \brief Socket address structure of appropriate size to hold any supported
64  socket type's addresses.
65  \headerfile sys/socket.h
66 */
68  /** \brief Address family. */
70 
71  /** \brief First padding field. */
73 
74  /** \brief Used to force alignment. */
75  __uint64_t _ss_align;
76 
77  /** \brief Second padding field to fill up the space required. */
79 };
80 
81 /** \brief Datagram socket type.
82 
83  This socket type specifies that the socket in question transmits datagrams
84  that may or may not be reliably transmitted. With IP, this implies using UDP
85  as the underlying protocol.
86 */
87 #define SOCK_DGRAM 1
88 
89 /** \brief Stream socket type.
90 
91  This socket type specifies that the socket in question acts like a stream
92  or pipe between the two endpoints. Sockets of this type can be assumed to be
93  reliable -- unless an error is returned, all packets will be received at the
94  other end in the order they are sent. With IP, this implies using TCP as the
95  underlying protocol.
96 */
97 #define SOCK_STREAM 2
98 
99 /** \brief Socket-level option setting.
100 
101  This constant should be used with the setsockopt() or getsockopt() function
102  to represent that options should be accessed at the socket level, not the
103  protocol level.
104 */
105 #define SOL_SOCKET 1
106 
107 /** \defgroup so_opts Socket-level options
108 
109  These are the various socket-level options that can be accessed with the
110  setsockopt() and getsockopt() functions for the SOL_SOCKET level value.
111 
112  Not all of these are currently supported, but they are listed for
113  completeness.
114 
115  \see ipv6_opts
116  \see ipv4_opts
117  \see udp_opts
118 
119  @{
120 */
121 #define SO_ACCEPTCONN 1 /**< \brief Socket is accepting connections (get) */
122 #define SO_BROADCAST 2 /**< \brief Support broadcasting (get/set) */
123 #define SO_DEBUG 3 /**< \brief Record debugging info (get/set) */
124 #define SO_DONTROUTE 4 /**< \brief Do not route packets (get/set) */
125 #define SO_ERROR 5 /**< \brief Retrieve error status (get) */
126 #define SO_KEEPALIVE 6 /**< \brief Send keepalive messages (get/set) */
127 #define SO_LINGER 7 /**< \brief Socket lingers on close (get/set) */
128 #define SO_OOBINLINE 8 /**< \brief OOB data is inline (get/set) */
129 #define SO_RCVBUF 9 /**< \brief Receive buffer size (get/set) */
130 #define SO_RCVLOWAT 10 /**< \brief Receive low-water mark (get/set) */
131 #define SO_RCVTIMEO 11 /**< \brief Receive timeout value (get/set) */
132 #define SO_REUSEADDR 12 /**< \brief Reuse local addresses (get/set) */
133 #define SO_SNDBUF 13 /**< \brief Send buffer size (get/set) */
134 #define SO_SNDLOWAT 14 /**< \brief Send low-water mark (get/set) */
135 #define SO_SNDTIMEO 15 /**< \brief Send timeout value (get/set) */
136 #define SO_TYPE 16 /**< \brief Socket type (get) */
137 /** @} */
138 
139 /** \defgroup msg_flags Socket message flags
140 
141  The following flags can be used with the recv(), recvfrom(), send(),
142  and sendto() functions as the flags parameter.
143 
144  Note that not all of these are currently supported, but they are listed for
145  completeness. Those that are unsupported have (U) at the end of their
146  description. Also, for the time being, the supported flags are only
147  supported for TCP.
148 
149  @{
150 */
151 #define MSG_CTRUNC 0x01 /**< \brief Control data truncated (U) */
152 #define MSG_DONTROUTE 0x02 /**< \brief Send without routing (U) */
153 #define MSG_EOR 0x04 /**< \brief Terminate a record (U) */
154 #define MSG_OOB 0x08 /**< \brief Out-of-band data (U) */
155 #define MSG_PEEK 0x10 /**< \brief Leave received data in queue */
156 #define MSG_TRUNC 0x20 /**< \brief Normal data truncated (U) */
157 #define MSG_WAITALL 0x40 /**< \brief Attempt to fill read buffer */
158 #define MSG_DONTWAIT 0x80 /**< \brief Make this call non-blocking (non-standard) */
159 /** @} */
160 
161 /** \brief Unspecified address family. */
162 #define AF_UNSPEC 0
163 
164 /** \brief Internet domain sockets for use with IPv4 addresses. */
165 #define AF_INET 1
166 
167 /** \brief Internet domain sockets for use with IPv6 addresses. */
168 #define AF_INET6 2
169 
170 /** \brief Unspecified protocol family. */
171 #define PF_UNSPEC AF_UNSPEC
172 
173 /** \brief Protocol family for Internet domain sockets (IPv4). */
174 #define PF_INET AF_INET
175 
176 /** \brief Protocol family for Internet domain sockets (IPv6). */
177 #define PF_INET6 AF_INET6
178 
179 /** \brief Disable furhter receive operations. */
180 #define SHUT_RD 0x00000001
181 
182 /** \brief Disable further send operations. */
183 #define SHUT_WR 0x00000002
184 
185 /** \brief Disable further send and receive operations. */
186 #define SHUT_RDWR (SHUT_RD | SHUT_WR)
187 
188 /** \brief Maximum backlog for a listening socket. */
189 #define SOMAXCONN 32
190 
191 /** \brief Accept a new connection on a socket.
192 
193  This function extracts the first connection on the queue of connections of
194  the specified socket, creating a new socket with the same protocol and
195  address family as that socket for communication with the extracted
196  connection.
197 
198  \param socket A socket created with socket() that has been bound to an
199  address with bind() and is listening for connections
200  after a call to listen().
201  \param address A pointer to a sockaddr structure where the address of
202  the connecting socket will be returned (can be NULL).
203  \param address_len A pointer to a socklen_t which specifies the amount of
204  space in address on input, and the amount used of the
205  space on output.
206  \return On success, the non-negative file descriptor of the
207  new connection, otherwise -1 and errno will be set to
208  the appropriate error value.
209 */
210 int accept(int socket, struct sockaddr *address, socklen_t *address_len);
211 
212 /** \brief Bind a name to a socket.
213 
214  This function assigns the socket to a unique name (address).
215 
216  \param socket A socket that is to be bound.
217  \param address A pointer to a sockaddr structure where the name to be
218  assigned to the socket resides.
219  \param address_len The length of the address structure.
220  \retval 0 On success.
221  \retval -1 On error, sets errno as appropriate.
222 */
223 int bind(int socket, const struct sockaddr *address, socklen_t address_len);
224 
225 /** \brief Connect a socket.
226 
227  This function attempts to make a connection to a resource on a connection-
228  mode socket, or sets/resets the peer address on a connectionless one.
229 
230  \param socket A socket that is to be connected.
231  \param address A pointer to a sockaddr structure where the name of the
232  peer resides.
233  \param address_len The length of the address structure.
234  \retval 0 On success.
235  \retval -1 On error, sets errno as appropriate.
236 */
237 int connect(int socket, const struct sockaddr *address, socklen_t address_len);
238 
239 /** \brief Listen for socket connections and set the queue length.
240 
241  This function marks a connection-mode socket for incoming connections.
242 
243  \param socket A connection-mode socket to listen on.
244  \param backlog The number of queue entries.
245  \retval 0 On success.
246  \retval -1 On error, sets errno as appropriate.
247 */
248 int listen(int socket, int backlog);
249 
250 /** \brief Receive a message on a connected socket.
251 
252  This function receives messages from the peer on a connected socket.
253 
254  \param socket The socket to receive on.
255  \param buffer A pointer to a buffer to store the message in.
256  \param length The length of the buffer.
257  \param flags The type of message reception. Set to 0 for now.
258  \return On success, the length of the message in bytes. If no
259  messages are available, and the socket has been shut
260  down, 0. On error, -1, and sets errno as appropriate.
261 */
262 ssize_t recv(int socket, void *buffer, size_t length, int flags);
263 
264 /** \brief Receive a message on a socket.
265 
266  This function receives messages from a peer on a (usually connectionless)
267  socket.
268 
269  \param socket The socket to receive on.
270  \param buffer A pointer to a buffer to store the message in.
271  \param length The length of the buffer.
272  \param flags The type of message reception. Set to 0 for now.
273  \param address A pointer to a sockaddr structure to store the peer's
274  name in.
275  \param address_len A pointer to the length of the address structure on
276  input, the number of bytes used on output.
277  \return On success, the length of the message in bytes. If no
278  messages are available, and the socket has been shut
279  down, 0. On error, -1, and sets errno as appropriate.
280 */
281 ssize_t recvfrom(int socket, void *buffer, size_t length, int flags,
282  struct sockaddr *address, socklen_t *address_len);
283 
284 /** \brief Send a message on a connected socket.
285 
286  This function sends messages to the peer on a connected socket.
287 
288  \param socket The socket to send on.
289  \param message A pointer to a buffer with the message to send.
290  \param length The length of the message.
291  \param flags The type of message transmission. Set to 0 for now.
292  \return On success, the number of bytes sent. On error, -1,
293  and sets errno as appropriate.
294 */
295 ssize_t send(int socket, const void *message, size_t length, int flags);
296 
297 /** \brief Send a message on a socket.
298 
299  This function sends messages to the peer on a (usually connectionless)
300  socket. If used on a connection-mode socket, this function may change the
301  peer that the socket is connected to, or it may simply return error.
302 
303  \param socket The socket to send on.
304  \param message A pointer to a buffer with the message to send.
305  \param length The length of the message.
306  \param flags The type of message transmission. Set to 0 for now.
307  \param dest_addr A pointer to a sockaddr structure with the peer's name.
308  \param dest_len The length of dest_addr, in bytes.
309  \return On success, the number of bytes sent. On error, -1,
310  and sets errno as appropriate.
311 */
312 ssize_t sendto(int socket, const void *message, size_t length, int flags,
313  const struct sockaddr *dest_addr, socklen_t dest_len);
314 
315 /** \brief Shutdown socket send and receive operations.
316 
317  This function closes a specific socket for the set of specified operations.
318 
319  \param socket The socket to shutdown.
320  \param how The type of shutdown.
321  \retval 0 On success.
322  \retval -1 On error, sets errno as appropriate.
323  \see SHUT_RD
324  \see SHUT_WR
325  \see SHUT_RDWR
326 */
327 int shutdown(int socket, int how);
328 
329 /** \brief Create an endpoint for communications.
330 
331  This function creates an unbound socket for communications with the
332  specified parameters.
333 
334  \param domain The domain to create the socket in (i.e, AF_INET).
335  \param type The type of socket to be created (i.e, SOCK_DGRAM).
336  \param protocol The protocol to use with the socket. May be 0 to allow
337  a default to be used.
338  \return A non-negative file descriptor on success. -1 on error,
339  and sets errno as appropriate.
340 */
341 int socket(int domain, int type, int protocol);
342 
343 /** \brief Get socket options.
344 
345  This function retrieves options associated with a socket. This function
346  shall attempt to retrieve the specified option (at the specified level) from
347  the given socket.
348 
349  \param socket The socket to get options for.
350  \param level The protocol level to get options at.
351  \param option_name The option to look up.
352  \param option_value Storage for the value of the option.
353  \param option_len The length of option_value on call, and the real
354  option length (if less than the original value)
355  on return.
356  \return Zero on success. -1 on error, and sets errno as
357  appropriate.
358 
359  \see so_opts
360  \see ipv4_opts
361  \see ipv6_opts
362  \see udp_opts
363 */
364 int getsockopt(int socket, int level, int option_name, void *option_value,
365  socklen_t *option_len);
366 
367 /** \brief Set socket options.
368 
369  This function sets options associated with a socket. This function shall
370  attempt to set the specified option (at the specified level) from the given
371  socket.
372 
373  \param socket The socket to set options for.
374  \param level The protocol level to set options at.
375  \param option_name The option to set.
376  \param option_value The value to set for the option.
377  \param option_len The length of option_value in bytes.
378  \return Zero on success. -1 on error, and sets errno as
379  appropriate.
380 
381  \see so_opts
382  \see ipv4_opts
383  \see ipv6_opts
384  \see udp_opts
385 */
386 int setsockopt(int socket, int level, int option_name, const void *option_value,
387  socklen_t option_len);
388 
389 __END_DECLS
390 
391 #endif /* __SYS_SOCKET_H */
ssize_t sendto(int socket, const void *message, size_t length, int flags, const struct sockaddr *dest_addr, socklen_t dest_len)
Send a message on a socket.
__uint8_t sa_family_t
Socket address family type.
Definition: socket.h:33
__uint64_t _ss_align
Used to force alignment.
Definition: socket.h:75
int getsockopt(int socket, int level, int option_name, void *option_value, socklen_t *option_len)
Get socket options.
sa_family_t sa_family
Address family.
Definition: socket.h:40
int bind(int socket, const struct sockaddr *address, socklen_t address_len)
Bind a name to a socket.
sa_family_t ss_family
Address family.
Definition: socket.h:69
int shutdown(int socket, int how)
Shutdown socket send and receive operations.
#define _SS_PAD1SIZE
First padding size used within struct sockaddr_storage.
Definition: socket.h:57
#define _SS_PAD2SIZE
Second padding size used within struct sockaddr_storage.
Definition: socket.h:60
char _ss_pad2[_SS_PAD2SIZE]
Second padding field to fill up the space required.
Definition: socket.h:78
ssize_t send(int socket, const void *message, size_t length, int flags)
Send a message on a connected socket.
int listen(int socket, int backlog)
Listen for socket connections and set the queue length.
Socket address structure.
Definition: socket.h:38
ssize_t recv(int socket, void *buffer, size_t length, int flags)
Receive a message on a connected socket.
char sa_data[]
Address data.
Definition: socket.h:42
int accept(int socket, struct sockaddr *address, socklen_t *address_len)
Accept a new connection on a socket.
int connect(int socket, const struct sockaddr *address, socklen_t address_len)
Connect a socket.
Socket address structure of appropriate size to hold any supported socket type's addresses.
Definition: socket.h:67
int socket(int domain, int type, int protocol)
Create an endpoint for communications.
__uint32_t socklen_t
Socket length type.
Definition: socket.h:30
int setsockopt(int socket, int level, int option_name, const void *option_value, socklen_t option_len)
Set socket options.
char _ss_pad1[_SS_PAD1SIZE]
First padding field.
Definition: socket.h:72
ssize_t recvfrom(int socket, void *buffer, size_t length, int flags, struct sockaddr *address, socklen_t *address_len)
Receive a message on a socket.