416 lines
17 KiB
ReStructuredText
416 lines
17 KiB
ReStructuredText
==================
|
|
Network Interfaces
|
|
==================
|
|
|
|
NuttX supports a BSD-compatible socket interface layer. These socket
|
|
interface can be enabled by settings in the architecture configuration
|
|
file. Those socket APIs are discussed in
|
|
the following paragraphs.
|
|
|
|
- :c:func:`socket`
|
|
- :c:func:`bind`
|
|
- :c:func:`connect`
|
|
- :c:func:`listen`
|
|
- :c:func:`accept`
|
|
- :c:func:`send`
|
|
- :c:func:`sendto`
|
|
- :c:func:`recv`
|
|
- :c:func:`recvfrom`
|
|
- :c:func:`setsockopt`
|
|
- :c:func:`getsockopt`
|
|
|
|
.. c:function:: int socket(int domain, int type, int protocol);
|
|
|
|
Creates an endpoint for communication and
|
|
returns a descriptor.
|
|
|
|
:param domain: (see sys/socket.h)
|
|
:param type: (see sys/socket.h)
|
|
:param protocol: (see sys/socket.h)
|
|
|
|
:return:
|
|
0 on success; -1 on error with
|
|
``errno`` set appropriately:
|
|
|
|
- ``EACCES``. Permission to create a socket of the specified type
|
|
and/or protocol is denied.
|
|
- ``EAFNOSUPPORT``. The implementation does not support the specified
|
|
address family.
|
|
- ``EINVAL``. Unknown protocol, or protocol family not available.
|
|
- ``EMFILE``. Process file table overflow.
|
|
- ``ENFILE`` The system limit on the total number of open files has
|
|
been reached.
|
|
- ``ENOBUFS`` or ``ENOMEM``. Insufficient memory is available. The
|
|
socket cannot be created until sufficient resources are freed.
|
|
- ``EPROTONOSUPPORT``. The protocol type or the specified protocol is
|
|
not supported within this domain.
|
|
|
|
.. c:function:: int bind(int sockfd, const struct sockaddr *addr, socklen_t addrlen)
|
|
|
|
Gives the socket sockfd the local address
|
|
``addr``. ``addr`` is ``addrlen`` bytes long. Traditionally, this is
|
|
called "assigning a name to a socket." When a socket is created with
|
|
``socket()``, it exists in a name space (address family) but has no name
|
|
assigned.
|
|
|
|
:param sockfd: Socket descriptor from socket.
|
|
:param addr: Socket local address.
|
|
:param addrlen: Length of ``addr``.
|
|
|
|
:return: 0 on success; -1 on error with ``errno`` set appropriately:
|
|
- ``EACCES`` The address is protected, and the user is not the
|
|
superuser.
|
|
- ``EADDRINUSE`` The given address is already in use.
|
|
- ``EBADF`` ``sockfd`` is not a valid descriptor.
|
|
- ``EINVAL`` The socket is already bound to an address.
|
|
- ``ENOTSOCK`` ``sockfd`` is a descriptor for a file, not a socket.
|
|
|
|
.. c:function:: int connect(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
|
|
|
|
``connect()`` connects the socket referred to by the
|
|
file descriptor ``sockfd`` to the address specified by ``addr``. The
|
|
``addrlen`` argument specifies the size of ``addr``. The format of the
|
|
address in ``addr`` is determined by the address space of the socket
|
|
sockfd. If the socket sockfd is of type SOCK_DGRAM then ``addr`` is the
|
|
address to which datagrams are sent by default, and the only address
|
|
from which datagrams are received. If the socket is of type SOCK_STREAM
|
|
or SOCK_SEQPACKET, this call attempts to make a connection to the socket
|
|
that is bound to the address specified by ``addr``. Generally,
|
|
connection-based protocol sockets may successfully ``connect()`` only
|
|
once; connectionless protocol sockets may use ``connect()`` multiple
|
|
times to change their association. Connectionless sockets may dissolve
|
|
the association by connecting to an address with the sa_family member of
|
|
sockaddr set to AF_UNSPEC.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor returned by ``socket()``
|
|
- ``addr``: Server address (form depends on type of socket)
|
|
- ``addrlen``: Length of actual ``addr``
|
|
|
|
**Returned Value:** 0 on success; -1 on error with
|
|
```errno`` <#ErrnoAccess>`__ set appropriately:
|
|
|
|
``EACCES`` or EPERM: The user tried to connect to a broadcast address
|
|
without having the socket broadcast flag enabled or the connection
|
|
request failed because of a local firewall rule.
|
|
|
|
``EADDRINUSE`` Local address is already in use.
|
|
|
|
``EAFNOSUPPORT`` The passed address didn't have the correct address
|
|
family in its sa_family field.
|
|
|
|
``EAGAIN`` No more free local ports or insufficient entries in the
|
|
routing cache. For PF_INET.
|
|
|
|
``EALREADY`` The socket is non-blocking and a previous connection
|
|
attempt has not yet been completed.
|
|
|
|
``EBADF`` The file descriptor is not a valid index in the descriptor
|
|
table.
|
|
|
|
``ECONNREFUSED`` No one listening on the remote address.
|
|
|
|
``EFAULT`` The socket structure address is outside the user's address
|
|
space.
|
|
|
|
``EINPROGRESS`` The socket is non-blocking and the connection cannot be
|
|
completed immediately.
|
|
|
|
``EINTR`` The system call was interrupted by a signal that was caught.
|
|
|
|
``EISCONN`` The socket is already connected.
|
|
|
|
``ENETUNREACH`` Network is unreachable.
|
|
|
|
``ENOTSOCK`` The file descriptor is not associated with a socket.
|
|
|
|
``ETIMEDOUT`` Timeout while attempting connection. The server may be too
|
|
busy to accept new connections.
|
|
|
|
.. c:function:: int listen(int sockfd, int backlog);
|
|
|
|
To accept connections, a socket is first created with
|
|
``socket()``, a willingness to accept incoming connections and a queue
|
|
limit for incoming connections are specified with ``listen()``, and then
|
|
the connections are accepted with ``accept()``. The ``listen()`` call
|
|
applies only to sockets of type ``SOCK_STREAM`` or ``SOCK_SEQPACKET``.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of the bound socket.
|
|
- ``backlog``: The maximum length the queue of pending connections may
|
|
grow. If a connection request arrives with the queue full, the client
|
|
may receive an error with an indication of ECONNREFUSED or, if the
|
|
underlying protocol supports retransmission, the request may be
|
|
ignored so that retries succeed.
|
|
|
|
**Returned Value:** On success, zero is returned. On error, -1 is
|
|
returned, and ```errno`` <#ErrnoAccess>`__ is set appropriately.
|
|
|
|
- ``EADDRINUSE``: Another socket is already listening on the same port.
|
|
- ``EBADF``: The argument ``sockfd`` is not a valid descriptor.
|
|
- ``ENOTSOCK``: The argument ``sockfd`` is not a socket.
|
|
- ``EOPNOTSUPP``: The socket is not of a type that supports the listen
|
|
operation.
|
|
|
|
.. c:function:: int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);
|
|
|
|
The ``accept()`` function is used with connection-based
|
|
socket types (``SOCK_STREAM``, ``SOCK_SEQPACKET`` and ``SOCK_RDM``). It
|
|
extracts the first connection request on the queue of pending
|
|
connections, creates a new connected socket with most of the same
|
|
properties as ``sockfd``, and allocates a new socket descriptor for the
|
|
socket, which is returned. The newly created socket is no longer in the
|
|
listening state. The original socket ``sockfd`` is unaffected by this
|
|
call. Per file descriptor flags are not inherited across an accept.
|
|
|
|
The ``sockfd`` argument is a socket descriptor that has been created
|
|
with ``socket()``, bound to a local address with ``bind()``, and is
|
|
listening for connections after a call to ``listen()``.
|
|
|
|
On return, the ``addr`` structure is filled in with the address of the
|
|
connecting entity. The ``addrlen`` argument initially contains the size
|
|
of the structure pointed to by ``addr``; on return it will contain the
|
|
actual length of the address returned.
|
|
|
|
If no pending connections are present on the queue, and the socket is
|
|
not marked as non-blocking, accept blocks the caller until a connection
|
|
is present. If the socket is marked non-blocking and no pending
|
|
connections are present on the queue, accept returns ``EAGAIN``.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of the listening socket.
|
|
- ``addr``: Receives the address of the connecting client.
|
|
- ``addrlen``: Input: allocated size of ``addr``, Return: returned size
|
|
of ``addr``.
|
|
|
|
**Returned Value:** Returns -1 on error. If it succeeds, it returns a
|
|
non-negative integer that is a descriptor for the accepted socket.
|
|
|
|
- ``EAGAIN`` or ``EWOULDBLOCK``: The socket is marked non-blocking and
|
|
no connections are present to be accepted.
|
|
- ``EBADF``: The descriptor is invalid.
|
|
- ``ENOTSOCK``: The descriptor references a file, not a socket.
|
|
- ``EOPNOTSUPP``: The referenced socket is not of type ``SOCK_STREAM``.
|
|
- ``EINTR``: The system call was interrupted by a signal that was
|
|
caught before a valid connection arrived.
|
|
- ``ECONNABORTED``: A connection has been aborted.
|
|
- ``EINVAL``: Socket is not listening for connections.
|
|
- ``EMFILE``: The per-process limit of open file descriptors has been
|
|
reached.
|
|
- ``ENFILE``: The system maximum for file descriptors has been reached.
|
|
- ``EFAULT``: The addr parameter is not in a writable part of the user
|
|
address space.
|
|
- ``ENOBUFS`` or ``ENOMEM``: Not enough free memory.
|
|
- ``EPROTO``: Protocol error.
|
|
- ``EPERM``: Firewall rules forbid connection.
|
|
|
|
.. c:function:: ssize_t send(int sockfd, const void *buf, size_t len, int flags);
|
|
|
|
The ``send()`` call may be used only when the socket is
|
|
in a connected state (so that the intended recipient is known). The only
|
|
difference between ``send()`` and ``write()`` is the presence of
|
|
``flags``. With ``zero`` flags parameter, ``send()`` is equivalent to
|
|
``write()``. Also, ``send(s,buf,len,flags)`` is equivalent to
|
|
``sendto(s,buf,len,flags,NULL,0)``.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of socket
|
|
- ``buf``: Data to send
|
|
- ``len``: Length of data to send
|
|
- ``flags``: Send flags
|
|
|
|
**Returned Value:** See ```sendto()`` <#sendto>`__.
|
|
|
|
.. c:function:: ssize_t sendto(int sockfd, const void *buf, size_t len, int flags, \
|
|
const struct sockaddr *to, socklen_t tolen);
|
|
|
|
If ``sendto()`` is used on a connection-mode
|
|
(SOCK_STREAM, SOCK_SEQPACKET) socket, the parameters to and tolen are
|
|
ignored (and the error EISCONN may be returned when they are not NULL
|
|
and 0), and the error ENOTCONN is returned when the socket was not
|
|
actually connected.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of socket
|
|
- ``buf``: Data to send
|
|
- ``len``: Length of data to send
|
|
- ``flags``: Send flags
|
|
- ``to``: Address of recipient
|
|
- ``tolen``: The length of the address structure
|
|
|
|
**Returned Value:** On success, returns the number of characters sent.
|
|
On error, -1 is returned, and ```errno`` <#ErrnoAccess>`__ is set
|
|
appropriately:
|
|
|
|
- ``EAGAIN`` or ``EWOULDBLOCK``. The socket is marked non-blocking and
|
|
the requested operation would block.
|
|
- ``EBADF``. An invalid descriptor was specified.
|
|
- ``ECONNRESET``. Connection reset by peer.
|
|
- ``EDESTADDRREQ``. The socket is not connection-mode, and no peer
|
|
address is set.
|
|
- ``EFAULT``. An invalid user space address was specified for a
|
|
parameter.
|
|
- ``EINTR``. A signal occurred before any data was transmitted.
|
|
- ``EINVAL``. Invalid argument passed.
|
|
- ``EISCONN``. The connection-mode socket was connected already but a
|
|
recipient was specified. (Now either this error is returned, or the
|
|
recipient specification is ignored.)
|
|
- ``EMSGSIZE``. The socket type requires that message be sent
|
|
atomically, and the size of the message to be sent made this
|
|
impossible.
|
|
- ``ENOBUFS``. The output queue for a network interface was full. This
|
|
generally indicates that the interface has stopped sending, but may
|
|
be caused by transient congestion.
|
|
- ``ENOMEM``. No memory available.
|
|
- ``ENOTCONN``. The socket is not connected, and no target has been
|
|
given.
|
|
- ``ENOTSOCK``. The argument s is not a socket.
|
|
- ``EOPNOTSUPP``. Some bit in the flags argument is inappropriate for
|
|
the socket type.
|
|
- ``EPIPE``. The local end has been shut down on a connection oriented
|
|
socket. In this case the process will also receive a SIGPIPE unless
|
|
MSG_NOSIGNAL is set.
|
|
|
|
.. c:function:: ssize_t recv(int sockfd, void *buf, size_t len, int flags);
|
|
|
|
The ``recv()`` call is identical to
|
|
```recvfrom()`` <#recvfrom>`__ with a NULL ``from`` parameter.
|
|
|
|
**Input Parameters:**
|
|
|
|
- sockfd: Socket descriptor of socket
|
|
- buf: Buffer to receive data
|
|
- len: Length of buffer
|
|
- flags: Receive flags
|
|
|
|
**Returned Value:** See ```recvfrom()`` <#recvfrom>`__.
|
|
|
|
.. c:function:: ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags, \
|
|
struct sockaddr *from, socklen_t *fromlen);
|
|
|
|
``recvfrom()`` receives messages from a socket, and may
|
|
be used to receive data on a socket whether or not it is
|
|
connection-oriented.
|
|
|
|
If ``from`` is not NULL, and the underlying protocol provides the source
|
|
address, this source address is filled in. The argument ``fromlen``
|
|
initialized to the size of the buffer associated with ``from``, and
|
|
modified on return to indicate the actual size of the address stored
|
|
there.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of socket.
|
|
- ``buf``: Buffer to receive data.
|
|
- ``len``: Length of buffer.
|
|
- ``flags``: Receive flags.
|
|
- ``from``: Address of source.
|
|
- ``fromlen``: The length of the address structure.
|
|
|
|
**Returned Value:** On success, returns the number of characters sent.
|
|
If no data is available to be received and the peer has performed an
|
|
orderly shutdown, recv() will return 0. Otherwise, on errors, -1 is
|
|
returned, and ```errno`` <#ErrnoAccess>`__ is set appropriately:
|
|
|
|
- ``EAGAIN``. The socket is marked non-blocking and the receive
|
|
operation would block, or a receive timeout had been set and the
|
|
timeout expired before data was received.
|
|
- ``EBADF``. The argument ``sockfd`` is an invalid descriptor.
|
|
- ``ECONNREFUSED``. A remote host refused to allow the network
|
|
connection (typically because it is not running the requested
|
|
service).
|
|
- ``EFAULT``. The receive buffer pointer(s) point outside the process's
|
|
address space.
|
|
- ``EINTR``. The receive was interrupted by delivery of a signal before
|
|
any data were available.
|
|
- ``EINVAL``. Invalid argument passed.
|
|
- ``ENOMEM``. Could not allocate memory.
|
|
- ``ENOTCONN``. The socket is associated with a connection-oriented
|
|
protocol and has not been connected.
|
|
- ``ENOTSOCK``. The argument ``sockfd`` does not refer to a socket.
|
|
|
|
.. c:function:: int setsockopt(int sockfd, int level, int option, \
|
|
const void *value, socklen_t value_len);
|
|
|
|
``setsockopt()`` sets the option specified by the
|
|
``option`` argument, at the protocol level specified by the ``level``
|
|
argument, to the value pointed to by the ``value`` argument for the
|
|
socket associated with the file descriptor specified by the ``sockfd``
|
|
argument.
|
|
|
|
The ``level`` argument specifies the protocol level of the option. To
|
|
set options at the socket level, specify the level argument as
|
|
SOL_SOCKET.
|
|
|
|
See ``sys/socket.h`` for a complete list of values for the ``option``
|
|
argument.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of socket
|
|
- ``level``: Protocol level to set the option
|
|
- ``option``: identifies the option to set
|
|
- ``value``: Points to the argument value
|
|
- ``value_len``: The length of the argument value
|
|
|
|
**Returned Value:** On success, returns the number of characters sent.
|
|
On error, -1 is returned, and ```errno`` <#ErrnoAccess>`__ is set
|
|
appropriately:
|
|
|
|
- ``BADF``. The ``sockfd`` argument is not a valid socket descriptor.
|
|
- ``DOM``. The send and receive timeout values are too big to fit into
|
|
the timeout fields in the socket structure.
|
|
- ``INVAL``. The specified option is invalid at the specified socket
|
|
``level`` or the socket has been shut down.
|
|
- ``ISCONN``. The socket is already connected, and a specified option
|
|
cannot be set while the socket is connected.
|
|
- ``NOPROTOOPT``. The ``option`` is not supported by the protocol.
|
|
- ``NOTSOCK``. The ``sockfd`` argument does not refer to a socket.
|
|
- ``NOMEM``. There was insufficient memory available for the operation
|
|
to complete.
|
|
- ``NOBUFS``. Insufficient resources are available in the system to
|
|
complete the call.
|
|
|
|
.. c:function:: int getsockopt(int sockfd, int level, int option, void *value, socklen_t *value_len);
|
|
|
|
``getsockopt()`` retrieve those value for the option
|
|
specified by the ``option`` argument for the socket specified by the
|
|
``sockfd`` argument. If the size of the option value is greater than
|
|
``value_len``, the value stored in the object pointed to by the
|
|
``value`` argument will be silently truncated. Otherwise, the length
|
|
pointed to by the ``value_len`` argument will be modified to indicate
|
|
the actual length of the ``value``.
|
|
|
|
The ``level`` argument specifies the protocol level of the option. To
|
|
retrieve options at the socket level, specify the level argument as
|
|
SOL_SOCKET.
|
|
|
|
See ``sys/socket.h`` for a complete list of values for the ``option``
|
|
argument.
|
|
|
|
**Input Parameters:**
|
|
|
|
- ``sockfd``: Socket descriptor of socket
|
|
- ``level``: Protocol level to set the option
|
|
- ``option``: Identifies the option to get
|
|
- ``value``: Points to the argument value
|
|
- ``value_len``: The length of the argument value
|
|
|
|
**Returned Value:** On success, returns the number of characters sent.
|
|
On error, -1 is returned, and ```errno`` <#ErrnoAccess>`__ is set
|
|
appropriately:
|
|
|
|
- ``BADF``. The ``sockfd`` argument is not a valid socket descriptor.
|
|
- ``INVAL``. The specified option is invalid at the specified socket
|
|
``level`` or the socket has been shutdown.
|
|
- ``NOPROTOOPT``. The ``option`` is not supported by the protocol.
|
|
- ``NOTSOCK``. The ``sockfd`` argument does not refer to a socket.
|
|
- ``NOBUFS``. Insufficient resources are available in the system to
|
|
complete the call.
|
|
|