errno handling

[enkore]

Docs:

sodium_lock() will return -1 when any limit is reached.

Sometimes it will set errno as well, e.g. if Sodium doesn't support it on the build platform, or if it is running on Windows.

While I noticed this in this specific example first, many Sodium functions set errno directly, but this is usually not documented. I've only noticed documentation on interaction with errno regarding sodium_malloc. I'm not sure if this is important enough to address, since it's probably a lot of work to comb through all public APIs and check how they behave regarding errno. Especially with platform-dependent functions having multiple implementations.

int
sodium_mlock(void *const addr, const size_t len)
{
#if defined(MADV_DONTDUMP) && defined(HAVE_MADVISE)
    (void) madvise(addr, len, MADV_DONTDUMP);
#endif
#ifdef HAVE_MLOCK
    return mlock(addr, len);
#elif defined(WINAPI_DESKTOP)
    return -(VirtualLock(addr, len) == 0);
#else
    errno = ENOSYS;
    return -1;
#endif
}

int
sodium_munlock(void *const addr, const size_t len)
{
    sodium_memzero(addr, len);
#if defined(MADV_DODUMP) && defined(HAVE_MADVISE)
    (void) madvise(addr, len, MADV_DODUMP);
#endif
#ifdef HAVE_MLOCK
    return munlock(addr, len);
#elif defined(WINAPI_DESKTOP)
    return -(VirtualUnlock(addr, len) == 0);
#else
    errno = ENOSYS;
    return -1;
#endif
}

[jedisct1]

This is intentionally not documented, because it is not portable across all platforms.

It's probably better not to document something than document something that sometimes work.

[enkore]

Given normal use of errno I also wouldn't expect any portability issues.