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 ex-
       amine  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.   In-
		stead,	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  in-
       spected	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 un-
       available 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 de-
       fault most of the time.

				  11 Oct 2005			       proc(1)


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

home | help