mbs(3m)

NAME
mbs - multibyte string functions

SYNOPSIS
int mbslen(const char *src);
int mbsnlen(const char *src, size_t sn, int cn);
size_t mbssize(const char *src);
size_t mbsnsize(const char *src, size_t sn, int cn);
char *mbsdup(const char *src);
char *mbsndup(const char *src, size_t n, int cn);
char *mbsoff(char *src, int off);
char *mbsnoff(char *src, int off, size_t sn);
char *mbschr(char *src, wchar_t wc);
char *mbsnchr(char *src, size_t sn, int cn, wchar_t wc);
int mbswidth(const char *src, size_t sn, int wn);
char *mbssub(char *src, size_t sn, int wn);

DESCRIPTION
The mbs(3m) module provides extended string functions that will work with the locale dependant encoding such as UTF-8 or any 8 bit encoding. They are useful for determining complete substrings of UTF-8 sequences such as when terminal output must consider the number of display positions that a sequence of characters will occupy.

mbslen
    The mbslen function will return the number of characters in the multibyte string pointed to by src. Characters in this context are contol characters and complete multibyte sequences. Combining characters are not reduced. See mbswidth(3m) for calculating display positions.

mbsnlen
    The mbsnlen function will return the number of characters in the multibyte string pointed to by src. Characters in this context are contol characters and complete multibyte sequences. Combining characters are not reduced. See mbswidth(3m) for calculating display positions. No more than sn bytes of src will be examined and no more than cn characters will be converted to make the determination. Either or both sn and cn can be -1 indicating that the constraint should be ignored (no limit).

mbssize
    The mbssize function returns the number of bytes in a complete character sequence. Note this will not be the same as strlen(3) if there is an incomplete multibyte sequence at the end of the string.

mbsnsize
    The mbsnsize function returns the number of bytes in a complete character sequence. No more than sn bytes of src will be examined and no more than cn characters will be converted. Note this will not be the same as strnlen(3) if the sn or cn constraints end on an incomplete multibyte sequence or if the ' ' is encountered in the middle of an incomplete multibyte sequence.

mbsdup
    The mbsdup function will return a copy of the multibyte string at src. An incomplete multibyte sequence at the end of the string will not be copied. Only a complete valid multibyte string will be returned.

mbsndup
    The mbsndup function will return a copy of the multibyte string at src. No more than sn bytes of src will be examined and no more than cn characters will be converted. If the sn or cn constraints end on an incomplete multibyte sequence or if the ' ' is encountered in the middle of an incomplete multibyte sequence those extra bytes will not be copied. Only a complete multibyte string will be returned.

mbsoff
    The mbsoff function will return the substring of src that starts at off. The off parameter is measured in characters where characters are display positions and control character however it is not common that strings contain control characters (should not from an ADT perspective).

mbsnoff
    The mbsnoff function will return the substring of src that starts at off number of characters. No more than sn number of bytes of src will be examined. If the sn parameter is exhausted, a pointer to the next valid multibyte character sequence following the sn position is returned.

mbschr
    The mbschr function will return a substring pointing to the first occurrence of the character wc in the mutibyte string represented by src.

mbsnchr
    The mbschr function will return a substring pointing to the first occurrence of the character wc in the mutibyte string represented by src. No more than sn bytes of src will be examined and no more than cn characters will be converted. Either or both sn and cn may be -1 indicating the constraint should be ignored (no limit).

mbswidth
    The mbswidth function will return the number of display positions a multibyte sequence will occupy. No more than sn bytes of src will be examined and no more than wn display positions will be considered. Control characters are considered to occupy 1 display position (so there should be no control characters in the src string).

mbssub
    The mbssub function will return a substring of the multibyte sequence src that is no larger in size than sn and will occupy no more than wn display positions should it be printed on a mutilbyte (UTF-8) capable display.