share/man/man3dlpi/dlpi_set_timeout.3dlpi

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DLPI_SET_TIMEOUT 3DLPI "Aug 21, 2007"
   7 .SH NAME
   8 dlpi_set_timeout \- set DLPI handle timeout interval
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldlpi\fR [ \fIlibrary\fR ... ]
  13 #include <libdlpi.h>
  14
  15 \fBint\fR \fIdlpi_set_timeout\fR(\fBdlpi_handle_t\fR \fIdh\fR, \fBint\fR \fIsec\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBdlpi_set_timeout()\fR function sets the timeout interval to \fIsec\fR
  22 seconds on DLPI handle \fIdh\fR. This timeout is used by \fBlibdlpi\fR(3LIB)
  23 functions that require explicit acknowledgment from the associated DLPI link,
  24 and bounds the number of seconds that a function will wait for an
  25 acknowledgment before returning \fBDLPI_ETIMEDOUT\fR. Except for
  26 \fBdlpi_recv\fR(3DLPI), which has a \fItimeout\fR argument, any function that
  27 is documented to return \fBDLPI_ETIMEDOUT\fR can take up to the \fItimeout\fR
  28 interval to complete.
  29 .sp
  30 .LP
  31 Callers that do not require an upper bound on timeouts are strongly encouraged
  32 to never call \fBdlpi_set_timeout()\fR, and allow \fBlibdlpi\fR to use its
  33 default \fItimeout\fR value. The default \fItimeout\fR value is intended to
  34 ensure that \fBDLPI_ETIMEDOUT\fR will only be returned if the DLPI link has
  35 truly become unresponsive. The default \fItimeout\fR value is intended to
  36 ensure that \fBDLPI_ETIMEDOUT\fR will be returned only if the DLPI link has
  37 truly become unresponsive.
  38 .sp
  39 .LP
  40 Callers that do require an explicit upper bound can specify that value at any
  41 time by calling \fBdlpi_set_timeout()\fR.  However, note that values less than
  42 5 seconds may trigger spurious failures on certain DLPI links and systems under
  43 high load, and thus are discouraged. Attempts to set the \fItimeout\fR value to
  44 less than 1 second will fail.
  45 .sp
  46 .LP
  47 If \fIsec\fR is set to \fBDLPI_DEF_TIMEOUT\fR, the default \fItimeout\fR value
  48 is restored.
  49 .SH RETURN VALUES
  50 .sp
  51 .LP
  52 Upon success, \fBDLPI_SUCCESS\fR is returned. Otherwise, a \fBDLPI\fR error
  53 value is returned.
  54 .SH ERRORS
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBDLPI_EINHANDLE\fR\fR
  59 .ad
  60 .RS 18n
  61 Invalid \fBDLPI\fR handle
  62 .RE
  63
  64 .SH ATTRIBUTES
  65 .sp
  66 .LP
  67 See \fBattributes\fR(5) for description of the following attributes:
  68 .sp
  69
  70 .sp
  71 .TS
  72 box;
  73 c | c
  74 l | l .
  75 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  76 _
  77 Interface Stability     Committed
  78 _
  79 MT-Level        Safe
  80 .TE
  81
  82 .SH SEE ALSO
  83 .sp
  84 .LP
  85 \fBlibdlpi\fR(3LIB), \fBattributes\fR(5)