pathmgr_link()

Updated: April 19, 2023

Create a node in the path space that represents the mountpoint of a device or filesystem

Synopsis:

#include <sys/pathmgr.h>

int pathmgr_link( const char *path,
                  uint32_t nd,
                  pid_t pid,
                  int chid,
                  unsigned handle,
                  enum _file_type file_type,
                  unsigned flags );

Arguments:

path
The path that you want to link to, or NULL to link to /.
nd
The node descriptor of the node (e.g., ND_LOCAL_NODE for the local node) of the process you want to associate the link with; see Node descriptors,” below.
pid
The process ID to associate with the link, or 0 for the calling process.
chid
The channel ID to associate with the link.
handle
A handle to associate with the link.
file_type
The file type; one of the following (defined in <sys/ftype.h>):
  • _FTYPE_ANY — the path name can be anything.
  • _FTYPE_LINK — reserved for the process manager.
  • _FTYPE_MOUNT — receive mount requests on the path (path must be NULL).
  • _FTYPE_MQ — reserved for an alternate message-queue manager.
  • _FTYPE_MQUEUE — reserved for a traditional message-queue manager.
  • _FTYPE_PIPE — reserved for a pipe manager.
  • _FTYPE_SEM — reserved for a semaphore manager.
  • _FTYPE_SHMEM — reserved for a shared memory object.
  • _FTYPE_SOCKET — reserved for a socket manager.
  • _FTYPE_SYMLINK — reserved for the Process Manager.
flags
0, or a combination of the following:
  • PATHMGR_FLAG_AFTER
  • PATHMGR_FLAG_BEFORE
  • PATHMGR_FLAG_DIR
  • PATHMGR_FLAG_FTYPEALL
  • PATHMGR_FLAG_FTYPEONLY
  • PATHMGR_FLAG_OPAQUE
  • PATHMGR_FLAG_SELF
  • PATHMGR_FLAG_STICKY

For more information, see The flags argument,” below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pathmgr_link() function creates a node in the path space that represents the mountpoint of a device or filesystem. It implements high-level APIs such as name_attach() and resmgr_attach(). You probably don't need to call pathmgr_link() directly.

The nd, pid, chid, and handle together identify who handles the specified path; for more information, see The client's view in the Resource Managers chapter of Getting Started with QNX Neutrino.

The flags argument specifies additional information to control the pathname resolution:

PATHMGR_FLAG_AFTER
Force the path to be resolved after others with the same pathname at the same mountpoint.
PATHMGR_FLAG_BEFORE
Force the path to be resolved before others with the same pathname at the same mountpoint.
PATHMGR_FLAG_DIR
Treat the pathname as a directory and allow the resolving of longer pathnames. The _IO_CONNECT message contains the pathname passed to the client open() with the matching prefix stripped off. Without this flag, the pathname is treated as a simple file requiring an exact match.
Attached path Opened path PATHMGR_FLAG_DIR set PATHMGR_FLAG_DIR clear
/a/b /a/b Match "" Match ""
/a/b /a/b/c Match c No match
/a/b /a/b/c/d Match c/d No match
/a/b /a/bc No match No match

You can't attach a directory pathname that contains, as a subset, an existing file pathname. Likewise, you can't attach a file pathname that's a subset of an existing directory pathname.

Existing path New path New path allowed?
Directory /a/b Directory /a Yes
Directory /a/b Directory /a/b/c Yes
File /a/b Directory /a Yes
File /a/b Directory /a/b/c No; the directory is beneath a file
Directory /a/b File /a No; the directory is beneath a file
Directory /a/b File /a/b/c Yes
File /a/b File /a Yes
File /a/b File /a/b/c Yes
PATHMGR_FLAG_FTYPEALL
Handle requests for all file types. You must specify a registration file type of _FTYPE_ALL.
PATHMGR_FLAG_FTYPEONLY
Handle only requests for the specific filetype indicated. The pathname must be NULL.
PATHMGR_FLAG_OPAQUE
Don't resolve paths to mountpoints on a path shorter than this (i.e., find the longest match against all pathnames attached).
PATHMGR_FLAG_SELF
Allow requests to resolve back to this server.
CAUTION:
Be very careful if you set PATHMGR_FLAG_SELF because it's possible for a deadlock to occur. For more information, see Robust implementations with Send/Receive/Reply in the Interprocess Communication (IPC) chapter of the System Architecture guide.
PATHMGR_FLAG_STICKY
No ID is associated with the path. You must use pathmgr_unlink() to remove the link.

The nd (node descriptor) is a temporary numeric description of a remote node. For more information, see the Qnet Networking chapter of the System Architecture guide.

To: Use this function:
Compare two nd objects ND_NODE_CMP()
Convert a nd to text netmgr_ndtostr()
Convert text to a nd netmgr_strtond()

Returns:

A unique ID for the link, or -1 if an error occurred (errno is set).

Errors:

EACCES
(QNX Neutrino 7.0 or later) One of the following occurred:
  • Security policies are in use and there is no rule to permit the use of that path.
  • The process is sandboxed and the path is denied.
ENOMEM
There isn't enough free memory to complete the operation.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Classification:

QNX Neutrino

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