pathmgr_link()

Synopsis:

#include <sys/pathmgr.h>

int pathmgr_link( const char *path,
                  uint32_t reserved,
                  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 /.

reserved

Set this argument to zero.

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 the QNX OS.

The flags argument

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.

Returns:

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

Errors:

EACCES: Security policies are in use and there is no rule to permit the use of that path.
EINVAL: The file_type is invalid or a non-NULL path was used with PATHMGR_FLAG_FTYPEONLY.
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 OS


Safety:
Cancellation point	Yes
Signal handler	Yes
Thread	Yes