Skip to content
  • Carlos O'Donell's avatar
    61af4bbb
    mbstowcs: Document, test, and fix null pointer dst semantics (Bug 25219) · 61af4bbb
    Carlos O'Donell authored
    The function mbstowcs, by an XSI extension to POSIX, accepts a null
    pointer for the destination wchar_t array.  This API behaviour allows
    you to use the function to compute the length of the required wchar_t
    array i.e. does the conversion without storing it and returns the
    number of wide characters required.
    
    We remove the __write_only__ markup for the first argument because it
    is not true since the destination may be a null pointer, and so the
    length argument may not apply.  We remove the markup otherwise the new
    test case cannot be compiled with -Werror=nonnull.
    
    We add a new test case for mbstowcs which exercises the destination is
    a null pointer behaviour which we have now explicitly documented.
    
    The mbsrtowcs and mbsnrtowcs behave similarly, and mbsrtowcs is
    documented as doing this in C11, even if the standard doesn't come out
    and call out this specific use case.  We add one note to each of
    mbsrtowcs and mbsnrtowcs to call out that they support a null pointer
    for the destination.
    
    The wcsrtombs function behaves similarly but in the other way around
    and allows you to use a null destination pointer to compute how many
    bytes you would need to convert the wide character input.  We document
    this particular case also, but leave wcsnrtombs as a references to
    wcsrtombs, so the reader must still read the details of the semantics
    for wcsrtombs.
    61af4bbb
    mbstowcs: Document, test, and fix null pointer dst semantics (Bug 25219)
    Carlos O'Donell authored
    The function mbstowcs, by an XSI extension to POSIX, accepts a null
    pointer for the destination wchar_t array.  This API behaviour allows
    you to use the function to compute the length of the required wchar_t
    array i.e. does the conversion without storing it and returns the
    number of wide characters required.
    
    We remove the __write_only__ markup for the first argument because it
    is not true since the destination may be a null pointer, and so the
    length argument may not apply.  We remove the markup otherwise the new
    test case cannot be compiled with -Werror=nonnull.
    
    We add a new test case for mbstowcs which exercises the destination is
    a null pointer behaviour which we have now explicitly documented.
    
    The mbsrtowcs and mbsnrtowcs behave similarly, and mbsrtowcs is
    documented as doing this in C11, even if the standard doesn't come out
    and call out this specific use case.  We add one note to each of
    mbsrtowcs and mbsnrtowcs to call out that they support a null pointer
    for the destination.
    
    The wcsrtombs function behaves similarly but in the other way around
    and allows you to use a null destination pointer to compute how many
    bytes you would need to convert the wide character input.  We document
    this particular case also, but leave wcsnrtombs as a references to
    wcsrtombs, so the reader must still read the details of the semantics
    for wcsrtombs.
Loading