A computer may have multiple 1394 buses connected by having multiple 1394 chips. Each of these is called a port, and the handle has to be connected to one port before it can be used for anything. Even if no nodes are connected to the chip in question, it forms a complete bus (with just one node, itself).
A list of available ports together with some information about it (name
of the hardware, number of connected nodes) is available via
raw1394_get_port_info(), which is to be called
right after getting a fresh handle. The user should be presented with a
choice of available ports if there is more than one. It may be good
practice to do that even if there is only one port, since that may
result from a normally configured port just not being available, making
it confusing to be dropped right into the application attached to a port
without a choice and notion of anything going wrong.
The choice of port is then reported using
raw1394_set_port(). If this function fails and
errno is set to ESTALE, then
something has changed about the ports (port was added or removed)
between getting the port info and trying to set a port. It is
required that the current port list is fetched (presenting the user
with the choice again) and setting the port is retried with the new
data.
After a successful raw1394_set_port(), the get and
set port functions must not be used anymore on this handle. Undefined
results occur if you do so. To make up for this, all the other
functions are allowed now.