- bookworm 4.18.1-1
- bookworm-backports 4.24.0-2~bpo12+1
- testing 4.24.0-2
- unstable 4.24.0-2
getcwd(3) | Library Functions Manual | getcwd(3) |
ИМЯ¶
getcwd, getwd, get_current_dir_name - возвращают текущий рабочий каталог
LIBRARY¶
Standard C library (libc, -lc)
СИНТАКСИС¶
#include <unistd.h>
char *getcwd(char buf[.size], size_t size); char *get_current_dir_name(void);
[[deprecated]] char *getwd(char buf[PATH_MAX]);
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 <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>
Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.
5 февраля 2023 г. | Linux man-pages 6.03 |