1.\"	$OpenBSD: setproctitle.3,v 1.18 2013/06/05 03:39:22 tedu 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 by Christopher G. Demetriou
17.\"	 for the NetBSD Project.
18.\" 3. The name of the author may not be used to endorse or promote products
19.\"    derived from this software without specific prior written permission
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31.\"
32.Dd $Mdocdate: June 5 2013 $
33.Dt SETPROCTITLE 3
34.Os
35.Sh NAME
36.Nm setproctitle
37.Nd set process title
38.Sh SYNOPSIS
39.In stdlib.h
40.Ft void
41.Fn setproctitle "const char *fmt" "..."
42.Sh DESCRIPTION
43The
44.Fn setproctitle
45function sets the invoking process's title.
46The process title is set to the last component of the program
47name, followed by a colon, a single space, and the formatted string specified
48by
49.Fa fmt .
50If
51.Fa fmt
52is
53.Dv NULL ,
54the colon and formatted string are omitted.
55The length of a process title is limited to 2048 bytes.
56.Sh EXAMPLES
57Set the process title to the program name, with no further information:
58.Bd -literal -offset indent
59setproctitle(NULL);
60.Ed
61.Pp
62Set the process title to the program name, an informational string,
63and the process ID:
64.Bd -literal -offset indent
65setproctitle("foo! (%d)", getpid());
66.Ed
67.Sh SEE ALSO
68.Xr ps 1 ,
69.Xr w 1 ,
70.Xr getprogname 3 ,
71.Xr printf 3
72.Sh HISTORY
73The
74.Fn setproctitle
75function first appeared in
76.Nx 0.9a .
77.Sh CAVEATS
78It is important never to pass a string with user-supplied data as a
79format without using
80.Ql %s .
81An attacker can put format specifiers in the string to mangle the stack,
82leading to a possible security hole.
83This holds true even if the string has been built
84.Dq by hand
85using a function like
86.Fn snprintf ,
87as the resulting string may still contain user-supplied conversion specifiers
88for later interpolation by
89.Fn setproctitle .
90.Pp
91Always be sure to use the proper secure idiom:
92.Bd -literal -offset indent
93setproctitle("%s", string);
94.Ed
95