usr/src/man/man3c/getpeerucred.3c

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GETPEERUCRED 3C "May 26, 2004"
   7 .SH NAME
   8 getpeerucred \- get connected socket or stream peer's credentials
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <ucred.h>
  13
  14 \fBint\fR \fBgetpeerucred\fR(\fBint\fR \fIfd\fR, \fBucred_t **\fR\fIucred\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBgetpeerucred()\fR function returns the credentials of the peer endpoint
  21 of a connection-oriented socket (\fBSOCK_STREAM\fR) or stream \fIfd\fR at the
  22 time the endpoint was created or the connection was established.  A process
  23 that initiates a connection retrieves the credentials of its peer at the time
  24 the peer's endpoint was created. A process that listens for connections
  25 retrieves the credentials of the peer at the time the peer initiated the
  26 connection.
  27 .sp
  28 .LP
  29 When successful, \fBgetpeerucred()\fR stores the pointer to a freshly allocated
  30 \fBucred_t\fR in the memory location pointed to by the \fIucred\fR argument if
  31 that memory location contains the null pointer. If the memory location is
  32 non-null, it will reuse the existing \fBucred_t\fR.
  33 .sp
  34 .LP
  35 When \fIucred\fR is no longer needed, a credential allocated by
  36 \fBgetpeerucred()\fR should be freed with \fBucred_free\fR(3C).
  37 .sp
  38 .LP
  39 It is possible that all fields of the \fBucred_t\fR are not available to all
  40 peer endpoints and all callers.
  41 .SH RETURN VALUES
  42 .sp
  43 .LP
  44 Upon successful completion, \fBgetpeerucred()\fR returns 0. Otherwise, it
  45 returns \(mi1 and \fBerrno\fR is set to indicate the error.
  46 .SH ERRORS
  47 .sp
  48 .LP
  49 The \fBgetpeerucred()\fR function will fail if:
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBEAGAIN\fR\fR
  54 .ad
  55 .RS 12n
  56 There is not enough memory available to allocate sufficient memory to hold the
  57 user credential. The application can try again later.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBEBADF\fR\fR
  64 .ad
  65 .RS 12n
  66 The \fIfd\fR argument is not a valid file descriptor.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBEFAULT\fR\fR
  73 .ad
  74 .RS 12n
  75 The pointer location pointed to by the \fBucred_t **\fR argument points to an
  76 invalid, non-null address.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBEINVAL\fR\fR
  83 .ad
  84 .RS 12n
  85 The socket is connected but the peer credentials are unknown.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBENOMEM\fR\fR
  92 .ad
  93 .RS 12n
  94 The physical limits of the system are exceeded by the memory allocation needed
  95 to hold the user credential.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBENOTCONN\fR\fR
 102 .ad
 103 .RS 12n
 104 The socket or stream is not connected or the stream's peer is unknown.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBENOTSUP\fR\fR
 111 .ad
 112 .RS 12n
 113 This operation is not supported on this file descriptor.
 114 .RE
 115
 116 .SH ATTRIBUTES
 117 .sp
 118 .LP
 119 See \fBattributes\fR(5) for descriptions of the following attributes:
 120 .sp
 121
 122 .sp
 123 .TS
 124 box;
 125 c | c
 126 l | l .
 127 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 128 _
 129 Interface Stability     Evolving
 130 _
 131 MT-Level        MT-Safe
 132 .TE
 133
 134 .SH SEE ALSO
 135 .sp
 136 .LP
 137 \fBdoor_ucred\fR(3C), \fBucred_get\fR(3C), \fBattributes\fR(5),
 138 \fBconnld\fR(7M)
 139 .SH NOTES
 140 .sp
 141 .LP
 142 The system currently supports both sides of connection endpoints for local
 143 \fBAF_UNIX\fR, \fBAF_INET\fR, and \fBAF_INET6\fR sockets, \fB/dev/tcp\fR,
 144 \fB/dev/ticots\fR, and \fB/dev/ticotsord\fR XTI/TLI connections, and pipe file
 145 descriptors sent using \fBI_SENDFD\fR as a result of the open of a named pipe
 146 with the "connld" module pushed.