1
0

proc 12 KB

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