Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / getprogname.3
1 .\"
2 .\" Copyright (c) 2001 Christopher G. Demetriou
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, 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. All advertising materials mentioning features or use of this software
14 .\"    must display the following acknowledgement:
15 .\"          This product includes software developed for the
16 .\"          NetBSD Project.  See http://www.netbsd.org/ for
17 .\"          information about NetBSD.
18 .\" 4. The name of the author may not be used to endorse or promote products
19 .\"    derived from this software without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .\" $FreeBSD: src/lib/libc/gen/getprogname.3,v 1.1.2.5 2001/12/14 18:33:51 ru Exp $
33 .\" $DragonFly: src/lib/libc/gen/getprogname.3,v 1.3 2004/03/11 12:28:50 hmp Exp $
34 .\"
35 .Dd May 1, 2001
36 .Dt GETPROGNAME 3
37 .Os
38 .Sh NAME
39 .Nm getprogname ,
40 .Nm setprogname
41 .Nd get or set the program name
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In stdlib.h
46 .Ft const char *
47 .Fn getprogname "void"
48 .Ft void
49 .Fn setprogname "const char *progname"
50 .Sh DESCRIPTION
51 The
52 .Fn getprogname
53 and
54 .Fn setprogname
55 functions manipulate the name of the current program.
56 They are used by error-reporting routines to produce
57 consistent output.
58 .Pp
59 The
60 .Fn getprogname
61 function returns the name of the program.
62 If the name has not been set yet, it will return
63 .Dv NULL .
64 .Pp
65 The
66 .Fn setprogname
67 function sets the name of the program to be the last component of the
68 .Fa progname
69 argument.
70 Since a pointer to the given string is kept as the program name,
71 it should not be modified for the rest of the program's lifetime.
72 .Pp
73 In
74 .Dx ,
75 the name of the program is set by the start-up code that is run before
76 .Fn main ;
77 thus,
78 running
79 .Fn setprogname
80 is not necessary.
81 Programs that desire maximum portability should still call it;
82 on another operating system,
83 these functions may be implemented in a portability library.
84 Calling
85 .Fn setprogname
86 allows the aforementioned library to learn the program name without
87 modifications to the start-up code.
88 .Sh SEE ALSO
89 .Xr err 3 ,
90 .Xr setproctitle 3
91 .Sh HISTORY
92 These functions first appeared in
93 .Nx 1.6 ,
94 and made their way into
95 .Fx 4.4 .