[IPhone-network] BSD Socket API function reference

 

BSD Sockets API

IntSocket(INT family, int type, int Protocol );

creates a socket. currently family can only be af_inet (Ot does not support IPv6 so there is no af_inet6 support ). protocol can be pf_inet or pf_unspec (both have the same effect of creating an Internet socket. type can be sock_stream for TCP sockets or sock_dgram for UDP sockets.

socket () Returns a socket file descriptor ( sockfd ) which is a small non-negative integer. this file descriptor number shocould be used for all other socket operations on that socket. if socket () encounters an error, it will return-1, in which case the application shocould call getmitliberror () to get the error code.

Note: errno is not supported by the sockets library. Use errorlib.

IntSocket_bind(INT sockfd, const struct sockaddr * myaddr, int addrlength );

Binds a socket to a local port and/or IP address. Either the port or the IP address inStruct sockaddrStructure may be wildcarded in which case the library will select appropriate values. To wildcard the port setSin_portField of the address to 0. To wildcard the IP, setSin_addr.s_addrField of the addressInaddr_any

TCP has a port reuse time limit. If an application attempts to bind to the same local port twice in rapid succession, the second attempt will failEaddrinuse. Just wait and try again.

Socket_bind ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

Note that the second argumentSocket_bind ()Is actuallyStruct sockaddr_in *Which is cast to the more generalStruct sockaddr *Because Internet addresses are used by the socket library.

Also, it is not necessary to bind a socket prior to connecting it. If a socket is not bound the library will choose the local port and IP.

IntSocket_connect(INT sockfd, struct sockaddr * servaddr, int addrlength );

Connects a socket to a remote host on a given port. If this isSock_stream(TCP) socket,Socket_connect ()Will actually perform TCP negotation To open a connection. If this isSock_dgram(UDP) socket,Socket_connect ()Will just store the address for use later with other socket operations (this is important to note because ifSockfdRefers to a UDP socket, errors will not be reported prior to an attempt to read or write data on the socket ).

Socket_connect ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

Note that the second argumentConnectIs actuallyStruct sockaddr_in *Which is cast to the more generalStruct sockaddr *Because Internet addresses are used by the socket library.

IntSocket_select(INT maxfdsexamined, fd_set * readfds, fd_set * writefds, fd_set * limit TFDs, struct timeval * timeout );

Socket_select ()Allows for conditions to be checked on one or more sockets.

MaxfdsexaminedShocould be one greater than value of the largest valued socket descriptor in any of the lists. If you don't wish to calculate this, useFd_setsizeInstead. For small numbers of sockets,Socket_select ()Will be less efficient if fd_setsize is passed.

If the bit corresponding to a socket inFd_setIs set, that socket will be checked for the conditionFd_setCorresponds to. If the condition they are checked for is true, they will still be setTrueWhenSocket_select ()Returns (otherwise they will be set to false). Note that the sets are modifiedSocket_select (): Thus they must be reset between each call to the function.

Fd_setS can be manipulated using the following macros:

fd_set (FD, fdset)	sets socket FD in fdset to true.
fd_clr (FD, fdset)	sets socket FD in fdset to false.
fd_isset (FD, fdset)	Returns true IFF socket FD is set to true in fdset .
fd_zero (fdset)	sets all the sockets in fdset to false.

currently only the readfds condition (whether there is data to read on a socket) is supported. however, in order to stay compatible with most clients, writefds (whether there is room in the kernel buffers to write to a socket) behaves as though writing data will succeed (this is usually fine) and condition TFDs behaves as though there are no exception conditions on the socket ( condition TFDs will always be returned with all sockets set to false).

If timeout is null, socket_select () blocks until one of the conditions becomes true for one of the sockets. if timeout is non-null, socket_select () checks for the amount of time corresponding to timeout and then returns (regardless of whether it has found any conditions to be true ). if one of the conditions becomes true for one of the sockets it finds before the timeout has expired, it always returns immediately. to use socket_select () in non-blocking mode call it with a non-null timeout whose TV _sec and TV _usec fields are both set to zero.

Socket_select ()Returns the number of sockets for which the specified conditions are true. If it encounters an error, it will return-1 (in which caseGetmitliberror ()Can be called to retrieve the error code .)

IntSocket_fcntl(INT sockfd, int command, int flags );

Socket_fcntl ()Sets various options on a socket. Currently the only flag supported is o_nonblock which sets a socket to non-blocking mode.

IfSocket_fcntl ()Is calledCommandEqualF_getflIt will return the current flags for the socketSockfd.The ParameterFlagsIs ignored in this case.

If the function is calledCommandEqualF_setflIt will replace the socket's flags with those specifiedFlags.

The correct way to change a flag on a socket is as wrongly strated in the following example:

Flags = socket_fcntl (sockfd, f_getfl, 0 );
Flags | = o_nonblock;
Err = socket_fcntl (sockfd, f_setfl, flags );

Getting the current flags and modifying them avoids the potential error of clearing other flags.

Socket_fcntl ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

Note: The corresponding BSD call,FcntlTakes a variable number of arguments whileSocket_fcntlDoes not.

IntSocket_getpeername(INT sockfd, struct sockaddr * peeraddr, int * addrlength );

Socket_getpeername ()Gets the address of the remote host the socket is connected to, if any. If the socket is not connected,Getmitliberror ()Will returnEnotconn.

Socket_getpeername ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

IntSocket_getsockname(INT sockfd, struct sockaddr * localaddr, int * addrlength );

Socket_getsockname ()Gets the socket's local address and port.

Socket_getsockname ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

IntSocket_read(INT sockfd, void * buffer, uint32 numbytes );

reads data from the socket into buffer . numbytes shocould be the size of the buffer. socket_read () may not fill the entire buffer.

socket_read () returns the amount of data which was read. if there is an error,-1 is returned and getmitliberror () can be called to retrieve the error code. if 0 is returned, this means that the socket has ed an EOF (the remote host closed the connection gracefully .) to perform a full read on a socket, continue to call socket_read () until the desired number of bytes have been accumulated. note that socket_read () may block if no data is available to be read. this condition can be checked using socket_select () .

the socket must be connected.

Note: The standard library call Read () is not supported for sockets.

IntSocket_write(INT sockfd, void * buffer, uint32 numbytes );

Writes data to the socket fromBuffer.NumbytesShocould be the amount of data in the buffer.Socket_write ()May not write out the entire buffer.

Socket_write ()Returns the amount of data which was written. If there is an error,-1 is returned andGetmitliberror ()Can be called to get the error code.

The socket must be connected.

IntSocket_readv(INT sockfd, struct iovec * IOV, uint32 iovcount );

TheSocket_readv ()Function is equivalentSocket_read (), But places the input data intoIovcntBuffers specified by the members ofIOVArray:Iov0, iov1,..., IOV [iovcnt-1].IovcntArgument is valid if greater than 0 and less than or equalIov_max.

TheIovecStructure contains the following members:

Caddr_t iov_base;
Int iov_len;

EachIovecEntry specifies the base address and length of an area in memory where data shocould be placed.Socket_readv ()Function always fills an area completely before proceeding to the next.

Upon successful completion,Socket_readv ()Marks for updateSt_atimeField of the file.

Socket_readv ()Returns the total amount of data which was read into all buffers. If there is an error,-1 is returned andGetmitliberror ()Can be called to get the error code. If 0 is returned, this means that the socket got an EOF (the remote host closed the connection gracefully.

The socket must be connected.

IntSocket_writev(INT sockfd, struct iovec * IOV, uint32 iovcount );

TheSocket_writev ()Function performs the same actionSocket_write (), But gathers the output data fromIovcntBuffers specified by the members ofIOVArray:IOV [0], IOV [1],..., IOV [iovcnt-1].IovcntBuffer is valid if greater than 0 and less than or equalIov_max.

TheIovecStructure contains the following members:

Caddr_t iov_base;
Int iov_len;

EachIovecEntry specifies the base address and length of an area in memory from which data shocould be written.Socket_writev ()Always writes all data from an area before proceeding to the next.

Socket_writev ()Returns the amount of data which was written. If there is an error,-1 is returned andGetmitliberror ()Can be called to get the error code.

The socket must be connected.

IntSocket_recv(INT sockfd, void * buffer, uint32 numbytes, int flags );

this function is similiar to socket_read () with the addition of a final parameter. socket_recv () reads data from the socket into buffer . numbytes shocould be the size of the buffer. socket_recv () may not fill the entire buffer. if flags is set to msg_dontwait , then socket_recv will not block if not data is available.

socket_recv () returns the amount of data which was read. if there is an error,-1 is returned and getmitliberror () can be called to get the error code. if 0 is returned, this means that the socket has ed an EOF (the remote host closed the connection gracefully.

the socket must be connected.

IntSocket_send(INT sockfd, void * buffer, uint32 numbytes, int flags );

SimiliarSocket_write (),Socket_send ()Writes data to the socket fromBuffer.NumbytesShocould be the amount of data in the buffer.Socket_send ()May not write out the entire buffer. IfFlagsIs setMsg_dontwait, ThenSocket_send ()Will not block waiting for buffers to become free.

Socket_send ()Returns the amount of data which was written. If there is an error,-1 is returned andGetmitliberror ()Can be called to receive the error code.

The socket must be connected.

int socket_recvfrom (INT sockfd, void * buffer, uint32 numbytes, int flags, struct sockaddr * fromaddr, socklen_t * addrlength );

reads data from the remote host specified by fromaddr into buffer . the socket must be a sock_dgram (UDP) socket. numbytes shocould be the size of the buffer. socket_recvfrom () may not fill the entire buffer. if flags is set to msg_dontwait , then socket_recvfrom () will not block waiting for data.

note that fromaddr will actually be a struct sockaddr_in *

socket_recvfrom () returns the amount of data which was read. if there is an error,-1 is returned and getmitliberror () may be called to get the error code. if 0 is returned, this means that the socket got an EOF (the remote host closed the connection gracefully.

int socket_sendto (INT sockfd, void * buffer, uint32 numbytes, int flags, struct sockaddr * toaddr, socklen_t addrlength );

Writes data the remote host specifiedFromaddrIntoBuffer. The socket must beSock_dgram(UDP) socket.NumbytesShocould be the amount of data in the buffer.Socket_sendto ()May not write out the entire buffer. IfFlagsIs setMsg_dontwait, ThenSocket_sendto ()Will not block waiting for buffers to become free.

Note thatToaddrWill actually beStruct sockaddr_in *

Socket_sendto ()Returns the amount of data which was written. If there is an error,-1 is returned andGetmitliberror ()Can be called to get the error code.

IntSocket_shutdown(INT sockfd, int howto );

socket_shutdown () closes one or both directions of a connected socket. howto can be shut_rd , shut_wr or shut_rdwr . shut_rd tells it to close the reading side of the connection (reads from the socket will no longer be possible ). shut_wr tells it to close the writing half of the socket (this will cause it to send an orderly disconnect to the remote host, telling that host it no longer has anything to write ). shut_rdwr tells it to close both halves of the connection (it is still necessary to free the socket with socket_close () ).

socket_shutdown () returns 0 on success and-1 on failure. if-1 is returned, call getmitliberror () to get the error code.

IntSocket_close(INT sockfd );

Socket_close ()Frees a socket's resources, disconnecting it from the remote host, if necessary. Both TCP and UDP sockets shoshould be closed with this function.

Socket_close ()Returns 0 on success and-1 on failure. If-1 is returned, callGetmitliberror ()To get the error code.

 

From: http://web.mit.edu/macdev/Development/MITSupportLib/SocketsLib/Documentation/sockets.html