getsockname (Windows Sockets)

Article
06/30/2006

This function retrieves the local name for a socket.

int getsockname(
  SOCKET s,
  struct SOCK_ADDR* name,
  int FAR* namelen
);

Parameters

s
[in] Descriptor identifying a socket.
name
[out] Receives the address (name) of the socket.
namelen
[in, out] Size of the name buffer.

Return Values

If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The name or namelen parameter is not a valid part of the user address space, or the namelen parameter is too small.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINVAL	The socket has not been bound to an address with bind (Windows Sockets), or ADDR_ANY is specified in bind but connection has not yet occurred.

Remarks

This function retrieves the current name for the specified socket descriptor in the name parameter. It is used on the bound or connected socket specified by the s parameter. The local association is returned. This call is especially useful when a connect (Windows Sockets) call has been made without doing a bind call first. The getsockname function provides the only way to determine the local association that has been set by the system.

On call, the namelen argument contains the size of the name buffer, in bytes. On return, the namelen parameter contains the actual size in bytes of the name parameter.

This function does not always return information about the host address when the socket has been bound to an unspecified address, unless the socket has been connected with connect (Windows Sockets) or accept (Windows Sockets) (for example, using ADDR_ANY). A Windows Sockets application must not assume that the address will be specified unless the socket is connected. The address that will be used for the socket is unknown unless the socket is connected when used in a multihomed host. If the socket is using a connectionless protocol, the address may not be available until I/O occurs on the socket.

Notes for Bluetooth

An RFCOMM Winsock server calls getsockname to determine the channel number assigned to its socket.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winsock2.h.
Link Library: Ws2.lib.