qnx_prefix_attach()

attach a pathname prefix

Synopsis:

#include <sys/prfx.h>
int qnx_prefix_attach( char *prefix,
                       char *replace,
                       unsigned unit );

The qnx_prefix_attach() function attaches a pathname prefix passed as prefix. You may optionally specify a replacement string passed as replace. If replace is NULL, no replacement is done. You may associate a unit with the prefix to simplify your code if you have multiple prefixes.

This function is used in one of two ways:

to associate a pathname prefix with a resource manager (replace is NULL)
to provide an alias (replace isn't NULL). In this case the prefix isn't associated with the current process, and the unit is ignored.

As an example of a resource manager, a filesystem manager might call qnx_prefix_attach() as follows, if it had two logical drives named / (a hard disk) and /fd (a floppy disk):

qnx_prefix_attach( "/", NULL, 0 );
qnx_prefix_attach( "/fd", NULL, 1 );

The device manager calls qnx_prefix_attach() with:

qnx_prefix_attach( "/dev", NULL, 0 );

When the open() function is called with a pathname that matches one of these prefixes, the prefix is stripped, the unit number returned in a message, and the open message is sent to the resource manager that created the prefix.

The prefix utility can be used to create an alias. If the prefix utility is invoked with:

prefix -A /lpt=//20/dev/par1

it calls qnx_prefix_attach() with:

qnx_prefix_attach( "/lpt", "//20/dev/par1", 0 );

When the open() function is called with a pathname that matches one of these alias prefixes, the prefix is replaced with replace, and the newly formed pathname is retried. This replacement and retry is limited to 32 times to prevent alias loops.

This function is typically only called by resource managers or the prefix utility, and shouldn't be needed by a typical application.

Returns:

0: Success
-1: An error occurred. errno is set to indicate the error.

Errors:

EAGAIN: Insufficient resources to create a new prefix.
EEXIST: The prefix is in use.
ENAMETOOLONG: The prefix is longer than the prefix space.
EPERM: You don't have sufficient permission to attach a prefix.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/prfx.h>

char buf[1000];

void main()
  {
    print();
    qnx_prefix_attach( "/dev/console",
               "//0/dev/tty1", 0 );
    print();
    qnx_prefix_detach( "/dev/console" );
    print();
  }

void print()
  {
    if( qnx_prefix_query( 0, "", buf, 1000 ) != -1 )
      printf( "%s\n", buf );
    else
      printf( "Unable to print prefix tree.\n" );
  }

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes

Caveats:

If your application calls this function, it must run as root.