Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
proc(1)								       proc(1)

       proc,  pflags,  pcred,  pldd,  psig, pstack, pfiles, pwdx, pstop, prun,
       pwait, ptime - proc tools

       /usr/bin/pflags [-r] pid	| core [/lwp] ...

       /usr/bin/pcred [pid | core] ...

       /usr/bin/pcred [-u user/uid] [-g	group/gid] [-G grouplist] pid...

       /usr/bin/pcred -l login pid...

       /usr/bin/pldd [-F] [pid | core] ...

       /usr/bin/psig [-n] pid ...

       /usr/bin/pstack [-F] pid	| core	[/lwp] ...

       /usr/bin/pfiles [-Fn] pid...

       /usr/bin/pwdx pid...

       /usr/bin/pstop pid...

       /usr/bin/prun pid...

       /usr/bin/pwait [-v] pid...

       /usr/bin/ptime command [arg...]

       The proc	tools are utilities  that  exercise  features  of  /proc  (see
       proc(4)).  Most	of  them  take a list of process-ids (pid).  The tools
       that do take process-ids	also accept /proc/nnn as a process-id, so  the
       shell  expansion	 /proc/*  can  be used to specify all processes	in the

       Some of the proc	tools can also be applied to core files	(see core(4)).
       The  tools that apply to	core files accept a list of either process IDs
       or names	of core	files or both.

       Some of the proc	tools can operate on  individual  threads.  Users  can
       examine only selected threads by	appending /thread-id to	the process-id
       or core.	Multiple threads can be	selected using the - and , delimiters.
       For example /1,2,7-9 examines threads 1,	2, 7, 8, and 9.

       See .

       pflags	       Print  the  /proc  tracing  flags, the pending and held
		       signals,	and other /proc	status	information  for  each
		       lwp in each process.

       pcred	       Print  or  set  the credentials (effective, real, saved
		       UIDs and	GIDs) of each process.

       pldd	       List the	dynamic	libraries linked  into	each  process,
		       including  shared  objects  explicitly  attached	 using
		       dlopen(3C).  See	also ldd(1).

       psig	       List the	signal actions and handlers of	each  process.
		       See signal.h(3HEAD).

       pstack	       Print  a	 hex+symbolic stack trace for each lwp in each

       pfiles	       Report fstat(2) and fcntl(2) information	for  all  open
		       files  in each process. In addition, a path to the file
		       is  reported  if	 the  information  is  available  from
		       /proc/pid/path.	This  is not necessarily the same name
		       used to open the	file. See proc(4)  for	more  informa-

       pwdx	       Print the current working directory of each process.

       pstop	       Stop each process (PR_REQUESTED stop).

       prun	       Set each	process	running	(inverse of pstop).

       pwait	       Wait for	all of the specified processes to terminate.

       ptime	       Time  the  command,  like time(1), but using microstate
		       accounting for reproducible precision. Unlike  time(1),
		       children	of the command are not timed.

       The following options are supported:

       -F	Force.	Grabs  the  target process even	if another process has

       -n	(psig and pfiles only) Sets non-verbose	 mode.	psig  displays
		signal	handler	 addresses  rather than	names. pfiles does not
		display	 verbose  information  for   each   file   descriptor.
		Instead,  pfiles  limits  its  output  to the information that
		would be retrieved if the process applied fstat(2) to each  of
		its file descriptors.

       -r	(pflags	 only) If the process is stopped, displays its machine

       -v	(pwait only) Verbose. Reports terminations to standard output.

       Additionally, pcred supports the	following options:

       -g group/gid    Sets the	real, effective, and saved group ids (GIDs) of
		       the target processes to the specified value.

       -G grouplist    Sets the	supplementary GIDs of the  target  process  to
		       the  specified list of groups. The supplementary	groups
		       should be specified as a	comma-separated	list of	 group
		       names ids. An empty list	clears the supplementary group
		       list of the target processes.

       -l login	       Sets the	real, effective, and saved UIDs	of the	target
		       processes  to  the UID of the specified login. Sets the
		       real, effective,	and saved GIDs of the target processes
		       to  the GID of the specified login. Sets	the supplemen-
		       tary group list to the supplementary groups list	of the
		       specified login.

       -u user/uid     Sets  the real, effective, and saved user ids (UIDs) of
		       the target processes to the specified value.

       In order	to set the credentials of another process, a process must have
       sufficient  privilege  to change	its user and group ids to those	speci-
       fied according to the rules laid	out in setuid(2) and it	must have suf-
       ficient privilege to control the	target process.

       These  proc tools stop their target processes while inspecting them and
       reporting the results: pfiles, pldd, and	pstack.	A process can do noth-
       ing  while  it  is  stopped.  Thus,  for	 example,  if  the X server is
       inspected by one	of these proc tools running in a window	 under	the  X
       server's	control, the whole window system can become deadlocked because
       the proc	tool would be attempting to print its results to a window that
       cannot  be  refreshed.  Logging	in  from  from	another	 system	 using
       rlogin(1) and killing the offending proc	tool would clear up the	 dead-
       lock in this case.

       See .

       Caution	should	be exercised when using	the -F flag. Imposing two con-
       trolling	processes on one victim	process	can lead to chaos.  Safety  is
       assured	only if	the primary controlling	process, typically a debugger,
       has stopped the victim process and the primary controlling  process  is
       doing  nothing  at  the moment of application of	the proc tool in ques-

       Some of the proc	tools can also be applied to core files, as  shown  by
       the  synopsis above. A core file	is a snapshot of a process's state and
       is produced by the kernel prior to terminating a	process	with a	signal
       or  by  the gcore(1) utility. Some of the proc tools can	need to	derive
       the name	of the executable corresponding	to the	process	 which	dumped
       core  or	 the  names  of	 shared	libraries associated with the process.
       These files are needed, for example, to provide symbol  table  informa-
       tion  for  pstack(1).  If the proc tool in question is unable to	locate
       the needed executable or	shared library,	 some  symbol  information  is
       unavailable  for	 display. Similarly, if	a core file from one operating
       system release is examined on a different operating system release, the
       run-time	link-editor debugging interface	(librtld_db) cannot be able to
       initialize. In this case, symbol	information for	 shared	 libraries  is
       not available.

       The following exit values are returned:

       0		       Successful operation.

       non-zero		       An error	has occurred.

       /proc/*		       process files

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWesu			   |
       |Interface Stability	     |See below.		   |

       Human Readable Output is	Unstable. Options are Evolving.

       gcore(1),  ldd(1),  pargs(1),  pgrep(1),	 pkill(1), plimit(1), pmap(1),
       preap(1),  ps(1),  ptree(1),  ppgsz(1),	pwd(1),	 rlogin(1),   time(1),
       truss(1),  wait(1),  fcntl(2),  fstat(2),  setuid(2),  dlopen(3C), sig-
       nal.h(3HEAD), core(4), proc(4), process(4), attributes(5), zones(5)

       The following proc tools	stop their target processes  while  inspecting
       them and	reporting the results: pfiles, pldd, and pstack.

       A  process  can do nothing while	it is stopped. Stopping	a heavily used
       process in a production environment, even for a short amount  of	 time,
       can cause severe	bottlenecks and	even hangs of these processes, causing
       them to be unavailable to users.	Some databases	could  also  terminate
       abnormally. Thus, for example, a	database server	under heavy load could
       hang when one of	the database processes is traced using the above  men-
       tioned  proc  tools. Because of this, stopping a	UNIX process in	a pro-
       duction environment should be avoided.

       A process being stopped by these	tools can  be  identified  by  issuing
       /usr/bin/ps  -eflL and looking for "T" in the first column. Notice that
       certain processes, for example "sched", can  show  the  "T"  status  by
       default most of the time.

				  11 Oct 2005			       proc(1)


Want to link to this manual page? Use this URL:

home | help