#include <stdlib.h>

void *malloc (

   size_t nchars

);

stand-alone

stack: 48 bytes

malloc allocates space for an object whose size is specified in octets (eight-bit bytes) by nchars and returns a pointer to the start of the allocated space. The space is aligned on an 8-byte boundary.

If the space cannot be allocated, malloc returns a null pointer.

It is a common mistake to call malloc and not check that it has succeeded in allocating the required memory.

The amount of storage available to malloc (the heap) is set by the configurer in the properties of the enclosing task.

Space allocated by malloc is not initialized by the run-time library and may contain arbitrary values. You should consider using calloc if a zeroed area of storage is required.

Note that calloc has two arguments compared to malloc's one. Thus, a call to malloc(n) must be rewritten as calloc(n,1).

If a request for a zero-length block is made, a pointer to a short—but real—block is returned by malloc. Note, however, that programs intended to be portable to other implementations of C should not make the assumption that this is so; some other implementations return a null pointer instead.

See also: calloc, memalign, and realloc.

#include <stdlib.h>

int mblen (

   const char *s,

   size_t      n

);

stand-alone

If s is a null pointer, mblen returns 0, indicating that, for the current version of Diamond, multibyte character encodings are never state dependent. Otherwise, it returns the width in octets (eight-bit bytes) of the multibyte character pointed to by s. In the current version, this is 1, unless s is pointing at a null character, in which case it is 0.

#include <stdlib.h>

size_t mbstowcs (

   wchar_t    *pwcs,

   const char *s,

   size_t      n

);

stand-alone

The multibyte string pointed to by s is converted to a wide character string and stored in the array pointed to by pwcs. Conversion stops when a null character has been converted, or when n elements have been converted. mbstowcs returns the number of elements converted, excluding the terminating zero, if any.

Note that, in the present version of Diamond, multibyte characters and wide characters are both one octet (eight-bit byte) in length and there is no state-dependent encoding, so this function is equivalent to a string copy. All possible element values are valid, so no error return can happen.

#include <stdlib.h>

int mbtowc (

   wchar_t    *pwc,

   const char *s,

   size_t      n

);

stand-alone

If s is a null pointer, mbtowc returns 0, indicating that, for the current version of Diamond, multibyte character encodings are never state dependent. Otherwise, it returns the width in octets (eight-bit bytes) of the multibyte character pointed to by s. In the current version, this is 1, unless s is pointing at a null character, in which case it is 0. In addition, the character pointed to by s is converted to a wide character and stored in the location pointed to by pwc.

In the current version, as both wide and multibyte characters are always 1 octet in length, this is equivalent to copying the character. The argument n specifies the maximum number of octets to be scanned.

#include <stdlib.h>

void *memalign (

   size_t alignment,

   size_t nchars

);

stand-alone

memalign allocates space for an object whose size is specified in octets (eight-bit bytes) in nchars and returns a pointer to the start of the allocated space. A constraint on the position of the space is specified as a power of two in alignment; the address returned from memalign is a multiple of alignment.  The result is undefined if alignment is not a power of two. As an example, if alignment is 16, the space returned is aligned on a 16-byte boundary. Note that all memory returned by heap functions is aligned on at least an eight-byte boundary.

If the space cannot be allocated, memalign returns a null pointer.

It is a common mistake to call memalign and not check that it has succeeded in allocating the required memory.

Space allocated by memalign is not initialized by the run-time library and may contain arbitrary values. You should use the function memset to clear the storage returned by memalign if you need a zeroed area of storage.

If a request for a zero-length block is made, a pointer to a short—but real—block is returned by memalign. Note, however, that programs intended to be portable to other implementations of C should not make the assumption that this is so; some other implementations return a null pointer instead.

#include <string.h>

void *memchr (

   const void *s,

   int         c,

   size_t      n);

stand-alone

The memchr function searches for the value c (converted to an unsigned char) in the memory block starting at s and returns a pointer to the first occurrence of c.  If the character is not located, a null pointer is returned. The memory block is n octets (eight-bit bytes) in length.

#include <string.h>

int memcmp (

   const void *s1,

   const void *s2,

   size_t      n

);

stand-alone

The memcmp function compares the first n octets (eight-bit bytes) of the two objects pointed to by s1 and s2. The result returned is less than, greater than, or equal to zero according to whether the object pointed to by s1 is less than, greater than, or equal to the object pointed to by s2.

The comparison operation is performed one character at a time on the complete object; a result is returned when the first difference between the objects is located.

When comparing complex objects, particularly when these were allocated using malloc from the heap, remember to take account of the following:

#include <string.h>

void *memcpy (

   void       *s1,

   const void *s2,

   size_t      n

);

stand-alone

memcpy copies n octets (eight-bit bytes) from the object pointed to by s2 into the object pointed to by s1. memcpy returns the value of s1.

If the two objects pointed to by s1 and s2 overlap, the behaviour of memcpy is undefined. To copy from one object to another which overlaps it, or when it is not known whether the two objects overlap, you can use the memmove function instead of memcpy.

#include <string.h>

void *memmove (

   void       *s1,

   const void *s2,

   size_t      n);

stand-alone

memmove copies n octets (eight-bit bytes) from the object pointed to by s2 into the object pointed to by s1. memmove returns the value of s1.

If the two objects pointed to by s1 and s2 overlap, memmove still performs the copy correctly. This is in contrast to memcpy, for which the behaviour would be undefined. If it is known that the objects pointed to by s1 and s2 definitely do not overlap, you can use the faster memcpy function instead of memmove.

#include <string.h>

void *memset (

   void  *ptr,

   int    cval,

   size_t num

);

stand-alone

The memset function copies the value of cval (converted to an unsigned char) into each of the first num octets (eight-bit bytes) of the object pointed to by ptr. It returns the value of ptr.

#include <math.h>

double modf (

   double  value,

   double *iptr

);

stand-alone

modf splits value into its integral and fractional parts. The function returns the signed fractional part and the integral part is stored in the double variable pointed to by iptr.