wait 2.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  1. .TH WAIT 2
  2. .SH NAME
  3. await, wait, waitpid \- wait for a process to exit
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .B
  10. Waitmsg* wait(void)
  11. .PP
  12. .B
  13. int waitpid(void)
  14. .PP
  15. .B
  16. int await(char *s, int n)
  17. .SH DESCRIPTION
  18. .I Wait
  19. causes a process to wait for any child process (see
  20. .IR fork (2))
  21. to exit.
  22. It returns a
  23. .B Waitmsg
  24. holding
  25. information about the exited child.
  26. A
  27. .B Waitmsg
  28. has this structure:
  29. .IP
  30. .EX
  31. .ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u
  32. typedef
  33. struct Waitmsg
  34. {
  35. int pid; /* of loved one */
  36. ulong time[3]; /* of loved one & descendants */
  37. char *msg;
  38. } Waitmsg;
  39. .EE
  40. .PP
  41. .B Pid
  42. is the child's
  43. process id.
  44. The
  45. .B time
  46. array contains the time the child and its descendants spent in user code,
  47. the time spent in system calls, and the child's elapsed real time,
  48. all in units of milliseconds.
  49. .B Msg
  50. contains the message that the child specified in
  51. .IR exits (2).
  52. For a normal exit,
  53. .B msg[0]
  54. is zero,
  55. otherwise
  56. .B msg
  57. is the exit string
  58. prefixed by the process name, a blank, the process id, and a colon.
  59. .PP
  60. If there are no more children to wait for,
  61. .I wait
  62. returns immediately, with return value nil.
  63. .PP
  64. The
  65. .B Waitmsg
  66. structure is allocated by
  67. .IR malloc (2)
  68. and should be freed after use.
  69. For programs that only need the pid of the exiting program,
  70. .I waitpid
  71. returns just the pid and discards the rest of the information.
  72. .PP
  73. The underlying system call is
  74. .IR await ,
  75. which fills in the n-byte buffer
  76. .I s
  77. with a textual representation of the pid, times, and exit string.
  78. There is no terminal NUL.
  79. The return value is the length, in bytes, of the data.
  80. .PP
  81. The buffer filled in by
  82. .I await
  83. may be parsed (after appending a NUL) using
  84. .IR tokenize
  85. (see
  86. .IR getfields (2));
  87. the resulting fields are, in order, pid, the three times, and the exit string,
  88. which will be
  89. .B ''
  90. for normal exit.
  91. If the representation is longer than
  92. .I n
  93. bytes, it is truncated but, if possible, properly formatted.
  94. The information that does not fit in the buffer is discarded, so
  95. a subsequent call to
  96. .I await
  97. will return the information about the next exiting child, not the remainder
  98. of the truncated message.
  99. In other words, each call to
  100. .I await
  101. returns the information about one child, blocking if necessary if no child has exited.
  102. If the calling process has no living children,
  103. .I await
  104. returns
  105. .BR -1 .
  106. .SH SOURCE
  107. .B /sys/src/libc/9syscall
  108. .SH "SEE ALSO"
  109. .IR fork (2),
  110. .IR exits (2),
  111. the
  112. .B wait
  113. file in
  114. .IR proc (3)
  115. .SH DIAGNOSTICS
  116. These routines set
  117. .IR errstr .