Return to getprogname.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/getprogname.3, Revision 1.7

1.7     ! dholland    1: .\" $NetBSD: getprogname.3,v 1.6 2003/07/26 19:24:42 salo Exp $
1.1       cgd         2: .\"
                      3: .\" Copyright (c) 2001 Christopher G. Demetriou
                      4: .\" All rights reserved.
1.2       wiz         5: .\"
1.1       cgd         6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
                     14: .\" 3. All advertising materials mentioning features or use of this software
                     15: .\"    must display the following acknowledgement:
                     16: .\"          This product includes software developed for the
1.6       salo       17: .\"          NetBSD Project.  See http://www.NetBSD.org/ for
1.1       cgd        18: .\"          information about NetBSD.
                     19: .\" 4. The name of the author may not be used to endorse or promote products
                     20: .\"    derived from this software without specific prior written permission.
1.2       wiz        21: .\"
1.1       cgd        22: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
                     23: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
                     24: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
                     25: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
                     26: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
                     27: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
                     28: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
                     29: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
                     30: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
                     31: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.2       wiz        32: .\"
1.1       cgd        33: .\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
                     34: .\"
1.7     ! dholland   35: .Dd March 29, 2008
1.1       cgd        36: .Dt GETPROGNAME 3
                     37: .Os
                     38: .Sh NAME
                     39: .Nm getprogname ,
                     40: .Nm setprogname
                     41: .Nd get/set the name of the current program
                     42: .Sh LIBRARY
                     43: .Lb libc
                     44: .Sh SYNOPSIS
1.5       wiz        45: .In stdlib.h
1.1       cgd        46: .Ft const char *
                     47: .Fn getprogname "void"
                     48: .Ft void
                     49: .Fn setprogname "const char *name"
                     50: .Sh DESCRIPTION
                     51: These utility functions get and set the current program's name
                     52: as used by various error-reporting functions.
                     53: .Pp
                     54: .Fn getprogname
                     55: returns the name of the current program.
                     56: This function is typically useful when generating error messages
1.4       wiz        57: or other diagnostic output.
                     58: If the program name has not been set,
1.1       cgd        59: .Fn getprogname
                     60: will return
                     61: .Dv NULL .
                     62: .Pp
                     63: .Fn setprogname
                     64: sets the name of the current program to be the last pathname
                     65: component of the
                     66: .Fa name
1.4       wiz        67: argument.
                     68: It should be invoked at the start of the program, using the
1.1       cgd        69: .Fa argv[0]
                     70: passed into the program's
                     71: .Fn main
1.4       wiz        72: function.
                     73: A pointer into the string pointed to by the
1.1       cgd        74: .Fa name
1.4       wiz        75: argument is kept as the program name.
                     76: Therefore, the string pointed to by
1.1       cgd        77: .Fa name
                     78: should not be modified during the rest of the program's operation.
                     79: .Pp
                     80: A program's name can only be set once, and in
                     81: .Nx
                     82: that is actually
                     83: done by program start-up code that is run before
                     84: .Fn main
1.4       wiz        85: is called.
                     86: Therefore, in
1.1       cgd        87: .Nx ,
                     88: calling
                     89: .Fn setprogname
                     90: from
                     91: .Fn main
1.4       wiz        92: has no effect.
                     93: However, it does serve to increase the portability of the program:
1.1       cgd        94: on other operating systems,
                     95: .Fn getprogname
                     96: and
                     97: .Fn setprogname
                     98: may be implemented by a portability library, and a call to
                     99: .Fn setprogname
                    100: allows that library to know the program name without
                    101: modifications to that system's program start-up code.
                    102: .Sh SEE ALSO
                    103: .Xr err 3 ,
                    104: .Xr setproctitle 3
                    105: .Sh HISTORY
                    106: The
                    107: .Nm getprogname
                    108: and
                    109: .Nm setprogname
                    110: function calls appeared in
                    111: .Nx 1.6 .
1.7     ! dholland  112: .Sh RESTRICTIONS
        !           113: The string returned by
        !           114: .Fn getprogname
        !           115: is supplied by the invoking process and should not be trusted by
        !           116: setuid or setgid programs.