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 July 4, 2018 24.Dt SETPROCTITLE 3 25.Os 26.Sh NAME 27.Nm setproctitle 28.Nd set process title 29.Sh SYNOPSIS 30.In sys/types.h 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 kvm 3 , 73.Xr kvm_getargv 3 , 74.Xr printf 3 75.Sh STANDARDS 76The 77.Fn setproctitle 78function 79is implicitly non-standard. 80Other methods of causing the 81.Xr ps 1 82command line to change, including copying over the argv[0] string are 83also implicitly non-portable. 84It is preferable to use an operating system 85supplied 86.Fn setproctitle 87if present. 88.Pp 89Unfortunately, it is possible that there are other calling conventions 90to other versions of 91.Fn setproctitle , 92although none have been found by the author as yet. 93This is believed to be 94the predominant convention. 95.Pp 96It is thought that the implementation is compatible with other systems, 97including 98.Nx 99and 100.Bsx . 101.Sh HISTORY 102The 103.Fn setproctitle 104function 105first appeared in 106.Fx 2.2 . 107The 108.Fn setproctitle_fast 109function first appeared in 110.Fx 12 . 111Other operating systems have 112similar functions. 113.Sh AUTHORS 114.An -nosplit 115.An Peter Wemm Aq Mt peter@FreeBSD.org 116stole the idea from the 117.Sy "Sendmail 8.7.3" 118source code by 119.An Eric Allman Aq Mt eric@sendmail.org . 120.Sh BUGS 121Never pass a string with user-supplied data as a format without using 122.Ql %s . 123An attacker can put format specifiers in the string to mangle your stack, 124leading to a possible security hole. 125This holds true even if the string was built using a function like 126.Fn snprintf , 127as the resulting string may still contain user-supplied conversion specifiers 128for later interpolation by 129.Fn setproctitle . 130.Pp 131Always use the proper secure idiom: 132.Pp 133.Dl setproctitle("%s", string); 134