The stream descriptor

A stream descriptor holds information about the stream that all stream I/O functions need to access.

The mi_stream_init() function accepts as its stream-descriptor argument either a NULL-valued pointer or a pointer to a valid, allocated MI_STREAM structure.

When you pass the mi_stream_init() function a NULL-valued pointer for its stream-descriptor argument, the function allocates a new stream descriptor in the current memory duration. If your application requires a specific memory duration for the stream descriptor, your stream-open function can perform one of the following tasks:
  • Before the call to mi_stream_init(), change the current memory duration to what is required.

    The mi_switch_mem_duration() function changes the current memory duration. Its return value is the previous current duration so that you can return the duration to its original value. For more information, see Change the memory duration.

    In this case, pass a NULL-valued pointer as the stream descriptor to mi_stream_init() so that mi_stream_init() allocates a new stream descriptor in the new current memory duration.

  • Allocate a stream descriptor in the required memory duration.

    In this case, pass a pointer to the allocated stream descriptor as the stream descriptor for mi_stream_init() so that this function does not allocate a new stream descriptor. The mi_stream_close() function does not automatically free a stream descriptor that your stream-open function allocates. Your code must handle the deallocation.