README
¶
luser
luser is a drop-in replacement for os/user which allows you to lookup users
and groups in cross-compiled builds without cgo.
Overview
os/user requires cgo to lookup users using the target OS's API. This is
the most reliable way to look up user and group information. However,
cross-compiling means that os/user will only work for the OS you're using.
user.Current() is usable when building without cgo, but doesn't always
work. The $USER and $HOME variables could be different from what you
expect or not even exist.
If you want to cross-compile a relatively simple program that needs to write a config file somewhere in the user's directory, the last thing you want to do is figure out some elaborate build scheme involving virtual machines.
Usage
luser has the same API as os/user. You should be able to just replace
user. with luser. in your files and let goimports do the rest. The
returned *User and *Group types will have an IsLuser field indicating
whether or not a fallback method was used.
Install
Install the package with:
$ go get github.com/tweekmonster/luser
A sample program called luser can be installed if you want to see the
fallback results on your platform:
$ CGO_ENABLED=0 go install github.com/tweekmonster/luser/cmd/luser
$ luser -c
$ luser username
$ luser 1000
Fallback lookup methods
os/user functions are used when built with cgo. Otherwise, it falls back
to one of the following lookup methods:
| Method | Used for |
|---|---|
/etc/passwd |
Parsed to lookup user information. (Unix, Linux) |
/etc/group |
Parsed to lookup group information. (Unix, Linux) |
getent |
Optional. Find user/group information. (Unix, Linux) |
dscacheutil |
Lookup user/group information via Directory Services. (Darwin) |
id |
Finding a user's groups when using GroupIds(). |
Note: Windows should always work regardless of the build platform since it
uses syscall instead of cgo.
Caveats
luser.Userandluser.Groupare new types. The underlyinguser.*types are embedded, however (e.g.u.User).- The lookup methods use
exec.Command()and will be noticeably slower if you're looking up users and groups a lot. - Group-releated functions will only be available when compiling with Go 1.7+.
Documentation
¶
Overview ¶
Package luser is a drop-in replacement for 'os/user' which allows you to lookup users and groups in cross-compiled builds without 'cgo'.
'os/user' requires 'cgo' to lookup users using the target OS's API. This is the most reliable way to look up user and group information. However, cross-compiling means that 'os/user' will only work for the OS you're using. 'user.Current()' is usable when building without 'cgo', but doesn't always work. The '$USER' and '$HOME' variables could be different from what you expect or not even exist.
If you want to cross-compile a relatively simple program that needs to write a config file somewhere in the user's directory, the last thing you want to do is figure out some elaborate build scheme involving virtual machines.
When cgo is not available for a build, one of the following methods will be used to lookup user and group information:
| Method | Used for | |---------------|----------------------------------------------------------------| | `/etc/passwd` | Parsed to lookup user information. (Unix, Linux) | | `/etc/group` | Parsed to lookup group information. (Unix, Linux) | | `getent` | Optional. Find user/group information. (Unix, Linux) | | `dscacheutil` | Lookup user/group information via Directory Services. (Darwin) | | `id` | Finding a user's groups when using `GroupIds()`. |
You should be able to simply replace 'user.' with 'luser.' (in most cases).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCurrentUser = errors.New("luser: unable to get current user")
ErrCurrentUser returned when Current() fails to get the user.
var ErrListGroups = errors.New("luser: unable to list groups")
ErrListGroups returned when LookupGroupId() has no fallback.
var GetentParseFiles = true
GetentParseFiles tells the getent fallback to prefer parsing the '/etc/passwd' and '/etc/group' files instead of executing the 'getent' program. This is on by default since the speed of parsing the files directly is comparible to the C API and is many times faster than executing the 'getent' program. If false, the files will still be parsed if 'getent' fails or isn't found.
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group struct {
*user.Group
// IsLuser is a flag indicating if the user was found without cgo.
IsLuser bool
}
Group represents a grouping of users. Embedded *user.Group reference: https://golang.ir/pkg/os/user/#Group
func LookupGroup ¶
LookupGroup looks up a group by name. If the group cannot be found, the returned error is of type UnknownGroupError.
func LookupGroupId ¶
LookupGroupId looks up a group by groupid. If the group cannot be found, the returned error is of type UnknownGroupIdError.
type UnknownGroupError ¶
type UnknownGroupError string
UnknownGroupError is returned by LookupGroup when a group cannot be found.
func (UnknownGroupError) Error ¶
func (e UnknownGroupError) Error() string
type UnknownGroupIdError ¶
type UnknownGroupIdError string
UnknownGroupIdError is returned by LookupGroupId when a group cannot be found.
func (UnknownGroupIdError) Error ¶
func (e UnknownGroupIdError) Error() string
type UnknownUserError ¶
type UnknownUserError string
UnknownUserError is returned by Lookup when a user cannot be found.
func (UnknownUserError) Error ¶
func (e UnknownUserError) Error() string
type UnknownUserIdError ¶
type UnknownUserIdError int
UnknownUserIdError is returned by LookupId when a user cannot be found.
func (UnknownUserIdError) Error ¶
func (e UnknownUserIdError) Error() string
type User ¶
User represents a user account. Embedded *user.User reference: https://golang.ir/pkg/os/user/#User
func Current ¶
Current returns the current user. On builds where cgo is available, this returns the result from user.Current(). Otherwise, alternate lookup methods are used before falling back to the built-in stub.
func Lookup ¶
Lookup looks up a user by username. If the user cannot be found, the returned error is of type UnknownUserError.
Source Files
Directories