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