---
name: "pvm_mkbuf"
section: "3"
platform: "linux"
package: "pvm-dev"
version: "3.4.2-8"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/pvm_mkbuf"
---

# pvm\_mkbuf(3)

Creates a new message buffer.

## NAME

pvm\_mkbuf - Creates a new message buffer.

## SYNOPSIS

```
C	int bufid = pvm_mkbuf( int encoding )
Fortran	call pvmfmkbuf( encoding, bufid )
```

## PARAMETERS

- encoding

  **Integer specifying the buffer's encoding scheme.**

  ```
  Options in C are:
  	Encoding value		MEANING
  	PvmDataDefault	0	XDR
  	PvmDataRaw	1	no encoding
  	PvmDataInPlace	2	data left in place
  Option names in Fortran are:
  	Encoding value		MEANING
  	PVMDEFAULT	0	XDR
  	PVMRAW	1	no encoding
  	PVMINPLACE	2	data left in place
  ```

- bufid

  **Integer message buffer identifier returned.** **Values less than zero indicate an error.**

## DESCRIPTION

**The routine** *pvm\_mkbuf* **creates a new message buffer and** **sets its encoding status to** *encoding.* **If pvm\_mkbuf is successful,** *bufid* **will be the identifier** **for the new buffer, which can be used as a send buffer.** **If some error occurs then** *bufid* **will be \< 0.**

**With the default setting** **XDR encoding is used when packing the message** **because PVM can not know** **if the user is going to add a heterogeneous machine** **before this message is sent.** **The other options to encoding allow the user to take advantage** **of knowledge about his virtual machine even when it is** **heterogeneous. For example, if the user knows that the** **next message will only be sent to a machine that understands** **the native format, then he can use** *PvmDataRaw* encoding and save on encoding costs.

PvmDataInPlace encoding specifies that data be left in place during packing. The message buffer only contains the sizes and pointers to the items to be sent. When pvm\_send is called the items are copied directly out of the user's memory. This option decreases the number of times a message is copied at the expense of requiring the user to not modify the items between the time they are packed and the time they are sent.

pvm\_mkbuf is required if the user wishes to manage multiple message buffers and should be used in conjunction with pvm\_freebuf. pvm\_freebuf should be called for a send buffer after a message has been sent and is no longer needed.

Receive buffers are created automatically by the pvm\_recv and pvm\_nrecv routines and do not have to be freed unless they have been explicitly saved with pvm\_setrbuf.

Typically multiple send and receive buffers are not needed and the user can simply use the pvm\_initsend routine to reset the default send buffer.

There are several cases where multiple buffers are useful. One example where multiple message buffers are needed involves libraries or graphical interfaces that use PVM and interact with a running PVM application but do not want to interfere with the application's own communication.

When multiple buffers are used they generally are made and freed for each message that is packed.

## RESTRICTIONS

PvmDataInPlace allows only dense (stride = 1) data in version 3.3. It cannot be used on shared memory (\*MP) architectures; a PvmNotImpl error will occur at send time.

## EXAMPLES

```
C:
	bufid = pvm_mkbuf( PvmDataRaw );
	/* send message */
	info = pvm_freebuf( bufid );

Fortran:
	CALL PVMFMKBUF(PVMDEFAULT, MBUF)
*	SEND MESSAGE HERE
	CALL PVMFFREEBUF( MBUF, INFO )
```

## ERRORS

These error conditions can be returned by *pvm\_mkbuf*

```
	PvmBadParam	giving an invalid encoding value.
	PvmNoMem	Malloc has failed. There is not enough memory
		to create the buffer
```

## SEE ALSO

pvm\_initsend(3PVM), pvm\_freebuf(3PVM)