svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
port_associate(3c)
port_associate(3C) Standard C Library Functions port_associate(3C)
NAME
port_associate, port_dissociate - associate or dissociate the object
with the port
SYNOPSIS
#include <port.h>
int port_associate(int port, int source, uintptr_t object,
int events, void *user);
int port_dissociate(int port, int source, uintptr_t object);
DESCRIPTION
The port_associate() function associates specific events of a given ob‐
ject with a port. Only objects associated with a particular port are
able to generate events that can be retrieved using port_get(3C) or
port_getn(3C). The delivery event has its portev_user member set to the
value specified in the user parameter. If the specified object is al‐
ready associated with the specified port, the port_associate() function
serves to update the events and user arguments of the association. The
port_dissociate() function removes the association of an object with a
port.
The objects that can be associated with a port by way of the port_asso‐
ciate() function are objects of type PORT_SOURCE_FD and
PORT_SOURCE_FILE. Objects of other types have type-specific association
mechanisms. A port_notify_t structure, defined in <port.h>, is used to
specify the event port and an application-defined cookie to associate
with these event sources. See port_create(3C) and signal.h(3HEAD).
The port_notify_t structure contains the following members:
int portntfy_port; /* bind request(s) to port */
void *portntfy_user; /* user defined cookie */
Objects of type PORT_SOURCE_FD are file descriptors. The event types
for PORT_SOURCE_FD objects are described in poll(2). At most one event
notification will be generated per associated file descriptor. For ex‐
ample, if a file descriptor is associated with a port for the POLLRD‐
NORM event and data is available on the file descriptor at the time the
port_associate() function is called, an event is immediately sent to
the port. If data is not yet available, one event is sent to the port
when data first becomes available.
When an event for a PORT_SOURCE_FD object is retrieved, the object no
longer has an association with the port. The event can be processed
without the possibility that another thread can retrieve a subsequent
event for the same object. After processing of the file descriptor is
completed, the port_associate() function can be called to reassociate
the object with the port.
Objects of type PORT_SOURCE_FILE are pointer to the structure file_obj
defined in <sys/port.h>. This event source provides event notification
when the specified file/directory is accessed or modified or when its
status changes. The path name of the file/directory to be watched is
passed in the struct file_obj along with the access, modification, and
change time stamps acquired from a stat(2) call. If the file name is a
symbolic link, it is followed by default. The FILE_NOFOLLOW needs to be
passed in along with the specified events if the symbolic link itself
needs to be watched and lstat() needs to be used to get the file status
of the symbolic link file.
The struct file_obj contains the following elements:
timestruc_t fo_atime; /* Access time from stat() */
timestruc_t fo_mtime; /* Modification time from stat() */
timestruc_t fo_ctime; /* Change time from stat() */
char *fo_name; /* Pointer to a null terminated path name */
At the time the port_associate() function is called, the timestamps
passed in the structure file_obj are compared with the file or direc‐
tory's current time stamps and, if there has been a change, an event is
immediately sent to the port. If not, an event will be sent when such a
change occurs. If all the time stamps passed in file_obj structure are
set to zero, this routine behaves as if the timestamps were set to the
values obtained from a call to the stat() function at the moment of the
call to the port_associate() function.
The event types that can be specified at port_associate() time for
PORT_SOURCE_FILE are FILE_ACCESS, FILE_MODIFIED, and FILE_ATTRIB, cor‐
responding to the three time stamps. An fo_atime change results in the
FILE_ACCESS event, an fo_mtime change results in the FILE_MODIFIED
event, and an fo_ctime change results in the FILE_ATTRIB event.
The following exception events are delivered when they occur. These
event types cannot be filtered.
FILE_DELETE /* Monitored file/directory was deleted */
FILE_RENAME_TO /* Monitored file/directory was renamed */
FILE_RENAME_FROM /* Monitored file/directory was renamed */
UNMOUNTED /* Monitored file system got unmounted */
MOUNTEDOVER /* Monitored file/directory was mounted over */
At most one event notification will be generated per associated
file_obj. When the event for the associated file_obj is retrieved, the
object is no longer associated with the port. The event can be
processed without the possibility that another thread can retrieve a
subsequent event for the same object. The port_associate() can be
called to reassociate the file_obj object with the port.
The association is also removed if the port gets closed or when
port_dissociate() is called.
The parent and child processes are allowed to retrieve events from file
descriptors shared after a call to fork(2). The process performing the
first association with a port (parent or child process) is designated
as the owner of the association. Only the owner of an association is
allowed to dissociate the file descriptor from a port. The association
is removed if the owner of the association closes the port.
On NFS file systems, events from only the client side (local) ac‐
cess/modifications to files or directories will be delivered.
Objects of event source type PORT_SOURCE_POSTWAIT are a pointer to the
struct postwk_obj_t defined in <sys/port.h>. This event source provides
post events submitted by postwait_post(3C), postwait_postn(3C), and
postwait_post_deferred(3C). The struct postwk_obj_t contains the fol‐
lowing elements:
int ko_flags /* flags */
postwkey_t ko_key; /* key from postwait_genkey(3C) call */
The key is acquired by calling postwait_genkey(3C).
One event at a time is delivered for an associated key with type POST‐
WKEY_COUNTING specified in ko_flags. Along with the event a count of
number of times the key was posted since the last time an event was re‐
trieved is returned in port_events member of the port_event_t struct.
If type POSTWKEY_QUEUING is specified in ko_flags, one event for every
post submitted will be delivered. Each event has the portev_events and
portev_user members of port_event_t set to the user event and user
value passed with the submitted post respectively.
The postwk_obj_t object pointer is returned in the portev_object mem‐
ber.
For POSTWKEY_QUEUING key association type, the user cookie passed at
the time of port_associate call is ignored by this event source.
If the OR operation is performed on POSTWKEY_EXCLUSIVE with either
POSTWKEY_COUNTING or POSTWKEY_QUEUING, the calling process must be the
first to associate this key. Association will fail if the specified key
has already been associated with a port, regardless of whether or not
POSTWKEY_EXCLUSIVE was specified.
RETURN VALUES
Upon successful completion, 0 is returned. Otherwise, −1 is returned
and errno is set to indicate the error.
ERRORS
The port_associate() and port_dissociate() functions will fail if:
EBADF The port identifier is not valid.
EBADFD The source argument is of type PORT_SOURCE_FD and the object
argument is not a valid file descriptor.
EINVAL The source argument is not valid.
EBUSY If the source is PORT_SOURCE_POSTWAIT, the key specified is
already associated with the port.
EFAULT If the source is PORT_SOURCE_POSTWAIT, the postwk_obj_t
pointer is invalid.
EEXIST If the source is PORT_SOURCE_POSTWAIT and POSTWKEY_EXCLUSIVE
was specified, another port is already associated with this
key, or this key has been already associated with another
port with POSTWKEY_EXCLUSIVE specified.
EINVAL If the source is PORT_SOURCE_POSTWAIT, incorrect type speci‐
fied in ko_flags.
The port_associate() function will fail if:
EACCES The source argument is PORT_SOURCE_FILE and, Search permis‐
sion is denied on a component of path prefix or the file ex‐
ists and the permissions, corresponding to the events argu‐
ment, are denied.
EAGAIN The maximum number of objects associated with the port was
exceeded. The maximum allowable number of events or associa‐
tion of objects per port is the minimum value of the
process.max-port-events resource control at the time
port_create(3C) was used to create the port. See setrctl(2)
and rctladm(8) for information on using resource controls.
The number of objects associated with a port is composed of
all supported resource types. Some of the source types do
not explicitly use the port_associate() function.
ENOENT The source argument is PORT_SOURCE_FILE and the file does
not exist or the path prefix does not exist or the path
points to an empty string. The source argument is
PORT_SOURCE_SIGNAL and the object argument (signal) is one
of the following SIGKILL, SIGSTOP, SIGILL, SIGSEGV, SIGFPE.
ENOMEM The physical memory limits of the system have been exceeded.
ENOTSUP The source argument is PORT_SOURCE_FILE and the file system
on which the specified file resides, does not support watch‐
ing for file events notifications.
The port_dissociate() function will fail if:
EACCES The process is not the owner of the association.
ENOENT The specified object is not associated with the port.
EXAMPLES
Example 1 Retrieve data from a pipe file descriptor.
The following example retrieves data from a pipe file descriptor.
#include <port.h>
int port;
int fd;
int error;
int index;
void *mypointer;
port_event_t pev;
struct timespec_t timeout;
char rbuf[STRSIZE];
int fds[MAXINDEX];
/* create a port */
port = port_create();
for (index = 0; index < MAXINDEX; index++) {
error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
if (error)
/* handle error code */
fds[index] = open(name[index], O_RDWR);
/* associate pipe file descriptor with the port */
error = port_associate(port, PORT_SOURCE_FD, fds[index],
POLLIN, mypointer);
}
...
timeout.tv_sec = 1; /* user defined */
timeout.tv_nsec = 0;
/* loop to retrieve data from the list of pipe file descriptors */
for (...) {
/* retrieve a single event */
error = port_get(port, &pev, &timeout);
if (error) {
/* handle error code */
}
fd = pev.portev_object;
if (read(fd, rbuf, STRSIZE)) {
/* handle error code */
}
if (fd-still-accepting-data) {
/*
* re-associate the file descriptor with the port.
* The re-association is required for the
* re-activation of the data detection.
* Internals events and user arguments are set to the
* new (or the same) values delivered here.
*/
error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
pev.portev_user);
} else {
/*
* If file descriptor is no longer required,
* - it can remain disabled but still associated with
* the port, or
* - it can be dissociated from the port.
*/
}
Example 2 Bind AIO transaction to a specific port.
The following example binds the AIO transaction to a specific port.
#include <port.h>
int port;
port_notify_t pn;
aiocb_t aiocb;
aiocb_t *aiocbp;
void *mypointer;
int error;
int my_errno;
int my_status;
struct timespec_t timeout;
port_event_t pev;
port = port_create();
...
/* fill AIO specific part */
aiocb.aio_fildes = fd;
aiocb.aio_nbytes = BUFSIZE;
aiocb.aio_buf = bufp;
aiocb.aio_offset = 0;
/* port specific part */
pn.portnfy_port = port;
pn.portnfy_user = mypointer;
aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
/*
* The aio_read() function binds internally the asynchronous I/O
* transaction with the port delivered in port_notify_t.
*/
error = aio_read(&aiocb);
timeout.tv_sec = 1; /* user defined */
timeout.tv_nsec = 0;
/* retrieve a single event */
error = port_get(port, &pev, &timeout);
if (error) {
/* handle error code */
}
/*
* pev.portev_object contains a pointer to the aiocb structure
* delivered in port_notify_t (see aio_read()).
*/
aiocbp = pev.portev_object;
/* check error code and return value in
my_errno = aio_error(aiocbp);
...
my_status = aio_return(aiocbp);
...
Example 3 Using signals as an event source.
The following example shows a way to use signals as an event source.
#include <port.h>
int portfd;
sigset_t mask;
port_event_t pe;
siginfo_t si;
timespec_t ts;
/* Create a port and associate PORT_SOURCE_SIGNAL with it */
portfd = port_create();
port_associate(portfd, PORT_SOURCE_SIGNAL, SIGUSR1, 0, (void *) &up);
/* Block the signals of interest */
(void)sigemptyset(&mask);
(void)sigaddset(&mask, SIGUSR1);
sigprocmask(SIG_BLOCK, &mask, NULL);
kill(getpid(), SIGUSR1);
port_get(portfd, &pe, NULL);
ts.tv_sec = 0;
ts.tv_nsec = 0;
/*
* 'while' loop to consume all pending signals.
* see sigtimedwait(3C).
*/
while (sigtimedwait(&mask, &si, &ts) != -1) {
/* fill code to consume signal here */
}
port_dissociate(portfd, PORT_SOURCE_SIGNAL, SIGUSR1)
close(portfd);
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Architectureall _ Interface StabilityCommitted _ MT-
LevelSafe
SEE ALSO
poll(2), setrctl(2), port_alert(3C), port_create(3C), port_get(3C),
port_send(3C), postwait_genkey(3C), postwait_post(3C), post‐
wait_postn(3C), postwait_post_deferred(3C), signal.h(3HEAD), attrib‐
utes(7), rctladm(8)
Oracle Solaris 11.4 25 Aug 2020 port_associate(3C)