| Previous | Contents | Index |
Converts a multibyte character to its wide-character representation.
#include <wchar.h>size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
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.
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.
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).
Converts a sequence of multibyte characters into a sequence of corresponding wide-character codes.
#include <stdlib.h>size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);
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.
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.
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.
Converts a multibyte character to its wide-character equivalent.
#include <stdlib.h>int mbtowc (wchar_t *pwc, const char *s, size_t n);
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.
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.
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.
Determines whether an mbstate_t object decribes an initial conversion state.
#include <wchar.h>int mbsinit (const mbstate_t *ps);
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.
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.
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.
Converts a sequence of multibyte characters to a sequence of corresponding wide-character codes.
#include <wchar.h>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.10 for more information on using pointer-size-specific functions.size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len, mbstate_t *ps);
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.
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.
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.
Copies characters sequentially between strings in memory areas.
#include <string.h>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.10 for more information on using pointer-size-specific functions.void *memccpy (void *dest, void *source, int c, size_t n);
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.
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.
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.
Locates the first occurrence of the specified byte within the initial size bytes of a given object.
#include <string.h>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.10 for more information on using pointer-size-specific functions.void *memchr (const void *s1, int c, size_t size);
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.
Unlike strchr , the memchr function does not stop when it encounters a null character.
pointer A pointer to the first occurrence of the byte. NULL Indicates that the specified byte does not occur in the object.
Compares two objects, byte by byte. The compare operation starts with the first byte in each object.
#include <string.h>int memcmp (const void *s1, const void *s2, size_t size);
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.
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.
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.
Copies a specified number of bytes from one object to another.
#include <string.h>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.10 for more information on using pointer-size-specific functions.void *memcpy (void *dest, const void *source, size_t size);
dest
A pointer to the destination object.source
A pointer to the source object.size
The length of the object to be copied.
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.
x The value of dest.
Copies a specified number of bytes from one object to another.
#include <string.h>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.10 for more information on using pointer-size-specific functions.void *memmove (void *dest, const void *source, size_t size);
dest
A pointer to the destination object.source
A pointer to the source object.size
The length of the object to be copied.
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.
x The value of dest.
#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
Sets a specified number of bytes in a given object to a given value.
#include <string.h>Function Variants The memset function has variants named _memset32 and _memset64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.void *memset (void *s, int value, size_t size);
s
An array pointer.value
The value to be placed in s.size
The number of bytes to be placed in s.
The memset function copies value (converted to an unsigned char ) into each of the first size characters of the object pointed to by s.This function returns s. It does not check for the overflow of the receiving memory area pointed to by s.
x The value of s.
Creates a directory.
#include <stat.h>int mkdir (const char *dir_spec, mode_t mode); (ISO POSIX-1)
int mkdir (const char *dir_spec, mode_t mode, ...); (HP C EXTENSION)
dir_spec
A valid OpenVMS or UNIX style directory specification that may contain a device name. For example:
DBA0:[BAY.WINDOWS] /* OpenVMS */ /dba0/bay/windows /* UNIX style */This specification cannot contain a node name, file name, file extension, file version, or a wildcard character. The same restriction applies to the UNIX style directory specifications. For more information about the restrictions on UNIX style specifications, see Chapter 1.
mode
A file protection. See the chmod function in this section for information about the specific file protections.The file protection of the new directory is derived from the mode argument, the process's file protection mask (see the umask function), and the parent-directory default protections.
In a manner consistent with the OpenVMS behavior for creating directories, mkdir never applies delete access to the directory. An application that needs to set delete access should use an explicit call to chmod to set write permission.
See the Description section of this function for more information about how the file protection is set for the newly created directory.
...
Represents the following optional arguments. These arguments have fixed position in the argument list, and cannot be arbitrarily placed.unsigned int uic
The user identification code (UIC) that identifies the owner of the created directory. If this argument is 0, the HP C RTL gives the created directory the UIC of the parent directory. If this argument is not specified, the HP C RTL gives the created directory your UIC. This optional argument is specific to the HP C RTL and is not portable.
unsigned short max_versions
The maximum number of file versions to be retained in the created directory. The system automatically purges the directory keeping, at most, max_versions number of every file.
If this argument is 0, the HP C RTL does not place a limit on the maximum number of file versions.
If this argument is not specified, the HP C RTL gives the created directory the default version limit of the parent directory.
This optional argument is specific to the HP C RTL and is not portable.
unsigned short r_v_number
The volume (device) on which to place the created directory if the device is part of a volume set. If this argument is not specified, the HP C RTL arbitrarily places the created directory within the volume set. This optional argument is specific to the HP C RTL and is not portable.
If dir_spec specifies a path that includes directories, which do not exist, intermediate directories are also created. This differs from the behavior of the UNIX system where these intermediate directories must exist and will not be created.If you do not specify any optional arguments, the HP C RTL gives the directory your UIC and the default version limit of the parent directory, and arbitrarily places the directory within the volume set. You cannot get the default behavior for the uic or max_versions arguments if you specify any arguments after them.
Note
The way to create files with OpenVMS RMS default protections using the UNIX system-call functions umask , mkdir , creat , and open is to call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.
In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.The file protection supplied by the mode argument is modified by the process's file protection mask in such a way that the file protection for the new directory is set to the bitwise AND of the mode argument and the complement of the file protection mask.
Default file protections are supplied to the new directory from the parent-directory such that if a protection value bit in the new directory is zero, then the value of this bit is inherited from the parent directory. However, bits in the parent directory's file protection that indicate delete access do not cause corresponding bits to be set in the new directory's file protection.
0 Indicates success. - 1 Indicates failure.
| #1 |
|---|
umask (0002); /* turn world write access off */
mkdir ("sys$disk:[.parentdir.childdir]", 0222); /* turn write
access on */
Parent directory file protection: System:RWD, Owner:RWD, Group:R,
World:R
|
The file protection derived from the combination of the mode argument and the file protection mask set by umask is (0222) & ~(0002), which is 0220. When the parent directory defaults are applied to this protection, the protection for the new directory becomes:
Previous Next Contents Index