what does function setlocale do?

Question

I write a function to convert wstring to string.If I remove the code setlocale(LC_CTYPE, "") the program goes wrong.I refer to cplusplus read the doc.

C string containing the name of a C locale. These are system specific, but at least the two following locales must exist:

"C" Minimal "C" locale
"" Environment's default locale

If the value of this parameter is NULL, the function does not make any changes to the current locale, but the name of the current locale is still returned by the function.

my code here,source code from cplusplus.com(I add some chinese character):

/* wcstombs example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* wcstombs, wchar_t(C) */
#include <locale.h>     /* setlocale */
int main() 
{
    setlocale(LC_CTYPE, "");
    const wchar_t str[] = L"中国、wcstombs example";
    char buffer[64];
    int ret;

    printf ("wchar_t string: %ls \n",str);

    ret = wcstombs ( buffer, str, sizeof(buffer) );
    if (ret==64) 
        buffer[63]='\0';
    if (ret) 
        printf ("length:%d,multibyte string: %s \n",ret,buffer);

  return 0;
}

If I remove the code setlocale(LC_CTYPE, ""),the program does not run as I expect. My question is :"If I run in different machine,the program will differ? As the doc say,if the locale is "" ,function does not make any changes to the current locale,but the name of the current locale is still returned by the funciton." Because the current locale in different machine may differ?

Here is a my c++ version of convert wstring with string,while string to wstring do not need function setlocale,and the program runs well:

/*
    string converts to wstring
*/
std::wstring s2ws(const std::string& src)     
{  
    std::wstring res = L"";
    size_t const wcs_len = mbstowcs(NULL, src.c_str(), 0);
    std::vector<wchar_t> buffer(wcs_len + 1);
    mbstowcs(&buffer[0], src.c_str(), src.size());
    res.assign(buffer.begin(), buffer.end() - 1);

    return res;
}  

/*
    wstring converts to string
*/
std::string ws2s(const std::wstring & src)
{ 
   setlocale(LC_CTYPE, "");

   std::string res = "";

   size_t const mbs_len = wcstombs(NULL, src.c_str(), 0);

   std::vector<char> buffer(mbs_len + 1);

   wcstombs(&buffer[0], src.c_str(), buffer.size());

   res.assign(buffer.begin(), buffer.end() - 1);

   return res;
}

Answer 1

If the second argument to setlocale is NULL, it does nothing apart from returning the current locale. But you're not doing that. You're sending it a string entirely consisting of a single nil byte, aka "". My setlocale man page says

If locale is an empty string, "", each part of the locale that should be modified is set according to the environment variables. The details are implementation-dependent.

So what this is doing for you is setting the locale to whatever the user has specified or to the system default.

Without running setlocale at all presumably leaves the current locale either uninitialized or NULL on your system, which is why your program fails without that setting.

Two other man pages for stuff you're using say

The behavior of mbstowcs() depends on the LC_CTYPE category of the current locale.

The behavior of wcstombs() depends on the LC_CTYPE category of the current locale.

Presumably these routines are what is failing if you haven't set the locale at all.

I would guess that you probably don't need to run the setlocale statement on every invocation of these routines, but you do need to make sure it's run at least once before running them.

As far as what happens differently depending on the current locale, I believe that would be how exactly the multibyte string is converted to wide characters and vis versa. I think that the man page for those routines leaves it vague because of that difference. Personally, I'd prefer if it set some examples, such as, "if the current locale is C, the multibyte string is ASCII characters." I would guess there's also at least one in which it is interpreted as UTF-8, but I don't know enough about the different locales to say exactly which one that is. There's probably also at least one locale where the multibyte string happened to be another two bytes per character encoding, but C and C++ would still treat it as bytes.

Edit: Thinking about this more, given the characters you added to the example code, it might make sense to explicitly state that using locales that do not support Chinese characters will cause the final printf to report that the length was -1, and this includes the default C locale. In this case, the contents of the buffer is not clearly specified by the standard - at least, my reading of it indicates that the buffer value will probably be all of the characters up to but not including the one that failed to convert. While neither the C++ documentation nor the C documentation state what happens regarding the character that could not be converted. I haven't paid for the official standards, but I do have copies of the last free releases. C++17 defers to C17. C17 also refrains from commenting on this aspect of this function. For wcsrtombs, it explicitly states that the conversion state is unspecified. However, on wcstombs_s, C17 states

If the conversion stops without converting a null wide character and dst is not a null pointer, then a null character is stored into the array pointed to by dst immediately following any multibyte characters already stored.

In my own experiments with the code provided by the OP above, it appears that the wcstombs implementation on Fedora 28 simply refrains from making any further changes to the buffer. That seems to indicate to me, if the exact behavior of the code matters for this situation, it may make sense to use wcstombs_s instead. But at a minimum, you just check to see if the length returned is -1, and if it is, report an error rather than assuming the conversion worked.