/share/man/man5/procfs.5

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 277 lines · 277 code · 0 blank · 0 comment · 0 complexity · 7c769c31b8d8ea887dc7df976b0f8d6f MD5 · raw file

  1. .\" $FreeBSD$
  2. .\" Written by Garrett Wollman
  3. .\" This file is in the public domain.
  4. .\"
  5. .Dd September 22, 2009
  6. .Dt PROCFS 5
  7. .Os
  8. .Sh NAME
  9. .Nm procfs
  10. .Nd process file system
  11. .Sh SYNOPSIS
  12. .Bd -literal
  13. proc /proc procfs rw 0 0
  14. .Ed
  15. .Sh DESCRIPTION
  16. The process file system, or
  17. .Nm ,
  18. implements a view of the system process table inside the file system.
  19. It is normally mounted on
  20. .Pa /proc ,
  21. and is required for the complete operation of programs such as
  22. .Xr ps 1
  23. and
  24. .Xr w 1 .
  25. .Pp
  26. The
  27. .Nm
  28. provides a two-level view of process space, unlike the previous
  29. .Fx 1.1
  30. .Nm
  31. implementation.
  32. At the highest level, processes themselves are named, according to
  33. their process ids in decimal, with no leading zeros.
  34. There is also a
  35. special node called
  36. .Pa curproc
  37. which always refers to the process making the lookup request.
  38. .Pp
  39. Each node is a directory which contains the following entries:
  40. .Pp
  41. Each directory contains several files:
  42. .Bl -tag -width status
  43. .It Pa ctl
  44. a write-only file which supports a variety
  45. of control operations.
  46. Control commands are written as strings to the
  47. .Pa ctl
  48. file.
  49. The control commands are:
  50. .Bl -tag -width detach -compact
  51. .It attach
  52. stops the target process and arranges for the sending
  53. process to become the debug control process.
  54. .It detach
  55. continue execution of the target process and
  56. remove it from control by the debug process (which
  57. need not be the sending process).
  58. .It run
  59. continue running the target process until
  60. a signal is delivered, a breakpoint is hit, or the
  61. target process exits.
  62. .It step
  63. single step the target process, with no signal delivery.
  64. .It wait
  65. wait for the target process to come to a steady
  66. state ready for debugging.
  67. The target process must be in this state before
  68. any of the other commands are allowed.
  69. .El
  70. .Pp
  71. The string can also be the name of a signal, lower case
  72. and without the
  73. .Dv SIG
  74. prefix,
  75. in which case that signal is delivered to the process
  76. (see
  77. .Xr sigaction 2 ) .
  78. .Pp
  79. The
  80. .Xr procctl 8
  81. utility can be used to clear tracepoints in a stuck process.
  82. .It Pa dbregs
  83. The debug registers as defined by
  84. .Dv "struct dbregs"
  85. in
  86. .In machine/reg.h .
  87. .Pa dbregs
  88. is currently only implemented on the i386 architecture.
  89. .It Pa etype
  90. The type of the executable referenced by the
  91. .Pa file
  92. entry.
  93. .It Pa file
  94. A symbolic link to the file from which the process text was read.
  95. This can be used to gain access to the process' symbol table,
  96. or to start another copy of the process.
  97. If the file cannot be found, the link target is
  98. .Ql unknown .
  99. .It Pa fpregs
  100. The floating point registers as defined by
  101. .Dv "struct fpregs"
  102. in
  103. .In machine/reg.h .
  104. .Pa fpregs
  105. is only implemented on machines which have distinct general
  106. purpose and floating point register sets.
  107. .It Pa map
  108. A map of the process' virtual memory.
  109. .It Pa mem
  110. The complete virtual memory image of the process.
  111. Only those address which exist in the process can be accessed.
  112. Reads and writes to this file modify the process.
  113. Writes to the text segment remain private to the process.
  114. .It Pa note
  115. Used for sending signals to the process.
  116. Not implemented.
  117. .It Pa notepg
  118. Used for sending signal to the process group.
  119. Not implemented.
  120. .It Pa osrel
  121. Allows read and write of the kernel osrel value assigned to the process.
  122. It affects the compatibility shims that are turned on and off
  123. depending on the value.
  124. Initial process value is read from the ABI note tag in the executed ELF image,
  125. and is zero if the tag not supported by binary format or was not found.
  126. .It Pa regs
  127. Allows read and write access to the process' register set.
  128. This file contains a binary data structure
  129. .Dv "struct regs"
  130. defined in
  131. .In machine/reg.h .
  132. .Pa regs
  133. can only be written when the process is stopped.
  134. .It Pa rlimit
  135. This is a read-only file containing the process current and maximum
  136. limits.
  137. Each line is of the format
  138. .Ar rlimit current max ,
  139. with -1
  140. indicating infinity.
  141. .It Pa status
  142. The process status.
  143. This file is read-only and returns a single line containing
  144. multiple space-separated fields as follows:
  145. .Pp
  146. .Bl -bullet -compact
  147. .It
  148. command name
  149. .It
  150. process id
  151. .It
  152. parent process id
  153. .It
  154. process group id
  155. .It
  156. session id
  157. .It
  158. .Ar major , Ns Ar minor
  159. of the controlling terminal, or
  160. .Dv -1,-1
  161. if there is no controlling terminal.
  162. .It
  163. a list of process flags:
  164. .Dv ctty
  165. if there is a controlling terminal,
  166. .Dv sldr
  167. if the process is a session leader,
  168. .Dv noflags
  169. if neither of the other two flags are set.
  170. .It
  171. the process start time in seconds and microseconds,
  172. comma separated.
  173. .It
  174. the user time in seconds and microseconds,
  175. comma separated.
  176. .It
  177. the system time in seconds and microseconds,
  178. comma separated.
  179. .It
  180. the wait channel message
  181. .It
  182. the process credentials consisting of
  183. the effective user id
  184. and the list of groups (whose first member
  185. is the effective group id)
  186. all comma separated.
  187. .It
  188. the hostname of the jail in which the process runs, or
  189. .Ql -
  190. to indicate that the process is not running within a jail.
  191. .El
  192. .El
  193. .Pp
  194. In a normal debugging environment,
  195. where the target is fork/exec'd by the debugger,
  196. the debugger should fork and the child should stop
  197. itself (with a self-inflicted
  198. .Dv SIGSTOP
  199. for example).
  200. The parent should issue a
  201. .Dv wait
  202. and then an
  203. .Dv attach
  204. command via the appropriate
  205. .Pa ctl
  206. file.
  207. The child process will receive a
  208. .Dv SIGTRAP
  209. immediately after the call to exec (see
  210. .Xr execve 2 ) .
  211. .Pp
  212. Each node is owned by the process's user, and belongs to that user's
  213. primary group, except for the
  214. .Pa mem
  215. node, which belongs to the
  216. .Li kmem
  217. group.
  218. .Sh FILES
  219. .Bl -tag -width /proc/curproc/XXXXXXX -compact
  220. .It Pa /proc
  221. normal mount point for the
  222. .Nm .
  223. .It Pa /proc/pid
  224. directory containing process information for process
  225. .Pa pid .
  226. .It Pa /proc/curproc
  227. directory containing process information for the current process
  228. .It Pa /proc/curproc/cmdline
  229. the process executable name
  230. .It Pa /proc/curproc/ctl
  231. used to send control messages to the process
  232. .It Pa /proc/curproc/etype
  233. executable type
  234. .It Pa /proc/curproc/file
  235. executable image
  236. .It Pa /proc/curproc/fpregs
  237. the process floating point register set
  238. .It Pa /proc/curproc/map
  239. virtual memory map of the process
  240. .It Pa /proc/curproc/mem
  241. the complete virtual address space of the process
  242. .It Pa /proc/curproc/note
  243. used for signaling the process
  244. .It Pa /proc/curproc/notepg
  245. used for signaling the process group
  246. .It Pa /proc/curproc/osrel
  247. the process osrel value
  248. .It Pa /proc/curproc/regs
  249. the process register set
  250. .It Pa /proc/curproc/rlimit
  251. the process current and maximum rlimit
  252. .It Pa /proc/curproc/status
  253. the process' current status
  254. .El
  255. .Sh EXAMPLES
  256. To mount a
  257. .Nm
  258. file system on
  259. .Pa /proc :
  260. .Pp
  261. .Dl "mount -t procfs proc /proc"
  262. .Sh SEE ALSO
  263. .Xr procstat 1 ,
  264. .Xr mount 2 ,
  265. .Xr sigaction 2 ,
  266. .Xr unmount 2 ,
  267. .Xr procctl 8 ,
  268. .Xr pseudofs 9
  269. .Sh AUTHORS
  270. .An -nosplit
  271. This manual page written by
  272. .An Garrett Wollman ,
  273. based on the description
  274. provided by
  275. .An Jan-Simon Pendry ,
  276. and revamped later by
  277. .An Mike Pritchard .