Documentation

Overview

    Package errors defines the error handling used by all Upspin software.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var Separator = ":\n\t"

      Separator is the string used to separate nested errors. By default, to make errors easier on the eye, nested errors are indented on a new line. A server may instead choose to keep each error on a single line by modifying the separator string, perhaps to ":: ".

      Functions

      func E

      func E(args ...interface{}) error

        E builds an error value from its arguments. There must be at least one argument or E panics. The type of each argument determines its meaning. If more than one argument of a given type is presented, only the last one is recorded.

        The types are:

        upspin.PathName
        	The Upspin path name of the item being accessed.
        upspin.UserName
        	The Upspin name of the user attempting the operation.
        errors.Op
        	The operation being performed, usually the method
        	being invoked (Get, Put, etc.).
        string
        	Treated as an error message and assigned to the
        	Err field after a call to errors.Str. To avoid a common
        	class of misuse, if the string contains an @, it will be
        	treated as a PathName or UserName, as appropriate. Use
        	errors.Str explicitly to avoid this special-casing.
        errors.Kind
        	The class of error, such as permission failure.
        error
        	The underlying error that triggered this one.
        

        If the error is printed, only those items that have been set to non-zero values will appear in the result.

        If Kind is not specified or Other, we set it to the Kind of the underlying error.

        func Errorf

        func Errorf(format string, args ...interface{}) error

          Errorf is equivalent to fmt.Errorf, but allows clients to import only this package for all error handling.

          func Is

          func Is(kind Kind, err error) bool

            Is reports whether err is an *Error of the given Kind. If err is nil then Is returns false.

            func MarshalError

            func MarshalError(err error) []byte

              MarshalError marshals an arbitrary error and returns the byte slice. If the error is nil, it returns nil. It returns the argument slice unchanged if the error is nil. If the error is not an *Error, it just records the result of err.Error(). Otherwise it encodes the full Error struct.

              func MarshalErrorAppend

              func MarshalErrorAppend(err error, b []byte) []byte

                MarshalErrorAppend marshals an arbitrary error into a byte slice. The result is appended to b, which may be nil. It returns the argument slice unchanged if the error is nil. If the error is not an *Error, it just records the result of err.Error(). Otherwise it encodes the full Error struct.

                func Match

                func Match(err1, err2 error) bool

                  Match compares its two error arguments. It can be used to check for expected errors in tests. Both arguments must have underlying type *Error or Match will return false. Otherwise it returns true iff every non-zero element of the first error is equal to the corresponding element of the second. If the Err field is a *Error, Match recurs on that field; otherwise it compares the strings returned by the Error methods. Elements that are in the second argument but not present in the first are ignored.

                  For example,

                  Match(errors.E(upspin.UserName("joe@schmoe.com"), errors.Permission), err)
                  

                  tests whether err is an Error with Kind=Permission and User=joe@schmoe.com.

                  Example
                  Output:
                  
                  
                  Match: true
                  Mismatch: false
                  

                  func Str

                  func Str(text string) error

                    Str returns an error that formats as the given text. It is intended to be used as the error-typed argument to the E function.

                    func UnmarshalError

                    func UnmarshalError(b []byte) error

                      UnmarshalError unmarshals the byte slice into an error value. If the slice is nil or empty, it returns nil. Otherwise the byte slice must have been created by MarshalError or MarshalErrorAppend. If the encoded error was of type *Error, the returned error value will have that underlying type. Otherwise it will be just a simple value that implements the error interface.

                      Types

                      type Error

                      type Error struct {
                      	// Path is the Upspin path name of the item being accessed.
                      	Path upspin.PathName
                      	// User is the Upspin name of the user attempting the operation.
                      	User upspin.UserName
                      	// Op is the operation being performed, usually the name of the method
                      	// being invoked (Get, Put, etc.). It should not contain an at sign @.
                      	Op Op
                      	// Kind is the class of error, such as permission failure,
                      	// or "Other" if its class is unknown or irrelevant.
                      	Kind Kind
                      	// The underlying error that triggered this one, if any.
                      	Err error
                      	// contains filtered or unexported fields
                      }

                        Error is the type that implements the error interface. It contains a number of fields, each of different type. An Error value may leave some values unset.

                        Example
                        Output:
                        
                        
                        Simple error:
                        Get: jane@doe.com/file: I/O error: network unreachable
                        
                        Nested error:
                        Read: jane@doe.com/file, user joe@blow.com: I/O error:
                        	Get: network unreachable
                        

                        func (*Error) Error

                        func (e *Error) Error() string

                        func (*Error) MarshalAppend

                        func (e *Error) MarshalAppend(b []byte) []byte

                          MarshalAppend marshals err into a byte slice. The result is appended to b, which may be nil. It returns the argument slice unchanged if the error is nil.

                          func (*Error) MarshalBinary

                          func (e *Error) MarshalBinary() ([]byte, error)

                            MarshalBinary marshals its receiver into a byte slice, which it returns. It returns nil if the error is nil. The returned error is always nil.

                            func (*Error) UnmarshalBinary

                            func (e *Error) UnmarshalBinary(b []byte) error

                              UnmarshalBinary unmarshals the byte slice into the receiver, which must be non-nil. The returned error is always nil.

                              type Kind

                              type Kind uint8

                                Kind defines the kind of error this is, mostly for use by systems such as FUSE that must act differently depending on the error.

                                const (
                                	Other         Kind = iota // Unclassified error. This value is not printed in the error message.
                                	Invalid                   // Invalid operation for this type of item.
                                	Permission                // Permission denied.
                                	IO                        // External I/O error such as network failure.
                                	Exist                     // Item already exists.
                                	NotExist                  // Item does not exist.
                                	IsDir                     // Item is a directory.
                                	NotDir                    // Item is not a directory.
                                	NotEmpty                  // Directory not empty.
                                	Private                   // Information withheld.
                                	Internal                  // Internal error or inconsistency.
                                	CannotDecrypt             // No wrapped key for user with read access.
                                	Transient                 // A transient error.
                                	BrokenLink                // Link target does not exist.
                                )

                                  Kinds of errors.

                                  The values of the error kinds are common between both clients and servers. Do not reorder this list or remove any items since that will change their values. New items must be added only to the end.

                                  func (Kind) String

                                  func (k Kind) String() string

                                  type Op

                                  type Op string

                                    Op describes an operation, usually as the package and method, such as "key/server.Lookup".