Standard C Library Functions portassociate(3C)
NAME
portassociate, portdissociate - associate or dissociate
the object with the port
SYNOPSIS
#include
int portassociate(int port, int source, uintptrt object,
int events, void *user);
int portdissociate(int port, int source, uintptrt object);
DESCRIPTION
The portassociate() function associates specific events of
a given object with a port. Only objects associated with a
particular port are able to generate events that can be
retrieved using portget(3C) or portgetn(3C). The delivery
event has its portevuser member set to the value specified
in the user parameter. If the specified object is already
associated with the specified port, the portassociate()
function serves to update the events and user arguments of
the association. The portdissociate() function removes the
association of an object with a port.
The objects that can be associated with a port by way of the
portassociate() function are objects of type PORTSOURCEFD
and PORTSOURCEFILE. Objects of other types have type-
specific association mechanisms. A portnotifyt structure,
defined in , is used to specify the event port and
an application-defined cookie to associate with these event
sources. See portcreate(3C) and signal.h(3HEAD).
The portnotifyt structure contains the following members:
int portntfyport; /* bind request(s) to port */
void *portntfyuser; /* user defined cookie */
Objects of type PORTSOURCEFD are file descriptors. The
event types for PORTSOURCEFD objects are described in
poll(2). At most one event notification will be generated
per associated file descriptor. For example, if a file
descriptor is associated with a port for the POLRDNORM
event and data is available on the file descriptor at the
time the portassociate() 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
SunOS 5.11 Last change: 9 Nov 2007 1
Standard C Library Functions portassociate(3C)
available.
When an event for a PORTSOURCEFD 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
portassociate() function can be called to reassociate the
object with the port.
Objects of type PORTSOURCEFILE are pointer to the struc-
ture fileobj defined in . 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 fileobj along with the access,
modification, and change time stamps acquired from a stat(2)
call. If the file name is a symbolic links, it is followed
by default. The FILENOFOLOW 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 fileobj contains the following elements:
timestruct foatime; /* Access time got from stat() */
timestruct fomtime; /* Modification time from stat() */
timestruct foctime; /* Change time from stat() */
char *foname; /* Pointer to a null terminated path name */
At the time the portassociate() function is called, the
time stamps passed in the structure fileobj are compared
with the file or directory'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.
The event types that can be specified at portassociate()
time for PORTSOURCEFILE are FILEACES, FILEMODIFIED,
and FILEATRIB, corresponding to the three time stamps. An
foatime change results in the FILEACES event, an
fomtime change results in the FILEMODIFIED event, and an
fotime change results in the FILEATRIB event.
SunOS 5.11 Last change: 9 Nov 2007 2
Standard C Library Functions portassociate(3C)
The following exception events are delivered when they
occur. These event types cannot be filtered.
FILEDELETE /* Monitored file/directory was deleted */
FILERENAMETO /* Monitored file/directory was renamed */
FILERENAMEFROM /* 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 associ-
ated fileobj. When the event for the associated fileobj 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 portassociate() can be called to reassociate
the fileobj object with the port.
The association is also removed if the port gets closed or
when portdissociate() 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) access/modifications to files or directories will be
delivered.
RETURN VALUES
Upon succesful completion, 0 is returned. Otherwise, -1 is
returned and errno is set to indicate the error.
ERORS
The portassociate() and portdissociate() functions will
fail if:
EBADF The port identifier is not valid.
EBADFD The source argument is of type PORTSOURCEFD and
the object argument is not a valid file descrip-
tor.
SunOS 5.11 Last change: 9 Nov 2007 3
Standard C Library Functions portassociate(3C)
EINVAL The source argument is not valid.
The portassociate() function will fail if:
EACES The source argument is PORTSOURCEFILE and,
Search permission is denied on a component of
path prefix or the file exists and the permis-
sions, corresponding to the events argument, are
denied.
EAGAIN The maximum number of objects associated with the
port was exceeded. The maximum allowable number
of events or association of objects per port is
the minimum value of the process.max-port-events
resource control at the time portcreate(3C) was
used to create the port. See setrctl(2) and
rctladm(1M) 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
portassociate() function.
ENOENT The source argument is PORTSOURCEFILE and the
file does not exist or the path prefix does not
exist or the path points to an empty string.
ENOMEM The physical memory limits of the system have
been exceeded.
ENOTSUP The source argument is PORTSOURCEFILE and the
file system on which the specified file resides,
does not support watching for file events notifi-
cations.
The portdissociate() function will fail if:
EACES The process is not the owner of the association.
ENOENT The specified object is not associated with the
port.
SunOS 5.11 Last change: 9 Nov 2007 4
Standard C Library Functions portassociate(3C)
EXAMPLES
Example 1 Retrieve data from a pipe file descriptor.
The following example retrieves data from a pipe file
descriptor.
#include
int port;
int fd;
int error;
int index;
void *mypointer;
porteventt pev;
struct timespect timeout;
char rbuf[STRSIZE];
int fds[MAXINDEX];
/* create a port */
port = portcreate();
for (index = 0; index < MAXINDEX; index]) {
error = mkfifo(name[index], SIRWXU SIRWXG SIRWXO);
if (error)
/* handle error code */
fds[index] = open(name[index], ORDWR);
/* associate pipe file descriptor with the port */
error = portassociate(port, PORTSOURCEFD, fds[index],
POLIN, mypointer);
}
...
timeout.tvsec = 1; /* user defined */
timeout.tvnsec = 0;
/* loop to retrieve data from the list of pipe file descriptors */
for (...) {
/* retrieve a single event */
error = portget(port, &pev, &timeout);
if (error) {
/* handle error code */
}
fd = pev.portevobject;
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
SunOS 5.11 Last change: 9 Nov 2007 5
Standard C Library Functions portassociate(3C)
* re-activation of the data detection.
* Internals events and user arguments are set to the
* new (or the same) values delivered here.
*/
error = portassociate(port, PORTSOURCEFD, fd, POLIN,
pev.portevuser);
} 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
int port;
portnotifyt pn;
aiocbt aiocb;
aiocbt *aiocbp;
void *mypointer;
int error;
int myerrno;
int mystatus;
struct timespect timeout;
porteventt pev;
port = portcreate();
...
/* fill AIO specific part */
aiocb.aiofildes = fd;
aiocb.aionbytes = BUFSIZE;
aiocb.aiobuf = bufp;
aiocb.aiooffset = 0;
/* port specific part */
pn.portnfyport = port;
pn.portnfyuser = mypointer;
aiocb.aiosigevent.sigevnotify = SIGEVPORT;
aiocb.aiosigevent.sigevvalue.sivalptr = &pn
/*
* The aioread() function binds internally the asynchronous I/O
SunOS 5.11 Last change: 9 Nov 2007 6
Standard C Library Functions portassociate(3C)
* transaction with the port delivered in portnotifyt.
*/
error = aioread(&aiocb);
timeout.tvsec = 1; /* user defined */
timeout.tvnsec = 0;
/* retrieve a single event */
error = portget(port, &pev, &timeout);
if (error) {
/* handle error code */
}
/*
* pev.portevobject contains a pointer to the aiocb structure
* delivered in portnotifyt (see aioread()).
*/
aiocbp = pev.portevobject;
/* check error code and return value in
myerrno = aioerror(aiocbp);
...
mystatus = aioreturn(aiocbp);
...
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture all
Availability SUNWcsr, SUNWhea
Interface Stability Committed
MT-Level Safe
SEE ALSO
rctladm(1M), poll(2), setrctl(2), portalert(3C),
portcreate(3C), portget(3C), portsend(3C),
signal.h(3HEAD), attributes(5)
SunOS 5.11 Last change: 9 Nov 2007 7
|
