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

   1 '\" te
   2 .\" Copyright (c) 2008 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH GETSPNAM 3C "Jan 23, 2008"
   8 .SH NAME
   9 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent,
  10 fgetspent_r \- get password entry
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <shadow.h>
  15
  16 \fBstruct spwd *\fR\fBgetspnam\fR(\fBconst char *\fR\fIname\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBstruct spwd *\fR\fBgetspnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct spwd *\fR\fIresult\fR,
  22      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBstruct spwd *\fR\fBgetspent\fR(\fBvoid\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBstruct spwd *\fR\fBgetspent_r\fR(\fBstruct spwd *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
  33      \fBint\fR \fIbuflen\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBvoid\fR \fBsetspent\fR(\fBvoid\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBvoid\fR \fBendspent\fR(\fBvoid\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBstruct spwd *\fR\fBfgetspent\fR(\fBFILE *\fR\fIfp\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBstruct spwd *\fR\fBfgetspent_r\fR(\fBFILE *\fR\fIfp\fR, \fBstruct spwd *\fR\fIresult\fR,
  54      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  55 .fi
  56
  57 .SH DESCRIPTION
  58 .sp
  59 .LP
  60 These functions are used to obtain shadow password entries.  An entry may come
  61 from any of the sources for \fBshadow\fR specified in the
  62 \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
  63 .sp
  64 .LP
  65 The \fBgetspnam()\fR function searches for a shadow password entry with the
  66 login name specified by the character string argument \fIname\fR.
  67 .sp
  68 .LP
  69 The  \fBsetspent()\fR, \fBgetspent()\fR, and \fBendspent()\fR functions are
  70 used to enumerate shadow password entries from the database.
  71 .sp
  72 .LP
  73 The \fBsetspent()\fR function sets (or resets) the enumeration to the beginning
  74 of the set of shadow password entries.  This function should be called before
  75 the first call to \fBgetspent()\fR. Calls to \fBgetspnam()\fR leave the
  76 enumeration position in an indeterminate state.
  77 .sp
  78 .LP
  79 Successive calls to \fBgetspent()\fR return either successive entries or
  80 \fINULL\fR, indicating the end of the enumeration.
  81 .sp
  82 .LP
  83 The \fBendspent()\fR function may be called to indicate that the caller expects
  84 to do no further shadow password retrieval operations; the system may then
  85 close the shadow password file, deallocate resources it was using, and so
  86 forth.  It is still allowed, but possibly less efficient, for the process to
  87 call more shadow password functions after calling \fBendspent()\fR.
  88 .sp
  89 .LP
  90 The \fBfgetspent()\fR function, unlike the other functions above, does not use
  91 \fBnsswitch.conf\fR; it reads and parses the next line from the stream
  92 \fIfp\fR, which is assumed to have the format of the \fBshadow\fR file (see
  93 \fBshadow\fR(4)).
  94 .SS "Reentrant Interfaces"
  95 .sp
  96 .LP
  97 The  \fBgetspnam()\fR, \fBgetspent()\fR, and \fBfgetspent()\fR functions use
  98 thread-specific data storage that is reused in each call to one of these
  99 functions by the same thread, making them safe to use but not recommended for
 100 multithreaded applications.
 101 .sp
 102 .LP
 103 The  \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and \fBfgetspent_r()\fR functions
 104 provide reentrant interfaces for these operations.
 105 .sp
 106 .LP
 107 Each reentrant interface performs the same operation as its non-reentrant
 108 counterpart, named by removing the  \fB_r\fR suffix.  The reentrant interfaces,
 109 however, use buffers supplied by the caller to store returned results, and  are
 110 safe for use in both single-threaded and multithreaded applications.
 111 .sp
 112 .LP
 113 Each reentrant interface takes the same argument as its non-reentrant
 114 counterpart, as well as the following additional arguments.  The \fIresult\fR
 115 argument must be a pointer to a \fBstruct spwd\fR structure allocated by the
 116 caller.  On successful completion, the function returns the shadow password
 117 entry in this structure. The  \fIbuffer\fR argument must be a pointer to a
 118 buffer supplied by the caller.  This buffer is used as storage space for the
 119 shadow password data.  All of the pointers within the returned \fBstruct
 120 spwd\fR \fIresult\fR point to data stored within this buffer (see \fBRETURN
 121 VALUES\fR). The buffer must be large enough to hold all of the data associated
 122 with the shadow password entry. The \fIbuflen\fR argument should give the size
 123 in bytes of the buffer indicated by \fIbuffer.\fR
 124 .sp
 125 .LP
 126 For enumeration in multithreaded applications, the position within the
 127 enumeration is a process-wide property shared by all threads. The
 128 \fBsetspent()\fR function may be used in a multithreaded application but resets
 129 the enumeration position for all threads.  If multiple threads interleave calls
 130 to \fBgetspent_r()\fR, the threads will enumerate disjoint subsets of the
 131 shadow password database.
 132 .sp
 133 .LP
 134 Like its non-reentrant counterpart, \fBgetspnam_r()\fR leaves the enumeration
 135 position in an indeterminate state.
 136 .SH RETURN VALUES
 137 .sp
 138 .LP
 139 Password entries are represented by the \fBstruct spwd\fR structure defined in
 140 \fB<shadow.h>\fR:
 141 .sp
 142 .in +2
 143 .nf
 144 \fBstruct spwd{
 145     char           *sp_namp;     /* login name */
 146     char           *sp_pwdp;     /* encrypted passwd */
 147     int            sp_lstchg;    /* date of last change */
 148     int            sp_min;       /* min days to passwd change */
 149     int            sp_max;       /* max days to passwd change*/
 150     int            sp_warn;      /* warning period */
 151     int            sp_inact;     /* max days inactive */
 152     int            sp_expire;    /* account expiry date */
 153     unsigned int   sp_flag;      /* not used */
 154 };\fR
 155 .fi
 156 .in -2
 157
 158 .sp
 159 .LP
 160 See \fBshadow\fR(4) for more information on the interpretation of this data.
 161 .sp
 162 .LP
 163 The  \fBgetspnam()\fRand \fBgetspnam_r()\fR functions each return a pointer to
 164 a \fBstruct spwd\fR if they successfully locate the requested entry; otherwise
 165 they return \fINULL\fR.
 166 .sp
 167 .LP
 168 The  \fBgetspent()\fR, \fBgetspent_r()\fR, \fBfgetspent()\fR, and
 169 \fBfgetspent()\fR functions each return a pointer to a \fBstruct spwd\fR if
 170 they successfully enumerate an entry; otherwise they return \fINULL\fR,
 171 indicating the end of the enumeration.
 172 .sp
 173 .LP
 174 The  \fBgetspnam()\fR, \fBgetspent()\fR, and \fBfgetspent()\fR functions use
 175 thread-specific data storage, so returned data must be copied before a
 176 subsequent call to any of these functions if the data is to be saved.
 177 .sp
 178 .LP
 179 When the pointer returned by the reentrant functions \fBgetspnam_r()\fR,
 180 \fBgetspent_r()\fR, and \fBfgetspent_r()\fR is non-null, it is always equal to
 181 the \fIresult\fR pointer that was supplied by the caller.
 182 .SH ERRORS
 183 .sp
 184 .LP
 185 The reentrant functions  \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and
 186 \fBfgetspent_r()\fR will return \fBNULL\fR and set \fBerrno\fR to \fBERANGE\fR
 187 if the length of the buffer supplied by caller is not large enough to store the
 188 result.  See \fBIntro\fR(2) for the proper usage and interpretation of
 189 \fBerrno\fR in multithreaded applications.
 190 .SH ATTRIBUTES
 191 .sp
 192 .LP
 193 See \fBattributes\fR(5) for descriptions of the following attributes:
 194 .sp
 195
 196 .sp
 197 .TS
 198 box;
 199 c | c
 200 l | l .
 201 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 202 _
 203 MT-Level        T{
 204 See "Reentrant Interfaces" in \fBDESCRIPTION\fR.
 205 T}
 206 .TE
 207
 208 .SH SEE ALSO
 209 .sp
 210 .LP
 211 \fBnispasswd\fR(1), \fBpasswd\fR(1), \fByppasswd\fR(1), \fBIntro\fR(3),
 212 \fBgetlogin\fR(3C), \fBgetpwnam\fR(3C), \fBnsswitch.conf\fR(4),
 213 \fBpasswd\fR(4), \fBshadow\fR(4), \fBattributes\fR(5)
 214 .SH WARNINGS
 215 .sp
 216 .LP
 217 The reentrant interfaces \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and
 218 \fBfgetspent_r()\fR are included in this release on an uncommitted basis only,
 219 and are subject to change or removal in future minor releases.
 220 .SH NOTES
 221 .sp
 222 .LP
 223 When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On
 224 Multithreaded Applications\fR, for information about the use of the
 225 \fB_REENTRANT\fR flag.
 226 .sp
 227 .LP
 228 Use of the enumeration interfaces \fBgetspent()\fR and \fBgetspent_r()\fR is
 229 not recommended; enumeration is supported for the shadow file, \fBNIS,\fR and
 230 \fBNIS+,\fR but in general is not efficient and may not be supported for all
 231 database sources.  The semantics of enumeration are discussed further in
 232 \fBnsswitch.conf\fR(4).
 233 .sp
 234 .LP
 235 Access to shadow password information may be restricted in a manner depending
 236 on the database source being used.  Access to the \fB/etc/shadow\fR file is
 237 generally restricted to processes running with the effective uid of the file
 238 owner or the {\fBPRIV_FILE_DAC_READ\fR} privilege.  Other database sources may
 239 impose stronger or less stringent restrictions.
 240 .sp
 241 .LP
 242 Empty fields in the database source return -1 values for all fields except
 243 \fBsp_pwdp\fR and \fBsp_flag\fR, where the value returned is 0.
 244 .sp
 245 .LP
 246 When \fBNIS\fR is used as the database source,  the information for the shadow
 247 password entries is obtained from the ``passwd.byname'' map. This map stores
 248 only the information for the \fBsp_namp\fR and \fBsp_pwdp\fR fields of the
 249 \fBstruct spwd\fR structure. Shadow password entries obtained from \fBNIS\fR
 250 will contain the value \fB-1\fR in the remainder of the fields.
 251 .sp
 252 .LP
 253 When \fBNIS+\fR is used as the database source, and the caller lacks the
 254 permission needed to retrieve the encrypted password from the \fBNIS+\fR
 255 ``passwd.org_dir'' table, the \fBNIS+\fR service returns the string ``*NP*''
 256 instead of the actual encrypted password string.  The functions described on
 257 this page will then return the string ``*NP*'' to the caller as the value of
 258 the member \fBsp_pwdp\fR in the returned shadow password structure.