The new function accepts a slightly more intuitive order of paramters,
and returns an error code, thus allowing applications to report a
meaningful error message.