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