ham_connect(), ham_connect_nd(), ham_connect_node()

Updated: April 19, 2023

Connect to the HAM

Synopsis:

#include <ha/ham.h>

int ham_connect( unsigned flags);
int ham_connect_nd( int nd, unsigned flags);
int ham_connect_node( const char *nodename, unsigned flags);


Arguments:

flags
Currently not used.
nd
(ham_connect_nd() only) The node identifier of the targeted remote node.
nodename
(ham_connect_node() only) The targeted remote HAM.

Library:

libham

Description:

The ham_connect() function initializes a connection to a HAM. The ham_connect_nd() and ham_connect_node() functions initialize connections to remote HAMs.

Note: A process may have only a single connection open to a HAM at any time.

The nd specified to ham_connect_nd is the node identifier of the remote node at the time the ham_connect_nd() call is made.

Note: Since node identifiers are transient objects, you should obtain the value for nd immediately before the call, using netmgr_strtond() or another function that converts nodenames into node identifiers.

The ham_connect_node() function takes as a parameter a fully qualified node name (FQNN).

You can call these functions any number of times, but because the library maintains a reference count, you need to call ham_disconnect() the same number of times to release the connection.

Connections are associated with a specific process ID (pid). If a process performs ham_connect() and then calls fork(), the child process needs to reconnect to the HAM by calling ham_connect() again.

But if a process only calls any of the following:

it doesn't need to call ham_connect*(), since those functions create their own temporary connection.

Note: For all other ham*() functions, clients must call ham_connect() first. If the process is doing multiple operations, it is more efficient to explicitly call ham_connect() before the series of operations and ham_disconnect() after to avoid multiple implicit connect/disconnect operations.

There are no flags defined at this time.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

Upon failure, the ham_connect*() functions return the error as set by the underlying open() library call that failed.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes