474 lines
13 KiB
HTML
474 lines
13 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>qtoq_ioctl()--Set QoS Sockets Control Options API</title>
|
||
|
|
<!-- Begin Header Records -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Created by John Hall and Dale LeFevre for V5R2 -->
|
||
|
|
<!-- File tagging cleanup completed Mar 2002 by v2cdijab -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>qtoq_ioctl()--Set QoS Sockets Control Options API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <qtoqsapi.h>
|
||
|
|
|
||
|
|
int qtoq_ioctl(
|
||
|
|
int descriptor,
|
||
|
|
int req_type,
|
||
|
|
qos_req *qos_data,
|
||
|
|
unsigned int *qos_session,
|
||
|
|
int *qos_descriptor,
|
||
|
|
)
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program Name: QSYS/QTOQSAPI<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *EXCLUDE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>qtoq_ioctl()</strong> API provides simplified Quality of Service
|
||
|
|
functionality for connectionless sockets communications between RSVP aware
|
||
|
|
applications on a client and server. This API can be used to initiate RSVP
|
||
|
|
signaling, as well as to determine the status of the RSVP connection. The NO
|
||
|
|
SIGNALLING option for loading RSVP rules also is supported.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong><em>descriptor</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>An opened socket descriptor that has been bound to the IP address and port
|
||
|
|
that the application will use for connectionless communications.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>req_type</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>The type of QoS service being requested. The possible values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="30 70" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>REQ_SIGNAL_RET_EVENTS(1)</em></td>
|
||
|
|
<td align="left" valign="top">Use normal RSVP signaling and return RSVP events
|
||
|
|
to the calling program.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>REQ_SIGNAL_NORET_EVENTS(2)</em></td>
|
||
|
|
<td align="left" valign="top">Use normal RSVP signaling without returning
|
||
|
|
events to the calling program.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>REQ_NOSIGNAL(3)</em></td>
|
||
|
|
<td align="left" valign="top">Load specified QoS policy if admission control
|
||
|
|
allows it.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>REQ_GET_RSVP_DATA(4)</em></td>
|
||
|
|
<td align="left" valign="top">Get the RSVP flowspec that has been returned as
|
||
|
|
the result of an RSVP event. This request is valid only if a previous
|
||
|
|
REQ_SIGNAL_RET_EVENTS request has been sent to the server.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_data</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>Pointer to a <samp>qos_req</samp> data structure that defines the type of
|
||
|
|
service being requested and the source and destination addresses of the
|
||
|
|
request.</p>
|
||
|
|
|
||
|
|
<p>The <samp>qos_req</samp> data structure is defined below:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
int service; ; /* Values can be GUARANTEED_SERV (2)
|
||
|
|
or CONTROLLED_LOAD_SERV (5) */
|
||
|
|
union
|
||
|
|
{
|
||
|
|
struct CL_spec /* Controlled-Load service */
|
||
|
|
{
|
||
|
|
float TB_Tspec_r; /* token bucket rate in bytes/sec */
|
||
|
|
float TB_Tspec_b; /* token bucket depth in bytes */
|
||
|
|
float TB_Tspec_p; /* token bucket peak in bytes/sec */
|
||
|
|
unsigned long TB_Tspec_m; /* min policed unit in bytes */
|
||
|
|
unsigned long TB_Tspec_M; /* max packet size in bytes */
|
||
|
|
} CL_spec;
|
||
|
|
struct Guar_spec /* Guaranteed service */
|
||
|
|
{
|
||
|
|
float Guar_R; /* guaranteed rate in bytes/sec */
|
||
|
|
unsigned long Guar_S; /* slack term in microsecs */
|
||
|
|
} Guar_spec;
|
||
|
|
} spec_u;
|
||
|
|
} qos_spec_t;
|
||
|
|
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
struct sockaddr dest; /* Destination address/port */
|
||
|
|
int d_length; /* Destination address length*/
|
||
|
|
struct sockaddr source; /* Source address/port */
|
||
|
|
int s_length; /* Source address length */
|
||
|
|
int style; /* Style of Reservation. */
|
||
|
|
qos_spec_t Spec; /* Flow info */
|
||
|
|
unsigned char result; /* API status */
|
||
|
|
} qos_req; /* End of QoS request structure */
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_session</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) Required
|
||
|
|
|
||
|
|
<p>Pointer to an integer value where the unique QoS session ID can be stored.
|
||
|
|
This ID is required for all future QoS API calls.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_descriptor</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) Optional
|
||
|
|
|
||
|
|
<p>Pointer to an integer where the value of the descriptor that the application
|
||
|
|
can wait on for RSVP events is stored. this value is set to NULL if it is not
|
||
|
|
used.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Values</h3>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">if successful.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
|
<td align="left" valign="top">if function failed. Errno indicates error
|
||
|
|
reason.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When this function call fails, the errno value is set to one of the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[EACCES]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Permission denied. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The process does not have the appropriate privileges to connect to the
|
||
|
|
address pointed to by the <strong><em>destination_address</em></strong>
|
||
|
|
parameter.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The socket pointed to by <strong><em>socket_descriptor</em></strong> is
|
||
|
|
using a connection-oriented transport service, and the <strong><em>
|
||
|
|
destination_address</em></strong> parameter specifies a TCP/IP limited
|
||
|
|
broadcast address (internet address of all ones).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EADDRINUSE]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Address already in use. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The <strong><em>socket_descriptor</em></strong> parameter points to a
|
||
|
|
connection-oriented socket that has been bound to a local address that
|
||
|
|
contained no wildcard values, and the <strong><em>
|
||
|
|
destination_address</em></strong> parameter specified an address that matched
|
||
|
|
the bound address.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <strong><em>socket_descriptor</em></strong> parameter points to a
|
||
|
|
socket that has been bound to a local address that contained no wildcard
|
||
|
|
values, and the <strong><em>destination_address</em></strong> parameter (also
|
||
|
|
containing no wildcard values) specified an address that would have resulted in
|
||
|
|
a connection with an association that is not unique.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EADDRNOTAVAIL]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Address not available. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The socket_descriptor parameter points to a socket with an address family
|
||
|
|
of AF_INET and either a port was not available or a route to the address
|
||
|
|
specified by the destination_address parameter could not be found.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EAFNOSUPPORT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>The type of socket is not supported in this protocol family. The address
|
||
|
|
family specified in the address structure pointed to by <strong><em>
|
||
|
|
destination_address</em></strong> parameter cannot be used with the socket
|
||
|
|
pointed to by the <strong><em>socket_descriptor</em></strong> parameter. This
|
||
|
|
error also will be reported if the API is called with a socket type that is not
|
||
|
|
AF_INET and SOCK_DGRAM or SOCK_STREAM.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EALREADY]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation already in progress. A previous connect() function had already
|
||
|
|
been issued for the socket pointed to by the socket_descriptor parameter, and
|
||
|
|
has yet to be completed. This error code is returned only on sockets that use a
|
||
|
|
connection-oriented transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EBADF]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Descriptor not valid.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ECONNREFUSED]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>The destination socket refused an attempted connect operation. This error
|
||
|
|
occurs when there is no application that is bound to the address specified by
|
||
|
|
the destination_address parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EFAULT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Bad address. The system detected an address which was not valid while
|
||
|
|
attempting to access the destination_address parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EHOSTUNREACH]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A route to the remote host is not available.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINPROGRESS]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation in progress. The socket_descriptor parameter points to a socket
|
||
|
|
that is marked as non blocking and the connection could not be completed
|
||
|
|
immediately. This error code is returned only on sockets that use a
|
||
|
|
connection-oriented transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINTR]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Interrupted function call.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINVAL]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Parameter not valid. This error code indicates one of the following:</p>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The address_length parameter specifies a length that is negative or not
|
||
|
|
valid for the address family.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The AF_INET socket is of type SOCK_STREAM, and a previous connect() has
|
||
|
|
already completed unsuccessfully. Only one connection attempt is allowed on a
|
||
|
|
connection-oriented socket.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EIO]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Input/output error.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EISCONN]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A connection has already been established.</p>
|
||
|
|
|
||
|
|
<p>This error code is returned only on sockets that use a connection-oriented
|
||
|
|
transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENETUNREACH]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Cannot reach the destination network. This error code indicates the
|
||
|
|
following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>For sockets that use the AF_INET address family, the address specified by
|
||
|
|
the destination_address parameter requires the use of a router, and the socket
|
||
|
|
option SO_DONTROUTE is currently set on.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOBUFS]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>There is not enough buffer space for the requested operation.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOTDIR]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Not a directory.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EOPNOTSUPP]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation not supported.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ETIMEDOUT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A remote host did not respond within the timeout period. This error code is
|
||
|
|
returned when connection establishment times out. No connection is established.
|
||
|
|
A possible cause may be that the partner application is bound to the address
|
||
|
|
specified by the destination_address parameter, but the partner application has
|
||
|
|
not yet issued a listen().</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Unknown system state.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNATCH]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>The protocol required to support the specified address family is not
|
||
|
|
available at this time.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EPROTO]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>An underlying protocol error has occurred.</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPE3418 E</td>
|
||
|
|
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
|
&2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFA081 E</td>
|
||
|
|
<td align="left" valign="top">Unable to set return value or error code.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>The application program can choose to be signaled when RSVP events occur or
|
||
|
|
it can choose to allow the QoS server to handle the events. If the server
|
||
|
|
handles the events, the application program will not be informed if the RSVP
|
||
|
|
signaling failed or if the requested reservations was changed by the
|
||
|
|
network.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<p>For a description of the RSVP protocol, see RFC 2205 on the RFC Pages for <a
|
||
|
|
href="http://www.ietf.org/rfc.html">The Internet Engineering Task
|
||
|
|
Force</a>.<img src="www.gif" alt="Link outside Information Center"></p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R2
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|