ra_get_attachinfo Subroutine

Purpose

Retrieves the resource set attachments to which a work component is attached.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>

attachinfo_t *ra_get_attachinfo(rstype, rsid, offset, length, flags)
rstype_t rstype;
rsid_t rsid;
off64_t offset;
size64_t length;
unsigned int flags;

Description

The ra_get_attachinfo subroutine retrieves information describing the attachments involving the work component specified by rstype and rsid.

This information is returned as a null-terminated linked list of attachinfo_t structures. The attachinfo_t structures are allocated in the caller's process heap. The ra_free_attachinfo subroutine is provided to free the list of attachinfo_t structures returned by ra_get_attachinfo.

The ra_get_attachinfo subroutine retrieves attachment information for the following work components:
  • A shared memory object identified by a shared memory segment ID.
  • A file identified by an open file descriptor.
  • An address range in the current user process.
  • An address range in one of the above work components identified by its offset in the object and its length.

If rstype is a memory object and length has a 0 value, the attachment information returned is for the last portion of the memory object, beginning with offset.

Note: Resource set attachments can change during or after ra_get_attachinfo retrieves them. There is no guarantee that the returned attachments still exist, or that all existing attachments were retrieved.

Parameters

Item Description
rstype Specifies the type of work component for which the attachment information is to be retrieved. This parameter can have one of the following values:
R_SHM
Attachment information of a shared memory, identified by its shared memory identifier, is to be retrieved.
R_FILDES
Attachment information of a file, identified by its open file descriptor, is to be retrieved.
R_PROCMEM
Attachment information of a memory range in the user process is to be retrieved.
rsid Identifies the work component for which the attachment information is to be retrieved. This parameter can be one of the following:
  • shared memory segment ID (if the value of rstype is R_SHM)
  • open file descriptor (if the value of rstype is R_FILDES)
  • RS_MYSELF (if value of rstype is R_PROCMEM)
offset Specifies the offset of a range within a memory object for which the attachment information is to be retrieved. This parameter is taken into account only for the following values of rstype:
  • R_SHM: starting offset within the shared memory object identified by rsid
  • R_FILDES: absolute offset within the file identified by rsid
  • R_PROCMEM: starting offset of memory range in user process.
length Specifies the length of a range within a memory object for which the attachment information is to be retrieved. This parameter is taken into account only for the following values of rstype:
  • R_SHM: length of a range within the shared memory object identified by rsid
  • R_FILDES: length of a range within the file identified by rsid
  • R_PROCMEM: length of range in user process.
flags Reserved for future use. Specify as 0.

Return Values

On successful completion, a pointer to the first element in a null-terminated list of attachinfo_t structures is returned. A null pointer is returned if the work component does not have any attachments. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The ra_get_attachinfo subroutine is unsuccessful if one or more of the following are true:
Item Description
EINVAL One of the following conditions is true:
  • The flags parameter contains an invalid value.
  • The rstype parameter contains an invalid type qualifier.
  • The rstype parameter is R_SHM and rsid is not a valid shared memory segment.
EBADF The rstype parameter is R_FILDES and rsid is not a valid open file descriptor.
ENOTSUP The rstype parameter is R_PROCMEM and rsid.at_pid field is not RS_MYSELF.