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/*
6Package user allows user account lookups by name or id.
7
8For most Unix systems, this package has two internal implementations of
9resolving user and group ids to names, and listing supplementary group IDs.
10One is written in pure Go and parses /etc/passwd and /etc/group. The other
11is cgo-based and relies on the standard C library (libc) routines such as
12getpwuid_r, getgrnam_r, and getgrouplist.
13
14When cgo is available, and the required routines are implemented in libc
15for a particular platform, cgo-based (libc-backed) code is used.
16This can be overridden by using osusergo build tag, which enforces
17the pure Go implementation.
18*/
19package user
20
21import (
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.
27var (
28	userImplemented      = true
29	groupImplemented     = true
30	groupListImplemented = true
31)
32
33// User represents a user account.
34type 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.
61type 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.
67type UnknownUserIdError int
68
69func (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.
75type UnknownUserError string
76
77func (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.
83type UnknownGroupIdError string
84
85func (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.
91type UnknownGroupError string
92
93func (e UnknownGroupError) Error() string {
94	return "group: unknown group " + string(e)
95}
96