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