man3/getpw.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de)
  12 .\"
  13 .TH getpw 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 getpw \- reconstruct password line entry
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  22 .B #include <sys/types.h>
  23 .B #include <pwd.h>
  24 .PP
  25 .BI "[[deprecated]] int getpw(uid_t " uid ", char *" buf );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR getpw ()
  30 function reconstructs the password line entry for
  31 the given user ID \fIuid\fP in the buffer \fIbuf\fP.
  32 The returned buffer contains a line of format
  33 .PP
  34 .in +4n
  35 .EX
  36 .B name:passwd:uid:gid:gecos:dir:shell
  37 .EE
  38 .in
  39 .PP
  40 The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
  41 .PP
  42 .in +4n
  43 .EX
  44 struct passwd {
  45     char   *pw_name;       /* username */
  46     char   *pw_passwd;     /* user password */
  47     uid_t   pw_uid;        /* user ID */
  48     gid_t   pw_gid;        /* group ID */
  49     char   *pw_gecos;      /* user information */
  50     char   *pw_dir;        /* home directory */
  51     char   *pw_shell;      /* shell program */
  52 };
  53 .EE
  54 .in
  55 .PP
  56 For more information about the fields of this structure, see
  57 .BR passwd (5).
  58 .SH RETURN VALUE
  59 The
  60 .BR getpw ()
  61 function returns 0 on success; on error, it returns \-1, and
  62 .I errno
  63 is set to indicate the error.
  64 .PP
  65 If
  66 .I uid
  67 is not found in the password database,
  68 .BR getpw ()
  69 returns \-1, sets
  70 .I errno
  71 to 0, and leaves
  72 .I buf
  73 unchanged.
  74 .SH ERRORS
  75 .TP
  76 .BR 0 " or " ENOENT
  77 No user corresponding to
  78 .IR uid .
  79 .TP
  80 .B EINVAL
  81 .I buf
  82 is NULL.
  83 .TP
  84 .B ENOMEM
  85 Insufficient memory to allocate
  86 .I passwd
  87 structure.
  88 .SH FILES
  89 .TP
  90 .I /etc/passwd
  91 password database file
  92 .SH ATTRIBUTES
  93 For an explanation of the terms used in this section, see
  94 .BR attributes (7).
  95 .TS
  96 allbox;
  97 lbx lb lb
  98 l l l.
  99 Interface       Attribute       Value
 100 T{
 101 .na
 102 .nh
 103 .BR getpw ()
 104 T}      Thread safety   MT-Safe locale
 105 .TE
 106 .sp 1
 107 .SH STANDARDS
 108 None.
 109 .SH HISTORY
 110 SVr2.
 111 .SH BUGS
 112 The
 113 .BR getpw ()
 114 function is dangerous as it may overflow the provided buffer
 115 .IR buf .
 116 It is obsoleted by
 117 .BR getpwuid (3).
 118 .SH SEE ALSO
 119 .BR endpwent (3),
 120 .BR fgetpwent (3),
 121 .BR getpwent (3),
 122 .BR getpwnam (3),
 123 .BR getpwuid (3),
 124 .BR putpwent (3),
 125 .BR setpwent (3),
 126 .BR passwd (5)