Function rb_sys::bindings::ruby_xrealloc2

source · 
pub unsafe extern "C" fn ruby_xrealloc2(
    ptr: *mut c_void,
    newelems: size_t,
    newsiz: size_t
) -> *mut c_void
Expand description

Identical to ruby_xrealloc(), except it resizes the given storage instance to newelems * newsiz bytes. This is needed because the multiplication could integer overflow. On such situations Ruby does not try to touch the contents of argument pointer at all but raises Ruby level exceptions instead. If there is no integer overflow the behaviour is exactly the same as ruby_xrealloc(ptr,nelems*elemsiz).

This is roughly the same as reallocarray() function that OpenBSD etc. provides, but also interacts with our GC.

  • @param in ptr A valid pointer to a storage instance that was previously returned from either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().

  • @param in newelems Requested new number of elements.

  • @param in newsiz Requested new size of each element.

  • @exception rb_eNoMemError No space left for allocation.

  • @exception rb_eArgError newelems * newsiz would overflow.

  • @retval ptr In case the function returns the passed pointer as-is, the storage instance that the pointer holds is either grown or shrunken to have at least newelems * newsiz bytes.

  • @retval otherwise A valid pointer to a newly allocated storage instance which has at least newelems * newsiz bytes width, and holds previous contents of ptr. In this case ptr is invalidated as if it was passed to ruby_xfree().

Note

It doesn’t return NULL.

Warning

Unlike some realloc() implementations, passing zero to either newelems or elemsiz are not the same as calling ruby_xfree(), because this function never returns NULL. Something meaningful still returns then.

Warning

It is a failure not to check the return value. Do not assume anything on it. It could be either identical to, or distinct form the passed argument.

Warning

Do not assume anything on the alignment of the return value. There is no guarantee that it inherits the passed argument’s one.

Warning

The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Generated by rb-sys for Ruby 3.0.0