GETPEERUCRED(3C) Standard C Library Functions GETPEERUCRED(3C)

NAME

getpeerucred - get connected socket or stream peer's credentials

SYNOPSIS

#include <ucred.h>

int getpeerucred(int fd, ucred_t **ucred);

DESCRIPTION

The getpeerucred() function returns the credentials of the peer
endpoint of a connection-oriented socket (SOCK_STREAM) or stream fd
at the time the endpoint was created or the connection was
established. A process that initiates a connection retrieves the
credentials of its peer at the time the peer's endpoint was created.
A process that listens for connections retrieves the credentials of
the peer at the time the peer initiated the connection.


When successful, getpeerucred() stores the pointer to a freshly
allocated ucred_t in the memory location pointed to by the ucred
argument if that memory location contains the null pointer. If the
memory location is non-null, it will reuse the existing ucred_t.


When ucred is no longer needed, a credential allocated by
getpeerucred() should be freed with ucred_free(3C).


It is possible that all fields of the ucred_t are not available to
all peer endpoints and all callers.

RETURN VALUES

Upon successful completion, getpeerucred() returns 0. Otherwise, it
returns -1 and errno is set to indicate the error.

ERRORS

The getpeerucred() function will fail if:

EAGAIN
There is not enough memory available to allocate
sufficient memory to hold the user credential. The
application can try again later.


EBADF
The fd argument is not a valid file descriptor.


EFAULT
The pointer location pointed to by the ucred_t **
argument points to an invalid, non-null address.


EINVAL
The socket is connected but the peer credentials are
unknown.


ENOMEM
The physical limits of the system are exceeded by the
memory allocation needed to hold the user credential.


ENOTCONN
The socket or stream is not connected or the stream's
peer is unknown.


ENOTSUP
This operation is not supported on this file descriptor.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO

door_ucred(3C), ucred_get(3C), connld(4M), attributes(7)

NOTES

The system currently supports both sides of connection endpoints for
local AF_UNIX, AF_INET, and AF_INET6 sockets, /dev/tcp, /dev/ticots,
and /dev/ticotsord XTI/TLI connections, and pipe file descriptors
sent using I_SENDFD as a result of the open of a named pipe with the
"connld" module pushed.

May 26, 2004 GETPEERUCRED(3C)