l4/pkg/libbsd/lib/contrib/man/setproctitle.3

   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 December 16, 1995
  24 .Dt SETPROCTITLE 3
  25 .Os
  26 .Sh NAME
  27 .Nm setproctitle
  28 .Nd set process title
  29 .Sh LIBRARY
  30 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
  31 .Lb libbsd
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In bsd/unistd.h
  35 .Ft void
  36 .Fn setproctitle_init "int argc" "char *argv[]" "char *envp[]"
  37 .Ft void
  38 .Fn setproctitle "const char *fmt" "..."
  39 .Sh DESCRIPTION
  40 The
  41 .Fn setproctitle
  42 library routine sets the process title that appears on the
  43 .Xr ps 1
  44 command.
  45 .Pp
  46 The
  47 .Fn setproctitle_init
  48 library routine only needs to be called (before any call to
  49 .Fn setproctitle
  50 and with
  51 .Fn main
  52 arguments), if the automatic constructor support has not
  53 been linked in through the libbsd-ctor pkg-config file.
  54 .Pp
  55 The title is set from the executable's name, followed by the
  56 result of a
  57 .Xr printf 3
  58 style expansion of the arguments as specified by the
  59 .Va fmt
  60 argument.
  61 If the
  62 .Va fmt
  63 argument begins with a
  64 .Dq -
  65 character, the executable's name is skipped.
  66 .Pp
  67 If
  68 .Va fmt
  69 is NULL, the process title is restored.
  70 .Sh EXAMPLES
  71 To set the title on a daemon to indicate its activity:
  72 .Bd -literal -offset indent
  73 setproctitle("talking to %s", inet_ntoa(addr));
  74 .Ed
  75 .Sh SEE ALSO
  76 .Xr ps 1 ,
  77 .Xr w 1 ,
  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 Other operating systems have
 114 similar functions.
 115 .Pp
 116 The
 117 .Fn setproctitle_init
 118 function is a libbsd extension not present on the BSDs, avoid using it
 119 in portable code.
 120 .Sh AUTHORS
 121 .An -nosplit
 122 .An Peter Wemm Aq peter@FreeBSD.org
 123 stole the idea from the
 124 .Sy "Sendmail 8.7.3"
 125 source code by
 126 .An Eric Allman Aq eric@sendmail.org .
 127 .Sh BUGS
 128 Never pass a string with user-supplied data as a format without using
 129 .Ql %s .
 130 An attacker can put format specifiers in the string to mangle your stack,
 131 leading to a possible security hole.
 132 This holds true even if the string was built using a function like
 133 .Fn snprintf ,
 134 as the resulting string may still contain user-supplied conversion specifiers
 135 for later interpolation by
 136 .Fn setproctitle .
 137 .Pp
 138 Always use the proper secure idiom:
 139 .Pp
 140 .Dl setproctitle("%s", string);