source: trunk/libs/mini-libc/socket.h @ 687

Last change on this file since 687 was 684, checked in by alain, 4 years ago

Introduce the socket.c & socket.h files.

File size: 11.9 KB
Line 
1/*
2 * socket.h - User level <socket> library definition.
3 *
4 * Author     Alain Greiner (2016,2017,2018,2019,2020)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _SOCKET_H_
25#define _SOCKET_H_
26
27/*****************************************************************************************
28 * This file defines the user level <socket> library.
29 * All these functions use the sys_socket() function to access the kernel structures.
30 * The user/kernel shared structures and mnemonics are defined in
31 * the <kernel/syscalls/shared_include/shared_socket.h> file.
32 ****************************************************************************************/
33
34#include <shared_socket.h>
35
36/*****************************************************************************************
37 * This function creates a local socket for communication, register it in the calling
38 * process and returns a socket index, that is actally a file descriptor.
39 * - The <domain> argument specifies a family of protocols to be used.
40 *   The only supported type is AF_INET : IP V4.
41 * - The <type> argument specifies the communication semantic.
42 *   The only supported values are SOCK_DGRAM (UDP) & SOC_STREAM (TCP).
43 * - The <protocol> argument is not supported, and must be zero.
44 *****************************************************************************************
45 * @ domain    : [in] must be PF_INET.
46 * @ type      : [in] must be SOCK_DGRAM / SOCK_STREAM
47 * @ protocol  : [in] must be 0.
48 * @ returns a file descriptor identifier (fdid) / return -1 if error.
49 ****************************************************************************************/
50int socket( int domain,
51            int type,
52            int protocol );
53
54/*****************************************************************************************
55 * This function assigns a socket address <local_addr> to an unnamed local socket,
56 * identified by the <fdid> argument, and set the socket state to BOUND.
57 *****************************************************************************************
58 * @ fdid        : [in] socket identifier.
59 * @ local_addr  : [in] local address in the communication space.
60 * @ addr_length : [in] addres length in bytes.
61 * @ returns 0 if success / return -1 if error.
62 ****************************************************************************************/
63int bind( int          fdid,
64          sockaddr_t * local_addr,
65          int          addr_length );
66
67/****************************************************************************************
68 * This function is executed by a TCP server on a socket identified by its <fdid>,
69 * after a bind(). It specifies the willingness to accept incoming connections requests
70 * from remote clients, and a max size for the queue of pending connection requests,
71 * as defined by the <backlog> argument. It sets the socket state to LISTEN.
72 * It applies only to sockets of type SOCK_STREAM (TCP).
73 * It can be called by a thread running in any cluster.
74 ****************************************************************************************
75 * @ fdid      : [in] file descriptor identifying the socket.
76 * @ backlog   : [in] max number of pending connection requests in CRQ queue.
77 * @ returns 0 if success / return -1 if error.
78 ***************************************************************************************/
79int listen( int     fdid,
80            int     backlog );
81
82/*****************************************************************************************
83 * This function connects a local socket identified by its <fdid> to a remote socket.
84 * The <remote_addr> argument defines the address to which UDP datagrams or TCP segments
85 * are to be sent, and the only address from which they are to be received.
86 * - If the socket identified by the <fdid> argument is of type SOCK_DGRAM (UDP), this
87 *   function simply updates the local socket descriptor using the <remote_addr> argument,
88 *   and updates the socket state to CONNECT.
89 * - If the socket is of type SOCK_STREAM (TCP), this function is called by a TCP client
90 *   to start the 3 steps handshake protocol with a TCP server identified by <remote_addr>.
91 *   It returns only when the connexion is established, and the local socket state
92 *   is set to ESTAB.
93 *****************************************************************************************
94 * @ fdid        : [in] file descriptor identifying the socket.
95 * @ remote_addr : [in] remote address in the communication space.
96 * @ addr_len    : [in] address length in bytes.
97 * @ returns 0 if success / return -1 if error.
98 ****************************************************************************************/
99int connect( int          fdid,
100             sockaddr_t * remote_addr,
101             int          addr_length );
102
103/*****************************************************************************************
104 * This function is executed by a TCP server on a socket identified by its <fdid>,
105 * after bind() and listen().
106 * It extracts the first connection request from the queue of pending connections,
107 * creates a new socket with the same properties as <socket>, and allocates a new file
108 * descriptor for the new socket.  If no pending connections are present on the queue,
109 * it blocks the call ,er until a connection is present. The new socket cannot accept more
110 * connections, but the original socket remains open. It returns in the <client_addr>
111 * argument the client address. The inout argument <addr_length> contains initially
112 * te size of the <client_addr> buffer, and returns the actual length of the address.
113 *****************************************************************************************
114 * @ fdid         : [in] file descriptor identifying the socket.
115 * @ remote_addr  : [in] remote client address in the communication space.
116 * @ addr_len     : [inout] address length in bytes.
117 * @ returns 0 if success / return -1 if error.
118 ****************************************************************************************/
119int accept( int          fdid,
120            sockaddr_t * remote_addr,
121            int        * addr_length );
122
123/*****************************************************************************************
124 * This function send data from a local socket identified by the <fdid> argument,
125 * to a remote socket. The payload is defined by the <buffer> and <size> arguments.
126 * The local socket must be in "connected" state, as the remote socket is identified
127 * by the remote_address and remote_port registered in the local socket.
128 * If the packet is too long to pass atomically through the underlying protocols,
129 * an error is returned, and the message is not transmitted.
130 * This blocking function returns only when all data have been sent (for an UDP socket),
131 * or acknowledged (for a TCP socket).
132 *****************************************************************************************
133 * @ fdid      : [in] file descriptor identifying the socket.
134 * @ buffer    : [in] local pointer on source buffer.
135 * @ length    : [in] number of bytes in source buffer.
136 * @ flags     : unused / must be 0.
137 * @ returns number of bytes sent if success / return -1 if error.
138 ****************************************************************************************/
139int send( int          fdid,
140          void       * buffer,
141          int          length,
142          int          flags );
143
144/*****************************************************************************************
145 * This function get data from a local socket identified by the <fdid> index,
146 * wether or not it is connected, and stores this data in the buffer identified by the
147 * <buffer> argument. The buffer size is defined by the <length> argument.
148 * This non blocking function returns as soon as data is available, returning the number
149 * of bytes actually moved to <buffer>.
150 *****************************************************************************************
151 * @ fdid      : [in] file descriptor identifying the socket.
152 * @ buffer    : [in] local pointer on destination buffer.
153 * @ length    : [in] number of bytes in destination buffer.
154 * @ flags     : unused / must be 0
155 * @ returns number of bytes received if success / return -1 if error.
156 ****************************************************************************************/
157int recv( int          fdid,
158          void       * buffer,
159          int          length,
160          int          flags );
161
162/*****************************************************************************************
163 * This function send a packet from a local socket identified by the <fdid> argument,
164 * to a remote socket. The payload is defined by the <buffer> and <size> arguments.
165 * The remote socket is identified by the <server_addr> and <addr_length> arguments.
166 * If the packet is too long to pass atomically through the underlying protocols,
167 * an error is returned, and the message is not transmitted.
168 * This blocking function returns only when all data have been sent (for an UDP socket),
169 * or acknowledged (for a TCP socket).
170 *****************************************************************************************
171 * @ fdid        : [in] file descriptor identifying the socket.
172 * @ buffer      : [in] local pointer on source buffer.
173 * @ length      : [in] number of bytes in source buffer.
174 * @ flags       : unused / must be 0.
175 * @ remote_addr : [in] remote socket address in communication space.
176 * @ addr_length : [in] size of buffer containing this remote address.
177 * @ returns number of bytes sent if success / return -1 if error.
178 ****************************************************************************************/
179int sendto( int          socket,
180            void       * buffer,
181            int          length,
182            int          flags,
183            sockaddr_t * remote_addr,
184            int          addr_length );
185
186/*****************************************************************************************
187 * This function get data from a local socket identified by the <fdid> argument,
188 * wether or not it is connected, and stores this data in the buffer identified by the
189 * <buffer> argument. The buffer size is defined by the <length> argument.
190 * This non blocking function returns as soon as data is available, returning the number
191 * of bytes actually moved to <buffer>.
192 * If the <remote_addr> argument is not NULL, and the local socket is not connected,
193 * the remote socket address is stored in the <remote_addr> buffer.
194 * The <addr_length> buffer is an in/out argument, that contains initially the size
195 * of the <remote_addr> buffer and returns the actual remote address length.
196 *****************************************************************************************
197 * @ socket      : [in] local socket identifier.
198 * @ buffer      : [in] local pointer on destination buffer.
199 * @ length      : [in] number of bytes in destination buffer.
200 * @ flags       : unused / must be 0.
201 * @ remote_addr : [out] buffer for remote socket address.
202 * @ addr_length : [in/out] size of this remote address buffer.
203 * @ returns number of bytes received if success / return -1 if error.
204 ****************************************************************************************/
205int recvfrom( int          socket,
206              void       * buffer,
207              int          length,
208              int          flags,
209              sockaddr_t * remote_addr,
210              int        * addr_length );
211
212#endif  // _SOCKET_H_
213
Note: See TracBrowser for help on using the repository browser.