getsockname(2) [netbsd man page]

GETSOCKNAME(2)						      BSD System Calls Manual						    GETSOCKNAME(2)

NAME

     getsockname -- get socket name

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <sys/socket.h>

     int
     getsockname(int s, struct sockaddr * restrict name, socklen_t * restrict namelen);

DESCRIPTION

     getsockname() returns the locally bound address information for a specified socket.

     Common uses of this function are as follows:

     o	 When bind(2) is called with a port number of 0 (indicating the kernel should pick an ephemeral port) getsockname() is used to retrieve
	 the kernel-assigned port number.

     o	 When a process calls bind(2) on a wildcard IP address, getsockname() is used to retrieve the local IP address for the connection.

     o	 When a function wishes to know the address family of a socket, getsockname() can be used.

     getsockname() takes three parameters:

     s, Contains the file descriptor for the socket to be looked up.

     name points to a sockaddr structure which will hold the resulting address information.  Normal use requires one to use a structure specific
     to the protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6 (IPv6), cast to a (struct sockaddr *).

     For greater portability (such as newer protocol families) the new structure sockaddr_storage exists.  sockaddr_storage is large enough to
     hold any of the other sockaddr_* variants.  On return, it should be cast to the correct sockaddr type, according to the current protocol fam-
     ily.

     namelen indicates the amount of space pointed to by name, in bytes.  Upon return, namelen is set to the actual size of the returned address
     information.

     If the address of the destination socket for a given socket connection is needed, the getpeername(2) function should be used instead.

     If name does not point to enough space to hold the entire socket address, the result will be truncated to namelen bytes.

RETURN VALUES

     On success, getsockname() returns a 0, and namelen is set to the actual size of the socket address returned in name.  Otherwise, errno is
     set, and a value of -1 is returned.

ERRORS

     The call succeeds unless:

     [EBADF]		The argument s is not a valid descriptor.

     [ENOTSOCK] 	The argument s is a file, not a socket.

     [EINVAL]		The socket has been shut down.

     [ENOBUFS]		Insufficient resources were available in the system to perform the operation.

     [EFAULT]		The name parameter points to memory not in a valid part of the process address space.

SEE ALSO

     bind(2), socket(2)

HISTORY

     The getsockname() function call appeared in 4.2BSD.

BUGS

     Names bound to sockets in the UNIX domain are inaccessible; getsockname() returns a zero length name.

BSD
								  August 11, 2002							       BSD

GETSOCKNAME(3P) 					     POSIX Programmer's Manual						   GETSOCKNAME(3P)

PROLOG

       This  manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (consult the correspond-
       ing Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

NAME

       getsockname - get the socket name

SYNOPSIS

       #include <sys/socket.h>

       int getsockname(int socket, struct sockaddr *restrict address,
	      socklen_t *restrict address_len);

DESCRIPTION

       The getsockname() function shall retrieve the locally-bound name of the specified socket, store this  address  in  the  sockaddr  structure
       pointed to by the address argument, and store the length of this address in the object pointed to by the address_len argument.

       If the actual length of the address is greater than the length of the supplied sockaddr structure, the stored address shall be truncated.

       If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

RETURN VALUE

       Upon  successful  completion, 0 shall be returned, the address argument shall point to the address of the socket, and the address_len argu-
       ment shall point to the length of the address.  Otherwise, -1 shall be returned and errno set to indicate the error.

ERRORS

       The getsockname() function shall fail if:

       EBADF  The socket argument is not a valid file descriptor.

       ENOTSOCK
	      The socket argument does not refer to a socket.

       EOPNOTSUPP
	      The operation is not supported for this socket's protocol.

       The getsockname() function may fail if:

       EINVAL The socket has been shut down.

       ENOBUFS
	      Insufficient resources were available in the system to complete the function.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       accept(), bind(), getpeername(), socket(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/socket.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
       ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and  the  original  IEEE
       and  The  Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained
       online at http://www.opengroup.org/unix/online.html .

IEEE
/The Open Group						       2003							   GETSOCKNAME(3P)