xref: /freebsd/lib/libc/gen/getprogname.3 (revision 1ffdcdadf61423dd02ddad82fc4f3f6c39090c8c)
1cd18ccdcSDima Dorfman.\"
2cd18ccdcSDima Dorfman.\" Copyright (c) 2001 Christopher G. Demetriou
3cd18ccdcSDima Dorfman.\" All rights reserved.
4cd18ccdcSDima Dorfman.\"
5cd18ccdcSDima Dorfman.\" Redistribution and use in source and binary forms, with or without
6cd18ccdcSDima Dorfman.\" modification, are permitted provided that the following conditions
7cd18ccdcSDima Dorfman.\" are met:
8cd18ccdcSDima Dorfman.\" 1. Redistributions of source code must retain the above copyright
9cd18ccdcSDima Dorfman.\"    notice, this list of conditions and the following disclaimer.
10cd18ccdcSDima Dorfman.\" 2. Redistributions in binary form must reproduce the above copyright
11cd18ccdcSDima Dorfman.\"    notice, this list of conditions and the following disclaimer in the
12cd18ccdcSDima Dorfman.\"    documentation and/or other materials provided with the distribution.
13cd18ccdcSDima Dorfman.\" 3. All advertising materials mentioning features or use of this software
14cd18ccdcSDima Dorfman.\"    must display the following acknowledgement:
15cd18ccdcSDima Dorfman.\"          This product includes software developed for the
16cd18ccdcSDima Dorfman.\"          NetBSD Project.  See http://www.netbsd.org/ for
17cd18ccdcSDima Dorfman.\"          information about NetBSD.
18cd18ccdcSDima Dorfman.\" 4. The name of the author may not be used to endorse or promote products
19cd18ccdcSDima Dorfman.\"    derived from this software without specific prior written permission.
20cd18ccdcSDima Dorfman.\"
21cd18ccdcSDima Dorfman.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22cd18ccdcSDima Dorfman.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23cd18ccdcSDima Dorfman.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24cd18ccdcSDima Dorfman.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25cd18ccdcSDima Dorfman.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26cd18ccdcSDima Dorfman.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27cd18ccdcSDima Dorfman.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28cd18ccdcSDima Dorfman.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29cd18ccdcSDima Dorfman.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30cd18ccdcSDima Dorfman.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31cd18ccdcSDima Dorfman.\"
32cd18ccdcSDima Dorfman.\" $FreeBSD$
33cd18ccdcSDima Dorfman.\"
34*1ffdcdadSMateusz Piotrowski.Dd April 18, 2021
35cd18ccdcSDima Dorfman.Dt GETPROGNAME 3
36cd18ccdcSDima Dorfman.Os
37cd18ccdcSDima Dorfman.Sh NAME
38cd18ccdcSDima Dorfman.Nm getprogname ,
39cd18ccdcSDima Dorfman.Nm setprogname
40cd18ccdcSDima Dorfman.Nd get or set the program name
41cd18ccdcSDima Dorfman.Sh LIBRARY
42cd18ccdcSDima Dorfman.Lb libc
43cd18ccdcSDima Dorfman.Sh SYNOPSIS
4432eef9aeSRuslan Ermilov.In stdlib.h
45cd18ccdcSDima Dorfman.Ft const char *
46cd18ccdcSDima Dorfman.Fn getprogname "void"
47cd18ccdcSDima Dorfman.Ft void
48cd18ccdcSDima Dorfman.Fn setprogname "const char *progname"
49cd18ccdcSDima Dorfman.Sh DESCRIPTION
50cd18ccdcSDima DorfmanThe
51cd18ccdcSDima Dorfman.Fn getprogname
52cd18ccdcSDima Dorfmanand
53cd18ccdcSDima Dorfman.Fn setprogname
54cd18ccdcSDima Dorfmanfunctions manipulate the name of the current program.
55cd18ccdcSDima DorfmanThey are used by error-reporting routines to produce
56cd18ccdcSDima Dorfmanconsistent output.
57cd18ccdcSDima Dorfman.Pp
58cd18ccdcSDima DorfmanThe
59cd18ccdcSDima Dorfman.Fn getprogname
60cd18ccdcSDima Dorfmanfunction returns the name of the program.
61cd18ccdcSDima DorfmanIf the name has not been set yet, it will return
62cd18ccdcSDima Dorfman.Dv NULL .
63cd18ccdcSDima Dorfman.Pp
64cd18ccdcSDima DorfmanThe
65cd18ccdcSDima Dorfman.Fn setprogname
66c9fa8f40SDima Dorfmanfunction sets the name of the program to be the last component of the
67c9fa8f40SDima Dorfman.Fa progname
68c9fa8f40SDima Dorfmanargument.
69cd18ccdcSDima DorfmanSince a pointer to the given string is kept as the program name,
70cd18ccdcSDima Dorfmanit should not be modified for the rest of the program's lifetime.
71cd18ccdcSDima Dorfman.Pp
72cd18ccdcSDima DorfmanIn
73cd18ccdcSDima Dorfman.Fx ,
74cd18ccdcSDima Dorfmanthe name of the program is set by the start-up code that is run before
75cd18ccdcSDima Dorfman.Fn main ;
76cd18ccdcSDima Dorfmanthus,
77cd18ccdcSDima Dorfmanrunning
78cd18ccdcSDima Dorfman.Fn setprogname
79cd18ccdcSDima Dorfmanis not necessary.
80cd18ccdcSDima DorfmanPrograms that desire maximum portability should still call it;
81cd18ccdcSDima Dorfmanon another operating system,
82cd18ccdcSDima Dorfmanthese functions may be implemented in a portability library.
83cd18ccdcSDima DorfmanCalling
84cd18ccdcSDima Dorfman.Fn setprogname
85cd18ccdcSDima Dorfmanallows the aforementioned library to learn the program name without
86cd18ccdcSDima Dorfmanmodifications to the start-up code.
87*1ffdcdadSMateusz Piotrowski.Sh EXAMPLES
88*1ffdcdadSMateusz PiotrowskiThe following example presents a simple program, which shows the difference
89*1ffdcdadSMateusz Piotrowskibetween
90*1ffdcdadSMateusz Piotrowski.Fn getprogname
91*1ffdcdadSMateusz Piotrowskiand
92*1ffdcdadSMateusz Piotrowski.Va "argv[0]" .
93*1ffdcdadSMateusz Piotrowski.Bd -literal -offset indent
94*1ffdcdadSMateusz Piotrowski#include <stdio.h>
95*1ffdcdadSMateusz Piotrowski#include <stdlib.h>
96*1ffdcdadSMateusz Piotrowski
97*1ffdcdadSMateusz Piotrowskiint
98*1ffdcdadSMateusz Piotrowskimain(int argc, char** argv)
99*1ffdcdadSMateusz Piotrowski{
100*1ffdcdadSMateusz Piotrowski	printf("getprogname(): %s\en", getprogname());
101*1ffdcdadSMateusz Piotrowski	printf("argv[0]: %s\en", argv[0]);
102*1ffdcdadSMateusz Piotrowski	return (0);
103*1ffdcdadSMateusz Piotrowski}
104*1ffdcdadSMateusz Piotrowski.Ed
105*1ffdcdadSMateusz Piotrowski.Pp
106*1ffdcdadSMateusz PiotrowskiWhen compiled and executed (e.g., with
107*1ffdcdadSMateusz Piotrowski.Ql ./a.out )
108*1ffdcdadSMateusz Piotrowskithe output of the program is going to look like this:
109*1ffdcdadSMateusz Piotrowski.Bd -literal -offset indent
110*1ffdcdadSMateusz Piotrowskigetprogname(): a.out
111*1ffdcdadSMateusz Piotrowskiargv[0]: ./a.out
112*1ffdcdadSMateusz Piotrowski.Ed
113cd18ccdcSDima Dorfman.Sh SEE ALSO
114cd18ccdcSDima Dorfman.Xr err 3 ,
115cd18ccdcSDima Dorfman.Xr setproctitle 3
116cd18ccdcSDima Dorfman.Sh HISTORY
117cd18ccdcSDima DorfmanThese functions first appeared in
118cd18ccdcSDima Dorfman.Nx 1.6 ,
119cd18ccdcSDima Dorfmanand made their way into
12086f47875SSheldon Hearn.Fx 4.4 .
121