getpeername Subroutine

Communications Technical Reference, Volume 2

getpeername Subroutine

Purpose

Gets the name of the peer socket.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socket.h>
#include <sys/ndd_var.h> /*Needed for AF_NDD address family only*/
#include <sys/atmsock.h> /*Needed for SOCK_CONN_DGRAM socket type only*/
 
int getpeername (Socket, Name, NameLength)
int Socket;
struct sockaddr *Name;
size_t *NameLength;

Description

The getpeername subroutine retrieves the Name parameter from the peer socket connected to the specified socket. The Name parameter contains the address of the peer socket upon successful completion.

A process created by another process can inherit open sockets. The created process may need to identify the addresses of the sockets it has inherited. The getpeername subroutine allows a process to retrieve the address of the peer socket at the remote end of the socket connection.

Note: The getpeername subroutine operates only on connected sockets.

A process can use the getsockname subroutine to retrieve the local address of a socket.

Parameters

Socket	Specifies the descriptor number of a connected socket.
Name	Points to a sockaddr structure that contains the address of the destination socket upon successful completion. The /usr/include/sys/socket.h file defines the sockaddr structure.
NameLength	Points to the size of the address structure. Initializes the NameLength parameter to indicate the amount of space pointed to by the Name parameter. Upon successful completion, it returns the actual size of the Name parameter returned.

Return Values

Upon successful completion, a value of 0 is returned and the Name parameter holds the address of the peer socket.

If the getpeername subroutine is unsuccessful, the system 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 getpeername 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.
ENOTCONN	The socket is not connected.
ENOBUFS	Insufficient resources were available in the system to complete the call.
EFAULT	The Address parameter is not in a writable part of the user address space.

Examples

The following program fragment illustrates the use of the getpeername subroutine to return the address of the peer connected on the other end of the socket:

struct sockaddr_in name;
int namelen = sizeof(name);
.
.
.
if(getpeername(0,(struct sockaddr*)&name, &namelen)<0){
  syslog(LOG_ERR,"getpeername: %m");
  exit(1);
} else
  syslog(LOG_INFO,"Connection from %s",inet_ntoa(name.sin_addr));
.
.
.

Implementation Specifics

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

All applications containing the getpeername 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, getsockname subroutine, socket subroutine.

Sockets Overview in AIX Version 4.3 Communications Programming Concepts.