FPATHCONF(3)               POSIX Programmer's Manual              FPATHCONF(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       fpathconf, pathconf -- get configurable pathname variables

SSYYNNOOPPSSIISS
       #include <unistd.h>

       long fpathconf(int _f_i_l_d_e_s, int _n_a_m_e);
       long pathconf(const char *_p_a_t_h, int _n_a_m_e);

DDEESSCCRRIIPPTTIIOONN
       The _f_p_a_t_h_c_o_n_f() and _p_a_t_h_c_o_n_f() functions shall determine the current
       value of a configurable limit or option (_v_a_r_i_a_b_l_e) that is associated
       with a file or directory.

       For _p_a_t_h_c_o_n_f(), the _p_a_t_h argument points to the pathname of a file or
       directory.

       For _f_p_a_t_h_c_o_n_f(), the _f_i_l_d_e_s argument is an open file descriptor.

       The _n_a_m_e argument represents the variable to be queried relative to
       that file or directory. Implementations shall support all of the
       variables listed in the following table and may support others. The
       variables in the following table come from _<_l_i_m_i_t_s_._h_> or _<_u_n_i_s_t_d_._h_> and
       the symbolic constants, defined in _<_u_n_i_s_t_d_._h_>, are the corresponding
       values used for _n_a_m_e.

       +----------------------------+--------------------------+--------------+
       |         VVaarriiaabbllee           |      VVaalluuee ooff _n_a_m_e       | RReeqquuiirreemmeennttss |
       +----------------------------+--------------------------+--------------+
       |{FILESIZEBITS}              | _PC_FILESIZEBITS         | 4,7          |
       |{LINK_MAX}                  | _PC_LINK_MAX             | 1            |
       |{MAX_CANON}                 | _PC_MAX_CANON            | 2            |
       |{MAX_INPUT}                 | _PC_MAX_INPUT            | 2            |
       |{NAME_MAX}                  | _PC_NAME_MAX             | 3,4          |
       |{PATH_MAX}                  | _PC_PATH_MAX             | 4,5          |
       |{PIPE_BUF}                  | _PC_PIPE_BUF             | 6            |
       |{POSIX2_SYMLINKS}           | _PC_2_SYMLINKS           | 4            |
       |{POSIX_ALLOC_SIZE_MIN}      | _PC_ALLOC_SIZE_MIN       | 10           |
       |{POSIX_REC_INCR_XFER_SIZE}  | _PC_REC_INCR_XFER_SIZE   | 10           |
       |{POSIX_REC_MAX_XFER_SIZE}   | _PC_REC_MAX_XFER_SIZE    | 10           |
       |{POSIX_REC_MIN_XFER_SIZE}   | _PC_REC_MIN_XFER_SIZE    | 10           |
       |{POSIX_REC_XFER_ALIGN}      | _PC_REC_XFER_ALIGN       | 10           |
       |{SYMLINK_MAX}               | _PC_SYMLINK_MAX          | 4,9          |
       |_POSIX_CHOWN_RESTRICTED     | _PC_CHOWN_RESTRICTED     | 7            |
       |_POSIX_NO_TRUNC             | _PC_NO_TRUNC             | 3,4          |
       |_POSIX_VDISABLE             | _PC_VDISABLE             | 2            |
       |_POSIX_ASYNC_IO             | _PC_ASYNC_IO             | 8            |
       |_POSIX_PRIO_IO              | _PC_PRIO_IO              | 8            |
       |_POSIX_SYNC_IO              | _PC_SYNC_IO              | 8            |
       |_POSIX_TIMESTAMP_RESOLUTION | _PC_TIMESTAMP_RESOLUTION | 1            |
       +----------------------------+--------------------------+--------------+
   RReeqquuiirreemmeennttss
        1. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, the value returned shall
           apply to the directory itself.

        2. If _p_a_t_h or _f_i_l_d_e_s does not refer to a terminal file, it is
           unspecified whether an implementation supports an association of
           the variable name with the specified file.

        3. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, the value returned shall
           apply to filenames within the directory.

        4. If _p_a_t_h or _f_i_l_d_e_s does not refer to a directory, it is unspecified
           whether an implementation supports an association of the variable
           name with the specified file.

        5. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, the value returned shall
           be the maximum length of a relative pathname that would not cross
           any mount points when the specified directory is the working
           directory.

        6. If _p_a_t_h refers to a FIFO, or _f_i_l_d_e_s refers to a pipe or FIFO, the
           value returned shall apply to the referenced object. If _p_a_t_h or
           _f_i_l_d_e_s refers to a directory, the value returned shall apply to any
           FIFO that exists or can be created within the directory. If _p_a_t_h or
           _f_i_l_d_e_s refers to any other type of file, it is unspecified whether
           an implementation supports an association of the variable name with
           the specified file.

        7. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, the value returned shall
           apply to any files, other than directories, that exist or can be
           created within the directory.

        8. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, it is unspecified whether
           an implementation supports an association of the variable name with
           the specified file.

        9. If _p_a_t_h or _f_i_l_d_e_s refers to a directory, the value returned shall
           be the maximum length of the string that a symbolic link in that
           directory can contain.

       10. If _p_a_t_h or _f_i_l_d_e_s des does not refer to a regular file, it is
           unspecified whether an implementation supports an association of
           the variable name with the specified file. If an implementation
           supports such an association for other than a regular file, the
           value returned is unspecified.

RREETTUURRNN VVAALLUUEE
       If _n_a_m_e is an invalid value, both _p_a_t_h_c_o_n_f() and _f_p_a_t_h_c_o_n_f() shall
       return -1 and set _e_r_r_n_o to indicate the error.

       If the variable corresponding to _n_a_m_e is described in _<_l_i_m_i_t_s_._h_> as a
       maximum or minimum value and the variable has no limit for the path or
       file descriptor, both _p_a_t_h_c_o_n_f() and _f_p_a_t_h_c_o_n_f() shall return -1
       without changing _e_r_r_n_o.  Note that indefinite limits do not imply
       infinite limits; see _<_l_i_m_i_t_s_._h_>.

       If the implementation needs to use _p_a_t_h to determine the value of _n_a_m_e
       and the implementation does not support the association of _n_a_m_e with
       the file specified by _p_a_t_h, or if the process did not have appropriate
       privileges to query the file specified by _p_a_t_h, or _p_a_t_h does not exist,
       _p_a_t_h_c_o_n_f() shall return -1 and set _e_r_r_n_o to indicate the error.

       If the implementation needs to use _f_i_l_d_e_s to determine the value of
       _n_a_m_e and the implementation does not support the association of _n_a_m_e
       with the file specified by _f_i_l_d_e_s, or if _f_i_l_d_e_s is an invalid file
       descriptor, _f_p_a_t_h_c_o_n_f() shall return -1 and set _e_r_r_n_o to indicate the
       error.

       Otherwise, _p_a_t_h_c_o_n_f() or _f_p_a_t_h_c_o_n_f() shall return the current variable
       value for the file or directory without changing _e_r_r_n_o.  The value
       returned shall not be more restrictive than the corresponding value
       available to the application when it was compiled with the
       implementation's _<_l_i_m_i_t_s_._h_> or _<_u_n_i_s_t_d_._h_>.

       If the variable corresponding to _n_a_m_e is dependent on an unsupported
       option, the results are unspecified.

EERRRROORRSS
       The _p_a_t_h_c_o_n_f() function shall fail if:

       EEIINNVVAALL The value of _n_a_m_e is not valid.

       EELLOOOOPP  A loop exists in symbolic links encountered during resolution of
              the _p_a_t_h argument.

       EEOOVVEERRFFLLOOWW
              The value of _n_a_m_e is _PC_TIMESTAMP_RESOLUTION and the resolution
              is larger than {LONG_MAX}.

       The _p_a_t_h_c_o_n_f() function may fail if:

       EEAACCCCEESS Search permission is denied for a component of the path prefix.

       EEIINNVVAALL The implementation does not support an association of the
              variable _n_a_m_e with the specified file.

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of a pathname is longer than
              {NAME_MAX}.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a pathname exceeds {PATH_MAX}, or pathname
              resolution of a symbolic link produced an intermediate result
              with a length that exceeds {PATH_MAX}.

       EENNOOEENNTT A component of _p_a_t_h does not name an existing file or _p_a_t_h is an
              empty string.

       EENNOOTTDDIIRR
              A component of the path prefix names an existing file that is
              neither a directory nor a symbolic link to a directory, or the
              _p_a_t_h argument contains at least one non-<slash> character and
              ends with one or more trailing <slash> characters and the last
              pathname component names an existing file that is neither a
              directory nor a symbolic link to a directory.

       The _f_p_a_t_h_c_o_n_f() function shall fail if:

       EEIINNVVAALL The value of _n_a_m_e is not valid.

       EEOOVVEERRFFLLOOWW
              The value of _n_a_m_e is _PC_TIMESTAMP_RESOLUTION and the resolution
              is larger than {LONG_MAX}.

       The _f_p_a_t_h_c_o_n_f() function may fail if:

       EEBBAADDFF  The _f_i_l_d_e_s argument is not a valid file descriptor.

       EEIINNVVAALL The implementation does not support an association of the
              variable _n_a_m_e with the specified file.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Application developers should check whether an option, such as
       _POSIX_ADVISORY_INFO, is supported prior to obtaining and using values
       for related variables such as {POSIX_ALLOC_SIZE_MIN}.

RRAATTIIOONNAALLEE
       The _p_a_t_h_c_o_n_f() function was proposed immediately after the _s_y_s_c_o_n_f()
       function when it was realized that some configurable values may differ
       across file system, directory, or device boundaries.

       For example, {NAME_MAX} frequently changes between System V and BSD-
       based file systems; System V uses a maximum of 14, BSD 255. On an
       implementation that provides both types of file systems, an application
       would be forced to limit all pathname components to 14 bytes, as this
       would be the value specified in _<_l_i_m_i_t_s_._h_> on such a system.

       Therefore, various useful values can be queried on any pathname or file
       descriptor, assuming that appropriate privileges are in place.

       The value returned for the variable {PATH_MAX} indicates the longest
       relative pathname that could be given if the specified directory is the
       current working directory of the process. A process may not always be
       able to generate a name that long and use it if a subdirectory in the
       pathname crosses into a more restrictive file system. Note that
       implementations are allowed to accept pathnames longer than {PATH_MAX}
       bytes long, but are not allowed to return pathnames longer than this
       unless the user specifies a larger buffer using a function that
       provides a buffer size argument.

       The value returned for the variable _POSIX_CHOWN_RESTRICTED also
       applies to directories that do not have file systems mounted on them.
       The value may change when crossing a mount point, so applications that
       need to know should check for each directory. (An even easier check is
       to try the _c_h_o_w_n() function and look for an error in case it happens.)

       Unlike the values returned by _s_y_s_c_o_n_f(), the pathname-oriented
       variables are potentially more volatile and are not guaranteed to
       remain constant throughout the lifetime of the process.  For example,
       in between two calls to _p_a_t_h_c_o_n_f(), the file system in question may
       have been unmounted and remounted with different characteristics.

       Also note that most of the errors are optional. If one of the variables
       always has the same value on an implementation, the implementation need
       not look at _p_a_t_h or _f_i_l_d_e_s to return that value and is, therefore, not
       required to detect any of the errors except the meaning of [[EEIINNVVAALL]]
       that indicates that the value of _n_a_m_e is not valid for that variable.

       If the value of any of the limits is unspecified (logically infinite),
       they will not be defined in _<_l_i_m_i_t_s_._h_> and the _p_a_t_h_c_o_n_f() and
       _f_p_a_t_h_c_o_n_f() functions return -1 without changing _e_r_r_n_o.  This can be
       distinguished from the case of giving an unrecognized _n_a_m_e argument
       because _e_r_r_n_o is set to [[EEIINNVVAALL]] in this case.

       Since -1 is a valid return value for the _p_a_t_h_c_o_n_f() and _f_p_a_t_h_c_o_n_f()
       functions, applications should set _e_r_r_n_o to zero before calling them
       and check _e_r_r_n_o only if the return value is -1.

       For the case of {SYMLINK_MAX}, since both _p_a_t_h_c_o_n_f() and _o_p_e_n() follow
       symbolic links, there is no way that _p_a_t_h or _f_i_l_d_e_s could refer to a
       symbolic link.

       It was the intention of IEEE Std 1003.1d-1999 that the following
       variables:

              {POSIX_ALLOC_SIZE_MIN} {POSIX_REC_INCR_XFER_SIZE}
              {POSIX_REC_MAX_XFER_SIZE} {POSIX_REC_MIN_XFER_SIZE}
              {POSIX_REC_XFER_ALIGN}

       only applied to regular files, but Note 10 also permits implementation
       of the advisory semantics on other file types unique to an
       implementation (for example, a character special device).

       The [[EEOOVVEERRFFLLOOWW]] error for _PC_TIMESTAMP_RESOLUTION cannot occur on
       POSIX-compliant file systems because POSIX requires a timestamp
       resolution no larger than one second. Even on 32-bit systems, this can
       be represented without overflow.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_h_o_w_n(), _c_o_n_f_s_t_r(), _s_y_s_c_o_n_f()

       The Base Definitions volume of POSIX.1-2008, <<lliimmiittss..hh>>, <<uunniissttdd..hh>>

       The Shell and Utilities volume of POSIX.1-2008, _g_e_t_c_o_n_f

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                         FPATHCONF(3)
