1 // Copyright 2011 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 /*
6 Package user allows user account lookups by name or id.
7 8 For most Unix systems, this package has two internal implementations of
9 resolving user and group ids to names, and listing supplementary group IDs.
10 One is written in pure Go and parses /etc/passwd and /etc/group. The other
11 is cgo-based and relies on the standard C library (libc) routines such as
12 getpwuid_r, getgrnam_r, and getgrouplist.
13 14 When cgo is available, and the required routines are implemented in libc
15 for a particular platform, cgo-based (libc-backed) code is used.
16 This can be overridden by using osusergo build tag, which enforces
17 the pure Go implementation.
18 */
19 package user
20 21 import (
22 "strconv"
23 )
24 25 // These may be set to false in init() for a particular platform and/or
26 // build flags to let the tests know to skip tests of some features.
27 var (
28 userImplemented = true
29 groupImplemented = true
30 groupListImplemented = true
31 )
32 33 // User represents a user account.
34 type User struct {
35 // Uid is the user ID.
36 // On POSIX systems, this is a decimal number representing the uid.
37 // On Windows, this is a security identifier (SID) in a string format.
38 // On Plan 9, this is the contents of /dev/user.
39 Uid string
40 // Gid is the primary group ID.
41 // On POSIX systems, this is a decimal number representing the gid.
42 // On Windows, this is a SID in a string format.
43 // On Plan 9, this is the contents of /dev/user.
44 Gid string
45 // Username is the login name.
46 Username string
47 // Name is the user's real or display name.
48 // It might be blank.
49 // On POSIX systems, this is the first (or only) entry in the GECOS field
50 // list.
51 // On Windows, this is the user's display name.
52 // On Plan 9, this is the contents of /dev/user.
53 Name string
54 // HomeDir is the path to the user's home directory (if they have one).
55 HomeDir string
56 }
57 58 // Group represents a grouping of users.
59 //
60 // On POSIX systems Gid contains a decimal number representing the group ID.
61 type Group struct {
62 Gid string // group ID
63 Name string // group name
64 }
65 66 // UnknownUserIdError is returned by [LookupId] when a user cannot be found.
67 type UnknownUserIdError int
68 69 func (e UnknownUserIdError) Error() string {
70 return "user: unknown userid " + strconv.Itoa(int(e))
71 }
72 73 // UnknownUserError is returned by [Lookup] when
74 // a user cannot be found.
75 type UnknownUserError string
76 77 func (e UnknownUserError) Error() string {
78 return "user: unknown user " + string(e)
79 }
80 81 // UnknownGroupIdError is returned by [LookupGroupId] when
82 // a group cannot be found.
83 type UnknownGroupIdError string
84 85 func (e UnknownGroupIdError) Error() string {
86 return "group: unknown groupid " + string(e)
87 }
88 89 // UnknownGroupError is returned by [LookupGroup] when
90 // a group cannot be found.
91 type UnknownGroupError string
92 93 func (e UnknownGroupError) Error() string {
94 return "group: unknown group " + string(e)
95 }
96