os/user: add a way to enforce pure Go implementation

This provides a way to enforce pure Go implementation of os/user
lookup functions on UNIX platforms by means of "osusergo" build tag,
in a manner similar to netgo/netcgo tags in the net package.

If "osusergo" build tag is set, Go implementation is selected.

If "osusergo" build tag is NOT set, the old behavior is retained,
that is to use cgo (libc-backed) implementation if both cgo and such
and such implementation are available.

The reason behind this change is to make it possible to build proper
static binaries on Linux. The problem is, glibc implementation of
getpw*, getgrp* and getgrouplist functions relies on presense of
libnss*.so libraries during runtime, making it impossible to build
a self-contained static binary which uses both cgo and os/user.
In such case, linker warnings like this are shown:

> warning: Using 'getgrouplist' in statically linked applications
> requires at runtime the shared libraries from the glibc version
> used for linking

While this can be solved by recompiling glibc with --enable-static-nss
flag or using a different libc implementation (like musl on Alpine Linux),
it is not always practical or even possible.

Fixes #23265

Change-Id: I383a448a2ecf15493ec93dbd5d076b6330cb14cb
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Reviewed-on: https://go-review.googlesource.com/92456
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/os/user/cgo_lookup_unix.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // +build darwin dragonfly freebsd !android,linux netbsd openbsd solaris
-// +build cgo
+// +build cgo,!osusergo
 
 package user
 

src/os/user/listgroups_unix.go

@@ -3,6 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // +build dragonfly darwin freebsd !android,linux netbsd openbsd
+// +build cgo,!osusergo
 
 package user
 

src/os/user/lookup_stubs.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// +build !cgo,!windows,!plan9 android
+// +build !cgo,!windows,!plan9 android osusergo
 
 package user
 

src/os/user/lookup_unix.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // +build darwin dragonfly freebsd !android,linux nacl netbsd openbsd solaris
-// +build !cgo
+// +build !cgo osusergo
 
 package user
 

src/os/user/user.go

@@ -2,7 +2,18 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package user allows user account lookups by name or id.
+/*
+Package user allows user account lookups by name or id.
+
+For most Unix systems, this package has two internal implementations of
+resolving user and group ids to names. One is written in pure Go and
+parses /etc/passwd and /etc/group. The other is cgo-based and relies on
+the standard C library (libc) routines such as getpwuid_r and getgrnam_r.
+
+When cgo is available, cgo-based (libc-backed) code is used by default.
+This can be overriden by using osusergo build tag, which enforces
+the pure Go implementation.
+*/
 package user
 
 import (