MPI_BUFFER_DETACH(3)				     Open MPI				      MPI_BUFFER_DETACH(3)

MPI_Buffer_detach — Removes an existing buffer (for use in in MPI_Bsend <#mpi-bsend>, etc.)

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_Buffer_detach(void *buf, int *size)

   Fortran Syntax
	  USE MPI
	  ! or the older form: INCLUDE 'mpif.h'

	  MPI_BUFFER_DETACH(BUF, SIZE, IERROR)
	      <type>  BUF(*)
	      INTEGER SIZE, IERROR

   Fortran 2008 Syntax
	  USE mpi_f08

	  MPI_Buffer_detach(buffer_addr, size, ierror)
	      USE, INTRINSIC :: ISO_C_BINDING, ONLY
	      TYPE(C_PTR), INTENT(OUT) :: buffer_addr
	      INTEGER, INTENT(OUT) :: size
	      INTEGER, OPTIONAL, INTENT(OUT) :: ierror

OUTPUT PARAMETERS
       • buf : Initial buffer address (choice).

       • size : Buffer size, in bytes (integer).

       • ierror : Fortran only: Error status (integer).

DESCRIPTION
       Detach  the buffer currently associated with MPI. The call returns the address and the size of the detached
       buffer. This operation will block until all messages currently in the buffer have  been	transmitted.  Upon
       return of this function, the user may reuse or deallocate the space taken by the buffer.

       Example: Calls to attach and detach buffers.

	  #define BUFFSIZE 10000

	  int size char *buff;
	  MPI_Buffer_attach( malloc(BUFFSIZE), BUFFSIZE);

	  // a buffer of 10000 bytes can now be used by MPI_Bsend

	  MPI_Buffer_detach( &buff, &size); // Buffer size reduced to zero
	  MPI_Buffer_attach( buff, size); // Buffer of 10000 bytes available again

NOTES
       The  reason  that  MPI_Buffer_detach  returns the address and size of the buffer being detached is to allow
       nested libraries to replace and restore the buffer. For example, consider

	  int size, mysize, idummy;
	  void *ptr, *myptr, *dummy;
	  MPI_Buffer_detach( &ptr, &size );
	  MPI_Buffer_attach( myptr, mysize );

	  /* ... library code ... */

	  MPI_Buffer_detach( &dummy, &idummy );
	  MPI_Buffer_attach( ptr, size );

       This is much like the action of the UNIX signal routine and has the same strengths (it’s simple) and  weak‐
       nesses (it only works for nested usages).

       For  Fortran: The Fortran binding for this routine is different. Because Fortran does not have pointers, it
       is impossible to provide a way to use the output of this routine to exchange buffers. In	 this  case,  only
       the size field is set.

       For  C:	Even  though the buf argument is declared as void, it is really the address of a void pointer. See
       Rationale, below, for more details.

       Even though the C functions MPI_Buffer_attach <#mpi-buffer-attach> and MPI_Buffer_detach both have a  first
       argument	 of  type  void*,  these  arguments  are  used	differently:  A pointer to the buffer is passed to
       MPI_Buffer_attach <#mpi-buffer-attach>; the address of the pointer is passed to MPI_Buffer_detach, so  that
       this call can return the pointer value.

ERRORS
       Almost  all MPI routines return an error value; C routines as the return result of the function and Fortran
       routines in the last argument.

       Before the error value is returned, the current MPI error handler associated with the communication  object
       (e.g.,  communicator, window, file) is called.  If no communication object is associated with the MPI call,
       then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler.  When
       MPI_COMM_SELF  is  not  initialized  (i.e., before MPI_Init <#mpi-init>/MPI_Init_thread <#mpi-init-thread>,
       after MPI_Finalize <#mpi-finalize>, or when using the Sessions Model  exclusively)  the	error  raises  the
       initial	error  handler.	 The  initial  error  handler can be changed by calling MPI_Comm_set_errhandler <#
       mpi-comm-set-errhandler> on MPI_COMM_SELF when using the World model,  or  the  mpi_initial_errhandler  CLI
       argument	  to   mpiexec	 or   info  key	 to  MPI_Comm_spawn  <#mpi-comm-spawn>/MPI_Comm_spawn_multiple	<#
       mpi-comm-spawn-multiple>.  If no other appropriate error handler has been set, then  the	 MPI_ERRORS_RETURN
       error  handler  is  called  for	MPI I/O functions and the MPI_ERRORS_ABORT error handler is called for all
       other MPI functions.

       Open MPI includes three predefined error handlers that can be used:

       • MPI_ERRORS_ARE_FATAL Causes the program to abort all connected MPI processes.

       • MPI_ERRORS_ABORT An error handler that can be invoked on a communicator, window, file, or  session.  When
	 called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If called
	 on  a window or file, acts as if MPI_Abort <#mpi-abort> was called on a communicator containing the group
	 of processes in the corresponding window or file. If called on a session, aborts only the local process.

       • MPI_ERRORS_RETURN Returns an error code to the application.

       MPI applications can also implement their own error handlers by calling:

       • MPI_Comm_create_errhandler	<#mpi-comm-create-errhandler>	  then	   MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	 <#mpi-file-create-errhandler>	   then	    MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       See also:

	  • MPI_Buffer_attach <#mpi-buffer-attach>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026				      MPI_BUFFER_DETACH(3)
