1.\" $NetBSD: setproctitle.3,v 1.18 2003/07/26 19:24:44 salo Exp $
2.\"
3.\" Copyright (c) 1994, 1995 Christopher G. Demetriou
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"          This product includes software developed for the
17.\"          NetBSD Project.  See http://www.NetBSD.org/ for
18.\"          information about NetBSD.
19.\" 4. The name of the author may not be used to endorse or promote products
20.\"    derived from this software without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32.\"
33.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
34.\"
35.Dd April 13, 1994
36.Dt SETPROCTITLE 3
37.Os
38.Sh NAME
39.Nm setproctitle
40.Nd set process title
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In stdlib.h
45.Ft void
46.Fn setproctitle "const char *fmt" "..."
47.Sh DESCRIPTION
48The
49.Fn setproctitle
50function sets the invoking process's title.
51The process title is set to the last component of the program
52name, followed by a colon and the formatted string specified
53by
54.Va fmt .
55If
56.Va fmt
57is
58.Dv NULL ,
59the colon and formatted string are omitted.
60The length of a process title is limited to 2048 bytes.
61.Sh EXAMPLES
62Set the process title to the program name, with no further information:
63.Bd -literal -offset indent
64setproctitle(NULL);
65.Ed
66.Pp
67Set the process title to the program name, an informational string,
68and the process id:
69.Bd -literal -offset indent
70setproctitle("foo! (%d)", getpid());
71.Ed
72.Sh SEE ALSO
73.Xr ps 1 ,
74.Xr w 1 ,
75.Xr getprogname 3 ,
76.Xr printf 3
77.Sh HISTORY
78The
79.Fn setproctitle
80function first appeared in
81.Nx 1.0 .
82.Sh CAVEATS
83It is important never to pass a string with user-supplied data as a
84format without using
85.Ql %s .
86An attacker can put format specifiers in the string to mangle your stack,
87leading to a possible security hole.
88This holds true even if you have built the string
89.Dq by hand
90using a function like
91.Fn snprintf ,
92as the resulting string may still contain user-supplied conversion specifiers
93for later interpolation by
94.Fn setproctitle .
95.Pp
96Always be sure to use the proper secure idiom:
97.Bd -literal -offset indent
98setproctitle("%s", string);
99.Ed
100