ARM Club 1

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / comms / a / freenet / !FreeNet_Docs_SWIs < prev next >

Wrap

Text File | 1995-05-18 | 24.8 KB | 669 lines

The Programmer Interface to the FreeNet TCP/IP Stack (C) Tom Hughes 1995 0. Copyright The FreeNet module and application and the tools and documentation that go with them are all copyright. They are however released as freeware subject to certain terms and conditions. These are described in the file named 'Licence' which should have accompanied this document. 1. Overview The FreeNet TCP/IP Stack provides the same interface to the programmer that the Acorn TCP/IP stack does, namely a BSD sockets interface provided via SWI calls. There is also a library of AOF object files available that provides a BSD sockets interface to these calls for use by C programmers. There is a one to one mapping between the SWI calls provided by the FreeNet stack, and the normal BSD socket calls. The arguments are passed in order starting with register 0 and working up, with the return value being passed back in R0. The only difference is that errors are signaled by returning a RISC OS error in the normal way (with V set and R0 pointing to an error block) instead of by returning a value of -1. The error number in the error block will be a normal Unix error code however, and the C library veneers convert these errors back into a -1 return code with errno set. The mapping between BSD calls and SWI calls is decribed by the following table: SWI Number SWI Name BSD Call &41200 Socket_Creat socket() &41201 Socket_Bind bind() &41202 Socket_Listen listen() &41203 Socket_Accept accept() &41204 Socket_Connect connect() &41205 Socket_Recv recv() &41206 Socket_Recvfrom recvfrom() &41207 Socket_Recvmsg recvmsg() &41208 Socket_Send send() &41209 Socket_Sendto sendto() &4120A Socket_Sendmsg sendmsg() &4120B Socket_Shutdown shutdown() &4120C Socket_Setsockopt setsockopt() &4120D Socket_Getsockopt getsockopt() &4120E Socket_Getpeername getpeername() &4120F Socket_Getsockname getsockname() &41210 Socket_Close close() &41211 Socket_Select select() &41212 Socket_Ioctl ioctl() &41213 Socket_Read read() &41214 Socket_Write write() &41215 Socket_Stat stat() &41216 Socket_Readv readv() &41217 Socket_Writev writev() &41218 Socket_Gettsize FD_SETSIZE &41219 Socket_Sendtosm ? The remainder of this document details each of these SWIs in full, describing the arguments and possible return values. 2. Error Codes The errors returned by the Socket SWIs are normal RISC OS errors, complete with suitable explanatory text. The error number will be a Unix error code. These numbers (and the sybolic names associated with them) are as follows: Name Number Explanation EBADF 9 Invalid socket descriptor given EFAULT 14 Buffer is invalid or too small EINVAL 22 Invalid argument EWOULDBLOCK 35 Socket is marked non-blocking, and this operation would normally block EINPROGRESS 36 Operation now in progress EALREADY 37 Operation already in progress EMSGSIZE 40 Message too long ENOPROTOOPT 42 Option not supported by protocol EPROTONOSUPPORT 43 Protocol not supported ESOCKTNOSUPPORT 44 Socket type not supported EOPNOTSUPP 45 Operation not supported EAFNOSUPPORT 47 Address family not supported EADDRINUSE 48 Address already in use ENETUNREACH 51 Network unreachable ECONNRESET 54 Connection reset by peer ENOBUFS 55 No buffer space available EISCONN 56 Socket is already connected ENOTCONN 57 Socket is not connected ECONNREFUSED 61 Connection refused EHOSTUNREACH 65 Host unreachable Throughout the rest of this document, the symbolic names referred to above will be used when talking about specific errors. 3. Other Symbolic Constants Various other constants are used as arguments to Socket SWIs, and these are referred to in this document by the symbolic names used for them in the BSD library code. Their values are as follows: Name Value Name Value SOCK_STREAM 1 SO_DEBUG &0001 SOCK_DGRAM 2 SO_ACCEPTCONN &0002 SOCK_RAW 3 SO_REUSEADDR &0004 SO_KEEPALIVE &0008 PF_INET 2 SO_DONTROUTE &0010 SO_BROADCAST &0020 AF_INET 2 SO_LINGER &0080 SO_OOBINLINE &0100 MSG_OOB &01 SO_SNDBUF &1001 MSG_PEEK &02 SO_RCVBUF &1002 MSG_EOR &08 SO_SNDLOWAT &1003 MSG_TRUNC &10 SO_RCVLOWAT &1004 MSG_WAITALL &40 SO_SNDTIMEO &1005 MSG_DONTWAIT &80 SO_RCVTIMEO &1006 SO_ERROR &1007 SOL_SOCKET &FFFF SO_TYPE &1008 IP_OPTIONS 1 FIOASYNC &8004667D IP_HDRINCL 2 FIONBIO &8004667E IP_TOS 3 FIONREAD &8004667F IP_TTL 4 TCP_NODELAY 1 TCP_MAXSEG 2 4. Socket_Creat In: R0 = Protocol family R1 = Socket type R2 = Protocol Out: R0 = Socket descriptor This call creates a new socket of a given type and using a given protocol. If the protocol is left unspecified (passed as zero), a default applicable to that socket type will be used. The internet protocol family (PF_INET) is the only one supported by this module. Three socket type are supported: SOCK_STREAM - Stream orientated connections providing bi-directional sequenced, reliable transfer of byte streams. The only protocol of this type currently supported is the transmission control protocol (TCP). SOCK_DGRAM - Connectionless, messages based protocols providing unreliable, non-sequence communication. The only protocol of this type currently supported is the user datagram protocol (UDP). SOCK_RAW - Low level access to the underlying packet based transport mechanism to allow the implementation of alternative higher level protocols. Note that this call will not give the socket an address, or connect it to any remote address. The socket can be given an address explicitly using the Socket_Bind call, or it will be assigned one automatically when it is first used to send data or to connect to a remote address. 5. Socket_Bind In: R0 = Socket descriptor R1 = Pointer to local address to bind socket to R2 = Size of local address Out: R0 corrupted This call binds a socket to a specified local address. The format of the address (for Internet addresses) is: R1 + 0 = Address family 2 = Port number 4 = IP address 8 = Reserved (should be zero) The address family is always AF_INET for internet addresses. The reserved portion of the address can be omitted, provided that the address size is passed correctly to indicate this. Note that the port number and IP address need to be in network byte order, which is the reverse of the normal byte order on all current Acorn machines. 6. Socket_Listen In: R0 = Socket descriptor R1 = Maximum backlog Out: R0 corrupted This call causes a socket of type SOCK_STREAM to begin listening for incoming connection attempts. The backlog parameter specifies the maximum length that the queue of pending connections may grow to before connection attempts will be refused. 7. Socket_Accept In: R0 = Socket descriptor of listening socket R1 = Pointer to address to be filled in R2 = Pointer to word giving the size of the address block Out: R0 = Socket descriptor for new connection This call is used to accept connections from server sockets that have been told to listen for new connections. A new socket will be created for each incoming connection, and this call in then used to obtain the descriptor for the next pending connection. The address of the host which initiated the returned connection will also be returned, in the supplied address block. This block is in the same format as that given to Socket_Bind. If there are no connections waiting to be accepted, this call will block until a connection is available to be returned, unless the socket has been marked as non-blocking using Socket_Ioctl, in which case the error EWOULDBLOCK will be returned. 8. Socket_Connect In: R0 = Socket descriptor R1 = Pointer to address of remote host R2 = Size of supplied address block Out: R0 corrupted This call initiates a connection from the specified socket to a given address on another host. When used on a raw or datagram socket, this will simply fix the remote address for future calls to Socket_Send, and this remote address can be changed by calling this routine again. For stream sockets, FreeNet will attempt to make a connection to the specified address, and will block until the connection is achieved or the attempt fails. If the socket has been marked non-blocking it will instead return immediately with the error EINPROGRESS and will continue with the connection attempt on its own. 9. Socket_Recv In: R0 = Socket descriptor R1 = Pointer to buffer for received data R2 = Size of buffer R3 = Flags Out: R0 = Amount of data received This call reads as much data as possible from the specified socket, and returns it in the supplied buffer. If no data is available, the call will block until data is available, unless the socket has been marked non-blocking, in which case EWOULDBLOCK will be returned. Various bits in the flags word can be set to affect how how the read is performed: MSG_PEEK - Just peek at the data, leaving it in place to be read by a subsequent call. MSG_OOB - Read any out-of-band data that is waiting on the socket, in place of the normal data. MSG_DONTWAIT - Treat this particular call as non-blocking, ignoring the sockets normal blocking/non-blocking status. MSG_WAITALL - Try and completely fill the supplied buffer, blocking for more data if necessary. For stream sockets, this call may return zero as an indication that the other end has closed the connection. 10. Socket_Recvfrom In: R0 = Socket descriptor R1 = Pointer to buffer for received data R2 = Size of buffer R3 = Flags R4 = Pointer to address to be filled in R5 = Size of supplied address block Out: R0 = Amount of data received This call has identical functionality to Socket_Recv except that the address of the host that sent the data will be returned in the block supplied, in the same format as used by Socket_Bind. 11. Socket_Recvmsg In: R0 = Socket descriptor R1 = Pointer to message descriptor R2 = Flags Out: R0 = Amount of data received This call behaves in the same way as Socket_Recvfrom, except that the message descriptor is used to indicate where the address should be placed and to give a list of buffers to return the data in. The format of the message descriptor is: R1 + 0 = Pointer to address to be filled in + 4 = Size of supplied address block + 8 = Pointer to array of buffer descriptors + 12 = Number of buffer descriptors in use + 16 = Pointer to list of access rights (unused by FreeNet) + 20 = Size of access rights list + 24 = Flags for received data Each buffer descriptor consists of two words. The first is a pointer to the buffer, and the second the size of the buffer. The flags which can be returned in the message descriptor are: MSG_TRUNC - Message was truncated. MSG_EOR - This data completes a record. 12. Socket_Send In: R0 = Socket descriptor R1 = Pointer to data to be sent R2 = Size of buffer R3 = Flags Out: R0 = Amount of data sent This call sends data on a socket. In the case of datagram and raw sockets, a single datagram containing the data will be sent, and EMSGSIZE will be returned if the data is too large to be sent in this way. For stream sockets, the call will block until all the data has been sent, unless the socket has been marked non-blocking, in which case as much data as possible will be sent. Various bits in the flags word can be set to affect how how the send is performed: MSG_OOB - Send data as out-of-band data instead of normal in-band data. Because this call does not specify the address to send to, the socket used for this call must be a connected socket. 13. Socket_Sendto In: R0 = Socket descriptor R1 = Pointer to data to be sent R2 = Size of buffer R3 = Flags R4 = Pointer to address to send to R5 = Size of supplied address block Out: R0 = Amount of data sent This call performs the same job as Socket_Send, except that the remote address is specified so that it can be used on unconnected sockets. This call is only useful for sockets that do not require a connection such as those using the UDP protocol. For sockets that require a connection such as those using the TCP protocol, you need to call Socket_Connect before you can use this routine, and the address given to this call is then ignored anyway. 14. Socket_Sendmsg In: R0 = Socket descriptor R1 = Pointer to message descriptor R2 = Flags Out: R0 = Amount of data sent This call behaves in the same way as Socket_Sendto, except that the message descriptor is used to indicate where the address should be taken from and to give a list of buffers containing the data in. The format of the message descriptor is as given for Socket_Recvmsg. 15. Socket_Shutdown In: R0 = Socket descriptor R1 = Direction of shutdown Out: R0 corrupted Perform a half close on a stream socket. This call is able to shut down either the send or received side of the socket, or both. The direction parameter is either 0 to shut down the receive side, 1 to shut down the send side, or 2 to shut down both sides of the socket. 16. Socket_Setsockopt In: R0 = Socket descriptor R1 = Option level R2 = Option R3 = Pointer to option value R4 = Size of option value Out: R0 corrupted This is used to set a particular option on a socket. The level is either SOL_SOCKET for options applicable to all sockets, or a protocol number for options applicable to a certain protocol. Currently supported socket level options are: SO_REUSEADDR - Enables or disables the reuse of local addresses during the wait period that normally occurs when a TCP stream socket is closed. The argument is a single word which contains zero to disable this option, or a non-zero value to enable it. SO_KEEPALIVE - Enable or disable attempts by FreeNet to probe the remote end of a TCP connection when the link has been idle for some time. SO_SNDBUF - Set the size of the send buffer to the value given by the argument, which is a single word. SO_RCVBUF - Set the size of the receive buffer to the value given by the argument, which is a single word. SO_SNDLOWAT - Set the low water mark of the send buffer. The stack will block a send until there is this much space in the send buffer before it starts to send the data. SO_RCVLOWAT - Set the low water mark of the receive buffer. The stack will always try and return at least this many bytes on a read, blocking if necessary. SO_SNDTIMEO - Set the send timeout. This is the maximum length of time that a send call will block for before returning. The argument is a pointer to a timeout block as described under Socket_Select. SO_RCVTIMEO - Set the receive timeout. This is the maximum length of time that a receive call will block for before returning. The argument is a pointer to a timeout block as described under Socket_Select. The IP protocol also supports several options: IP_OPTIONS - Set some IP options which will be added to each packet sent on a socket. IP_HDRINCL - This toggles whether data sent on a socket already has an IP header included or not. This should only ever be set on raw sockets. IP_TOS - Set the type of service field in packets sent using this socket to the specified value. IP_TTL - Set the time to live field in packets sent using this socket to the specified value. Finally, there are a number of options supported by the TCP protocol: TCP_NODELAY - Disable the Nagle algorithm for this connection, to ensure that data is always sent immediately. TCP_MAXSEG - Set the maximum segment size to use for data sent on this connection. 16. Socket_Getsockopt In: R0 = Socket descriptor R1 = Option level R2 = Option R3 = Pointer to buffer for option value R4 = Size of option value buffer Out: R0 corrupted This call can be used to read the current value of any of the options set using Socket_Setsockopt. In addition, there are two more socket level options that can be read but not written: SO_ERROR - Return the Unix error code for any error which has occurred on the socket, and clear the sockets error flag. SO_TYPE - Return the socket type set when the socket was created. 17. Socket_Getpeername In: R0 = Socket descriptor R1 = Pointer to address to be filled in R2 = Pointer to word giving the size of the address block Out: R0 corrupted This call returns the address that the socket is connected to (if any) in the supplied address block. 18. Socket_Getsockname In: R0 = Socket descriptor R1 = Pointer to address to be filled in R2 = Pointer to word giving the size of the address block Out: R0 corrupted This call returns the local address that the socket is bound to (if any) in the supplied address block. 19. Socket_Close In: R0 = Socket descriptor Out: R0 corrupted Close a socket, freeing the descriptor for reuse. For stream sockets, this is roughly equivalent to calling Socket_Shutdown with a type code of 2, whilst for datagram sockets this call immediately deletes the socket. 20. Socket_Select In: R0 = Number of descriptors to consider in each set R1 = Pointer to read descriptor set R2 = Pointer to write descriptor set R3 = Pointer to exception descriptor set R4 = Pointer to timeout block Out: Number of ready descriptors This call polls a specified groups of sockets to see which are ready for reading, which are ready for writing and which had exceptional conditions pending. Each of the three descriptor sets is a bitmask, where bit zero refers to socket zero, bit one to socket one and so on. Only those sockets whose bit is set in a mask will be considered when performing the checks. As FreeNet currently supports 128 sockets, the bitmasks are arrays of four words - descriptors 0 to 31 are in the first word and so on. The value in R0 is the number of bits in the descriptor sets which should be considered as having meaning, so if R0 is 9 only the first 9 bits (descriptors 0 to 8) will be considered. This call will return as soon as one or more of the sockets being tested is ready or when a timeout occurs. Passing a null pointer for the timeout means the call will never timeout, and will block until a socket is ready. The timeout takes the following form: R4 + 0 = Number of seconds to wait 4 = Number of microseconds to wait A timeout with both fields set to zero will cause the call to return immediately, regardless of how many sockets are ready. 21. Socket_Ioctl In: R0 = Socket descriptor R1 = Operation R2 = Pointer to argument Out: R0 corrupted This call is used to perform miscellaneous control operations on individual sockets and on the TCP/IP stack as a whole. At the moment, three operations are supported: FIOASYNC - Mark a socket for asynchronous operation. This means that a RISC OS event will be raised when important changes occur in the sockets status. See the section on events for more detail of the events that are raised. The argument is a single word acting as a boolean flag. FIONBIO - Mark a socket non-blocking so that no attempted operations on the socket will block. They will instead fail with the error EWOULDBLOCK if they are unable to complete straight away. The argument is a single word acting as a boolean flag. FIONREAD - Read the number of bytes available for reading from the socket. The argument is an integer which will be filled in with the number of bytes available. In the future, this call will support the operations used to read and modify the interface and routing tables. 22. Socket_Read In: R0 = Socket descriptor R1 = Pointer to buffer for received data R2 = Size of buffer Out: R0 = Amount of data received This call reads data from a socket in the same style as Socket_Recv except that there is no flags argument, so all flags are treated as being zero. 23. Socket_Write In: R0 = Socket descriptor R1 = Pointer to data to be sent R2 = Size of buffer Out: R0 = Amount of data sent This call sends data on a socket in the same style as Socket_Send except that there is no flags argument, so all flags are treated as being zero. 24. Socket_Stat This call is not supported by FreeNet yet. 25. Socket_Readv In: R0 = Socket descriptor R1 = Pointer to array of buffer descriptors R2 = Number of buffer descriptors Out: R0 = Amount of data received This call reads data into a gather array. The buffer descriptors are the same as those described for Socket_Recvmsg, and as with Socket_Read the flags are all treated as being zero. 25. Socket_Writev In: R0 = Socket descriptor R1 = Pointer to array of buffer descriptors R2 = Number of buffer descriptors Out: R0 = Amount of data received This call sends data from a scatter array. The buffer descriptors are the same as those described for Socket_Recvmsg, and as with Socket_Write the flags are all treated as being zero. 26. Socket_Gettsize In: Nothing Out: R0 = Number of descriptors available This call returns the number of descriptors available to the caller, including those currently in use. 27. Socket_Sendtosm This call is not supported by FreeNet yet. 28. The Internet Event If a socket has been marked for asynchronous operation using Socket_Ioctl the TCP/IP stack will raise a RISC OS event (event 19) when important changes occur which affect the socket. When the event occurs, registers will be set as follows: R0 = 19 R1 = Event code R2 = Socket descriptor Where the socket descriptor is the socket affected by the event, and the event code is on of the following values: 0 Socket has input waiting to be read 1 An urgent event has occured (eg arrival of OOB data ) 2 Socket's connection has been broken This event can be trapped and used to know when to read data from the socket, and when a connection has been closed.