mirror of https://github.com/mkerrisk/man-pages
215 lines
5.8 KiB
Groff
215 lines
5.8 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "DIRNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" dirname
|
|
.SH NAME
|
|
dirname \- return the directory portion of a pathname
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBdirname\fP \fIstring\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIstring\fP operand shall be treated as a pathname, as defined
|
|
in the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 3.266, Pathname. The string
|
|
\fIstring\fP shall be converted to the name of the directory containing
|
|
the filename corresponding to the last pathname component
|
|
in \fIstring\fP, performing actions equivalent to the following steps
|
|
in order:
|
|
.IP " 1." 4
|
|
If \fIstring\fP is \fB//\fP, skip steps 2 to 5.
|
|
.LP
|
|
.IP " 2." 4
|
|
If \fIstring\fP consists entirely of slash characters, \fIstring\fP
|
|
shall be set to a single slash character. In this case,
|
|
skip steps 3 to 8.
|
|
.LP
|
|
.IP " 3." 4
|
|
If there are any trailing slash characters in \fIstring\fP, they shall
|
|
be removed.
|
|
.LP
|
|
.IP " 4." 4
|
|
If there are no slash characters remaining in \fIstring\fP, \fIstring\fP
|
|
shall be set to a single period character. In this
|
|
case, skip steps 5 to 8.
|
|
.LP
|
|
.IP " 5." 4
|
|
If there are any trailing non-slash characters in \fIstring\fP, they
|
|
shall be removed.
|
|
.LP
|
|
.IP " 6." 4
|
|
If the remaining \fIstring\fP is \fB//\fP, it is implementation-defined
|
|
whether steps 7 and 8 are skipped or processed.
|
|
.LP
|
|
.IP " 7." 4
|
|
If there are any trailing slash characters in \fIstring\fP, they shall
|
|
be removed.
|
|
.LP
|
|
.IP " 8." 4
|
|
If the remaining \fIstring\fP is empty, \fIstring\fP shall be set
|
|
to a single slash character.
|
|
.LP
|
|
.LP
|
|
The resulting string shall be written to standard output.
|
|
.SH OPTIONS
|
|
.LP
|
|
None.
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operand shall be supported:
|
|
.TP 7
|
|
\fIstring\fP
|
|
A string.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
Not used.
|
|
.SH INPUT FILES
|
|
.LP
|
|
None.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIdirname\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
The \fIdirname\fP utility shall write a line to the standard output
|
|
in the following format:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s\\n", <\fP\fIresulting string\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
Successful completion.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The definition of \fIpathname\fP specifies implementation-defined
|
|
behavior for pathnames starting with two slash characters.
|
|
Therefore, applications shall not arbitrarily add slashes to the beginning
|
|
of a pathname unless they can ensure that there are more
|
|
or less than two or are prepared to deal with the implementation-defined
|
|
consequences.
|
|
.SH EXAMPLES
|
|
.TS C
|
|
center; l l.
|
|
\fBCommand\fP \fBResults\fP
|
|
\fIdirname\fP / /
|
|
\fIdirname\fP // / or //
|
|
\fIdirname\fP /\fIa\fP/\fIb\fP/ /\fIa\fP
|
|
\fIdirname\fP //\fIa\fP//\fIb\fP// //\fIa\fP
|
|
\fIdirname\fP Unspecified
|
|
\fIdirname a\fP . ($? = 0)
|
|
\fIdirname\fP "" . ($? = 0)
|
|
\fIdirname\fP /\fIa\fP /
|
|
\fIdirname\fP /\fIa\fP/\fIb\fP /\fIa\fP
|
|
\fIdirname\fP \fIa\fP/\fIb\fP \fIa\fP
|
|
.TE
|
|
.SH RATIONALE
|
|
.LP
|
|
The \fIdirname\fP utility originated in System III. It has evolved
|
|
through the System V releases to a version that matches the
|
|
requirements specified in this description in System V Release 3.
|
|
4.3 BSD and earlier versions did not include \fIdirname\fP.
|
|
.LP
|
|
The behaviors of \fIbasename\fP and \fIdirname\fP in this volume of
|
|
IEEE\ Std\ 1003.1-2001 have been coordinated so that when \fIstring\fP
|
|
is a valid pathname:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB$(basename "\fP\fIstring\fP\fB")
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
would be a valid filename for the file in the directory:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB$(dirname "\fP\fIstring\fP\fB")
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
This would not work for the versions of these utilities in early proposals
|
|
due to the way processing of trailing slashes was
|
|
specified. Consideration was given to leaving processing unspecified
|
|
if there were trailing slashes, but this cannot be done; the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.266,
|
|
Pathname allows trailing slashes. The \fIbasename\fP and \fIdirname\fP
|
|
utilities
|
|
have to specify consistent handling for all valid pathnames.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIbasename\fP() , \fIParameters and Variables\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|