But why attach this to the realpath() call?  Do you realize how amazingly expensive realpath()'ing multiple paths would be?  There is a stat syscall for each and every directory in each path plus the final stat for the file itself.  So say you had an include_path with 4 paths in it each one being 5 directories deep, that one realpath() call will cost you 25 stat calls.  Ouch!

Ok, I wasn't aware of that.

The idea was to have some generic way to find files in the include path for functions that want file system paths as their arguments.

Yup, I understand that and can see merit in that request, but your proposed implementation is bad.  There is no reason to tie this to the realpath() call.  Perhaps something like a find_include_path()

Yes, my first idea was find_include_path(). I had no idea of the implications of realpath() when I suggested that.