Clean missing function headers

include/nuttx/net/net.h

@@ -161,112 +161,533 @@ extern "C"
  * Public Function Prototypes
  ****************************************************************************/
 
-/* net_lock.c ****************************************************************/
+/****************************************************************************
-/* Critical section management.  The NuttX configuration setting
+ * Critical section management.  The NuttX configuration setting
  * CONFIG_NET_NOINT indicates that uIP not called from the interrupt level.
  * If CONFIG_NET_NOINTS is defined, then these will map to semaphore
  * controls.  Otherwise, it assumed that uIP will be called from interrupt
  * level handling and these will map to interrupt enable/disable controls.
- */
+ *
+ *
+ * If CONFIG_NET_NOINTS is defined, then semaphore based locking is used:
+ *
+ *   net_lock()          - Takes the semaphore().  Implements a re-entrant mutex.
+ *   net_unlock()        - Gives the semaphore().
+ *   net_lockedwait()    - Like pthread_cond_wait(); releases the semaphore
+ *                         momentarily to wait on another semaphore()
+ *
+ * Otherwise, interrupt based locking is used:
+ *
+ *   net_lock()          - Disables interrupts.
+ *   net_unlock()        - Conditionally restores interrupts.
+ *   net_lockedwait()    - Just wait for the semaphore.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Function: net_lock
+ *
+ * Description:
+ *   Take the lock
+ *
+ ****************************************************************************/
 
 #ifdef CONFIG_NET_NOINTS
-/* Semaphore based locking for non-interrupt based logic.
- *
- * net_lock()           -- Takes the semaphore().  Implements a re-entrant mutex.
- * net_unlock()         -- Gives the semaphore().
- * net_lockedwait()     -- Like pthread_cond_wait(); releases the semaphore
- *                         momentarily to wait on another semaphore()
- */
-
 net_lock_t net_lock(void);
-void net_unlock(net_lock_t flags);
-int net_lockedwait(sem_t *sem);
-
 #else
-
-/* Enable/disable locking for interrupt based logic:
- *
- * net_lock()           -- Disables interrupts.
- * net_unlock()         -- Conditionally restores interrupts.
- * net_lockedwait()     -- Just wait for the semaphore.
- */
-
 #  define net_lock() irqsave()
-#  define net_unlock(f)     irqrestore(f)
-#  define net_lockedwait(s) sem_wait(s)
-
 #endif
 
-/* This function may be used at boot time to set the initial ip_id.*/
+/****************************************************************************
+ * Function: net_unlock
+ *
+ * Description:
+ *   Release the lock.
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_NET_NOINTS
+void net_unlock(net_lock_t flags);
+#else
+#  define net_unlock(f) irqrestore(f)
+#endif
+
+/****************************************************************************
+ * Function: net_lockedwait
+ *
+ * Description:
+ *   Atomically wait for sem while temporarily releasing g_netlock.
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_NET_NOINTS
+int net_lockedwait(sem_t *sem);
+#else
+#  define net_lockedwait(s) sem_wait(s)
+#endif
+
+/****************************************************************************
+ * Function: net_setipid
+ *
+ * Description:
+ *   This function may be used at boot time to set the initial ip_id.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 void net_setipid(uint16_t id);
 
-/* net_checksd.c *************************************************************/
+/****************************************************************************
-/* Check if the socket descriptor is valid for the provided TCB and if it
+ * Name: net_checksd
- * supports the requested access.
+ *
- */
+ * Description:
+ *   Check if the socket descriptor is valid for the provided TCB and if it
+ *   supports the requested access.  This trivial operation is part of the
+ *   fdopen() operation when the fdopen() is performed on a socket descriptor.
+ *   It simply performs some sanity checking before permitting the socket
+ *   descriptor to be wrapped as a C FILE stream.
+ *
+ ****************************************************************************/
 
 int net_checksd(int fd, int oflags);
 
-/* net_sockets.c *************************************************************/
+/****************************************************************************
-/* There interfaces are called only from OS scheduling and iniialization logic
+ * Name: net_initialize
- * under sched/
+ *
- */
+ * Description:
+ *   This is called from the OS initialization logic at power-up reset in
+ *   order to configure the networking subsystem.
+ *
+ * Input Parameters:
+ *   None
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
 
 void net_initialize(void);
+
+/****************************************************************************
+ * Name:
+ *
+ * Description:
+ *   Initialize a list of sockets for a new task
+ *
+ * Input Parameters:
+ *   list -- A reference to the pre-alloated socket list to be initialized.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
 void net_initlist(FAR struct socketlist *list);
+
+/****************************************************************************
+ * Name: net_releaselist
+ *
+ * Description:
+ *   Release resources held by the socket list
+ *
+ * Input Parameters:
+ *   list -- A reference to the pre-allocated socket list to be un-initialized.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
 void net_releaselist(FAR struct socketlist *list);
 
-/* Given a socket descriptor, return the underlying NuttX-specific socket
+/****************************************************************************
- * structure.
+ * Name: sockfd_release
- */
+ *
+ * Description:
+ *   Free the socket by its socket descriptor.
+ *
+ * Input Parameters:
+ *   sockfd - Socket descriptor identifies the socket to be released.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
 
 FAR struct socket *sockfd_socket(int sockfd);
 
-/* socket.c ******************************************************************/
+/****************************************************************************
-/* socket using underlying socket structure */
+ * Function: psock_socket
+ *
+ * Description:
+ *   socket() creates an endpoint for communication and returns a socket
+ *   structure.
+ *
+ * Parameters:
+ *   domain   (see sys/socket.h)
+ *   type     (see sys/socket.h)
+ *   protocol (see sys/socket.h)
+ *   psock    A pointer to a user allocated socket structure to be initialized.
+ *
+ * Returned Value:
+ *   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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int psock_socket(int domain, int type, int protocol, FAR struct socket *psock);
 
-/* net_close.c ***************************************************************/
+/****************************************************************************
-/* The standard close() operation redirects operations on socket descriptors
+ * Function: net_close
- * to this function.
+ *
- */
+ * Description:
+ *   Performs the close operation on socket descriptors
+ *
+ * Parameters:
+ *   sockfd   Socket descriptor of socket
+ *
+ * Returned Value:
+ *   0 on success; -1 on error with errno set appropriately.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int net_close(int sockfd);
 
-/* Performs the close operation on a socket instance */
+/****************************************************************************
+ * Function: psock_close
+ *
+ * Description:
+ *   Performs the close operation on a socket instance
+ *
+ * Parameters:
+ *   psock   Socket instance
+ *
+ * Returned Value:
+ *   0 on success; -1 on error with errno set appropriately.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int psock_close(FAR struct socket *psock);
 
-/* net_close.c ***************************************************************/
+/****************************************************************************
-/* Performs the bind() operation on a socket instance */
+ * Function: psock_bind
+ *
+ * Description:
+ *   bind() gives the socket 'psock' 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.
+ *
+ * Parameters:
+ *   psock    Socket structure of the socket to bind
+ *   addr     Socket local address
+ *   addrlen  Length of 'addr'
+ *
+ * Returned Value:
+ *   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.
+ *   EINVAL
+ *     The socket is already bound to an address.
+ *   ENOTSOCK
+ *     psock is a descriptor for a file, not a socket.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 struct sockaddr; /* Forward reference. Defined in nuttx/include/sys/socket.h */
 int psock_bind(FAR struct socket *psock, FAR const struct sockaddr *addr,
                socklen_t addrlen);
 
-/* connect.c *****************************************************************/
+/****************************************************************************
-/* Performs the connect() operation on a socket instance */
+ * Name: psock_connect
+ *
+ * Description:
+ *   connect() connects the socket referred to by the structure 'psock'
+ *   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 'psock'.
+ *
+ *   If the socket 'psock' 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.
+ *
+ * Parameters:
+ *   psock     Pointer to a socket structure initialized by psock_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 set appropriately
+ *
+ *     EACCES, 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.
+ *     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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int psock_connect(FAR struct socket *psock, FAR const struct sockaddr *addr,
                   socklen_t addrlen);
 
-/* send.c ********************************************************************/
+/****************************************************************************
-/* Send using underlying socket structure */
+ * Function: psock_send
+ *
+ * Description:
+ *   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(sockfd,buf,len,flags) is
+ *   equivalent to sendto(sockfd,buf,len,flags,NULL,0).
+ *
+ * Parameters:
+ *   psock    An instance of the internal socket structure.
+ *   buf      Data to send
+ *   len      Length of data to send
+ *   flags    Send flags
+ *
+ * Returned Value:
+ *   On success, returns the number of characters sent.  On  error,
+ *   -1 is returned, and errno 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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 ssize_t psock_send(FAR struct socket *psock, const void *buf, size_t len,
                    int flags);
 
-/* sendto.c ******************************************************************/
+/****************************************************************************
-/* Sendto using underlying socket structure */
+ * Function: psock_sendto
+ *
+ * Description:
+ *   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.
+ *
+ * Parameters:
+ *   psock    A pointer to a NuttX-specific, internal socket structure
+ *   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 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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 ssize_t psock_sendto(FAR struct socket *psock, FAR const void *buf,
                      size_t len, int flags, FAR const struct sockaddr *to,
                      socklen_t tolen);
 
-/* recvfrom.c ****************************************************************/
+/****************************************************************************
-/* recvfrom using the underlying socket structure */
+ * Function: psock_recvfrom
+ *
+ * Description:
+ *   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.
+ *
+ * Parameters:
+ *   psock    A pointer to a NuttX-specific, internal socket structure
+ *   buf      Buffer to receive data
+ *   len      Length of buffer
+ *   flags    Receive flags
+ *   from     Address of source (may be NULL)
+ *   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
+ *   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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 ssize_t psock_recvfrom(FAR struct socket *psock, FAR void *buf, size_t len,
                        int flags, FAR struct sockaddr *from,
@@ -277,99 +698,364 @@ ssize_t psock_recvfrom(FAR struct socket *psock, FAR void *buf, size_t len,
 #define psock_recv(psock,buf,len,flags) \
   psock_recvfrom(psock,buf,len,flags,NULL,0)
 
-/* getsockopt.c **************************************************************/
+/****************************************************************************
-/* getsockopt using the underlying socket structure */
+ * Function: psock_getsockopt
+ *
+ * Description:
+ *   getsockopt() retrieve thse value for the option specified by the
+ *   'option' argument for the socket specified by the 'psock' 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> a complete list of values for the 'option' argument.
+ *
+ * Parameters:
+ *   psock     Socket structure of the socket to query
+ *   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:
+ *
+ *  EINVAL
+ *    The specified option is invalid at the specified socket 'level' or the
+ *    socket has been shutdown.
+ *  ENOPROTOOPT
+ *    The 'option' is not supported by the protocol.
+ *  ENOTSOCK
+ *    The 'psock' argument does not refer to a socket.
+ *  ENOBUFS
+ *    Insufficient resources are available in the system to complete the
+ *    call.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int psock_getsockopt(FAR struct socket *psock, int level, int option,
                      FAR void *value, FAR socklen_t *value_len);
 
-/* setsockopt.c **************************************************************/
+/****************************************************************************
-/* setsockopt using the underlying socket structure */
+ * Function: psock_setsockopt
+ *
+ * Description:
+ *   psock_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 on the 'psock' 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> a complete list of values for the 'option' argument.
+ *
+ * Parameters:
+ *   psock     Socket structure of socket to operate on
+ *   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:
+ *  0 on success; -1 on failure
+ *
+ *  EDOM
+ *    The send and receive timeout values are too big to fit into the
+ *    timeout fields in the socket structure.
+ *  EINVAL
+ *    The specified option is invalid at the specified socket 'level' or the
+ *    socket has been shut down.
+ *  EISCONN
+ *    The socket is already connected, and a specified option cannot be set
+ *    while the socket is connected.
+ *  ENOPROTOOPT
+ *    The 'option' is not supported by the protocol.
+ *  ENOTSOCK
+ *    The 'sockfd' argument does not refer to a socket.
+ *  ENOMEM
+ *    There was insufficient memory available for the operation to complete.
+ *  ENOBUFS
+ *    Insufficient resources are available in the system to complete the
+ *    call.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 int psock_setsockopt(FAR struct socket *psock, int level, int option,
                      FAR const void *value, socklen_t value_len);
 
-/* net_ioctl.c ***************************************************************/
+/****************************************************************************
-/* The standard ioctl() operation redirects operations on socket descriptors
+ * Name: netdev_ioctl
- * to this function.
+ *
- */
+ * Description:
+ *   Perform network device specific operations.
+ *
+ * Parameters:
+ *   sockfd   Socket descriptor of device
+ *   cmd      The ioctl command
+ *   arg      The argument of the ioctl cmd
+ *
+ * Return:
+ *   >=0 on success (positive non-zero values are cmd-specific)
+ *   On a failure, -1 is returned with errno set appropriately
+ *
+ *   EBADF
+ *     'sockfd' is not a valid descriptor.
+ *   EFAULT
+ *     'arg' references an inaccessible memory area.
+ *   ENOTTY
+ *     'cmd' not valid.
+ *   EINVAL
+ *     'arg' is not valid.
+ *   ENOTTY
+ *     'sockfd' is not associated with a network device.
+ *   ENOTTY
+ *      The specified request does not apply to the kind of object that the
+ *      descriptor 'sockfd' references.
+ *
+ ****************************************************************************/
 
 int netdev_ioctl(int sockfd, int cmd, unsigned long arg);
 
-/* net_poll.c ****************************************************************/
+/****************************************************************************
-/* The standard poll() operation redirects operations on socket descriptors
+ * Function: psock_poll
+ *
+ * Description:
+ *   The standard poll() operation redirects operations on socket descriptors
  *   to this function.
- */
+ *
+ * Input Parameters:
+ *   psock - An instance of the internal socket structure.
+ *   fds   - The structure describing the events to be monitored, OR NULL if
+ *           this is a request to stop monitoring events.
+ *   setup - true: Setup up the poll; false: Teardown the poll
+ *
+ * Returned Value:
+ *  0: Success; Negated errno on failure
+ *
+ ****************************************************************************/
 
 #ifndef CONFIG_DISABLE_POLL
 struct pollfd; /* Forward reference -- see poll.h */
-
 int psock_poll(FAR struct socket *psock, struct pollfd *fds, bool setup);
+#endif
+
+/****************************************************************************
+ * Function: net_poll
+ *
+ * Description:
+ *   The standard poll() operation redirects operations on socket descriptors
+ *   to this function.
+ *
+ * Input Parameters:
+ *   fd    - The socket descriptor of interest
+ *   fds   - The structure describing the events to be monitored, OR NULL if
+ *           this is a request to stop monitoring events.
+ *   setup - true: Setup up the poll; false: Teardown the poll
+ *
+ * Returned Value:
+ *  0: Success; Negated errno on failure
+ *
+ ****************************************************************************/
+
+#ifndef CONFIG_DISABLE_POLL
+struct pollfd; /* Forward reference -- see poll.h */
 int net_poll(int sockfd, struct pollfd *fds, bool setup);
 #endif
 
-/* net_dup.c *****************************************************************/
+/****************************************************************************
-/* The standard dup() operation redirects operations on socket descriptors to
+ * Function: net_dup
- * this function
+ *
- */
+ * Description:
+ *   Clone a socket descriptor to an arbitray descriptor number.  If file
+ *   descriptors are implemented, then this is called by dup() for the case
+ *   of socket file descriptors.  If file descriptors are not implemented,
+ *   then this function IS dup().
+ *
+ ****************************************************************************/
 
 int net_dup(int sockfd, int minsd);
 
-/* net_dup2.c ****************************************************************/
+/****************************************************************************
-/* The standard dup2() operation redirects operations on socket descriptors to
+ * Function: net_dup2
- * this function (when both file and socket descriptors are supported)
+ *
- */
+ * Description:
+ *   Clone a socket descriptor to an arbitray descriptor number.  If file
+ *   descriptors are implemented, then this is called by dup2() for the case
+ *   of socket file descriptors.  If file descriptors are not implemented,
+ *   then this function IS dup2().
+ *
+ ****************************************************************************/
 
-#if CONFIG_NFILE_DESCRIPTORS > 0
 int net_dup2(int sockfd1, int sockfd2);
-#else
-#  define net_dup2(sockfd1, sockfd2) dup2(sockfd1, sockfd2)
-#endif
 
-/* net_clone.c ***************************************************************/
+/****************************************************************************
-/* Performs the low level, common portion of net_dup() and net_dup2() */
+ * Function: net_clone
+ *
+ * Description:
+ *   Performs the low level, common portion of net_dup() and net_dup2()
+ *
+ ****************************************************************************/
 
 int net_clone(FAR struct socket *psock1, FAR struct socket *psock2);
 
-/* net_sendfile.c ************************************************************/
+/****************************************************************************
-/* Send files via a TCP connections */
+ * Function: net_sendfile
+ *
+ * Description:
+ *   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(sockfd,buf,len,flags) is
+ *   equivalent to sendto(sockfd,buf,len,flags,NULL,0).
+ *
+ * Parameters:
+ *   psock    An instance of the internal socket structure.
+ *   buf      Data to send
+ *   len      Length of data to send
+ *   flags    Send flags
+ *
+ * Returned Value:
+ *   On success, returns the number of characters sent.  On  error,
+ *   -1 is returned, and errno 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.
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
 
 #ifdef CONFIG_NET_SENDFILE
 struct file;
 ssize_t net_sendfile(int outfd, struct file *infile, off_t *offset, size_t count);
 #endif
 
-/* net_vfcntl.c **************************************************************/
+/****************************************************************************
-/* Performs fcntl operations on socket */
+ * Name: net_vfcntl
+ *
+ * Description:
+ *   Performs fcntl operations on socket
+ *
+ * Input Parameters:
+ *   sockfd - Socket descriptor of the socket to operate on
+ *   cmd    - The fcntl command.
+ *   ap     - Command-specific arguments
+ *
+ * Returned Value:
+ *   Zero (OK) is returned on success; -1 (ERROR) is returned on failure and
+ *   the errno value is set appropriately.
+ *
+ ****************************************************************************/
 
 int net_vfcntl(int sockfd, int cmd, va_list ap);
 
-/* netdev-register.c *********************************************************/
+/****************************************************************************
-/* This function is called by network interface device drivers to inform the
+ * Function: netdev_register
- * socket layer of their existence.  This registration is necesary to support
+ *
- * ioctl() operations on network devices to, for example, set MAC and IP
+ * Description:
- * addresses
+ *   Register a network device driver and assign a name to it so that it can
- */
+ *   be found in subsequent network ioctl operations on the device.
+ *
+ * Parameters:
+ *   dev - The device driver structure to register
+ *
+ * Returned Value:
+ *   0:Success; negated errno on failure
+ *
+ * Assumptions:
+ *   Called during system initialization from normal user mode
+ *
+ ****************************************************************************/
 
 int netdev_register(FAR struct net_driver_s *dev);
 
-/* netdev-unregister.c *********************************************************/
+/****************************************************************************
-/* Unregister a network device driver. */
+ * Function: netdev_unregister
+ *
+ * Description:
+ *   Unregister a network device driver.
+ *
+ * Parameters:
+ *   dev - The device driver structure to un-register
+ *
+ * Returned Value:
+ *   0:Success; negated errno on failure
+ *
+ * Assumptions:
+ *   Currently only called for USB networking devices when the device is
+ *   physically removed from the slot
+ *
+ ****************************************************************************/
 
 int netdev_unregister(FAR struct net_driver_s *dev);
 
-/* net_foreach.c ************************************************************/
+/****************************************************************************
-/* Enumerates all registered network devices */
+ * Function: netdev_foreach
+ *
+ * Description:
+ *   Enumerate each registered network device.
+ *
+ *   NOTE: netdev semaphore held throughout enumeration.
+ *
+ * Parameters:
+ *   callback - Will be called for each registered device
+ *   arg      - User argument passed to callback()
+ *
+ * Returned Value:
+ *  0:Enumeration completed 1:Enumeration terminated early by callback
+ *
+ * Assumptions:
+ *  Called from normal user mode
+ *
+ ****************************************************************************/
 
 int netdev_foreach(netdev_callback_t callback, void *arg);
 
-/* drivers/net/slip.c ******************************************************/
-/* Instantiate a SLIP network interface. */
-
-#ifdef CONFIG_NET_SLIP
-int slip_initialize(int intf, const char *devname);
-#endif
-
 #undef EXTERN
 #ifdef __cplusplus
 }

net/net_initialize.c

@@ -80,7 +80,20 @@
  * Public Functions
  ****************************************************************************/
 
-/* This is called from the initialization logic to configure the socket layer */
+/****************************************************************************
+ * Name: net_initialize
+ *
+ * Description:
+ *   This is called from the OS initialization logic at power-up reset in
+ *   order to configure the networking subsystem.
+ *
+ * Input Parameters:
+ *   None
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
 
 void net_initialize(void)
 {

net/netdev/Make.defs

@@ -35,7 +35,7 @@
 
 # Support for operations on network devices
 
-NETDEV_CSRCS += netdev_register.c netdev_ioctl.c net_poll.c netdev_txnotify.c
+NETDEV_CSRCS += netdev_register.c netdev_ioctl.c netdev_txnotify.c
 NETDEV_CSRCS += netdev_findbyname.c netdev_findbyaddr.c netdev_count.c
 NETDEV_CSRCS += netdev_foreach.c netdev_unregister.c netdev_sem.c
 NETDEV_CSRCS += netdev_carrier.c

net/netdev/netdev_register.c

@@ -95,7 +95,7 @@ struct net_driver_s *g_netdevices = NULL;
  * Function: netdev_register
  *
  * Description:
- *   Register a network device driver and assign a name to it so tht it can
+ *   Register a network device driver and assign a name to it so that it can
  *   be found in subsequent network ioctl operations on the device.
  *
  * Parameters:

net/socket/Make.defs

@@ -37,7 +37,7 @@
 
 SOCK_CSRCS += bind.c connect.c getsockname.c recv.c recvfrom.c socket.c
 SOCK_CSRCS += sendto.c net_sockets.c net_close.c net_dup.c net_dup2.c
-SOCK_CSRCS += net_clone.c net_vfcntl.c
+SOCK_CSRCS += net_clone.c net_poll.c net_vfcntl.c
 
 # TCP/IP support
 

net/socket/net_poll.c

@@ -386,7 +386,7 @@ static inline int net_pollteardown(FAR struct socket *psock,
  ****************************************************************************/
 
 /****************************************************************************
- * Function: net_poll
+ * Function: psock_poll
  *
  * Description:
  *   The standard poll() operation redirects operations on socket descriptors

net/socket/net_sockets.c

@@ -38,7 +38,6 @@
  ****************************************************************************/
 
 #include <nuttx/config.h>
-#ifdef CONFIG_NET
 
 #include <string.h>
 #include <semaphore.h>
@@ -52,6 +51,8 @@
 
 #include "socket/socket.h"
 
+#if CONFIG_NSOCKET_DESCRIPTORS > 0
+
 /****************************************************************************
  * Pre-processor Definitions
  ****************************************************************************/
@@ -72,7 +73,6 @@
  * Private Functions
  ****************************************************************************/
 
-#if CONFIG_NSOCKET_DESCRIPTORS > 0
 static void _net_semtake(FAR struct socketlist *list)
 {
   /* Take the semaphore (perhaps waiting) */
@@ -87,16 +87,23 @@ static void _net_semtake(FAR struct socketlist *list)
     }
 }
 
-# define _net_semgive(list) sem_post(&list->sl_sem)
-#endif
-
 /****************************************************************************
  * Public Functions
  ****************************************************************************/
 
-#if CONFIG_NSOCKET_DESCRIPTORS > 0
+/****************************************************************************
-
+ * Name:
-/* Initialize a list of sockets for a new task */
+ *
+ * Description:
+ *   Initialize a list of sockets for a new task
+ *
+ * Input Parameters:
+ *   list -- A reference to the pre-allocated socket list to be initialized.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
 
 void net_initlist(FAR struct socketlist *list)
 {
@@ -105,7 +112,19 @@ void net_initlist(FAR struct socketlist *list)
   (void)sem_init(&list->sl_sem, 0, 1);
 }
 
-/* Release release resources held by the socket list */
+/****************************************************************************
+ * Name: net_releaselist
+ *
+ * Description:
+ *   Release resources held by the socket list
+ *
+ * Input Parameters:
+ *   list -- A reference to the pre-allocated socket list to be un-initialized.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
 
 void net_releaselist(FAR struct socketlist *list)
 {
@@ -129,6 +148,21 @@ void net_releaselist(FAR struct socketlist *list)
   (void)sem_destroy(&list->sl_sem);
 }
 
+/****************************************************************************
+ * Name: sockfd_allocate
+ *
+ * Description:
+ *   Allocate a socket descriptor
+ *
+ * Input Parameters:
+ *   Lowest socket descripor index to be used.
+ *
+ * Returned Value:
+ *   On success, a socket desrciptor >= minsd is returned.  A negater errno
+ *   value is returned on failure.
+ *
+ ****************************************************************************/
+
 int sockfd_allocate(int minsd)
 {
   FAR struct socketlist *list;
@@ -158,12 +192,25 @@ int sockfd_allocate(int minsd)
                return i + __SOCKFD_OFFSET;
             }
         }
+
       _net_semgive(list);
     }
 
   return ERROR;
 }
 
+/****************************************************************************
+ * Name: sock_release
+ *
+ * Description:
+ *   Free a socket.
+ *
+ * Input Parameters:
+ *
+ * Returned Value:
+ *
+ ****************************************************************************/
+
 void sock_release(FAR struct socket *psock)
 {
 #if CONFIG_DEBUG
@@ -192,11 +239,26 @@ void sock_release(FAR struct socket *psock)
 
               memset(psock, 0, sizeof(struct socket));
             }
+
           _net_semgive(list);
         }
     }
 }
 
+/****************************************************************************
+ * Name: sockfd_release
+ *
+ * Description:
+ *   Free the socket by its socket descriptor.
+ *
+ * Input Parameters:
+ *   sockfd - Socket descriptor identifies the socket to be released.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
 void sockfd_release(int sockfd)
 {
   /* Get the socket structure for this sockfd */
@@ -211,6 +273,21 @@ void sockfd_release(int sockfd)
     }
 }
 
+/****************************************************************************
+ * Name: sockfd_socket
+ *
+ * Description:
+ *   Given a socket descriptor, return the underlying socket structure.
+ *
+ * Input Parameters:
+ *   sockfd - The socket descriptor index o use.
+ *
+ * Returned Value:
+ *   On success, a reference to the socket structure associated with the
+ *   the socket descriptor is returned.  NULL is returned on any failure.
+ *
+ ****************************************************************************/
+
 FAR struct socket *sockfd_socket(int sockfd)
 {
   FAR struct socketlist *list;
@@ -224,8 +301,8 @@ FAR struct socket *sockfd_socket(int sockfd)
           return &list->sl_sockets[ndx];
         }
     }
+
   return NULL;
 }
 
-#endif /* CONFIG_NSOCKET_DESCRIPTORS */
+#endif /* CONFIG_NSOCKET_DESCRIPTORS > 0 */
-#endif /* CONFIG_NET */

net/socket/net_vfcntl.c

@@ -56,7 +56,24 @@
  ****************************************************************************/
 
 /****************************************************************************
- * Global Functions
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: net_vfcntl
+ *
+ * Description:
+ *   Performs fcntl operations on socket
+ *
+ * Input Parameters:
+ *   sockfd - Socket descriptor of the socket to operate on
+ *   cmd    - The fcntl command.
+ *   ap     - Command-specific arguments
+ *
+ * Returned Value:
+ *   Zero (OK) is returned on success; -1 (ERROR) is returned on failure and
+ *   the errno value is set appropriately.
+ *
  ****************************************************************************/
 
 int net_vfcntl(int sockfd, int cmd, va_list ap)