BSD Socket API 函数参考大全

BSD Sockets API

int socket (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 should be used for all other socket operations on that socket. If 

socket()

 encounters an error, it will return -1, in which case the application should call 

GetMITLibError()

 to get the error code.

NOTE: errno is not supported by the Sockets Library. Use ErrorLib.

int socket_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 in the 

struct sockaddr

 structure may be wildcarded in which case the library will select appropriate values. To wildcard the port set the 

sin_port

 field of the address to 0. To wildcard the IP, set the 

sin_addr.s_addr

 field of the address to 

INADDR_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 fail with 

EADDRINUSE

. Just wait and try again.

socket_bind()

 returns 0 on success and -1 on failure. If -1 is returned, call 

GetMITLibError()

 to get the error code.

Note that the second argument to 

socket_bind()

 is actually a 

struct sockaddr_in*

 which is cast to the more general

struct 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.

int socket_connect (int sockFD, struct sockaddr *servAddr, int addrLength);

Connects a socket to a remote host on a given port. If this is a 

SOCK_STREAM

 (TCP) socket, 

socket_connect()

 will actually perform TCP negotation to open a connection. If this is a 

SOCK_DGRAM

 (UDP) socket, 

socket_connect()

 will just store the address for use later with other socket operations (this is important to note because if 

sockFD

 refers 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, call 

GetMITLibError()

 to get the error code.

Note that the second argument to 

connect

 is actually a 

struct sockaddr_in*

 which is cast to the more general 

struct sockaddr*

 because internet addresses are used by the Socket Library.

int socket_select (int maxFDsExamined, fd_set *readFDs, fd_set *writeFDs, fd_set*exceptFDs, struct timeval *timeOut);

socket_select()

 allows for conditions to be checked on one or more sockets.

maxFDsExamined

 should be one greater than value of the largest valued socket descriptor in any of the lists. If you don't wish to calculate this, use 

FD_SETSIZE

 instead. For small numbers of sockets, 

socket_select()

 will be less efficient if FD_SETSIZE is passed.

If the bit corresponding to a socket in an 

fd_set

 is set, that socket will be checked for the condition the 

fd_set

 corresponds to. If the condition they are checked for is true, they will still be set to 

true

 when 

socket_select()

 returns (otherwise they will be set to false). Note that the sets are modified by 

socket_select()

: thus they must be reset between each call to the function.

fd_set

s 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 

exceptfds

 behaves as though there are no exception conditions on the socket (

exceptfds

 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 case 

GetMITLibError()

 can be called to retrieve the error code.)

int socket_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.

If 

socket_fcntl()

 is called with 

command

 equal to 

F_GETFL

 it will return the current flags for the socket 

sockFD.

 The parameter 

flags

 is ignored in this case.

If the function is called with 

command

 equal to 

F_SETFL

 it will replace the socket's flags with those specified by 

flags.

The correct way to change a flag on a socket is as illustrated 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, call 

GetMITLibError()

 to get the error code.

Note: the corresponding BSD call, 

fcntl

 takes a variable number of arguments while 

socket_fcntl

 does not.

int socket_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 return 

ENOTCONN

.

socket_getpeername()

 returns 0 on success and -1 on failure. If -1 is returned, call 

GetMITLibError()

 to get the error code.

int socket_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, call 

GetMITLibError()

 to get the error code.

int socket_read (int sockFD, void *buffer, UInt32 numBytes);

Reads data from the socket into 

buffer

. 

numBytes

 should 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 received 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.

int socket_write (int sockFD, void *buffer, UInt32 numBytes);

Writes data to the socket from 

buffer

. 

numBytes

 should 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 and 

GetMITLibError()

can be called to get the error code.

The socket must be connected.

int socket_readv (int sockFD, struct iovec *iov, UInt32 iovCount);

The 

socket_readv()

 function is equivalent to 

socket_read()

, but places the input data into the 

iovcnt

 buffers specified by the members of the 

iov

 array: 

iov0, iov1, ..., iov[iovcnt-1]

. The 

iovcnt

 argument is valid if greater than 0 and less than or equal to 

IOV_MAX

.

The 

iovec

 structure contains the following members:

caddr_t iov_base;

int iov_len;

Each 

iovec

 entry specifies the base address and length of an area in memory where data should be placed. The

socket_readv()

 function always fills an area completely before proceeding to the next.

Upon successful completion, 

socket_readv()

 marks for update the 

st_atime

 field 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 and

GetMITLibError()

 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.

int socket_writev (int sockFD, struct iovec *iov, UInt32 iovCount);

The 

socket_writev()

 function performs the same action as 

socket_write()

, but gathers the output data from the

iovcnt

 buffers specified by the members of the 

iov

 array: 

iov[0], iov[1], ..., iov[iovcnt-1]

. The 

iovcnt

 buffer is valid if greater than 0 and less than or equal to 

IOV_MAX

.

The 

iovec

 structure contains the following members:

caddr_t iov_base;

int iov_len;

Each 

iovec

 entry specifies the base address and length of an area in memory from which data should 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 and 

GetMITLibError()

can be called to get the error code.

The socket must be connected.

int socket_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

 should 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 received an EOF (the remote host closed the connection gracefully.

The socket must be connected.

int socket_send (int sockFD, void *buffer, UInt32 numBytes, int flags);

Similiar to 

socket_write()

, 

socket_send()

 writes data to the socket from 

buffer

. 

numBytes

 should be the amount of data in the buffer. 

socket_send()

 may not write out the entire buffer. If 

flags

 is set to 

MSG_DONTWAIT

, then

socket_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 and 

GetMITLibError()

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

 should 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 specified by 

fromAddr

 into 

buffer

. The socket must be a 

SOCK_DGRAM

 (UDP) socket.

numBytes

 should be the amount of data in the buffer. 

socket_sendto()

 may not write out the entire buffer. If 

flags

 is set to 

MSG_DONTWAIT

, then 

socket_sendto()

 will not block waiting for buffers to become free.

Note that 

toAddr

 will actually be a 

struct sockaddr_in*

socket_sendto()

 returns the amount of data which was written. If there is an error, -1 is returned and 

GetMITLibError()

can be called to get the error code.

int socket_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.

int socket_close (int sockFD);

socket_close()

 frees a socket's resources, disconnecting it from the remote host, if necessary. Both TCP and UDP sockets should be closed with this function.

socket_close()

 returns 0 on success and -1 on failure. If -1 is returned, call 

GetMITLibError()

 to get the error code.

来自：http://web.mit.edu/macdev/Development/MITSupportLib/SocketsLib/Documentation/sockets.html

            作者：Alexliu（alex dotNet Learning）

   出处：http://alexliu.cnblogs.com/