NAME

rpc_ss_allocate - Allocates memory within the RPC stub memory management scheme

Used by server or possibly by client applications. 

SYNOPSIS

#include <dce/rpc.h>
idl_void_p_t rpc_ss_allocate (unsigned long size);

PARAMETERS

Input

sizeSpecifies, in bytes, the size of memory to be allocated. 

Note: In ANSI standard C environments, idl_void_p_t is defined as void ∗ and in other environments is defined as char ∗. 

DESCRIPTION

Usually, the rpc_ss_allocate routine is used in the manager code which is called from a server stub. Memory allocated by the rpc_ss_allocate routine is released by the server stub after marshalling any output parameters at the end of the remote call in which the memory was allocated.  If you want to release memory allocated by rpc_ss_allocate before returning from the manager code use rpc_ss_free. 

You can also use the rpc_ss_free routine in manager code to release memory pointed to by a full pointer (ptr) in an input parameter. 

When the server uses the rpc_ss_allocate routine, the server stub creates the environment the rpc_ss_allocate routine needs.  If the parameters of the operation include any pointers other than those used for passing parameters by reference, the environment is set up automatically. 

If you need to use the rpc_ss_allocate routine in a manager code routine that does not have a pointer in any of its parameters, use an ACF and apply the enable_allocate attribute to the relevant operation.  This causes the generated server stub to set up the necessary environment. 

Note: Memory allocated by allocators other than rpc_ss_allocate is not released when the operation on the server side completes execution. 

If you want to use the rpc_ss_allocate routine outside the code called from a server stub, you must create an environment for it by first calling the rpc_ss_enable_allocate routine. 

See the Rules for Using Memory Management Routines in the Pointers section of the Interface Definition Language chapter in the NCS 2.0 Programmer’s Guide. 

RETURN VALUES

A pointer to the allocated memory. 

An exception, rpc_x_no_memory, when no memory is available for allocation. 

RELATED INFORMATION

Functions: rpc_ss_free(3), rpc_ss_enable_allocate(3), rpc_ss_disable_allocate(3), rpc_ss_get_thread_handle(3), rpc_ss_set_thread_handle(3)