Contents | Prev | Next

12.7.1 The bind function

Description

The bind function assigns a local name to a socket.

Declaration

The system include file WinSock2.inc contains the following declaration for the bind function: 

function bind(s : SOCKET; name : address; namelen : integer) : integer;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the bind function is the unnamed socket to which you want to assign a name.

The Second Argument

The second argument passed to the bind function is the name to be assigned to the socket. The type of this argument is address which means that you must use the built-in function addr to pass the operating system address of the name. This type is choosen because the format of a socket's name could depend on what address family the socket belongs to, and using the address type leaves it up to you to choose the appropriate type. Usually the socket will belong to the internet address family and you can use a variable of type sockaddr_in to specify the name. sockaddr_in is a record type with the following four fields:

If you do not care what IP address is assigned to the socket then you should specify the constant INADDR_ANY for the sin_addr field. This allows the underlying network service provider to choose an appropriate IP address. If you do not care what port number is used then you should specify zero as the sin_port field. This allows the underlying network service provider to choose an appropriate port number. NOTE: The constant INADDR_ANY and the type sockaddr_in are declared in the system include file WinSock2.inc.

The Third Argument

The third argument passed to the bind function is the length (in bytes) of the name to be assigned to the socket.

Return Values

The bind function returns a value of integer type that indicates whether the call was successful. A value of zero means that the call succeeded. A value of SOCKET_ERROR indicates that the called failed, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail. NOTE: The constant SOCKET_ERROR is declared in the system include file WinSock2.inc.

Example

The following example function is taken from the sample sockets programs distributed with Irie Pascal, and demonstrates how to create a socket, bind it, and convert it into a listening socket. 

 //This function creates a listening socket.
 //First it creates a socket. Then it binds the socket to
 //a particular port (i.e. the port we want to listen on).
 //The socket is not bound to any particular address (INADDR_ANY is used instead)
 //because connections will be accepted from any IP address.
 //Finally "listen" is called to convert the socket to a listing socket.
 function CreateListeningSocket(port : integer) : socket;
 var
  s : socket;
  sa : sockaddr_in;
  iRet : integer;
 begin (* CreateListeningSocket *)
  s := createsocket(AF_INET, SOCK_STREAM, 0);
  if s = INVALID_SOCKET then
   FatalSocketError('CreateSocket call failed');
  fill(sa, 0);
  sa.sin_family := AF_INET;
  sa.sin_port := htonl(port) shr 16;
  sa.sin_addr := htonl(INADDR_ANY) shr 16;
  iRet := bind(s, addr(sa), sizeof(sa));
  if iRet <> 0 then
   FatalSocketError('Call to bind failed');
  iRet := listen(s, SOMAXCONN);
  if iRet <> 0 then
   FatalSocketError('Call to listen failed');
  CreateListeningSocket := s;
 end; (* CreateListeningSocket *)

Reference Information

The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.

Contents | Prev | Next