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. One is written in pure Go and
10parses /etc/passwd and /etc/group. The other is cgo-based and relies on
11the standard C library (libc) routines such as getpwuid_r and getgrnam_r.
12
13When cgo is available, cgo-based (libc-backed) code is used by default.
14This can be overridden by using osusergo build tag, which enforces
15the pure Go implementation.
16*/
17package user
18
19import (
20	"strconv"
21)
22
23var (
24	userImplemented  = true // set to false by lookup_stubs.go's init
25	groupImplemented = true // set to false by lookup_stubs.go's init
26)
27
28// User represents a user account.
29type User struct {
30	// Uid is the user ID.
31	// On POSIX systems, this is a decimal number representing the uid.
32	// On Windows, this is a security identifier (SID) in a string format.
33	// On Plan 9, this is the contents of /dev/user.
34	Uid string
35	// Gid is the primary group ID.
36	// On POSIX systems, this is a decimal number representing the gid.
37	// On Windows, this is a SID in a string format.
38	// On Plan 9, this is the contents of /dev/user.
39	Gid string
40	// Username is the login name.
41	Username string
42	// Name is the user's real or display name.
43	// It might be blank.
44	// On POSIX systems, this is the first (or only) entry in the GECOS field
45	// list.
46	// On Windows, this is the user's display name.
47	// On Plan 9, this is the contents of /dev/user.
48	Name string
49	// HomeDir is the path to the user's home directory (if they have one).
50	HomeDir string
51}
52
53// Group represents a grouping of users.
54//
55// On POSIX systems Gid contains a decimal number representing the group ID.
56type Group struct {
57	Gid  string // group ID
58	Name string // group name
59}
60
61// UnknownUserIdError is returned by LookupId when a user cannot be found.
62type UnknownUserIdError int
63
64func (e UnknownUserIdError) Error() string {
65	return "user: unknown userid " + strconv.Itoa(int(e))
66}
67
68// UnknownUserError is returned by Lookup when
69// a user cannot be found.
70type UnknownUserError string
71
72func (e UnknownUserError) Error() string {
73	return "user: unknown user " + string(e)
74}
75
76// UnknownGroupIdError is returned by LookupGroupId when
77// a group cannot be found.
78type UnknownGroupIdError string
79
80func (e UnknownGroupIdError) Error() string {
81	return "group: unknown groupid " + string(e)
82}
83
84// UnknownGroupError is returned by LookupGroup when
85// a group cannot be found.
86type UnknownGroupError string
87
88func (e UnknownGroupError) Error() string {
89	return "group: unknown group " + string(e)
90}
91