xref: /freebsd/lib/libc/gen/setproctitle.3 (revision 305ad8f90883326d5f36cd372dea91c3f0655dd1)
1.\" Copyright (c) 1995 Peter Wemm <peter@freebsd.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, is permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice immediately at the beginning of the file, without modification,
9.\"    this list of conditions, and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
14.\"    is permitted provided this notation is included.
15.\" 4. Absolutely no warranty of function or purpose is made by the author
16.\"    Peter Wemm.
17.\" 5. Modifications may be freely made to this file providing the above
18.\"    conditions are met.
19.\"
20.\" $FreeBSD$
21.\"
22.\" The following requests are required for all man pages.
23.Dd December 16, 1995
24.Os FreeBSD
25.Dt SETPROCTITLE 3
26.Sh NAME
27.Nm setproctitle
28.Nd set the process title for
29.Xr ps 1
30.Sh LIBRARY
31.Lb libutil
32.Sh SYNOPSIS
33.Fd #include <sys/types.h>
34.Fd #include <libutil.h>
35.Ft void
36.Fn setproctitle "const char *fmt" "..."
37.Sh DESCRIPTION
38The
39.Fn setproctitle
40library routine sets the process title that appears on the
41.Xr ps 1
42command.
43.Pp
44The title is set from the executable's name, followed by the
45result of a
46.Xr printf 3
47style expansion of the arguments as specified by the
48.Va fmt
49argument.
50If the
51.Va fmt
52argument begins with a
53.Dq -
54character, the executable's name is skipped.
55.Pp
56If
57.Va fmt
58is NULL, the process title is restored.
59.Sh EXAMPLES
60To set the title on a daemon to indicate its activity:
61.Bd -literal -offset indent
62setproctitle("talking to %s", inet_ntoa(addr));
63.Ed
64.Sh SEE ALSO
65.Xr ps 1 ,
66.Xr w 1 ,
67.Xr kvm 3 ,
68.Xr kvm_getargv 3 ,
69.Xr printf 3
70.Sh STANDARDS
71.Fn setproctitle
72is implicitly non-standard.  Other methods of causing the
73.Xr ps 1
74command line to change, including copying over the argv[0] string are
75also implicitly non-portable.  It is preferable to use an operating system
76supplied
77.Fn setproctitle
78if present.
79.Pp
80Unfortunately, it is possible that there are other calling conventions
81to other versions of
82.Fn setproctitle ,
83although none have been found by the author as yet.  This is believed to be
84the predominant convention.
85.Pp
86It is thought that the implementation is compatible with other systems,
87including
88.Nx
89and
90.Tn BSD/OS .
91.Sh HISTORY
92.Fn setproctitle
93first appeared in
94.Fx 2.2 .
95Other operating systems have
96similar functions.
97.Sh AUTHORS
98.An Peter Wemm Aq peter@FreeBSD.org
99stole the idea from the
100.Sy "Sendmail 8.7.3"
101source code by
102.An Eric Allman Aq eric@sendmail.org .
103