| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
enable_extended_FILE_stdio(3C)
posix_spawnattr_getschedparam(3C)
posix_spawnattr_getschedpolicy(3C)
posix_spawnattr_getsigdefault(3C)
posix_spawnattr_getsigignore_np(3C)
posix_spawnattr_getsigmask(3C)
posix_spawnattr_setschedparam(3C)
posix_spawnattr_setschedpolicy(3C)
posix_spawnattr_setsigdefault(3C)
posix_spawnattr_setsigignore_np(3C)
posix_spawnattr_setsigmask(3C)
posix_spawn_file_actions_addclose(3C)
posix_spawn_file_actions_addclosefrom_np(3C)
posix_spawn_file_actions_adddup2(3C)
posix_spawn_file_actions_addopen(3C)
posix_spawn_file_actions_destroy(3C)
posix_spawn_file_actions_init(3C)
pthread_attr_getdetachstate(3C)
pthread_attr_getinheritsched(3C)
pthread_attr_getschedparam(3C)
pthread_attr_getschedpolicy(3C)
pthread_attr_setdetachstate(3C)
pthread_attr_setinheritsched(3C)
pthread_attr_setschedparam(3C)
pthread_attr_setschedpolicy(3C)
pthread_barrierattr_destroy(3C)
pthread_barrierattr_getpshared(3C)
pthread_barrierattr_setpshared(3C)
pthread_condattr_getpshared(3C)
pthread_condattr_setpshared(3C)
pthread_cond_reltimedwait_np(3C)
pthread_key_create_once_np(3C)
pthread_mutexattr_getprioceiling(3C)
pthread_mutexattr_getprotocol(3C)
pthread_mutexattr_getpshared(3C)
pthread_mutexattr_getrobust(3C)
pthread_mutexattr_setprioceiling(3C)
pthread_mutexattr_setprotocol(3C)
pthread_mutexattr_setpshared(3C)
pthread_mutexattr_setrobust(3C)
pthread_mutex_getprioceiling(3C)
pthread_mutex_reltimedlock_np(3C)
pthread_mutex_setprioceiling(3C)
pthread_rwlockattr_destroy(3C)
pthread_rwlockattr_getpshared(3C)
pthread_rwlockattr_setpshared(3C)
pthread_rwlock_reltimedrdlock_np(3C)
pthread_rwlock_reltimedwrlock_np(3C)
pthread_rwlock_timedrdlock(3C)
pthread_rwlock_timedwrlock(3C)
rctlblk_get_enforced_value(3C)
- associate or dissociate the object with the port
#include <port.h>intport_associate(intport,intsource,uintptr_tobject,intevents,void *user);
intport_dissociate(intport,intsource,uintptr_tobject);
Theport_associate() function associates specificevents of a givenobject with aport. Only objects associated with a particular port are able togenerate events that can be retrieved usingport_get(3C) orport_getn(3C). The deliveryevent has itsportev_user member set to the value specified in theuser parameter. If the specified object is already associated with the specifiedport, theport_associate() function serves to update theevents anduser argumentsof the association. Theport_dissociate() function removes the association of anobject with a port.
The objects that can be associated with a port by way oftheport_associate() function are objects of typePORT_SOURCE_FD andPORT_SOURCE_FILE. Objects ofother types have type-specific association mechanisms. Aport_notify_t structure, defined in<port.h>, isused to specify the event port and an application-defined cookie to associatewith these event sources. Seeport_create(3C) andsignal.h(3HEAD).
Theport_notify_t structure contains the following members:
int portntfy_port; /* bind request(s) to port */void *portntfy_user; /* user defined cookie */
Objects of typePORT_SOURCE_FD are file descriptors. The event types forPORT_SOURCE_FDobjects are described inpoll(2). At most one event notification will be generatedper associated file descriptor. For example, if a file descriptor isassociated with a port for thePOLLRDNORM event and data is availableon the file descriptor at the time theport_associate() function is called, anevent is immediately sent to the port. If data is not yetavailable, one event is sent to the port when data first becomesavailable.
When an event for aPORT_SOURCE_FD object is retrieved, the object nolonger has an association with the port. The event can beprocessed without the possibility that another thread can retrieve a subsequent eventfor the same object. After processing of the file descriptor is completed,theport_associate() function can be called to reassociate the object with theport.
Objects of typePORT_SOURCE_FILE are pointer to the structurefile_obj defined in<sys/port.h>. This event source provides event notification when the specified file/directory isaccessed or modified or when its status changes. The path name of thefile/directory to be watched is passed in thestruct file_obj along with theaccess,modification, andchange time stamps acquired from astat(2) call. Ifthe file name is a symbolic links, it is followed by default.TheFILE_NOFOLLOW needs to be passed in along with the specified eventsif the symbolic link itself needs to be watched andlstat() needsto be used to get the file status of the symbolic linkfile.
Thestruct file_obj contains the following elements:
timestruc_t fo_atime; /* Access time got 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 theport_associate() function is called, the time stamps passedin the structurefile_obj are compared with the file or directory's currenttime stamps and, if there has been a change, an event isimmediately sent to the port. If not, an event will be sent whensuch a change occurs.
The event types that can be specified atport_associate() time forPORT_SOURCE_FILEareFILE_ACCESS,FILE_MODIFIED, andFILE_ATTRIB, corresponding to the three time stamps. Anfo_atime change results in theFILE_ACCESS event, anfo_mtime change results in theFILE_MODIFIED event, and anfo_time change results in theFILE_ATTRIB event.
The following exception events are delivered when they occur. These event typescannot 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 associatedfile_obj. Whenthe event for the associatedfile_obj is retrieved, the object is nolonger associated with the port. The event can be processed without thepossibility that another thread can retrieve a subsequent event for the same object.Theport_associate() can be called to reassociate thefile_obj object with theport.
The association is also removed if the port gets closed or whenport_dissociate() is called.
The parent and child processes are allowed to retrieve events from filedescriptors shared after a call tofork(2). The process performing the firstassociation with a port (parent or child process) is designated as the ownerof the association. Only the owner of an association is allowed todissociate the file descriptor from a port. The association is removed ifthe owner of the association closes the port .
On NFS file systems, events from only the client side (local) access/modificationsto files or directories will be delivered.
Upon successful completion, 0 is returned. Otherwise, -1 is returned anderrnois set to indicate the error.
Theport_associate() andport_dissociate() functions will fail if:
Theport identifier is not valid.
Thesource argument is of typePORT_SOURCE_FD and the object argument is not a valid file descriptor.
Thesource argument is not valid.
Theport_associate() function will fail if:
The source argument isPORT_SOURCE_FILE and, Search permission is denied on a component of path prefix or the file exists and the permissions, corresponding to the events argument, are denied.
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 theprocess.max-port-events resource control at the timeport_create(3C) was used to create the port. Seesetrctl(2) andrctladm(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 theport_associate() function.
The source argument isPORT_SOURCE_FILE and the file does not exist or the path prefix does not exist or the path points to an empty string.
The physical memory limits of the system have been exceeded.
The source argument isPORT_SOURCE_FILE and the file system on which the specified file resides, does not support watching for file events notifications.
Theport_dissociate() function will fail if:
The process is not the owner of the association.
The specified object is not associated with the port.
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 inmy_errno = aio_error(aiocbp);...my_status = aio_return(aiocbp);...Seeattributes(5) for descriptions of the following attributes:
|
rctladm(1M),poll(2),setrctl(2),port_alert(3C),port_create(3C),port_get(3C),port_send(3C),signal.h(3HEAD),attributes(5)
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |