[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


mblen

Determines the number of bytes comprising a multibyte character.

Format

#include <stdlib.h>

int mblen (const char *s, size_t n);


Arguments

s

A pointer to the multibyte character.

n

The maximum number of bytes that comprise the multibyte character.

Description

If the character is n bytes or less, the mblen function returns the number of bytes comprising the multibyte character pointed to by s. If the character is greater than n bytes, the function returns - 1 to indicate an error.

This function is affected by the LC_CTYPE category of the program's current locale.


Return Values

x The number of bytes that comprise the multibyte character, if the next n or fewer bytes form a valid character.
0 If s is NULL or a pointer to the NULL character.
- 1 Indicates an error. The function sets errno to EILSEQ -- Invalid character detected.

mbrlen

Determines the number of bytes comprising a multibyte character.

Format

#include <wchar.h>

size_t mbrlen (const char *s, size_t n, mbstate_t *ps);


Arguments

s

A pointer to a multibyte character.

n

The maximum number of bytes that comprise the multibyte character.

ps

A pointer to the mbstate_t object. If a NULL pointer is specified, the function uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

Description

The mbrlen function is equivalent to the call:


    mbrtowc(NULL, s, n, ps != NULL ? ps : &internal) 

Where internal is the mbstate_t object for the mbrlen function.

If the multibyte character pointed to by s is of n bytes or less, the function returns the number of bytes comprising the character (including any shift sequences).

If either an encoding error occurs or the next n bytes contribute to an incomplete but potentially valid multibyte character, the function returns - 1 or - 2, respectively.

See also mbrtowc .


Return Values

x The number of bytes comprising the multibyte character.
0 Indicates that s is a NULL pointer or a pointer to a null byte.
- 1 Indicates an encoding error, in which case the next n or fewer bytes do not contribute to a complete and valid multibyte character. errno is set to EILSEQ; the conversion state is undefined.
- 2 Indicates an incomplete but potentially valid multibyte character (all n bytes have been processed).

mbrtowc

Converts a multibyte character to its wide-character representation.

Format

#include <wchar.h>

size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);


Arguments

pwc

A pointer to the resulting wide-character code.

s

A pointer to a multibyte character.

n

The maximum number of bytes that comprise the multibyte character.

ps

A pointer to the mbstate_t object. If a NULL pointer is specified, the function uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

Description

If s is a NULL pointer, mbrtowc is equivalent to the call:


    mbrtowc(NULL, "", 1, ps) 

In this case, the values of pwc and n are ignored.

If s is not a NULL pointer, mbrtowc inspects at most n bytes beginning with the byte pointed to by s to determine the number of bytes needed to complete the next multibyte character (including any shift sequences).

If the function determines that the next multibyte character is completed, it determines the value of the corresponding wide character and then, if pwc is not a NULL pointer, stores that value in the object pointed to by pwc. If the corresponding wide character is the null wide character, the resulting state described is the initial conversion state.

If mbrtowc is called as a counting function, which means that pwc is a NULL pointer and s is neither a NULL pointer nor a pointer to a null byte, the value of the internal mbstate_t object will remain unchanged.


Return Values

x The number of bytes comprising the multibyte character.
0 The next n or fewer bytes complete the multibyte character that corresponds to the null wide character (which is the value stored if pwc is not a NULL pointer). The wide-character code corresponding to a null byte is zero.
- 1 Indicates an encoding error. The next n or fewer bytes do not contribute to a complete and valid multibyte character. errno is set to EILSEQ . The conversion state is undefined.
- 2 Indicates an incomplete but potentially valid multibyte character (all n bytes have been processed).

mbstowcs

Converts a sequence of multibyte characters into a sequence of corresponding wide-character codes.

Format

#include <stdlib.h>

size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);


Arguments

pwcs

A pointer to the array containing the resulting sequence of wide-character codes.

s

A pointer to the array of multibyte characters.

n

The maximum number of wide-character codes that can be stored in the array pointed to by pwcs.

Description

The mbstowcs function converts a sequence of multibyte characters from the array pointed to by s to a sequence of wide-character codes that are stored into the array pointed to by pwcs, up to a maximum of n codes.

This function is affected by the LC_CTYPE category of the program's current locale. If copying takes place between objects that overlap, the behavior is undefined.


Return Values

x The number of array elements modified or required, not included any terminating zero code. The array will not be zero-terminated if the value returned is n. If pwcs is the NULL pointer, mbstowcs returns the number of elements required for the wide-character array.
( size_t ) - 1 Indicates that an error occurred. The function sets errno to EILSEQ - Invalid character detected.

mbtowc

Converts a multibyte character to its wide-character equivalent.

Format

#include <stdlib.h>

int mbtowc (wchar_t *pwc, const char *s, size_t n);


Arguments

pwc

A pointer to the resulting wide-character code.

s

A pointer to the multibyte character.

n

The maximum number of bytes that comprise the next multibyte character.

Description

If the character is n or fewer bytes, the mbtowc function converts the multibyte character pointed to by s to its wide-character equivalent. If the character is invalid or greater than n bytes, the function returns - 1 to indicate an error.

If pwc is a NULL pointer and s is not a null pointer, the function determines the number of bytes that constitute the multibyte character pointed to by s (regardless of the value of n).

This function is affected by the LC_CTYPE category of the program's current locale.


Return Values

x The number of bytes that comprise the valid character pointed to by s.
0 If s is either a NULL pointer or a pointer to the null byte.
- 1 Indicates an error. The function sets errno to EILSEQ -- Invalid character detected.

mbsinit

Determines whether an mbstate_t object decribes an initial conversion state.

Format

#include <wchar.h>

int mbsinit (const mbstate_t *ps);


Argument

ps

A pointer to the mbstate_t object. mbstate_t is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

Description

If ps is not a NULL pointer, the mbsinit function determines whether the mbstate_t object pointed to by ps describes an initial conversion state. A zero mbstate_t object always describes an initial conversion state.

Return Values

nonzero The ps argument is a NULL pointer, or the mbstate_t object pointed to by ps describes an initial conversion state.
0 The mbstate_t object pointed to by ps does not describe an initial conversion state.

mbsrtowcs

Converts a sequence of multibyte characters to a sequence of corresponding wide-character codes.

Format

#include <wchar.h>

size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len, mbstate_t *ps);

Function Variants The mbsrtowcs function has variants named _mbsrtowcs32 and _mbsrtowcs64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

dst

A pointer to the destination array containing the resulting sequence of wide-character codes.

src

An address of the pointer to an array containing a sequence of multibyte characters to be converted.

len

The maximum number of wide character codes that can be stored in the array pointed to by dst.

ps

A pointer to the mbstate_t object. If a NULL pointer is specified, the function uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

Description

The mbsrtowcs function converts a sequence of multibyte characters, beginning in the conversion state described by the object pointed to by ps, from the array indirectly pointed to by src, into a sequence of corresponding wide characters.

If dst is not a NULL pointer, the converted characters are stored into the array pointed to by dst. Conversion continues up to and including a terminating null character, which is also stored.

Conversion stops earlier for one of the following reasons:

  • A sequence of bytes is encountered that does not form a valid multibyte character.
  • If dst is not a NULL pointer, when len codes have been stored into the array pointed to by dst.

If dst is not a NULL pointer, the pointer object pointed to by src is assigned either a NULL pointer (if the conversion stopped because of reaching a terminating null wide character), or the address just beyond the last multibyte character converted (if any). If conversion stopped because of reaching a terminating null wide character, the resulting state described is the initial conversion state.


Return Values

n The number of multibyte characters successfully converted, sequence, not including the terminating null (if any).
- 1 Indicates an error. A sequence of bytes that do not form valid multibyte character was encountered. errno is set to EILSEQ; the conversion state is undefined.

memccpy

Copies characters sequentially between strings in memory areas.

Format

#include <string.h>

void *memccpy (void *dest, void *source, int c, size_t n);

Function Variants The memccpy function has variants named _memccpy32 and _memccpy64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

dest

A pointer to the location of a destination string.

source

A pointer to the location of a source string.

c

A character that you want to search for.

n

The number of charcter you want to copy.

Description

The memccpy function operates on strings in memory areas. A memory area is a group of contiguous characters bound by a count and not terminated by a null character. The function does not check for overflow of the receiving memory area. The memccpy function is defined in the <string.h> header file.

The memccpy function sequentially copies characters from the location pointed to by source into the location pointed to by dest until one of the following occurs:

  • The character specified by c (converted to an unsigned char ) is copied.
  • The number of characters specified by n is copied.

Return Values

x A pointer to the character following the character specified by c in the string pointed to by dest.
NULL Indicates an error. The character c is not found after scanning n characters in the string.

memchr

Locates the first occurrence of the specified byte within the initial size bytes of a given object.

Format

#include <string.h>

void *memchr (const void *s1, int c, size_t size);

Function Variants The memchr function has variants named _memchr32 and _memchr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

s1

A pointer to the object to be searched.

c

The byte value to be located.

size

The length of the object to be searched.

If size is zero, memchr returns NULL.


Description

Unlike strchr , the memchr function does not stop when it encounters a null character.

Return Values

pointer A pointer to the first occurrence of the byte.
NULL Indicates that the specified byte does not occur in the object.

memcmp

Compares two objects, byte by byte. The compare operation starts with the first byte in each object.

Format

#include <string.h>

int memcmp (const void *s1, const void *s2, size_t size);


Arguments

s1

A pointer to the first object.

s2

A pointer to the second object.

size

The length of the objects to be compared.

If size is zero, the two objects are considered equal.


Description

The memcmp function uses native byte comparison. The sign of the value returned is determined by the sign of the difference between the values of the first pair of unlike bytes in the objects being compared. Unlike the strcmp function, the memcmp function does not stop when a null character is encountered.

Return Value

x An integer less than, equal to, or greater than 0, depending on whether the lexical value of the first object is less than, equal to, or greater than that of the second object.

memcpy

Copies a specified number of bytes from one object to another.

Format

#include <string.h>

void *memcpy (void *dest, const void *source, size_t size);

Function Variants The memcpy function has variants named _memcpy32 and _memcpy64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

dest

A pointer to the destination object.

source

A pointer to the source object.

size

The length of the object to be copied.

Description

The memcpy function copies size bytes from the object pointed to by source to the object pointed to by dest; it does not check for the overflow of the receiving memory area (dest). Unlike the strcpy function, the memcpy function does not stop when a null character is encountered.

Return Value

x The value of dest.

memmove

Copies a specified number of bytes from one object to another.

Format

#include <string.h>

void *memmove (void *dest, const void *source, size_t size);

Function Variants The memmove function has variants named _memmove32 and _memmove64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

dest

A pointer to the destination object.

source

A pointer to the source object.

size

The length of the object to be copied.

Description

In HP C for OpenVMS Systems, memmove and memcpy perform the same function. Programs that require portability should use memmove if the area pointed at by dest could overlap the area pointed at by source.

Return Value

x The value of dest.

Example


#include <string.h> 
#include <stdio.h> 
                      
main() 
{ 
   char pdest[14] = "hello   there"; 
   char *psource = "you are there"; 
 
   memmove(pdest, psource, 7); 
   printf("%s\n", pdest); 
} 

This example produces the following output:


you are there 


Previous Next Contents Index