|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH DIRNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
dirname
|
|
Packit |
7cfc04 |
\(em return the directory portion of a pathname
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
dirname \fIstring\fR
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 3.267" ", " "Pathname".
|
|
Packit |
7cfc04 |
The string
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
shall be converted to the name of the directory containing the
|
|
Packit |
7cfc04 |
filename corresponding to the last pathname component in
|
|
Packit |
7cfc04 |
.IR string ,
|
|
Packit |
7cfc04 |
performing actions equivalent to the following steps in order:
|
|
Packit |
7cfc04 |
.IP " 1." 4
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
is
|
|
Packit |
7cfc04 |
.BR // ,
|
|
Packit |
7cfc04 |
skip steps 2 to 5.
|
|
Packit |
7cfc04 |
.IP " 2." 4
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
consists entirely of
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters,
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
shall be set to a single
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
character. In this case, skip steps 3 to 8.
|
|
Packit |
7cfc04 |
.IP " 3." 4
|
|
Packit |
7cfc04 |
If there are any trailing
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters in
|
|
Packit |
7cfc04 |
.IR string ,
|
|
Packit |
7cfc04 |
they shall be removed.
|
|
Packit |
7cfc04 |
.IP " 4." 4
|
|
Packit |
7cfc04 |
If there are no
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters remaining in
|
|
Packit |
7cfc04 |
.IR string ,
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
shall be set to a single
|
|
Packit |
7cfc04 |
<period>
|
|
Packit |
7cfc04 |
character. In this case, skip steps 5 to 8.
|
|
Packit |
7cfc04 |
.IP " 5." 4
|
|
Packit |
7cfc04 |
If there are any trailing non-\c
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters in
|
|
Packit |
7cfc04 |
.IR string ,
|
|
Packit |
7cfc04 |
they shall be removed.
|
|
Packit |
7cfc04 |
.IP " 6." 4
|
|
Packit |
7cfc04 |
If the remaining
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
is
|
|
Packit |
7cfc04 |
.BR // ,
|
|
Packit |
7cfc04 |
it is implementation-defined whether steps 7 and 8 are skipped or
|
|
Packit |
7cfc04 |
processed.
|
|
Packit |
7cfc04 |
.IP " 7." 4
|
|
Packit |
7cfc04 |
If there are any trailing
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters in
|
|
Packit |
7cfc04 |
.IR string ,
|
|
Packit |
7cfc04 |
they shall be removed.
|
|
Packit |
7cfc04 |
.IP " 8." 4
|
|
Packit |
7cfc04 |
If the remaining
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
is empty,
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
shall be set to a single
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
character.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The resulting string shall be written to standard output.
|
|
Packit |
7cfc04 |
.SH OPTIONS
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH OPERANDS
|
|
Packit |
7cfc04 |
The following operand shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fIstring\fR" 10
|
|
Packit |
7cfc04 |
A string.
|
|
Packit |
7cfc04 |
.SH STDIN
|
|
Packit |
7cfc04 |
Not used.
|
|
Packit |
7cfc04 |
.SH "INPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
7cfc04 |
The following environment variables shall affect the execution of
|
|
Packit |
7cfc04 |
.IR dirname :
|
|
Packit |
7cfc04 |
.IP "\fILANG\fP" 10
|
|
Packit |
7cfc04 |
Provide a default value for the internationalization variables that are
|
|
Packit |
7cfc04 |
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 8.2" ", " "Internationalization Variables"
|
|
Packit |
7cfc04 |
for the precedence of internationalization variables used to determine
|
|
Packit |
7cfc04 |
the values of locale categories.)
|
|
Packit |
7cfc04 |
.IP "\fILC_ALL\fP" 10
|
|
Packit |
7cfc04 |
If set to a non-empty string value, override the values of all the
|
|
Packit |
7cfc04 |
other internationalization variables.
|
|
Packit |
7cfc04 |
.IP "\fILC_CTYPE\fP" 10
|
|
Packit |
7cfc04 |
Determine the locale for the interpretation of sequences of bytes of
|
|
Packit |
7cfc04 |
text data as characters (for example, single-byte as opposed to
|
|
Packit |
7cfc04 |
multi-byte characters in arguments).
|
|
Packit |
7cfc04 |
.IP "\fILC_MESSAGES\fP" 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
Determine the locale that should be used to affect the format and
|
|
Packit |
7cfc04 |
contents of diagnostic messages written to standard error.
|
|
Packit |
7cfc04 |
.IP "\fINLSPATH\fP" 10
|
|
Packit |
7cfc04 |
Determine the location of message catalogs for the processing of
|
|
Packit |
7cfc04 |
.IR LC_MESSAGES .
|
|
Packit |
7cfc04 |
.SH "ASYNCHRONOUS EVENTS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.SH STDOUT
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR dirname
|
|
Packit |
7cfc04 |
utility shall write a line to the standard output in the following
|
|
Packit |
7cfc04 |
format:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
"%s\en", <\fIresulting string\fR>
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH STDERR
|
|
Packit |
7cfc04 |
The standard error shall be used only for diagnostic messages.
|
|
Packit |
7cfc04 |
.SH "OUTPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXTENDED DESCRIPTION"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXIT STATUS"
|
|
Packit |
7cfc04 |
The following exit values shall be returned:
|
|
Packit |
7cfc04 |
.IP "\00" 6
|
|
Packit |
7cfc04 |
Successful completion.
|
|
Packit |
7cfc04 |
.IP >0 6
|
|
Packit |
7cfc04 |
An error occurred.
|
|
Packit |
7cfc04 |
.SH "CONSEQUENCES OF ERRORS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The definition of
|
|
Packit |
7cfc04 |
.IR pathname
|
|
Packit |
7cfc04 |
specifies implementation-defined behavior for pathnames starting with
|
|
Packit |
7cfc04 |
two
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters. Therefore, applications shall not arbitrarily add
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters to the beginning of a pathname unless they can ensure
|
|
Packit |
7cfc04 |
that there are more or less than two or are prepared to deal with the
|
|
Packit |
7cfc04 |
implementation-defined consequences.
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
center tab(@) box;
|
|
Packit |
7cfc04 |
cB | cB
|
|
Packit |
7cfc04 |
l | l.
|
|
Packit |
7cfc04 |
Command@Results
|
|
Packit |
7cfc04 |
_
|
|
Packit |
7cfc04 |
\fIdirname\fR /@/
|
|
Packit |
7cfc04 |
\fIdirname\fR //@/ or //
|
|
Packit |
7cfc04 |
\fIdirname\fR /\fIa\fR/\fIb\fR/@/\fIa\fR
|
|
Packit |
7cfc04 |
\fIdirname\fR //\fIa\fR//\fIb\fR//@//\fIa\fR
|
|
Packit |
7cfc04 |
\fIdirname\fR@Unspecified
|
|
Packit |
7cfc04 |
\fIdirname a\fR@. ($? = 0)
|
|
Packit |
7cfc04 |
\fIdirname\fR ""@. ($? = 0)
|
|
Packit |
7cfc04 |
\fIdirname\fR /\fIa\fR@/
|
|
Packit |
7cfc04 |
\fIdirname\fR /\fIa\fR/\fIb\fR@/\fIa\fR
|
|
Packit |
7cfc04 |
\fIdirname\fR \fIa\fR/\fIb\fR@\fIa\fR
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
See also the examples for the
|
|
Packit |
7cfc04 |
.IR basename
|
|
Packit |
7cfc04 |
utility.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR dirname
|
|
Packit |
7cfc04 |
utility originated in System III. It has evolved through the System V
|
|
Packit |
7cfc04 |
releases to a version that matches the requirements specified in this
|
|
Packit |
7cfc04 |
description in System V Release 3. 4.3 BSD and earlier versions did
|
|
Packit |
7cfc04 |
not include
|
|
Packit |
7cfc04 |
.IR dirname .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The behaviors of
|
|
Packit |
7cfc04 |
.IR basename
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR dirname
|
|
Packit |
7cfc04 |
in this volume of POSIX.1\(hy2008 have been coordinated so that when
|
|
Packit |
7cfc04 |
.IR string
|
|
Packit |
7cfc04 |
is a valid pathname:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
$(basename -- "\fIstring\fP")
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
would be a valid filename for the file in the directory:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
$(dirname -- "\fIstring\fP")
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
This would not work for the versions of these utilities in early proposals
|
|
Packit |
7cfc04 |
due to the way processing of trailing
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters was specified. Consideration was given to leaving processing
|
|
Packit |
7cfc04 |
unspecified if there were trailing
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters, but this cannot be done; the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 3.267" ", " "Pathname"
|
|
Packit |
7cfc04 |
allows trailing
|
|
Packit |
7cfc04 |
<slash>
|
|
Packit |
7cfc04 |
characters. The
|
|
Packit |
7cfc04 |
.IR basename
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR dirname
|
|
Packit |
7cfc04 |
utilities have to specify consistent handling for all valid pathnames.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "Section 2.5" ", " "Parameters and Variables",
|
|
Packit |
7cfc04 |
.IR "\fIbasename\fR\^"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 3.267" ", " "Pathname",
|
|
Packit |
7cfc04 |
.IR "Chapter 8" ", " "Environment Variables"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|