.\" -*- coding: UTF-8 -*-
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>,
.\" Copyright (C) 2008-2014, Michael Kerrisk <mtk.manpages@gmail.com>,
.\" and Copyright (C) 2016, Heinrich Schuchardt <xypron.glpk@gmx.de>
.\"
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.\" %%%LICENSE_END
.\"
.\" Modified, 2003-12-02, Michael Kerrisk, <mtk.manpages@gmail.com>
.\" Modified, 2003-09-23, Adam Langley
.\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com>
.\"	Added SOCK_SEQPACKET
.\" 2008-05-27, mtk, Provide a clear description of the three types of
.\"     address that can appear in the sockaddr_un structure: pathname,
.\"     unnamed, and abstract.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH UNIX 7 "1 listopada 2020 r." Linux "Podręcznik programisty Linuksa"
.SH NAZWA
unix \- gniazda lokalnej komunikacji międzyprocesowej
.SH SKŁADNIA
\fB#include <sys/socket.h>\fP
.br
\fB#include <sys/un.h>\fP
.PP
\fIunix_socket\fP\fB = socket(AF_UNIX, type, 0);\fP
.br
\fIerror\fP\fB = socketpair(AF_UNIX, type, 0, int *\fP\fIsv\fP\fB);\fP
.SH OPIS
Rodzina gniazd \fBAF_UNIX\fP (znana również jako \fBAF_LOCAL\fP) służy do wydajnej
komunikacji pomiędzy procesami na tej samej maszynie. Zgodnie z tradycją,
gniazda domeny uniksowej mogą być albo anonimowe (tworzone przez
\fBsocketpair\fP(2)), albo skojarzone z plikiem typu gniazda. Linux wspiera
również abstrakcyjną przestrzeń nazw, niezależną od systemu plików.
.PP
Poprawne typy gniazd w domenie Uniksa to: \fBSOCK_STREAM\fP dla gniazd
strumieniowych, \fBSOCK_DGRAM\fP dla  gniazd datagramowych, które zachowują
granice komunikatów (w przypadku większości implementacji Uniksa gniazda
uniksowe są zawsze niezawodne i nie zmieniają kolejności datagramów), oraz
(od wersji Linuksa 2.6.4) \fBSOCK_SEQPACKET\fP dla gniazd pakietów
sekwencyjnych zorientowanych połączeniowo, które zachowują granice
komunikatu i dostarczają komunikaty w kolejności ich wysyłania.
.PP
Za pośrednictwem pomocniczych danych można przez gniazda domeny uniksowej
przekazywać do innych procesów deskryptory plików i uwierzytelnienia
procesów.
.SS "Format adresu"
Adres gniazda domeny uniksowej jest reprezentowany przez następującą
strukturę:
.PP
.in +4n
.EX
.\" #define UNIX_PATH_MAX    108
.\"
struct sockaddr_un {
    sa_family_t sun_family;               /* AF_UNIX */
    char        sun_path[108];            /* Pathname */
};
.EE
.in
.PP
Pole \fIsun_family\fP zawsze zawiera \fBAF_UNIX\fP. W Linuksie \fIsun_path\fP ma
rozmiar 108 bajtów, zob. też UWAGI poniżej.
.PP
Różne wywołania systemowe (np. \fBbind\fP(2), \fBconnect\fP(2) i \fBsendto\fP(2))
przyjmują argument \fIsockaddr_un\fP jako wejście. Niektóre inne wywołania
systemowe (np. \fBgetsockname\fP(2), \fBgetpeername\fP(2), \fBrecvfrom\fP(2) i
\fBaccept\fP(2)) zwracają argument tego typu.
.PP
W strukturze \fIsockaddr_un\fP rozróżniane są trzy typy adresów:
.IP * 3
\fIpathname\fP: gniazdo domeny uniksowej może zostać związane z zakończoną
znakiem NULL nazwą ścieżki systemowej za pomocą \fBbind\fP(2). Jeśli adres
ścieżki gniazda jest zwracany (przez jedno z ww. wywołań\ systemowych) to
jego długością jest
.IP
    offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1
.IP
a \fIsun_path\fP zawiera zakończoną null ścieżkę. (W Linuksie powyższe
wyrażenie \fBoffsetof\fP() jest równe tej samej wartości co
\fIsizeof(sa_family_t)\fP, lecz niektóre inne implementacje dołączają\ inne pola
przed \fIsun_path\fP, więc bardziej przenośnie, wyrażenie \fBoffsetof\fP() opisuje
rozmiar struktury adresu).
.IP
Więcej informacji o ścieżkach gniazd znajduje się\ poniżej.
.IP *
.\" There is quite some variation across implementations: FreeBSD
.\" says the length is 16 bytes, HP-UX 11 says it's zero bytes.
\fIunnamed\fP: Gniazdo strumieniowe nie związane z nazwą ścieżki za pomocą
\fBbind\fP(2) nie jest nazwane. Podobnie dwa gniazda utworzone przez
\fBsocketpair\fP(2) nie są nazwane. Jeśli adres nienazwanego gniazda jest
zwracany, to jego długością jest \fIsizeof(sa_family_t)\fP, a zawartość
\fIsun_path\fP nie powinna być sprawdzana.
.IP *
\fIabstract\fP: adres gniazda abstrakcyjnego jest rozróżniany (od adresu
ścieżki) po tym, że \fIsun_path[0]\fP jest bajtem NULL (\(aq\e0\(aq). Adres
gniazda znajduje się w przestrzeni nazw podanej w dodatkowych bajtach w
\fIsun_path\fP, które są pokryte przez długość struktury adresu (Bajty NULL w
nazwie nie mają żadnego specjalnego znaczenia). Nazwa nie ma żadnego
powiązania z nazwą pliku w systemie plików. Zwracany adres gniazda
abstrakcyjnego ma w polu \fIaddrlen\fP ustawioną długość większą niż
\fIsizeof(sa_family_t)\fP (tj. większą niż 2), a nazwa gniazda zawarta jest w
pierwszych \fI(addrlen \- sizeof(sa_family_t))\fP bajtach pola \fIsun_path\fP.
.SS "Ścieżki gniazd"
Przy przypisywaniu gniazda do ścieżki powinno się\ przestrzegać kilku zasad w
celu maksymalnej przenośności i łatwości programowania:
.IP * 3
Ścieżka w \fIsun_path\fP powinna być zakończona znakiem NULL.
.IP *
Długość ścieżki, w tym kończący bajt null nie powinna przekraczać rozmiaru
\fIsun_path\fP.
.IP *
Argument \fIaddrlen\fP opisujący obejmującą\ strukturę \fIsockaddr_un\fP powinien
mieć wartość przynajmniej:
.IP
.nf
    offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1
.fi
.IP
lub, prościej, \fIaddrlen\fP powinien być\ podany jako \fIsizeof(struct
sockaddr_un)\fP.
.PP
.\" Linux does this, including for the case where the supplied path
.\" is 108 bytes
W różnych implementacjach różnie obsługiwane są adresy gniazd domen Uniksa,
które nie przestrzegają powyższych zaleceń. Na przykład niektóre (lecz nie
wszystkie) implementacje dodają kończący znak null, jeśli nie jest on obecny
w przekazanej \fIsun_path\fP.
.PP
.\" HP-UX
.\" Modern BSDs generally have 104, Tru64 and AIX have 104,
.\" Solaris and Irix have 108
Przy programowaniu przenośnych aplikacji proszę\ wziąć pod uwagę, że niektóre
implementację mają \fIsun_path\fP o długości zaledwie 92 bajtów.
.PP
.\"
Różne wywołania systemowe (\fBaccept\fP(2), \fBrecvfrom\fP(2), \fBgetsockname\fP(2),
\fBgetpeername\fP(2)) zwracają struktury adresów gniazd. Gdy chodzi o gniazda
domeny Uniksa, wartość\-rezultat argumentu \fIaddrlen\fP umieszczonego w
wywołaniu powinna być\ zainicjowana jw. Gdy jest zwracany, argument ten jest
ustawiany aby przedstawiać \fIaktualny\fP rozmiar struktury adresu. Wywołujący
powinien sprawdzić wartość zwracaną w tym argumencie, jeśli wartość
wyjściowa przekracza wartość wejściową, to nie ma gwarancji, że kończący
znak null jest obecny w \fIsun_path\fP (zob PROBLEMY).
.SS "Pathname socket ownership and permissions"
In the Linux implementation, pathname sockets honor the permissions of the
directory they are in.  Creation of a new socket fails if the process does
not have write and search (execute) permission on the directory in which the
socket is created.
.PP
On Linux, connecting to a stream socket object requires write permission on
that socket; sending a datagram to a datagram socket likewise requires write
permission on that socket.  POSIX does not make any statement about the
effect of the permissions on a socket file, and on some systems (e.g., older
BSDs), the socket permissions are ignored.  Portable programs should not
rely on this feature for security.
.PP
When creating a new socket, the owner and group of the socket file are set
according to the usual rules.  The socket file has all permissions enabled,
other than those that are turned off by the process \fBumask\fP(2).
.PP
.\" However, fchown() and fchmod() do not seem to have an effect
.\"
The owner, group, and permissions of a pathname socket can be changed (using
\fBchown\fP(2)  and \fBchmod\fP(2)).
.SS "Abstract sockets"
Socket permissions have no meaning for abstract sockets: the process
\fBumask\fP(2)  has no effect when binding an abstract socket, and changing the
ownership and permissions of the object (via \fBfchown\fP(2)  and \fBfchmod\fP(2))
has no effect on the accessibility of the socket.
.PP
Abstract sockets automatically disappear when all open references to the
socket are closed.
.PP
.\"
The abstract socket namespace is a nonportable Linux extension.
.SS "Opcje gniazda"
Ze względów historycznych następujące opcje gniazd są podawane przy typie
\fBSOL_SOCKET\fP, pomimo że są one specyficzne dla \fBAF_UNIX\fP. Można je ustawić
za pomocą \fBsetsockopt\fP(2), a odczytać za pomocą \fBgetsockopt\fP(2), podając
\fBSOL_SOCKET\fP jako rodzinę gniazd.
.TP 
\fBSO_PASSCRED\fP
Enabling this socket option causes receipt of the credentials of the sending
process in an \fBSCM_CREDENTIALS ancillary\fP message in each subsequently
received message.  The returned credentials are those specified by the
sender using \fBSCM_CREDENTIALS\fP, or a default that includes the sender's
PID, real user ID, and real group ID, if the sender did not specify
\fBSCM_CREDENTIALS\fP ancillary data.
.IP
Przy włączonej tej opcji i niepołączonym jeszcze gnieździe, unikatowa nazwa
gniazda z abstrakcyjnej przestrzeni nazw jest generowana automatycznie.
.IP
The value given as an argument to \fBsetsockopt\fP(2)  and returned as the
result of \fBgetsockopt\fP(2)  is an integer boolean flag.
.TP 
\fBSO_PASSSEC\fP
Enables receiving of the SELinux security label of the peer socket in an
ancillary message of type \fBSCM_SECURITY\fP (see below).
.IP
The value given as an argument to \fBsetsockopt\fP(2)  and returned as the
result of \fBgetsockopt\fP(2)  is an integer boolean flag.
.IP
.\" commit 877ce7c1b3afd69a9b1caeb1b9964c992641f52a
.\" commit 37a9a8df8ce9de6ea73349c9ac8bdf6ba4ec4f70
The \fBSO_PASSSEC\fP option is supported for UNIX domain datagram sockets since
Linux 2.6.18; support for UNIX domain stream sockets was added in Linux 4.2.
.TP 
\fBSO_PEEK_OFF\fP
Patrz \fBsocket\fP(7).
.TP 
\fBSO_PEERCRED\fP
This read\-only socket option returns the credentials of the peer process
connected to this socket.  The returned credentials are those that were in
effect at the time of the call to \fBconnect\fP(2)  or \fBsocketpair\fP(2).
.IP
The argument to \fBgetsockopt\fP(2)  is a pointer to a \fIucred\fP structure;
define the \fB_GNU_SOURCE\fP feature test macro to obtain the definition of
that structure from \fI<sys/socket.h>\fP.
.IP
The use of this option is possible only for connected \fBAF_UNIX\fP stream
sockets and for \fBAF_UNIX\fP stream and datagram socket pairs created using
\fBsocketpair\fP(2).
.TP 
\fBSO_PEERSEC\fP
This read\-only socket option returns the security context of the peer socket
connected to this socket.  By default, this will be the same as the security
context of the process that created the peer socket unless overridden by the
policy or by a process with the required permissions.
.IP
The argument to \fBgetsockopt\fP(2)  is a pointer to a buffer of the specified
length in bytes into which the security context string will be copied.  If
the buffer length is less than the length of the security context string,
then \fBgetsockopt\fP(2)  returns \-1, sets \fIerrno\fP to \fBERANGE\fP, and returns
the required length via \fIoptlen\fP.  The caller should allocate at least
\fBNAME_MAX\fP bytes for the buffer initially, although this is not guaranteed
to be sufficient.  Resizing the buffer to the returned length and retrying
may be necessary.
.IP
The security context string may include a terminating null character in the
returned length, but is not guaranteed to do so: a security context "foo"
might be represented as either {'f','o','o'} of length 3 or
{'f','o','o','\e0'} of length 4, which are considered to be
interchangeable.  The string is printable, does not contain non\-terminating
null characters, and is in an unspecified encoding (in particular, it is not
guaranteed to be ASCII or UTF\-8).
.IP
.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
.\"
The use of this option for sockets in the \fBAF_UNIX\fP address family is
supported since Linux 2.6.2 for connected stream sockets, and since Linux
4.18 also for stream and datagram socket pairs created using
\fBsocketpair\fP(2).
.SS "Automatyczne przypisywanie adresów"
.\" i.e., sizeof(short)
Jeśli w wywołaniu \fBbind\fP(2) podane zostanie \fIaddrlen\fP równe
\fIsizeof(sa_family_t)\fP lub opcja \fBSO_PASSCRED\fP gniazda była ustawiona dla
gniazda nieprzypisanego do adresu, wtedy gniazdo jest automatycznie
przypisywane do adresu abstrakcyjnego. Adres ten składa się z bajtu NULL, po
którym następuje 5 bajtów ze zbioru znaków \fI[0\-9a\-f]\fP. W związku z tym
liczba automatycznie przypisywanych adresów jest ograniczona przez 2^20. (W
Linuksie 2.1.15, w którym dodano możliwość automatycznego przypisywania
adresów, i w kolejnych wersjach używane było 8 bajtów, a limit wynosił 2^32
adresów. Zostało to zmienione na 5 bajtów w Linuksie 2.3.15).
.SS "API gniazd"
W kolejnych paragrafach opisano pewne szczegóły implementacji API gniazd
domeny UNIX specyficzne dla Linuksa oraz cechy niewspierane.
.PP
Gniazda z domeny uniksowej nie obsługują zawiadomienia o danych
autonomicznych (flaga \fBMSG_OOB\fP funkcji \fBsend\fP(2) i \fBrecv\fP(2)).
.PP
Flaga \fBMSG_MORE\fP funkcji \fBsend\fP(2) nie jest obsługiwana dla gniazd domeny
uniksowej.
.PP
.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
Before Linux 3.4, the use of \fBMSG_TRUNC\fP in the \fIflags\fP argument of
\fBrecv\fP(2)  was not supported by UNIX domain sockets.
.PP
Opcja \fBSO_SNDBUF\fP działa w przypadku gniazd domeny uniksowej, ale opcja
\fBSO_RCVBUF\fP już nie. Dla gniazd datagramowych wartość \fBSO_SNDBUF\fP nakłada
górny limit na rozmiar wychodzących datagramów. Limit ten jest liczony jako
podwojona (patrz \fBsocket\fP(7)) wartość opcji minus 32 bajty wymagane na
informacje nie będące danymi.
.SS "Komunikaty pomocnicze"
Dane pomocnicze są wysyłane i odbierane za pomocą \fBsendmsg\fP(2) i
\fBrecvmsg\fP(2). Ze względów historycznych komunikaty pomocnicze poniższych
typów są podawane przy typie \fBSOL_SOCKET\fP, pomimo że są one specyficzne dla
\fBAF_UNIX\fP. Aby je wysłać, należy ustawić pole \fIcmsg_level\fP struktury
\fIcmsghdr\fP na \fBSOL_SOCKET\fP, a pole \fIcmsg_type\fP na typ. Więcej informacji
można znaleźć w \fBcmsg\fP(3).
.TP 
\fBSCM_RIGHTS\fP
Odbieranie od innego procesu lub wysyłanie do niego zbioru otwartych
deskryptorów plików. Porcja danych zawiera tablicę liczb całkowitych
będących deskryptorami plików.
.IP
Commonly, this operation is referred to as "passing a file descriptor" to
another process.  However, more accurately, what is being passed is a
reference to an open file description (see \fBopen\fP(2)), and in the receiving
process it is likely that a different file descriptor number will be used.
Semantically, this operation is equivalent to duplicating (\fBdup\fP(2))  a
file descriptor into the file descriptor table of another process.
.IP
If the buffer used to receive the ancillary data containing file descriptors
is too small (or is absent), then the ancillary data is truncated (or
discarded)  and the excess file descriptors are automatically closed in the
receiving process.
.IP
If the number of file descriptors received in the ancillary data would cause
the process to exceed its \fBRLIMIT_NOFILE\fP resource limit (see
\fBgetrlimit\fP(2)), the excess file descriptors are automatically closed in
the receiving process.
.IP
.\" commit bba14de98753cb6599a2dae0e520714b2153522d
The kernel constant \fBSCM_MAX_FD\fP defines a limit on the number of file
descriptors in the array.  Attempting to send an array larger than this
limit causes \fBsendmsg\fP(2)  to fail with the error \fBEINVAL\fP.  \fBSCM_MAX_FD\fP
has the value 253 (or 255 in kernels before 2.6.38).
.TP 
\fBSCM_CREDENTIALS\fP
Odbieranie lub wysyłanie uwierzytelnień uniksowych. Może służyć do
autoryzacji. Uwierzytelnienia są przekazywane jako komunikat pomocniczy typu
\fIstruct ucred\fP, zdefiniowanego w \fI<sys/socket.h>\fP następująco:
.IP
.in +4n
.EX
struct ucred {
    pid_t pid;  /* identyfikator procesu wysyłającego */
    uid_t uid;  /* ident. użytkownika procesu wysyłającego */
    gid_t gid;  /* ident. grupy procesu wysyłającego */
};
.EE
.in
.IP
Począwszy od wersji 2.8 biblioteki glibc, aby uzyskać dostęp do definicji
powyższej struktury, należy zdefiniować makro \fB_GNU_SOURCE\fP (przed
dołączeniem \fIjakichkolwiek\fP plików nagłówkowych).
.IP
The credentials which the sender specifies are checked by the kernel.  A
privileged process is allowed to specify values that do not match its own.
The sender must specify its own process ID (unless it has the capability
\fBCAP_SYS_ADMIN\fP, in which case the PID of any existing process may be
specified), its real user ID, effective user ID, or saved set\-user\-ID
(unless it has \fBCAP_SETUID\fP), and its real group ID, effective group ID, or
saved set\-group\-ID (unless it has \fBCAP_SETGID\fP).
.IP
To receive a \fIstruct ucred\fP message, the \fBSO_PASSCRED\fP option must be
enabled on the socket.
.TP 
\fBSCM_SECURITY\fP
Receive the SELinux security context (the security label)  of the peer
socket.  The received ancillary data is a null\-terminated string containing
the security context.  The receiver should allocate at least \fBNAME_MAX\fP
bytes in the data portion of the ancillary message for this data.
.IP
To receive the security context, the \fBSO_PASSSEC\fP option must be enabled on
the socket (see above).
.PP
When sending ancillary data with \fBsendmsg\fP(2), only one item of each of the
above types may be included in the sent message.
.PP
At least one byte of real data should be sent when sending ancillary data.
On Linux, this is required to successfully send ancillary data over a UNIX
domain stream socket.  When sending ancillary data over a UNIX domain
datagram socket, it is not necessary on Linux to send any accompanying real
data.  However, portable applications should also include at least one byte
of real data when sending ancillary data over a datagram socket.
.PP
When receiving from a stream socket, ancillary data forms a kind of barrier
for the received data.  For example, suppose that the sender transmits as
follows:
.PP
.RS
.PD 0
.IP 1. 3
\fBsendmsg\fP(2)  of four bytes, with no ancillary data.
.IP 2.
\fBsendmsg\fP(2)  of one byte, with ancillary data.
.IP 3.
\fBsendmsg\fP(2)  of four bytes, with no ancillary data.
.PD
.RE
.PP
Suppose that the receiver now performs \fBrecvmsg\fP(2)  calls each with a
buffer size of 20 bytes.  The first call will receive five bytes of data,
along with the ancillary data sent by the second \fBsendmsg\fP(2)  call.  The
next call will receive the remaining four bytes of data.
.PP
.\"
If the space allocated for receiving incoming ancillary data is too small
then the ancillary data is truncated to the number of headers that will fit
in the supplied buffer (or, in the case of an \fBSCM_RIGHTS\fP file descriptor
list, the list of file descriptors may be truncated).  If no buffer is
provided for incoming ancillary data (i.e., the \fImsg_control\fP field of the
\fImsghdr\fP structure supplied to \fBrecvmsg\fP(2)  is NULL), then the incoming
ancillary data is discarded.  In both of these cases, the \fBMSG_CTRUNC\fP flag
will be set in the \fImsg.msg_flags\fP value returned by \fBrecvmsg\fP(2).
.SS "Kontrolki systemowe (ioctl)"
Następujące wywołania \fBioctl\fP(2) zwracają informacje w parametrze
\fIvalue\fP. Poprawna składnia to:
.PP
.RS
.nf
\fBint\fP\fI value\fP\fB;\fP
\fIerror\fP\fB = ioctl(\fP\fIunix_socket\fP\fB, \fP\fIioctl_type\fP\fB, &\fP\fIvalue\fP\fB);\fP
.fi
.RE
.PP
\fIioctl_type\fP może przyjmować wartość:
.TP 
\fBSIOCINQ\fP
.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
.\" SIOCOUTQ also has an effect for UNIX domain sockets, but not
.\" quite what userland might expect. It seems to return the number
.\" of bytes allocated for buffers containing pending output.
.\" That number is normally larger than the number of bytes of pending
.\" output. Since this info is, from userland's point of view, imprecise,
.\" and it may well change, probably best not to document this now.
For \fBSOCK_STREAM\fP sockets, this call returns the number of unread bytes in
the receive buffer.  The socket must not be in LISTEN state, otherwise an
error (\fBEINVAL\fP)  is returned.  \fBSIOCINQ\fP is defined in
\fI<linux/sockios.h>\fP.  Alternatively, you can use the synonymous
\fBFIONREAD\fP, defined in \fI<sys/ioctl.h>\fP.  For \fBSOCK_DGRAM\fP
sockets, the returned value is the same as for Internet domain datagram
sockets; see \fBudp\fP(7).
.SH BŁĘDY
.TP 
\fBEADDRINUSE\fP
Podany adres lokalny jest zajęty lub obiekt gniazda w systemie plików już
istnieje.
.TP 
\fBEBADF\fP
This error can occur for \fBsendmsg\fP(2)  when sending a file descriptor as
ancillary data over a UNIX domain socket (see the description of
\fBSCM_RIGHTS\fP, above), and indicates that the file descriptor number that is
being sent is not valid (e.g., it is not an open file descriptor).
.TP 
\fBECONNREFUSED\fP
Adres zdalny podany w \fBconnect\fP(2) nie odnosił się do gniazda
nasłuchującego. Błąd może także wystąpić jeśli docelowa ścieżka nie jest
gniazdem.
.TP 
\fBECONNRESET\fP
Zdalne gniazdo zostało nieoczekiwanie zamknięte.
.TP 
\fBEFAULT\fP
Nieprawidłowy adres pamięci użytkownika.
.TP 
\fBEINVAL\fP
Podano nieprawidłowy argument. Najczęstszą przyczyną jest brak ustawionego
\fBAF_UNIX\fP w polu \fIsun_type\fP przekazywanych gniazdu adresów lub
nieprawidłowy dla danej operacji stan gniazda.
.TP 
\fBEISCONN\fP
Wywołano \fBconnect\fP(2) dla już połączonego gniazda lub podano adres docelowy
dla połączonego gniazda.
.TP 
\fBENOENT\fP
Nie istnieje ścieżka dla zdalnego adresu przekazanego do \fBconnect\fP(2).
.TP 
\fBENOMEM\fP
Brak pamięci.
.TP 
\fBENOTCONN\fP
Operacja na gnieździe wymaga adresu docelowego, a gniazdo nie jest
połączone.
.TP 
\fBEOPNOTSUPP\fP
Operacja strumieniowa wywołana dla gniazda niestrumieniowego lub próba
użycia opcji danych autonomicznych.
.TP 
\fBEPERM\fP
Wysyłający podał nieprawidłowe uwierzytelnienia w \fIstruct ucred\fP.
.TP 
\fBEPIPE\fP
Zdalne gniazdo strumieniowe zostało zamknięte. Gdy włączone, wysyłany jest
jednocześnie sygnał \fBSIGPIPE\fP. Można tego uniknąć, przekazując znacznik
\fBMSG_NOSIGNAL\fP do \fBsend\fP(2) lub \fBsendmsg\fP(2).
.TP 
\fBEPROTONOSUPPORT\fP
Podanym protokołem nie jest \fBAF_UNIX\fP.
.TP 
\fBEPROTOTYPE\fP
Typ gniazda zdalnego różni się od typu gniazda lokalnego (\fBSOCK_DGRAM\fP
wobec \fBSOCK_STREAM\fP).
.TP 
\fBESOCKTNOSUPPORT\fP
Nieznany typ gniazda.
.TP 
\fBESRCH\fP
While sending an ancillary message containing credentials
(\fBSCM_CREDENTIALS\fP), the caller specified a PID that does not match any
existing process.
.TP 
\fBETOOMANYREFS\fP
This error can occur for \fBsendmsg\fP(2)  when sending a file descriptor as
ancillary data over a UNIX domain socket (see the description of
\fBSCM_RIGHTS\fP, above).  It occurs if the number of "in\-flight" file
descriptors exceeds the \fBRLIMIT_NOFILE\fP resource limit and the caller does
not have the \fBCAP_SYS_RESOURCE\fP capability.  An in\-flight file descriptor
is one that has been sent using \fBsendmsg\fP(2)  but has not yet been accepted
in the recipient process using \fBrecvmsg\fP(2).
.IP
.\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593
This error is diagnosed since mainline Linux 4.5 (and in some earlier kernel
versions where the fix has been backported).  In earlier kernel versions, it
was possible to place an unlimited number of file descriptors in flight, by
sending each file descriptor with \fBsendmsg\fP(2)  and then closing the file
descriptor so that it was not accounted against the \fBRLIMIT_NOFILE\fP
resource limit.
.PP
Inne błędy mogą zostać wygenerowane przez podstawową warstwę gniazd lub
przez system plików podczas tworzenia obiektu gniazda w systemie
plików. Więcej informacji można znaleźć na odpowiednich stronach
podręcznika.
.SH WERSJE
\fBSCM_CREDENTIALS\fP oraz abstrakcyjna przestrzeń nazw zostały wprowadzone w
Linuksie 2.2 i nie należy ich używać w przenośnych programach. (Niektóre
systemy wywodzące się z BSD również wspierają przekazywanie uwierzytelnień,
ale implementacje różnią się szczegółami).
.SH UWAGI
W trakcie łączenia się z gniazdem mającym przypisaną nazwę pliku, tworzony
jest plik specjalny gniazda w systemie plików, który musi zostać usunięty
(za pomocą \fBunlink\fP(2)) przez wywołującego, gdy już nie będzie
potrzebny. Stosuje się tu zwykła uniksowa składnia opóźnionego zamknięcia
(ang. close\-behind): gniazdo można skasować w dowolnym momencie, ale
zostanie ono ostatecznie usunięte z systemu plików po zamknięciu ostatniego
odwołania do niego.
.PP
Aby przekazać deskryptory plików lub uwierzytelnienia poprzez \fBSOCK_STREAM\fP
trzeba wysłać/odebrać co najmniej jeden bajt niepomocniczych danych w tym
samym wywołaniu \fBsendmsg\fP(2) lub \fBrecvmsg\fP(2)
.PP
.\"
Gniazda strumieniowe z domeny uniksowej nie obsługują zawiadomienia o danych
autonomicznych.
.SH BŁĘDY
.\" The behavior on Solaris is quite similar.
Przy wiązaniu gniazda z adresem, Linux jest jedną\ z implementacji dodających
kończące null, jeśli nie poda się go w \fIsun_path\fP. Zwykle jest to
bezproblemowe, gdy adres gniazda jest pozyskiwany będzie on o jeden bajt
dłuższy niż podawany początkowo. Jest jednak jeden przypadek mogący
spowodować mylące zachowanie: jeśli podany zostanie adres 108 bajtowy, bez
znaku null, to dodanie znaku null spowodowałoby przekroczenie długości
ścieżki poza \fIsizeof(sun_path)\fP. W konsekwencji, przy pozyskiwaniu adresu
gniazda (np. poprzez \fBaccept\fP(2)), jeśli wejściowy argument \fIaddrlen\fP dla
pozyskiwanego wywołania jest podany jako \fIsizeof(struct sockaddr_un)\fP, to
zwrócona struktura adresu \fInie\fP będzie miała kończącego null w \fIsun_path\fP.
.PP
.\" i.e., traditional BSD
Dodatkowo, niektóre implementacje nie wymagają\ kończącego null przy wiązaniu
gniazda (argument \fIaddrlen\fP jest używany do określenia długości
\fIsun_path\fP), a gdy w tych implementacjach jest pozyskiwany adres gniazda,
to nie ma kończącego null w \fIsun_path\fP.
.PP
Aplikacje pozyskujące adresy gniazd mogą posiadać\ (przenośny) kod do obsługi
możliwości, że w \fIsun_path\fP nie ma kończącego null zauważając fakt, że
liczba prawidłowych bajtów w ścieżce to:
.PP
.\" The following patch to amend kernel behavior was rejected:
.\" http://thread.gmane.org/gmane.linux.kernel.api/2437
.\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path
.\" 2012-04-17
.\" And there was a related discussion in the Austin list:
.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735
.\" Subject: Having a sun_path with no null terminator
.\" 2012-04-18
.\"
.\" FIXME . Track http://austingroupbugs.net/view.php?id=561
    strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
.PP
Alternatywnie, aplikacja może pozyskać adres gniazda przez przydzielenie
buforu o rozmiarze \fIsizeof(struct sockaddr_un)+1\fP który jest wyzerowany
przed pozyskaniem. Pobierające wywołanie może określić \fIaddrlen\fP jako
\fIsizeof(struct sockaddr_un)\fP, a dodatkowy bajt zero zapewnia, że w łańcuchu
zwróconym w \fIsun_path\fP będzie kończące null:
.PP
.in +4n
.EX
void *addrp;

addrlen = sizeof(struct sockaddr_un);
addrp = malloc(addrlen + 1);
if (addrp == NULL)
    /* Obsługa błędu */ ;
memset(addrp, 0, addrlen + 1);

if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1)
    /* obsługa błędu */ ;

printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path);
.EE
.in
.PP
Tego bałaganu można uniknąć, jeśli jest pewność, że aplikacja \fItworząca\fP
ścieżki gniazd przestrzega reguł opisanych powyżej rozdziale \fIŚcieżki
gniazd\fP.
.SH PRZYKŁADY
Poniższy kod demonstruje użycie gniazd pakietów sekwencyjnych do lokalnej
komunikacji międzyprocesowej. Składa się z dwóch programów. Serwer czeka na
połączenie z programu klienckiego. Klient wysyła każdy ze swoich argumentów
wiersza poleceń w oddzielnych wiadomościach. Serwer traktuje przychodzące
wiadomości jako liczby całkowite i dodaje je. Klient wysyła łańcuch
polecenia "END". Serwer odsyła komunikat zawierający sumę klienckich liczb
całkowitych. Klient wypisuje sumę i wychodzi. Serwer czeka na połączenie od
kolejnego klienta. Aby zatrzymać\ serwer, klient jest wywoływany z argumentem
wiersza poleceń "DOWN".
.PP
Podczas działania serwera w tle i kolejnych uruchomień\ klienta
zarejestrowano następujące wyjście. Wykonywanie programu serwera kończy się,
gdy otrzymuje on polecenie "DOWN".
.SS "Przykładowe wyjście"
.in +4n
.EX
$ \fB./server &\fP
[1] 25887
$ \fB./client 3 4\fP
Result = 7
$ \fB./client 11 \-5\fP
Result = 6
$ \fB./client DOWN\fP
Result = 0
[1]+  Done                    ./server
$
.EE
.in
.SS "Kod źródłowy programu"
\&
.EX
/*
 * Plik connection.h
 */

#define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket"
#define BUFFER_SIZE 12

/*
 * Plik server.c
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include "connection.h"

int
main(int argc, char *argv[])
{
    struct sockaddr_un name;
    int down_flag = 0;
    int ret;
    int connection_socket;
    int data_socket;
    int result;
    char buffer[BUFFER_SIZE];

    /* Tworzenie lokalnego gniazda. */

    connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0);
    if (connection_socket == \-1) {
        perror("socket");
        exit(EXIT_FAILURE);
    }

    /*
     * Dla przenośności wyczyść całą strukturę, ponieważ niektóre
     * implementacje mają\ dodatkowe (niestandardowe) pola
     * w strukturze.
     */

    memset(&name, 0, sizeof(name));

    /* Wiązanie gniazda z nazwą gniazda. */

    name.sun_family = AF_UNIX;
    strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) \- 1);

    ret = bind(connection_socket, (const struct sockaddr *) &name,
               sizeof(name));
    if (ret == \-1) {
        perror("bind");
        exit(EXIT_FAILURE);
    }

    /*
     * Przygotowywanie do akceptowania połączeń. Rozmiar bufora jest
     * ustawiany na 20. Podczas przetwarzania jednego żądania, inne
     * mogą czekać.
     */

    ret = listen(connection_socket, 20);
    if (ret == \-1) {
        perror("listen");
        exit(EXIT_FAILURE);
    }

    /* To główna pętla do obsługi połączeń. */

    for (;;) {

        /* Czekanie na połączenie przychodzące. */

        data_socket = accept(connection_socket, NULL, NULL);
        if (data_socket == \-1) {
            perror("accept");
            exit(EXIT_FAILURE);
        }

        result = 0;
        for (;;) {

            /* Czekanie na następny pakiet danych. */

            ret = read(data_socket, buffer, sizeof(buffer));
            if (ret == \-1) {
                perror("read");
                exit(EXIT_FAILURE);
            }

            /* Upewnienie się, że bufor kończy się\ 0. */

            buffer[sizeof(buffer) \- 1] = 0;

            /* Obsługa poleceń. */

            if (!strncmp(buffer, "DOWN", sizeof(buffer))) {
                down_flag = 1;
                break;
            }

            if (!strncmp(buffer, "END", sizeof(buffer))) {
                break;
            }

            /* Dodawanie otrzymanej sumy. */

            result += atoi(buffer);
        }

        /* Wysyłanie wyniku. */

        sprintf(buffer, "%d", result);
        ret = write(data_socket, buffer, sizeof(buffer));
        if (ret == \-1) {
            perror("write");
            exit(EXIT_FAILURE);
        }

        /* Zamknięcie gniazda. */

        close(data_socket);

        /* Wyjście po poleceniu DOWN. */

        if (down_flag) {
            break;
        }
    }

    close(connection_socket);

    /* Usunięcie gniazda. */

    unlink(SOCKET_NAME);

    exit(EXIT_SUCCESS);
}

/*
 * Plik client.c
 */

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include "connection.h"

int
main(int argc, char *argv[])
{
    struct sockaddr_un addr;
    int ret;
    int data_socket;
    char buffer[BUFFER_SIZE];

    /* Tworzenie lokalnego gniazda. */

    data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0);
    if (data_socket == \-1) {
        perror("socket");
        exit(EXIT_FAILURE);
    }

    /*
     * Dla przenośności wyczyść całą strukturę, ponieważ niektóre
     * implementacje mają\ dodatkowe (niestandardowe) pola
     * w strukturze.
     */

    memset(&addr, 0, sizeof(addr));

    /* Łączenie gniazda z adresem gniazda */

    addr.sun_family = AF_UNIX;
    strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) \- 1);

    ret = connect(data_socket, (const struct sockaddr *) &addr,
                   sizeof(addr));
    if (ret == \-1) {
        fprintf(stderr, "The server is down.\en");
        exit(EXIT_FAILURE);
    }

    /* Wysyłanie argumentów. */

    for (int i = 1; i < argc; ++i) {
        ret = write(data_socket, argv[i], strlen(argv[i]) + 1);
        if (ret == \-1) {
            perror("write");
            break;
        }
    }

    /* Żądanie wyniku. */

    strcpy(buffer, "END");
    ret = write(data_socket, buffer, strlen(buffer) + 1);
    if (ret == \-1) {
        perror("write");
        exit(EXIT_FAILURE);
    }

    /* Otrzymanie wyniku. */

    ret = read(data_socket, buffer, sizeof(buffer));
    if (ret == \-1) {
        perror("read");
        exit(EXIT_FAILURE);
    }

    /* Upewnienie się, że bufor kończy się\ 0. */

    buffer[sizeof(buffer) \- 1] = 0;

    printf("Result = %s\en", buffer);

    /* Zamknięcie gniazda. */

    close(data_socket);

    exit(EXIT_SUCCESS);
}
.EE
.PP
Przykład użycia \fBSCM_RIGHTS\fP można znaleźć w \fBcmsg\fP(3).
.SH "ZOBACZ TAKŻE"
\fBrecvmsg\fP(2), \fBsendmsg\fP(2), \fBsocket\fP(2), \fBsocketpair\fP(2), \fBcmsg\fP(3),
\fBcapabilities\fP(7), \fBcredentials\fP(7), \fBsocket\fP(7), \fBudp\fP(7)
.SH "O STRONIE"
Angielska wersja tej strony pochodzi z wydania 5.10 projektu Linux
\fIman\-pages\fP. Opis projektu, informacje dotyczące zgłaszania błędów oraz
najnowszą wersję oryginału można znaleźć pod adresem
\%https://www.kernel.org/doc/man\-pages/.
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>,
Robert Luberda <robert@debian.org>
i
Michał Kułach <michal.kulach@gmail.com>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
