lib/libc/gen/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: src/lib/libc/gen/setproctitle.3,v 1.16.2.4 2001/12/14 18:33:51 ru Exp $
  21 .\" $DragonFly: src/lib/libc/gen/setproctitle.3,v 1.3 2007/08/18 20:48:47 swildner Exp $
  22 .\"
  23 .\" The following requests are required for all man pages.
  24 .Dd December 16, 1995
  25 .Os
  26 .Dt SETPROCTITLE 3
  27 .Sh NAME
  28 .Nm setproctitle
  29 .Nd set the process title for
  30 .Xr ps 1
  31 .Sh LIBRARY
  32 .Lb libc
  33 .Sh SYNOPSIS
  34 .In sys/types.h
  35 .In unistd.h
  36 .Ft void
  37 .Fn setproctitle "const char *fmt" "..."
  38 .Sh DESCRIPTION
  39 The
  40 .Fn setproctitle
  41 library routine sets the process title that appears on the
  42 .Xr ps 1
  43 command.
  44 .Pp
  45 The title is set from the executable's name, followed by the
  46 result of a
  47 .Xr printf 3
  48 style expansion of the arguments as specified by the
  49 .Va fmt
  50 argument.
  51 If the
  52 .Va fmt
  53 argument begins with a
  54 .Dq -
  55 character, the executable's name is skipped.
  56 .Pp
  57 If
  58 .Va fmt
  59 is NULL, the process title is restored.
  60 .Sh EXAMPLES
  61 To set the title on a daemon to indicate its activity:
  62 .Bd -literal -offset indent
  63 setproctitle("talking to %s", inet_ntoa(addr));
  64 .Ed
  65 .Sh SEE ALSO
  66 .Xr ps 1 ,
  67 .Xr w 1 ,
  68 .Xr kvm 3 ,
  69 .Xr kvm_getargv 3 ,
  70 .Xr printf 3
  71 .Sh STANDARDS
  72 .Fn setproctitle
  73 is implicitly non-standard.  Other methods of causing the
  74 .Xr ps 1
  75 command line to change, including copying over the argv[0] string are
  76 also implicitly non-portable.  It is preferable to use an operating system
  77 supplied
  78 .Fn setproctitle
  79 if present.
  80 .Pp
  81 Unfortunately, it is possible that there are other calling conventions
  82 to other versions of
  83 .Fn setproctitle ,
  84 although none have been found by the author as yet.  This is believed to be
  85 the predominant convention.
  86 .Pp
  87 It is thought that the implementation is compatible with other systems,
  88 including
  89 .Nx
  90 and
  91 .Bsx .
  92 .Sh HISTORY
  93 .Fn setproctitle
  94 first appeared in
  95 .Fx 2.2 .
  96 Other operating systems have
  97 similar functions.
  98 .Sh AUTHORS
  99 .An -nosplit
 100 .An Peter Wemm Aq peter@FreeBSD.org
 101 stole the idea from the
 102 .Sy "Sendmail 8.7.3"
 103 source code by
 104 .An Eric Allman Aq eric@sendmail.org .