lib/libc/gen/setproctitle.3

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