Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / getprogname.3
CommitLineData
984263bc
MD
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 $
9bb2a92d 33.\" $DragonFly: src/lib/libc/gen/getprogname.3,v 1.3 2004/03/11 12:28:50 hmp Exp $
984263bc
MD
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
51The
52.Fn getprogname
53and
54.Fn setprogname
55functions manipulate the name of the current program.
56They are used by error-reporting routines to produce
57consistent output.
58.Pp
59The
60.Fn getprogname
61function returns the name of the program.
62If the name has not been set yet, it will return
63.Dv NULL .
64.Pp
65The
66.Fn setprogname
67function sets the name of the program to be the last component of the
68.Fa progname
69argument.
70Since a pointer to the given string is kept as the program name,
71it should not be modified for the rest of the program's lifetime.
72.Pp
73In
9bb2a92d 74.Dx ,
984263bc
MD
75the name of the program is set by the start-up code that is run before
76.Fn main ;
77thus,
78running
79.Fn setprogname
80is not necessary.
81Programs that desire maximum portability should still call it;
82on another operating system,
83these functions may be implemented in a portability library.
84Calling
85.Fn setprogname
86allows the aforementioned library to learn the program name without
87modifications to the start-up code.
88.Sh SEE ALSO
89.Xr err 3 ,
90.Xr setproctitle 3
91.Sh HISTORY
92These functions first appeared in
93.Nx 1.6 ,
94and made their way into
95.Fx 4.4 .