capability: Deprecate NewPid and NewFile for NewPid2 and NewFile2 (#14)

The old methods had an internal Load(), which is unnecessary for some
use cases.  For example, if you're going to drop all capabilities, you
don't need to load the current set first.  This commit deprecates the
old New* functions and adds New*2 functions which do not include the
internal Load.  Callers who do need the Load will need to call it
explicitly after initializing their Capabilities object.  Callers who
do not need the Load can just add the "2" to the function name and get
more efficient/robust behavior.

The "Deprecated:" paragraph syntax is recommended in [1]:

  To signal that an identifier should not be used, add a paragraph to
  its doc comment that begins with "Deprecated:" followed by some
  information about the deprecation.

[1]: https://blog.golang.org/godoc-documenting-go-code

capability/capability.go

@@ -60,13 +60,74 @@ type Capabilities interface {
 	Apply(kind CapType) error
 }
 
-// NewPid create new initialized Capabilities object for given pid when it
-// is nonzero, or for the current pid if pid is 0
+// NewPid initializes a new Capabilities object for given pid when
+// it is nonzero, or for the current process if pid is 0.
+//
+// Deprecated: Replace with NewPid2.  For example, replace:
+//
+//    c, err := NewPid(0)
+//    if err != nil {
+//      return err
+//    }
+//
+// with:
+//
+//    c, err := NewPid2(0)
+//    if err != nil {
+//      return err
+//    }
+//    err = c.Load()
+//    if err != nil {
+//      return err
+//    }
 func NewPid(pid int) (Capabilities, error) {
+	c, err := newPid(pid)
+	if err != nil {
+		return c, err
+	}
+	err = c.Load()
+	return c, err
+}
+
+// NewPid2 initializes a new Capabilities object for given pid when
+// it is nonzero, or for the current process if pid is 0.  This
+// does not load the process's current capabilities; to do that you
+// must call Load explicitly.
+func NewPid2(pid int) (Capabilities, error) {
 	return newPid(pid)
 }
 
-// NewFile create new initialized Capabilities object for given named file.
-func NewFile(name string) (Capabilities, error) {
-	return newFile(name)
+// NewFile initializes a new Capabilities object for given file path.
+//
+// Deprecated: Replace with NewFile2.  For example, replace:
+//
+//    c, err := NewFile(path)
+//    if err != nil {
+//      return err
+//    }
+//
+// with:
+//
+//    c, err := NewFile2(path)
+//    if err != nil {
+//      return err
+//    }
+//    err = c.Load()
+//    if err != nil {
+//      return err
+//    }
+func NewFile(path string) (Capabilities, error) {
+	c, err := newFile(path)
+	if err != nil {
+		return c, err
+	}
+	err = c.Load()
+	return c, err
+}
+
+// NewFile2 creates a new initialized Capabilities object for given
+// file path.  This does not load the process's current capabilities;
+// to do that you must call Load explicitly.
+func NewFile2(path string) (Capabilities, error) {
+	return newFile(path)
 }

capability/capability_linux.go

@@ -114,10 +114,6 @@ func newPid(pid int) (c Capabilities, err error) {
 		err = errUnknownVers
 		return
 	}
-	err = c.Load()
-	if err != nil {
-		c = nil
-	}
 	return
 }
 
@@ -492,10 +488,6 @@ func (c *capsV3) Apply(kind CapType) (err error) {
 
 func newFile(path string) (c Capabilities, err error) {
 	c = &capsFile{path: path}
-	err = c.Load()
-	if err != nil {
-		c = nil
-	}
 	return
 }