proc 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494
  1. .TH PROC 3
  2. .SH NAME
  3. proc \- running processes
  4. .SH SYNOPSIS
  5. .nf
  6. .B bind #p /proc
  7. .B /proc/trace
  8. .BI /proc/ n /args
  9. .BI /proc/ n /ctl
  10. .BI /proc/ n /fd
  11. .BI /proc/ n /fpregs
  12. .BI /proc/ n /kregs
  13. .BI /proc/ n /mem
  14. .BI /proc/ n /note
  15. .BI /proc/ n /noteid
  16. .BI /proc/ n /notepg
  17. .BI /proc/ n /ns
  18. .BI /proc/ n /proc
  19. .BI /proc/ n /profile
  20. .BI /proc/ n /regs
  21. .BI /proc/ n /segment
  22. .BI /proc/ n /status
  23. .BI /proc/ n /text
  24. .BI /proc/ n /wait
  25. \&...
  26. .fi
  27. .SH DESCRIPTION
  28. The
  29. .I proc
  30. device serves a two-level directory structure.
  31. The first level contains the
  32. .B trace
  33. file (see below) and numbered directories
  34. corresponding to pids of live processes;
  35. each such directory contains a set of files
  36. representing the corresponding process.
  37. .PP
  38. The
  39. .B mem
  40. file contains the current memory image of the process.
  41. A read or write at offset
  42. .IR o ,
  43. which must be a valid virtual address,
  44. accesses bytes from address
  45. .IR o
  46. up to the end of the memory segment containing
  47. .IR o .
  48. Kernel virtual memory, including the kernel stack for the process and
  49. saved user registers (whose addresses are machine-dependent),
  50. can be accessed through
  51. .BR mem .
  52. Writes are permitted only while the process is in the
  53. .B Stopped
  54. state and only to user addresses or registers.
  55. .PP
  56. The read-only
  57. .B proc
  58. file contains the kernel per-process
  59. structure.
  60. Its main use is to recover the kernel stack and program counter
  61. for kernel debugging.
  62. .PP
  63. The files
  64. .BR regs ,
  65. .BR fpregs ,
  66. and
  67. .BR kregs
  68. hold representations of the user-level registers, floating-point registers,
  69. and kernel registers in machine-dependent form.
  70. The
  71. .B kregs
  72. file is read-only.
  73. .PP
  74. The read-only
  75. .B fd
  76. file lists the open file descriptors of the process.
  77. The first line of the file is its current directory; subsequent lines list, one per line,
  78. the open files, giving the decimal file descriptor number; whether the file is open for read
  79. .RB ( r ),
  80. write,
  81. .RB ( w ),
  82. or both
  83. .RB ( rw );
  84. the type, device number, and qid of the file; its I/O unit (the amount of data
  85. that may be transferred on the file as a contiguous piece; see
  86. .IR iounit (2)),
  87. its I/O offset; and its name at the time it was opened.
  88. .PP
  89. The read-only
  90. .B ns
  91. file contains a textual representation of the process's file name space, in the format of
  92. .IR namespace (6)
  93. accepted by
  94. .B newns
  95. (see
  96. .IR auth (2)).
  97. The last line of the file identifies the current working directory of the process, in the form of a
  98. .B cd
  99. command
  100. (see
  101. .IR rc (1)).
  102. The information in this file is based on the names files had when the name space was assembled,
  103. so the names it contains may be inaccessible if the files have been subsequently renamed or rearranged.
  104. .PP
  105. The read-only
  106. .B segment
  107. file contains a textual display of the memory segments
  108. attached to the process. Each line has multiple fields:
  109. the type of segment (\c
  110. .BR Stack ,
  111. .BR Text ,
  112. .BR Data ,
  113. .BR Bss ,
  114. etc.); one-letter flags such as
  115. .B R
  116. for read-only, if any;
  117. starting virtual address, in hexadecimal;
  118. ending virtual address, and reference count.
  119. .PP
  120. The read-only
  121. .B status
  122. file contains a string with twelve fields, each followed by a space.
  123. The fields are:
  124. .IP \-
  125. the process name and user name, each 27 characters left justified
  126. .IP \-
  127. the process state, 11 characters left justified (see
  128. .IR ps (1))
  129. .IP \-
  130. the six 11-character numbers also held in the process's
  131. .B #c/cputime
  132. file
  133. .IP \-
  134. the amount of memory used by the process, except its stack,
  135. in units of 1024 bytes
  136. .IP \-
  137. the base and current scheduling priority, each 11 character numbers
  138. .PP
  139. The read-only
  140. .B args
  141. file contains the arguments of the program when it was created by
  142. .IR exec (2).
  143. If the program was not created by
  144. .BR exec ,
  145. such as by
  146. .IR fork (2),
  147. its
  148. .B args
  149. file will be empty.
  150. The format of the file is a list of quoted strings suitable for
  151. .BR tokenize ;
  152. see
  153. .IR getfields (2).
  154. .PP
  155. The
  156. .B text
  157. file is a pseudonym for the file
  158. from which the process was executed;
  159. its main use is to recover the symbol table of the process.
  160. .PP
  161. The
  162. .B wait
  163. file may be read to recover
  164. records from the exiting children of the process in the format of
  165. .B await
  166. (see
  167. .IR wait (2)).
  168. If the process has no extant children, living or exited,
  169. a read of
  170. .B wait
  171. will block.
  172. It is an error for a process to attempt to read its own
  173. .B wait
  174. file when it has no children.
  175. When a process's
  176. .B wait
  177. file is being read,
  178. the process will draw an error
  179. if it attempts an
  180. .B await
  181. system call; similarly, if a process is in an
  182. .B await
  183. system call, its
  184. .B wait
  185. file cannot be read by any process.
  186. .PP
  187. Textual messages written to the
  188. .B ctl
  189. file control the execution of the process.
  190. Some require that the process is in a particular state
  191. and return an error if it is not.
  192. .TP 10n
  193. .B stop
  194. Suspend execution of the process, putting it in the
  195. .B Stopped
  196. state.
  197. .TP 10n
  198. .B start
  199. Resume execution of a
  200. .B Stopped
  201. process.
  202. .TP 10n
  203. .B waitstop
  204. Do not affect the process directly but, like all other messages ending with
  205. .BR stop ,
  206. block the process writing the
  207. .B ctl
  208. file until the target process is in the
  209. .B Stopped
  210. state or exits.
  211. Also like other
  212. .B stop
  213. control messages,
  214. if the target process would receive a note while the message is pending,
  215. it is instead stopped and the debugging process is resumed.
  216. .TP 10n
  217. .B startstop
  218. Allow a
  219. .B Stopped
  220. process to resume, and then do a
  221. .B waitstop
  222. action.
  223. .TP 10n
  224. .B hang
  225. Set a bit in the process so that,
  226. when it completes an
  227. .IR exec (2)
  228. system call, it will enter the
  229. .B Stopped
  230. state before returning to user mode.
  231. This bit is inherited across
  232. .IR fork (2)
  233. and
  234. .IR exec (2).
  235. .TP 10n
  236. .B "close\ \fIn
  237. Close file descriptor
  238. .I n
  239. in the process.
  240. .TP 10n
  241. .B closefiles
  242. Close all open file descriptors in the process.
  243. .TP 10n
  244. .B nohang
  245. Clear the hang bit.
  246. .TP 10n
  247. .B noswap
  248. Don't allow this process to be swapped out. This should
  249. be used carefully and sparingly or the system could run
  250. out of memory. It is meant for processes that can't be
  251. swapped, like the ones implementing the swap device and for
  252. processes containing sensitive data.
  253. .TP 10n
  254. .B kill
  255. Kill the process the next time it crosses the user/kernel boundary.
  256. .TP 10n
  257. .B private
  258. Make it impossible to read the process's user memory.
  259. This property is inherited on fork, cleared on
  260. .IR exec (2),
  261. and is not otherwise resettable.
  262. .TP 10n
  263. .B "pri\ \fIn
  264. Set the base priority for the process to the integer
  265. .IR n .
  266. .TP 10n
  267. .B "wired\ \fIn
  268. Wire the process to processor
  269. .IR n .
  270. .TP 10n
  271. .B trace
  272. Without an argument, toggle trace event generation for this process into
  273. .B /proc/trace
  274. (see below).
  275. With a zero argument, tracing for the proc is turned off, with a non-zero numeric
  276. argument, it is turned on.
  277. .TP 10n
  278. .B "period\ \fInu
  279. Set the real-time scheduling period of the process to
  280. .IR nu ,
  281. where
  282. .I n
  283. is an optionally signed number containing an optional decimal point and
  284. .I u
  285. is one of
  286. .BR s ,
  287. .BR ms ,
  288. .BR us ,
  289. .BR µs ,
  290. .BR ns ,
  291. or
  292. empty. The time is interpreted, respectively, as
  293. .IR seconds ,
  294. .IR milliseconds ,
  295. .IR microseconds ,
  296. .IR microseconds ,
  297. .IR nanoseconds ,
  298. or, in the case of an absent units specifier, as
  299. .IR nanoseconds .
  300. If the time specifier is signed, it is interpreted as an increment or decrement
  301. from a previously set value. See also the
  302. .B admit
  303. command below.
  304. .TP 10n
  305. .B "deadline\ \fInu
  306. Set the real-time deadline interval of the process to
  307. .IR nu ,
  308. where
  309. .I n
  310. and
  311. .I u
  312. are interpreted as for
  313. .B period
  314. above.
  315. .TP 10n
  316. .B "cost\ \fInu
  317. Set the real-time cost (maximum CPU time per period) of the process to
  318. .IR nu ,
  319. where
  320. .I n
  321. and
  322. .I u
  323. are interpreted as for
  324. .B period
  325. above.
  326. .TP 10n
  327. .B "sporadic
  328. Use sporadic scheduling for the real-time process. The description of the
  329. .B admit
  330. command below contains further details.
  331. .TP 10n
  332. .B "yieldonblock
  333. Make the real-time process yield on blocking I/O.
  334. The description of the
  335. .B admit
  336. command below contains further details.
  337. .TP 10n
  338. .B "admit
  339. Given real-time
  340. .IR period ,
  341. .I deadline
  342. and
  343. .I cost
  344. are set (an unset
  345. .I deadline
  346. will set
  347. .I deadline
  348. to
  349. .IR period ),
  350. perform a schedulability test and start scheduling the process as a real-time
  351. process if the test succeeds. If the test fails, the
  352. .B write
  353. will fail with error set to the reason for failure. For details on real time, read on.
  354. .PP
  355. Real-time processes are periodically
  356. .IR released ,
  357. giving them a higher priority than non-real-time processes until they either
  358. give up the processor voluntarily, they exhaust their CPU allocation, or they reach their
  359. .IR deadline .
  360. The moment of release is dictated by the
  361. .I period
  362. and whether the process is
  363. .I sporadic
  364. or not.
  365. Non-sporadic processes are called
  366. .I periodic
  367. and they are released precisely at intervals of their period (but periods can be skipped
  368. if the process blocks on I/O). Sporadic processes are released whenever they become
  369. runnable (after being blocked by
  370. .IR sleep ()
  371. or I/O), but always at least an interval of
  372. .I period
  373. after the previous release.
  374. .PP
  375. The
  376. .I deadline
  377. of a real-time process specifies that the process must complete within the first
  378. .I deadline
  379. seconds of its
  380. .IR period .
  381. The dealine must be less than or equal to the period. If it is not specified, it is set to the period.
  382. .PP
  383. The
  384. .I cost
  385. of a real-time process describes the maximum CPU time the process may use per period.
  386. .PP
  387. A real-time process can give up the CPU before its deadline is reached or its allocation is exhausted.
  388. It does this by calling
  389. .IR sleep (0).
  390. If
  391. .I yieldonblock
  392. is specified, it also does it by executing any blocking system call.
  393. .I Yieldonblock
  394. is assumed for
  395. .I sporadic
  396. processes.
  397. .PP
  398. Of the released processes, the one with the earliest deadline has the highest priority.
  399. Care should be taken using spin locks (see
  400. .IR lock (2))
  401. because a real-time process spinning on a lock will not give up the processor until
  402. its CPU allocation is exhausted; this is unlikely to be the desired behavior.
  403. .PP
  404. When a real-time process reaches its deadline or exhausts its CPU allocation, it remains
  405. schedulable, but at a very low priority.
  406. .PP
  407. The priority is interpreted by Plan 9's multilevel process scheduler.
  408. Priorities run from 0 to 19, with higher
  409. numbers representing higher priorities.
  410. A process has a base priority and
  411. a running priority which is less than or equal to the base priority.
  412. As a process uses up more of its allocated time, its priority is lowered.
  413. Unless
  414. explicitly set, user processes have base priority 10, kernel processes
  415. 13.
  416. Children inherit the parent's base priority.
  417. .PP
  418. The read-only
  419. .B profile
  420. file contains the instruction frequency count information used for multiprocess profiling; see
  421. .B tprof
  422. in
  423. .IR prof (1).
  424. The information is gleaned by sampling the program's user-level program counter
  425. at interrupt time.
  426. .PP
  427. Strings written to the
  428. .B note
  429. file will be posted as a note to the process
  430. (see
  431. .IR notify (2)).
  432. The note should be less than
  433. .B ERRLEN-1
  434. characters long;
  435. the last character is reserved for a terminating NUL character.
  436. A read of at least
  437. .B ERRLEN
  438. characters will retrieve the oldest note posted to the
  439. process and prevent its delivery to the process.
  440. The
  441. .B notepg
  442. file is similar, but the note will be delivered to all the
  443. processes in the target process's
  444. .I note group
  445. (see
  446. .IR fork (2)).
  447. However, if the process doing the write is in the group,
  448. it will not receive the note.
  449. The
  450. .B notepg
  451. file is write-only.
  452. .PP
  453. The textual
  454. .B noteid
  455. file may be read to recover an integer identifying the note group of the process
  456. (see
  457. .B RFNOTEG
  458. in
  459. .IR fork (2)).
  460. The file may be written to cause the process to change to another note group,
  461. provided the group exists and is owned by the same user.
  462. .PP
  463. The file
  464. .B /proc/trace
  465. can be opened once and read to see trace events from processes that have
  466. had the string
  467. .B trace
  468. written to their
  469. .B ctl
  470. file.
  471. Each event produces, in native machine format, the
  472. .IR pid ,
  473. a
  474. .IR type ,
  475. and a
  476. .I "time stamp"
  477. (see
  478. .B /sys/include/trace.h
  479. and
  480. .BR /sys/src/cmd/trace.c ).
  481. .SH FILES
  482. .nf
  483. .B /sys/src/9/*/mem.h
  484. .B /sys/src/9/*/dat.h
  485. .B /sys/include/trace.h
  486. .fi
  487. .SH SEE ALSO
  488. .IR trace (1),
  489. .IR debugger (2),
  490. .IR mach (2),
  491. .IR cons (3)
  492. .SH SOURCE
  493. .B /sys/src/9/port/devproc.c