Content-type: text/html Man page of port_create

port_create

Section: Standard C Library Functions (3C)
Updated: 22 Feb 2005
Index Return to Main Contents
 

NAME

port_create - create a port  

SYNOPSIS

#include <port.h>

int port_create(void);  

DESCRIPTION

The port_create() function establishes a queue that multiplexes events from disjoint sources. Each source has a corresponding object type and source-specific mechanism for associating an object with a port.

sourceobject typeassociation mechanism
PORT_SOURCE_AIOstruct aiocb aio_read(3RT), aio_write(3RT), lio_listio(3RT)
PORT_SOURCE_FDfile descriptorport_associate(3C)
PORT_SOURCE_TIMERtimer_ttimer_create(3RT)
PORT_SOURCE_USERuintptr_tport_send(3C)
PORT_SOURCE_ALERTuintptr_tport_alert(3C)

PORT_SOURCE_AIO events represent the completion of an asynchronous I/O transaction. An asynchronous I/O transaction is associated with a port by specifying SIGEV_PORT as its notification mechanism. See aio_read(3RT), aio_write(3RT), lio_listio(3RT), and aio.h(3HEAD) for details.

PORT_SOURCE_FD events represent a transition in the poll(2) status of a given file descriptor. Once an event is delivered, the file descriptor is no longer associated with the port. A file descriptor is associated (or re-associated) with a port using the port_associate(3C) function.

PORT_SOURCE_TIMER events represent one or more timer expirations for a given timer. A timer is associated with a port by specifying SIGEV_PORT as its notification mechanism. See timer_create(3RT) for more information.

PORT_SOURCE_USER events represent user-defined events. These events are generated by port_send(3C) or port_sendn(3C).

PORT_SOURCE_ALERT events indicate that the port itself is in alert mode. The mode of the port is changed with port_alert(3C).The port_create() function returns a file descriptor that represents a newly created port. The close(2) function destroys the port and frees all allocated resources.

The port_get(3C) and port_getn(3C) functions retrieve events from a port. They ignore non retrievable events (non-own or non-shareable events).

As a port is represented by a file descriptor, ports are shared between child and parent processes after fork(). Both can continue to associate sources with the port, both can receive events from the port, and events associated with and/or generated by either process are retrievable in the other. Since some events might not have meaning in both parent and child, care must be taken when using ports after fork().

If a port is exported to other processes, the port is destroyed on last close.

PORT_SOURCE_USER and PORT_SOURCE_ALERT events can be distributed across processes. PORT_SOURCE_FD events can only be shared between processes when child processes inherit opened file decriptors from the parent process. See fork(2). PORT_SOURCE_TIMER and PORT_SOURCE_AIO cannot be shared between processes.  

RETURN VALUES

Upon succesful completion, the port_create() function returns a non-negative value, the port identifier. Otherwise, -1 is returned and errno is set to indicate the error.  

ERRORS

The port_create() function will fail if:

EAGAIN The maximum allowable number of ports is currently open in the system. The maximum allowable number of ports is the minimum value of the project.max-port-ids resource control. See setrctl(2) and rctladm(1M) for information on using resource controls.

EMFILE The process has too many open descriptors.

 

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
Architectureall
AvailabilitySUNWcsr, SUNWhea
Interface StabilityEvolving
MT-LevelSafe

 

SEE ALSO

rctladm(1M), close(2), exit(2), fork(2), poll(2), setrctl(2), aio_read(3RT), aio_write(3RT), aio.h(3HEAD), lio_listio(3RT), port_get(3C), timer_create(3RT), attributes(5)


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
ERRORS
ATTRIBUTES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:37:21 GMT, October 02, 2010