Now we're limiting ourselves to only functions that allocate or acquire
locks.

This adds a `-Wunused-result`-proof `GIT_UNUSED()`, just to demonstrate
that it works. With this, sortedcache.h is now completely
`GIT_WARN_UNUSED_RESULT`-annotated!

This change adds the GIT_WARN_UNUSED_RESULT annotation, which makes the
compiler warn when a return result is not used. This avoids bugs.

Our file utils functions all have a "futils" prefix, e.g.
`git_futils_touch`. One would thus naturally guess that their
definitions and implementation would live in files "futils.h" and
"futils.c", respectively, but in fact they live in "fileops.h".

Rename the files to match expectations.

Next to including several files, our "common.h" header also declares
various macros which are then used throughout the project. As such, we
have to make sure to always include this file first in all
implementation files. Otherwise, we might encounter problems or even
silent behavioural differences due to macros or defines not being
defined as they should be. So in fact, our header and implementation
files should make sure to always include "common.h" first.

This commit does so by establishing a common include pattern. Header
files inside of "src" will now always include "common.h" as its first
other file, separated by a newline from all the other includes to make
it stand out as special. There are two cases for the implementation
files. If they do have a matching header file, they will always include
this one first, leading to "common.h" being transitively included as
first file. If they do not have a matching header file, they instead
include "common.h" as first file themselves.

This fixes the outlined problems and will become our standard practice
for header and source files inside of the "src/" from now on.

All use of sortedcache will need this header, so put it in the
definition of the sortedcache API.

This converts an internal lock from a write lock to a read lock
where write isn't needed, and also clarifies some doc things about
where various locks are acquired and how various APIs are intended
to be used.

This is the first use we have of pthread_rwlock_t in libgit2.
Hopefully it won't cause any serious portability problems.