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 November 13, 2020 24.Dt SETPROCTITLE 3 25.Os 26.Sh NAME 27.Nm setproctitle 28.Nm setproctitle_fast 29.Nd set process title 30.Sh SYNOPSIS 31.In sys/types.h 32.In unistd.h 33.Ft void 34.Fn setproctitle "const char *fmt" "..." 35.Ft void 36.Fn setproctitle_fast "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. 43The 44.Fn setproctitle_fast 45variant is optimized for high frequency updates, but may make the 46.Xr ps 1 47command slightly slower by not updating the kernel cache of the program 48arguments. 49.Pp 50The title is set from the executable's name, followed by the 51result of a 52.Xr printf 3 53style expansion of the arguments as specified by the 54.Va fmt 55argument. 56If the 57.Va fmt 58argument begins with a 59.Dq - 60character, the executable's name is skipped. 61.Pp 62If 63.Va fmt 64is NULL, the process title is restored. 65.Sh EXAMPLES 66To set the title on a daemon to indicate its activity: 67.Bd -literal -offset indent 68setproctitle("talking to %s", inet_ntoa(addr)); 69.Ed 70.Sh SEE ALSO 71.Xr ps 1 , 72.Xr w 1 , 73.Xr setprogname 3 , 74.Xr kvm 3 , 75.Xr kvm_getargv 3 , 76.Xr printf 3 77.Sh STANDARDS 78The 79.Fn setproctitle 80function 81is implicitly non-standard. 82Other methods of causing the 83.Xr ps 1 84command line to change, including copying over the argv[0] string are 85also implicitly non-portable. 86It is preferable to use an operating system 87supplied 88.Fn setproctitle 89if present. 90.Pp 91Unfortunately, it is possible that there are other calling conventions 92to other versions of 93.Fn setproctitle , 94although none have been found by the author as yet. 95This is believed to be 96the predominant convention. 97.Pp 98It is thought that the implementation is compatible with other systems, 99including 100.Nx 101and 102.Bsx . 103.Sh HISTORY 104The 105.Fn setproctitle 106function 107first appeared in 108.Fx 2.2 . 109The 110.Fn setproctitle_fast 111function first appeared in 112.Fx 12 . 113Other operating systems have 114similar functions. 115.Sh AUTHORS 116.An -nosplit 117.An Peter Wemm Aq Mt peter@FreeBSD.org 118stole the idea from the 119.Sy "Sendmail 8.7.3" 120source code by 121.An Eric Allman Aq Mt eric@sendmail.org . 122.Sh BUGS 123Never pass a string with user-supplied data as a format without using 124.Ql %s . 125An attacker can put format specifiers in the string to mangle your stack, 126leading to a possible security hole. 127This holds true even if the string was built using a function like 128.Fn snprintf , 129as the resulting string may still contain user-supplied conversion specifiers 130for later interpolation by 131.Fn setproctitle . 132.Pp 133Always use the proper secure idiom: 134.Pp 135.Dl setproctitle("%s", string); 136