getsockname Subroutine

Purpose

Gets the socket name.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
int getsockname (Socket, Name, NameLength)
int  Socket;
struct sockaddr * Name;
socklen_t * NameLength;

Description

The getsockname subroutine retrieves the locally bound address of the specified socket. The socket address represents a port number in the Internet domain and is stored in the sockaddr structure pointed to by the Name parameter. The sys/socket.h file defines the sockaddr data structure.

A process created by another process can inherit open sockets. To use the inherited socket, the created process needs to identify their addresses. The getsockname subroutine allows a process to retrieve the local address bound to the specified socket.

A process can use the getpeername subroutine to determine the address of a destination socket in a socket connection.

Parameters

Item Description
Socket Specifies the socket for which the local address is desired.
Name Points to the structure containing the local address of the specified socket.
NameLength Specifies the size of the local address in bytes. Initializes the value pointed to by the NameLength parameter to indicate the amount of space pointed to by the Name parameter.

Return Values

Upon successful completion, a value of 0 is returned, and the NameLength parameter points to the size of the socket address.

If the getsockname subroutine is unsuccessful, the subroutine handler performs the following functions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.
  • For sockets in the AF_UNIX domain, if the returned value of the NameLength parameter is greater than 255, the corresponding value of the sun_len field in the overloaded sockaddr structure is assigned an address of 0xFF because of the bit size limitations of the sun_len field.

Error Codes

The getsockname subroutine is unsuccessful if any of the following errors occurs:

Error Description
EBADF The Socket parameter is not valid.
ENOTSOCK The Socket parameter refers to a file, not a socket.
ENOBUFS Insufficient resources are available in the system to complete the call.
EFAULT The Address parameter is not in a writable part of the user address space.