locale.1, localedef.1, _exit.2, accept.2, access.2, acct.2, adjtimex.2, bdflush.2...

[thirdparty/man-pages.git] / man2 / getpeername.2

diff --git a/man2/getpeername.2 b/man2/getpeername.2
index 22a7451e5e7087a5d8f44ffc1d0c8339b0b80216..89f76a0dd9959e297a09ba7bb3a03d8c2ea46100 100644 (file)
--- a/man2/getpeername.2
+++ b/man2/getpeername.2
@@ -1,6 +1,7 @@
 .\" 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:
@@ -28,6 +29,7 @@
 .\" 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
 .\"
@@ -37,25 +39,33 @@
 .\" 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 "Linux" "Linux Programmer's Manual"
+.TH GETPEERNAME 2 2016-03-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 );
+.BI "int getpeername(int " sockfd ", struct sockaddr *" addr \
+", socklen_t *" addrlen );
 .SH DESCRIPTION
 .BR getpeername ()
-returns the name of the peer connected to socket
-.IR s .
+returns the address of the peer connected to the socket
+.IR sockfd ,
+in the buffer pointed to by
+.IR addr .
 The
-.I namelen
+.I addrlen
 argument should be initialized to indicate the amount of space pointed to
 by
-.IR name .
+.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.
-.SH "RETURN VALUE"
+
+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
@@ -64,17 +74,17 @@ is set appropriately.
 .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
+.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
@@ -85,25 +95,52 @@ to perform the operation.
 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
-.BR getpeername ()
-function call first appeared in 4.2BSD), POSIX.1-2001.
+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
 The third argument of
 .BR getpeername ()
 is in reality an
-.I int *
+.I "int\ *"
 (and this is what 4.x BSD and libc4 and libc5 have).
 Some POSIX confusion resulted in the present
 .IR socklen_t ,
 also used by glibc.
 See also
 .BR accept (2).
-.SH "SEE ALSO"
+
+For stream sockets, once a
+.BR connect (2)
+has been performed, either socket can call
+.BR getpeername ()
+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 ()
+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),