getcwd

ИМЯ

getcwd, getwd, get_current_dir_name - возвращают текущий рабочий каталог

СИНТАКСИС

#include <unistd.h>

char *getcwd(char buf[.size], size_t size);
char *get_current_dir_name(void);

[[deprecated]] char *getwd(char buf[PATH_MAX]);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

get_current_dir_name():

    _GNU_SOURCE

getwd():

    Since glibc 2.12:
        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
            || /* glibc <= 2.19: */ _BSD_SOURCE
    Before glibc 2.12:
        _BSD_SOURCE || _XOPEN_SOURCE >= 500

Данные функции возвращают строку (с null в конце), содержащую абсолютный путь текущего рабочего каталога вызывающего процесса. Путь возвращается как результат функции или в аргументе buf, если он есть.

Функция getcwd() копирует абсолютный путь текущего рабочего каталога в массив, на который указывает buf, имеющий длину size.

Если длина абсолютного пути, включая конечный байт null, превышает size байт, то возвращается NULL, а errno принимает значение ERANGE; приложение должно проверить, возникла эта ошибка или нет и, если необходимо, выделить буфер большего размера.

Согласно расширению стандарта POSIX.1-2001 в glibc предусмотрено следующее: если buf равно NULL, то при вызове getcwd() буфер выделяется динамически с помощью функции malloc(3). В этом случае выделенный буфер имеет размер size; если size равно нулю, то выделяется buf необходимого размера. Вызывающий после использования должен освободить выделенный буфер с помощью free(3).

Функция get_current_dir_name() выделит с помощью malloc(3) массив, достаточно большой для помещения в него абсолютного пути имени текущего каталога. Если существует и имеет правильное значение переменная окружения PWD, то будет возвращено её значение. Вызывающий после использования должен освободить выделенный буфер с помощью free(3).

Функция getwd() не выделяет память с помощью malloc(3). Аргумент buf должен быть указателем на массив длиной не менее PATH_MAX байтов. Если длина абсолютного пути текущего рабочего каталога, включая конечный байт null, превышает PATH_MAX байт, то возвращается NULL и errno присваивается значение ENAMETOOLONG (заметим, что в некоторых системах PATH_MAX может не являться константой времени компиляции; более того, её значение может зависеть от файловой системы, смотрите pathconf(3)). Для переносимости и безопасности использование getwd() не рекомендуется.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

On success, these functions return a pointer to a string containing the pathname of the current working directory. In the case of getcwd() and getwd() this is the same value as buf.

При ошибках эти функции возвращают NULL и в errno помещают причину ошибки. Содержимое массива buf в этом случае не определено.

ОШИБКИ

EACCES: Нет прав на чтение или поиск одного из компонентов пути файла.

EFAULT: Значение buf указывает на неправильный адрес.

EINVAL: Аргумент size равен нулю, а buf не является указателем null.

EINVAL: getwd(): buf равно NULL.

ENAMETOOLONG: getwd(): Размер строки абсолютного пути, включая конечный null, превышает PATH_MAX байт.

ENOENT: Текущий рабочий каталог был удалён.

ENOMEM: Не хватает памяти.

ERANGE: Аргумент size меньше длины абсолютного пути рабочего каталога, включая конечный байт null. Вам нужно выделить массив большего размера попробовать ещё раз.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
getcwd(), getwd()	Безвредность в нитях	MT-Safe
get_current_dir_name()	Безвредность в нитях	MT-Safe env

СТАНДАРТЫ

Функция getcwd() соответствует POSIX.1-2001. Однако заметим, что в POSIX.1-2001 не описано поведение getcwd(), если buf равно NULL.

Функция getwd() описана в POSIX.1-2001, но помечена как УСТАРЕВШАЯ. В POSIX.1-2008 getwd() удалена. Вместо неё используйте getcwd(). В POSIX.1-2001 не определены ошибки, возвращаемые getwd().

Функция get_current_dir_name() является расширением GNU.

ЗАМЕЧАНИЯ

В Linux, эти функции используют системный вызов getcwd() (доступен в Linux, начиная с версии 2.1.92). В старых системах они опрашивают /proc/self/cwd. Если в системе отсутствует системный вызов и файловая система proc, то задействуется обобщённая реализация. Только в этом случает данные вызовы в Linux могут завершиться с ошибкой EACCES.

Данные функции часто используются для сохранения расположения текущего рабочего каталога с целью возврата в него позднее. Открытие текущего каталога («.») и вызов fchdir(2) для возврата, обычно, более быстрая и надёжная альтернатива при наличии достаточного количества файловых дескрипторов, особенно на платформах, отличных от Linux.

Отличия между библиотекой C и ядром

Ядро Linux предоставляет системный вызов getcwd(), который, если возможно, будут использовать описываемые на этой страницы функции. Системный вызов имеет такие же параметры как и библиотечная функция с тем же именем, но возвращает не более PATH_MAX байт (до Linux 3.12 размер возвращаемого пути ограничивался размером системной страницы. На многих архитектурах PATH_MAX и размер системной страницы равны 4096 байтам, но у некоторых архитектур размер страницы больше этого значения). Если длина пути текущего рабочего каталога превышает это ограничение, то системный вызов возвращает ошибку ENAMETOOLONG. В этом случае библиотечные функции переходят к использованию альтернативной (медленной) реализации, которая возвращает полный путь.

После внесения изменения в Linux 2.6.36, путь, возвращаемый системным вызовом getcwd(), будет начинаться со строки «(unreachable)», если текущий каталог не ниже корневого каталога текущего процесса (например, из-за того, что процесс установил новую корневую файловую систему с помощью chroot(2) без изменения своего текущего каталога в новый корень). Такое поведение также проявляется у непривилегированного пользователя текущий каталог переводится в другое пространство имён монтирования. При работе с путём из недоверенных источников вызывающие описанные на этой странице функции должны учитывать, что возвращаемый путь может начинаться с «/» или «(», и не принимать недоступный путь за относительный.

ДЕФЕКТЫ

Так как изменения в Linux 2.6.36 добавляет при описанных выше определённых обстоятельствах «(unreachable)», реализация getcwd() в glibc нарушает POSIX и возвращает относительный путь, в то время как по соглашению API требуется абсолютный путь. В glibc 2.27 и новее это исправлено; вызов getcwd() из такого пути приводит к ошибке ENOENT.

СМ. ТАКЖЕ

pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <[email protected]>, Dmitry Bolkhovskikh <[email protected]>, Vladislav <[email protected]>, Yuri Kozlov <[email protected]> и Иван Павлов <[email protected]>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на [email protected]

5 февраля 2023 г.

Linux man-pages 6.03