1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 1995 Peter Wemm 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" The following requests are required for all man pages. 28.Dd November 28, 2022 29.Dt SETPROCTITLE 3 30.Os 31.Sh NAME 32.Nm setproctitle 33.Nm setproctitle_fast 34.Nd set process title 35.Sh SYNOPSIS 36.In unistd.h 37.Ft void 38.Fn setproctitle "const char *fmt" "..." 39.Ft void 40.Fn setproctitle_fast "const char *fmt" "..." 41.Sh DESCRIPTION 42The 43.Fn setproctitle 44library routine sets the process title that appears on the 45.Xr ps 1 46command. 47The 48.Fn setproctitle_fast 49variant is optimized for high frequency updates, but may make the 50.Xr ps 1 51command slightly slower by not updating the kernel cache of the program 52arguments. 53.Pp 54The title is set from the executable's name, followed by the 55result of a 56.Xr printf 3 57style expansion of the arguments as specified by the 58.Va fmt 59argument. 60If the 61.Va fmt 62argument begins with a 63.Dq - 64character, the executable's name is skipped. 65.Pp 66If 67.Va fmt 68is NULL, the process title is restored. 69.Sh EXAMPLES 70To set the title on a daemon to indicate its activity: 71.Bd -literal -offset indent 72setproctitle("talking to %s", inet_ntoa(addr)); 73.Ed 74.Sh SEE ALSO 75.Xr ps 1 , 76.Xr w 1 , 77.Xr kvm 3 , 78.Xr kvm_getargv 3 , 79.Xr printf 3 , 80.Xr setprogname 3 81.Sh STANDARDS 82The 83.Fn setproctitle 84function 85is implicitly non-standard. 86Other methods of causing the 87.Xr ps 1 88command line to change, including copying over the argv[0] string are 89also implicitly non-portable. 90It is preferable to use an operating system 91supplied 92.Fn setproctitle 93if present. 94.Pp 95Unfortunately, it is possible that there are other calling conventions 96to other versions of 97.Fn setproctitle , 98although none have been found by the author as yet. 99This is believed to be 100the predominant convention. 101.Pp 102It is thought that the implementation is compatible with other systems, 103including 104.Nx 105and 106.Bsx . 107.Sh HISTORY 108The 109.Fn setproctitle 110function 111first appeared in 112.Fx 2.2 . 113The 114.Fn setproctitle_fast 115function first appeared in 116.Fx 12 . 117Other operating systems have 118similar functions. 119.Sh AUTHORS 120.An -nosplit 121.An Peter Wemm Aq Mt peter@FreeBSD.org 122stole the idea from the 123.Sy "Sendmail 8.7.3" 124source code by 125.An Eric Allman Aq Mt eric@sendmail.org . 126.Sh BUGS 127Never pass a string with user-supplied data as a format without using 128.Ql %s . 129An attacker can put format specifiers in the string to mangle your stack, 130leading to a possible security hole. 131This holds true even if the string was built using a function like 132.Fn snprintf , 133as the resulting string may still contain user-supplied conversion specifiers 134for later interpolation by 135.Fn setproctitle . 136.Pp 137Always use the proper secure idiom: 138.Pp 139.Dl setproctitle("%s", string); 140