---
name: "pvm_addmhf"
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_addmhf"
---

# pvm\_addmhf(3)

Install message-handler functions. pvm\_delmhf - Remove message-handler functions.

## NAME

pvm\_addmhf - Install message-handler functions.\
 pvm\_delmhf - Remove message-handler functions.

## SYNOPSIS

```
C	int mhid = pvm_addmhf( int src, int tag, int ctx, int (*func)(int mid) )
	int info = pvm_delmhf( int mhid )
Fortran	Not available
```

## PARAMETERS

- src

  **The tid of the sender.**

- tag

  **The tag sent with the message.**

- ctx

  **The context sent with the message.**

- func

  **Function to call when message received.**

- mhid

  **Message handler id.**

- info

  **Result code.**

- mid

  **Message buffer identifier for new active receive buffer.**

## DESCRIPTION

**pvm\_addmhf** **specifies a function that will be called whenever** **libpvm copies in a message whose header fields of**  *src*, *tag*, and *ctx* match those provided to pvm\_addmhf().

The src and tag fields may be left unspecified (wildcard) by setting to -1.

The calling sequence of the message handler function is:

```
	int handler( int mid )
```

Where *mid* is the bufid of the received message. The handler function can be used to unpack and process the received message buffer. PVM automatically saves the current send and receive buffers, so the handler need not worry about interfering with message buffers in the regular program flow.  PVM also sets the current receive buffer to the received message (using pvm\_setrbuf()) before invoking the message handler, so the message can be unpacked directly.  PVM will free this message buffer when the message handler returns, if the handler has not already done so.  But, any other message buffers created by the handler routine should be freed using pvm\_freebuf() before returning.

Note: Operation in the message handler context is somewhat restricted. The function may call some PVM functions, but not others. For example, it may compose and send a reply message as shown:

```
	pvm_packf( "%+ %s", PvmDataDefault, "got your message" );
	pvm_send( tid, tag );
	pvm_freebuf( pvm_setsbuf( 0 ) );
```

or equivalently:

```
	pvm_setsbuf( pvm_mkbuf( PvmDataDefault ) );
	pvm_pkstr( "got your message" );
	pvm_send( tid, tag );
	pvm_freebuf( pvm_setsbuf( 0 ) );
```

but is not allowed to call certain other PVM communication functions, such as multicast or receive.

pvm\_addmhf returns the id number of the newly created message handler if successful; this number may be passed to pvm\_delmhf to remove the entry. There is no guarantee to the ordering of id values returned by pvm\_addmhf, or to the order in which message handlers will be invoked. PvmExists is returned if the handler already exists.

pvm\_delmhf returns PvmOk if successful. PvmBadParam if pvm\_delmhf is passed a negative id value. PvmNotFound if the id value is not found.

## EXAMPLES

```
	/* Print a message when hosts are added to virtual machine */
	int
	hostAdded( int mid )
	{
		int n;
		pvm_unpackf( "%d", &n );
		printf( "*** %d new hosts just added ***\n", n );
	}
	void
	main()
	{
		int src, tag, ctx;
		. . .
		src = -1;
		tag = 99;
		ctx = -1;
		pvm_addmhf( src, tag, ctx, hostAdded );
		pvm_notify( PvmHostAdd, 99, -1, (int *) NULL );
		. . .
	}
```

## ERRORS

The following error conditions can be returned by pvm\_addmhf():

- PvmExists

  Can't insert as handler already exists with same  (tag, ctx, src) including "wild-cards" (those set to -1)

The following error conditions can be returned by pvm\_delmhf():

- PvmBadParam

  Invalid (negative) *mhid* passed in.

- PvmNotFound

  Message handler *mhid* does not exist.

## SEE ALSO

pvm\_setrbuf(3PVM), pvm\_setsbuf(3PVM), pvm\_freebuf(3PVM)