logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git/

timeout.1 (2096B)

    

  1. .\" utils-std: Collection of commonly available Unix tools
  2. .\" Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
  3. .\" SPDX-License-Identifier: MPL-2.0
  4. .Dd June 18, 2025
  5. .Dt TIMEOUT 1
  6. .Os
  7. .Sh NAME
  8. .Nm timeout
  9. .Nd run a command with a time limit
  10. .Sh SYNOPSIS
  11. .Nm
  12. .Op Fl fp
  13. .Op Fl k Ar time
  14. .Op Fl s Ar SIGNAL
  15. .Ar duration
  16. .Ar command
  17. .Op Ar argument...
  18. .Sh DESCRIPTION
  19. The
  20. .Nm
  21. utility executes
  22. .Ar command ,
  23. and propagates any signal to it.
  24. And if still running after a non-zero value in the
  25. .Ar duration
  26. argument has elapsed, sends a
  27. .Dv SIGTERM
  28. to it.
  29. .Pp
  30. The
  31. .Ar duration
  32. argument and
  33. .Fl k Ar time
  34. option-argument
  35. accept non-negative decimal numbers including floats,
  36. each terminated by a suffix:
  37. .Sy s
  38. for seconds,
  39. .Sy m
  40. for minutes,
  41. .Sy h
  42. for hours,
  43. .Sy d
  44. for days.
  45. If the final number doesn't have a suffix it is assumed to be seconds.
  46. Longer durations are taken as out of scope.
  47. .Sh OPTIONS
  48. .Bl -tag -width __
  49. .It Fl f
  50. Disables killing child processes.
  51. .It Fl k Ar time
  52. Enables sending a
  53. .Dv SIGKILL
  54. after
  55. .Ar time
  56. has elapsed.
  57. .It Fl p
  58. Preserve (mimic) the wait status of
  59. .Ar command ,
  60. even after
  61. .Ar duration .
  62. .It Fl s Ar SIGNAL
  63. Signal to be sent instead of
  64. .Dv SIGTERM
  65. when the
  66. .Ar duration
  67. argument has elapsed.
  68. Signal may be a name like 'HUP' or 'SIGHUP', or a number like '9'.
  69. .Pp
  70. A list of signals may be obtained with
  71. .Cm kill
  72. .Fl l .
  73. .El
  74. .Sh EXIT STATUS
  75. The
  76. .Nm
  77. utility may return one of the following statuses:
  78. .Pp
  79. .Bl -tag -width 111 -compact
  80. .It 124
  81. Timeout reached
  82. .It 125
  83. Error within
  84. .Nm
  85. .It 126
  86. Failed to execute
  87. .Ar command
  88. .El
  89. .Pp
  90. Otherwise, the exit status of
  91. .Ar command
  92. is returned.
  93. .Sh SEE ALSO
  94. .Xr kill 1 ,
  95. .Xr sleep 1
  96. .Sh STANDARDS
  97. .Nm
  98. should be compliant with the
  99. IEEE Std 1003.1-2024 (“POSIX.1”)
  100. specification.
  101. .Pp
  102. Allowing multiple numbers separated by a suffix into
  103. .Ar duration
  104. and
  105. .Fl k Ar time
  106. is an extension.
  107. .Sh HISTORY
  108. A
  109. .Nm
  110. utility appeared in SATAN, Netatalk, GNU Coreutils 7.0,
  111. .Ox 7.0 ,
  112. .Nx 7.0 ,
  113. .Fx 10.3 ,
  114. and IEEE Std 1003.1-2024 (“POSIX.1”).
  115. .Sh AUTHORS
  116. .An Haelwenn (lanodan) Monnier Aq Mt contact+utils@hacktivis.me