.\" Copyright (c) 1983, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)getpeername.2 6.5 (Berkeley) 3/10/91
.\"
.\" Modified Sat Jul 24 16:37:50 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Thu Jul 30 14:37:50 1993 by Martin Schulze <joey@debian.org>
.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer <aeb@cwi.nl>
-.\" Modified 17 Jul 2002, Michael Kerrisk <mtk-manpages@gmx.net>
+.\" Modified 17 Jul 2002, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added 'socket' to NAME, so that "man -k socket" will show this page.
.\"
-.TH GETPEERNAME 2 1993-07-30 "BSD Man Page" "Linux Programmer's Manual"
+.TH GETPEERNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
getpeername \- get name of connected peer socket
.SH SYNOPSIS
.B #include <sys/socket.h>
-.sp
-.BI "int getpeername(int " s ", struct sockaddr *" name ", socklen_t *" namelen );
+.PP
+.BI "int getpeername(int " sockfd ", struct sockaddr *" addr \
+", socklen_t *" addrlen );
.SH DESCRIPTION
-.B Getpeername
-returns the name of the peer connected to socket
-.IR s .
+.BR getpeername ()
+returns the address of the peer connected to the socket
+.IR sockfd ,
+in the buffer pointed to by
+.IR addr .
The
-.I namelen
-parameter should be initialized to indicate the amount of space pointed to
+.I addrlen
+argument should be initialized to indicate the amount of space pointed to
by
-.IR name .
-On return it contains the actual size of the name returned (in bytes). The
-name is truncated if the buffer provided is too small.
-.SH "RETURN VALUE"
-On success, zero is returned. On error, \-1 is returned, and
+.IR addr .
+On return it contains the actual size of the name returned (in bytes).
+The name is truncated if the buffer provided is too small.
+.PP
+The returned address is truncated if the buffer provided is too small;
+in this case,
+.I addrlen
+will return a value greater than was supplied to the call.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EBADF
The argument
-.I s
-is not a valid descriptor.
+.I sockfd
+is not a valid file descriptor.
.TP
.B EFAULT
-The
-.I name
-parameter points to memory not in a valid part of the
+The
+.I addr
+argument points to memory not in a valid part of the
process address space.
.TP
.B EINVAL
-.I namelen
+.I addrlen
is invalid (e.g., is negative).
.TP
.B ENOBUFS
The socket is not connected.
.TP
.B ENOTSOCK
-The argument
-.I s
-is a file, not a socket.
-.SH "CONFORMING TO"
-SVr4, 4.4BSD (the
+The file descriptor
+.I sockfd
+does not refer to a socket.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD
+.RB ( getpeername ()
+first appeared in 4.2BSD).
+.SH NOTES
+For background on the
+.I socklen_t
+type, see
+.BR accept (2).
+.PP
+For stream sockets, once a
+.BR connect (2)
+has been performed, either socket can call
.BR getpeername ()
-function call first appeared in 4.2BSD).
-.SH NOTE
-The third argument of
+to obtain the address of the peer socket.
+On the other hand, datagram sockets are connectionless.
+Calling
+.BR connect (2)
+on a datagram socket merely sets the peer address for outgoing
+datagrams sent with
+.BR write (2)
+or
+.BR recv (2).
+The caller of
+.BR connect (2)
+can use
.BR getpeername ()
-is in reality an `int *' (and this is what 4.x BSD and libc4 and libc5 have).
-Some POSIX confusion resulted in the present socklen_t, also used by glibc.
-See also
-.BR accept (2).
-.SH "SEE ALSO"
+to obtain the peer address that it earlier set for the socket.
+However, the peer socket is unaware of this information, and calling
+.BR getpeername ()
+on the peer socket will return no useful information (unless a
+.BR connect (2)
+call was also executed on the peer).
+Note also that the receiver of a datagram can obtain
+the address of the sender when using
+.BR recvfrom (2).
+.SH SEE ALSO
.BR accept (2),
.BR bind (2),
-.BR getsockname (2)
+.BR getsockname (2),
+.BR ip (7),
+.BR socket (7),
+.BR unix (7)
projects / thirdparty / man-pages.git / blobdiff