user.go

     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
View as plain text