getsockname Subroutine

AIX Version 4.3 Communications Technical Reference, Volume 2

getsockname Subroutine

Purpose

Gets the socket name.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socket.h>

int getsockname (Socket, Name, NameLength)
int Socket;
struct sockaddr *Name;
size_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.

Note: The getsockname subroutine does not perform operations on UNIX domain sockets.

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

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.

Error Codes

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

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.

Implementation Specifics

The getsockname subroutine is part of Base Operating System (BOS) Runtime.

All applications containing the getsockname subroutine must be compiled with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Related Information

The accept subroutine, bind subroutine, getpeername subroutine, socket subroutine.

Checking for Pending Connections Example Program, Reading Internet Datagrams Example Program, and Sockets Overview in AIX Version 4.3 Communications Programming Concepts.