share/man/man3c/ualarm.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The Berkeley software License Agreement specifies the terms and conditions
  28 .\" for redistribution.
  29 .\"
  30 .\"
  31 .\" Copyright (c) 1980 Regents of the University of California.
  32 .\" All rights reserved.
  33 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  34 .\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved.
  35 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  36 .\"
  37 .Dd "Aug 16, 2014"
  38 .Dt UALARM 3C
  39 .Os
  40 .Sh NAME
  41 .Nm ualarm
  42 .Nd schedule signal after interval in microseconds
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft useconds_t
  46 .Fn ualarm "useconds_t useconds" "useconds_t interval"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn ualarm
  50 function causes the
  51 .Dv SIGALRM
  52 signal to be generated for
  53 the calling process after the number of real-time microseconds specified by the
  54 .Fa useconds
  55 argument has elapsed.
  56 When the
  57 .Fa interval
  58 argument is
  59 non-zero, repeated timeout notification occurs with a period in microseconds
  60 specified by the
  61 .Fa interval
  62 argument.
  63 If the notification signal,
  64 .Dv SIGALRM ,
  65 is not caught or ignored, the calling process is terminated.
  66 .Lp
  67 Because of scheduling delays, resumption of execution when the signal is caught
  68 may be delayed an arbitrary amount of time.
  69 .Lp
  70 Interactions between
  71 .Fn ualarm
  72 and either
  73 .Xr alarm 2
  74 or
  75 .Xr sleep 3C
  76 are unspecified.
  77 .Sh RETURN VALUES
  78 The
  79 .Fn ualarm
  80 function returns the number of microseconds remaining from
  81 the previous
  82 .Fn ualarm
  83 call.
  84 If no timeouts are pending or if
  85 .Fn ualarm
  86 has not previously been called,
  87 .Fn ualarm
  88 returns 0.
  89 .Sh ERRORS
  90 No errors are defined.
  91 .Sh USAGE
  92 The
  93 .Fn ualarm
  94 function is a simplified interface to
  95 .Xr setitimer 2 ,
  96 and uses the
  97 .Dv ITIMER_REAL
  98 interval timer.
  99 It's use has been deprecated in favor of the
 100 .Xr timer_create 3C
 101 family of functions.
 102 .Sh INTERFACE STABILITY
 103 .Sy Obsolete Standard .
 104 .Sh SEE ALSO
 105 .Xr alarm 2 ,
 106 .Xr setitimer 2 ,
 107 .Xr sighold 3C ,
 108 .Xr signal 3C ,
 109 .Xr sleep 3C ,
 110 .Xr timer_create 3C ,
 111 .Xr usleep 3C ,
 112 .Xr unistd.h 3HEAD ,
 113 .Xr standards 5
 114 .Sh STANDARDS
 115 The
 116 .Fn ualarm
 117 function is available in the following compilation environments.
 118 See
 119 .Xr standards 5 .
 120 .Lp
 121 .Bl -bullet -compact
 122 .\".It
 123 .\".St -p1003.1-90
 124 .\".It
 125 .\".St -p1003.1b-93
 126 .\".It
 127 .\".St -p1003.1c-95
 128 .\".It
 129 .\".St -p1003.1-2001
 130 .\".It
 131 .\".St -xpg3
 132 .\".It
 133 .\".St -xpg4
 134 .It
 135 .St -xpg4.2
 136 .It
 137 .St -susv2
 138 .It
 139 .St -susv3
 140 .El
 141 .Lp
 142 It is marked obsolete in
 143 .St -susv3 , and was removed from
 144 .St -p1003.1-2008 .