resmgr_detach(), resmgr_detach_ctp()

Updated: April 19, 2023

Remove a pathname from the pathname space

Synopsis:

#include <sys/iofunc.h>
#include <sys/dispatch.h>

int resmgr_detach( dispatch_t * dpp,
                   int id,
                   unsigned flags );

int resmgr_detach_ctp( const dispatch_t *dpp,
                       resmgr_context_t *ctp,
                       const int id,
                       const unsigned flags );

Arguments:

dpp
A dispatch handle created by a successful call to dispatch_create().
ctp
(resmgr_detach_ctp() only) A pointer to a resmgr_context_t structure that the resource-manager library uses to pass context information between functions, or NULL (see below).
id
The link ID that resmgr_attach() returned.
flags
Flags that affect the operation. The possible flags (defined in <sys/dispatch.h> and <sys/resmgr.h>) are:
  • _RESMGR_DETACH_ALL — detach the name from the namespace and invalidate all open bindings.
  • _RESMGR_DETACH_CLOSE — close all bindings when detaching.
  • _RESMGR_DETACH_PATHNAME — detach only the name from the namespace, leaving existing bindings intact. This option is useful when you're unlinking a file or device, and you want to remove the name, but you want processes with open files to continue to use it until they close.

Library:

libc

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

Description:

The resmgr_detach() and resmgr_detach_ctp() functions remove the pathname indicated by id from the pathname space of context dpp. The resmgr_detach_ctp() function includes a pointer to the resmgr_context_t structure, which lets the function get information about the link currently being operated on. This latter function can be used only if the _RESMGR_FLAG_DETACH_CTP flag was passed in to resmgr_attach().

There are two main circumstances in which a resource manager may want to or need to detach a registered pathname:
  1. If a resource manager needs to be detached from within one of its message-handling functions, the framework must ensure there is no deadlock while accessing its internal structures. Usually this state information is passed through thread-local storage, but in some rare cases you may need more control over this. By setting _RESMGR_FLAG_DETACH_CTP, you can request that the state instead be passed through the ctp structure. If this flag is set, you must use resmgr_detach_ctp(); otherwise, you should use resmgr_detach().
  2. For a non-client reason, such as a device being removed. In this case, there is not the same synchronization issue with accessing internal structures. If _RESMGR_FLAG_DETACH_CTP was set, then resmgr_detach_ctp() must be called with NULL for the ctp argument.

Blocking states

These functions block until the RESMGR_HANDLE_T that was passed to the corresponding resmgr_attach() isn't being used in any connection function.

The effect that this has on servers is generally minimal. You should follow the following precautions to prevent potential deadlock situations:

Returns:

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

Errors:

EINVAL
The id was never attached with resmgr_attach().
ENOENT
A previous detachment request is in progress, or the id has already been detached.

Examples:

#include <sys/dispatch.h>
#include <stdio.h>
#include <stdlib.h>

int main( int argc, char **argv ) {
   dispatch_t  *dpp;
   int         id;

   if ( (dpp = dispatch_create()) == NULL ) {
      fprintf( stderr, "%s: Unable to allocate \
               dispatch handle.\n",argv[0] );
      return EXIT_FAILURE;
   }

   id = resmgr_attach ( … );

   …

   if ( resmgr_detach( dpp, id, 0) == -1 ) {
      fprintf( stderr, "Failed to remove pathname \
               from the pathname space.\n" );
      return EXIT_FAILURE;
}

For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().

Classification:

QNX Neutrino

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