exec 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. .TH EXEC 2
  2. .SH NAME
  3. exec, execl, _privates, _nprivates, _tos \- execute a file
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .nf
  10. .B
  11. void* exec(char *name, char* argv[])
  12. .PP
  13. .B
  14. void* execl(char *name, ...)
  15. .PP
  16. .B
  17. void **_privates;
  18. .PP
  19. .B
  20. int _nprivates;
  21. .PP
  22. .B
  23. #include <tos.h>
  24. .PP
  25. .ft L
  26. typedef struct Tos Tos;
  27. struct Tos {
  28. struct { ... } prof; /* profiling data */
  29. uvlong cyclefreq; /* cycle clock frequency */
  30. vlong kcycles; /* kernel cycles */
  31. vlong pcycles; /* process cycles (kernel + user) */
  32. ulong pid; /* process id */
  33. ulong clock; /* profiling clock */
  34. /* top of stack */
  35. };
  36. .PP
  37. .B
  38. extern Tos *_tos;
  39. .fi
  40. .SH DESCRIPTION
  41. .I Exec
  42. and
  43. .I execl
  44. overlay the calling process with the named file, then
  45. transfer to the entry point of the image of the file.
  46. .PP
  47. .I Name
  48. points to the name of the file
  49. to be executed; it must not be a directory, and the permissions
  50. must allow the current user to execute it
  51. (see
  52. .IR stat (2)).
  53. It should also be a valid binary image, as defined in the
  54. .IR a.out (6)
  55. for the current machine architecture,
  56. or a shell script
  57. (see
  58. .IR rc (1)).
  59. The first line of a
  60. shell script must begin with
  61. .L #!
  62. followed by the name of the program to interpret the file
  63. and any initial arguments to that program, for example
  64. .IP
  65. .EX
  66. #!/bin/rc
  67. ls | mc
  68. .EE
  69. .PP
  70. When a C program is executed,
  71. it is called as follows:
  72. .IP
  73. .EX
  74. void main(int argc, char *argv[])
  75. .EE
  76. .PP
  77. .I Argv
  78. is a copy of the array of argument pointers passed to
  79. .IR exec ;
  80. that array must end in a null pointer, and
  81. .I argc
  82. is the number of elements before the null pointer.
  83. By convention, the first argument should be the name of
  84. the program to be executed.
  85. .I Execl
  86. is like
  87. .I exec
  88. except that
  89. .I argv
  90. will be an array of the parameters that follow
  91. .I name
  92. in the call. The last argument to
  93. .I execl
  94. must be a null pointer.
  95. .PP
  96. For a file beginning
  97. .BR #! ,
  98. the arguments passed to the program
  99. .RB ( /bin/rc
  100. in the example above) will be the name of the file being
  101. executed, any arguments on the
  102. .B #!
  103. line, the name of the file again,
  104. and finally the second and subsequent arguments given to the original
  105. .I exec
  106. call.
  107. The result honors the two conventions of a program accepting as argument
  108. a file to be interpreted and
  109. .B argv[0]
  110. naming the file being
  111. executed.
  112. .PP
  113. Most attributes of the calling process are carried
  114. into the result; in particular,
  115. files remain open across
  116. .I exec
  117. (except those opened with
  118. .B OCEXEC
  119. OR'd
  120. into the open mode; see
  121. .IR open (2));
  122. and the working directory and environment
  123. (see
  124. .IR env (3))
  125. remain the same.
  126. However, a newly
  127. .I exec'ed
  128. process has no notification handler
  129. (see
  130. .IR notify (2)).
  131. .PP
  132. The global cell
  133. .B _privates
  134. points to an array of
  135. .B _nprivates
  136. elements of per-process private data.
  137. This storage is private for each process, even if the processes share data segments.
  138. .PP
  139. When the new program begins, the global pointer
  140. .B _tos
  141. is set to the address of a structure
  142. that holds information
  143. allowing accurate time keeping and clock reading in user space.
  144. If there is a user-space accessible fast clock (a processor
  145. cycle counter),
  146. .B cyclefreq
  147. will be set to its frequency in Hz.
  148. .B Kcycles
  149. .RB ( pcycles )
  150. counts the number of cycles
  151. this process has spent in kernel mode
  152. (kernel and user mode).
  153. .B Clock
  154. is the user-profiling clock (see
  155. .IR prof (1)).
  156. Its time is measured in milliseconds but is updated at
  157. a system-dependent lower rate.
  158. This clock is typically used by the profiler but is available
  159. to all programs.
  160. .PP
  161. The above conventions apply to C programs; the raw system
  162. interface to the new image is as follows:
  163. the word pointed to by the stack pointer is
  164. .BR argc ;
  165. the words beyond that are the zeroth and subsequent elements
  166. of
  167. .BR argv ,
  168. followed by a terminating null pointer; and
  169. the return register (e.g.
  170. .B R0
  171. on the 68020) contains the address of the clock information.
  172. .SH SOURCE
  173. .B /sys/src/libc/9syscall
  174. .br
  175. .B /sys/src/libc/port/execl.c
  176. .SH SEE ALSO
  177. .IR prof (1),
  178. .IR intro (2),
  179. .IR stat (2)
  180. .SH DIAGNOSTICS
  181. If these functions fail, they return and set
  182. .IR errstr .
  183. There can be no return to the calling process from a successful
  184. .I exec
  185. or
  186. .IR execl ;
  187. the calling image is lost.