rpcgen(1) General Commands Manual rpcgen(1)

rpcgen - کامپایلر پروتکل RPC

rpcgen infile
rpcgen [-Dname[=value]] [-T] [-K secs] infile
rpcgen -c|-h|-l|-m|-M|-t [-o outfile ] infile
rpcgen [-I] -s nettype [-o outfile] infile
rpcgen -n netid [-o outfile] infile

rpcgen ابزاری است که کدهای زبان C را برای پیاده‌سازی یک پروتکل RPC تولید می‌کند. ورودی rpcgen زبانی مشابه C است که به عنوان زبان RPC (زبان فراخوانی رویه از راه دور یا Remote Procedure Call Language) شناخته می‌شود.

rpcgen به طور معمول همانند اولین خلاصه دستور استفاده می‌شود که در آن یک فایل ورودی را دریافت کرده و حداکثر چهار فایل خروجی تولید می‌کند. اگر نام infile برابر با proto.x باشد، آنگاه rpcgen یک فایل سرایند در proto.h، روال‌های XDR در proto_xdr.c، استاب‌های سمت سرور در proto_svc.c، و استاب‌های سمت کلاینت در proto_clnt.c تولید خواهد کرد. با گزینهٔ -T، این ابزار همچنین جدول توزیع (dispatch table) پروتکل RPC را در proto_tbl.i تولید می‌کند. با گزینهٔ -Sc، همچنین کد نمونه‌ای تولید می‌شود که نحوهٔ استفاده از رویه‌های راه دور را در سمت کلاینت نشان می‌دهد. این کد در proto_client.c ایجاد خواهد شد. با گزینهٔ -Ss، همچنین یک کد نمونهٔ سرور تولید خواهد شد که نحوهٔ نوشتن رویه‌های راه دور را نشان می‌دهد. این کد در proto_server.c ایجاد می‌شود.

سرور ایجادشده می‌تواند هم توسط ناظران درگاه (برای نمونه، inetd یا listen) و هم به صورت مستقل راه‌اندازی شود. هنگامی که توسط یک ناظر درگاه راه‌اندازی می‌شود، تنها برای ترابری‌هایی (transports) سرور ایجاد می‌کند که توصیف‌کننده فایل 0 برای آن ارسال شده است. نام ترابری باید با مقداردهی متغیر محیطی PM_TRANSPORT مشخص گردد. هنگامی که سرور تولیدشده توسط rpcgen اجرا می‌شود، دستگیره‌های سرور (server handles) را برای تمام ترابری‌های مشخص‌شده در متغیر محیطی NETPATH ایجاد می‌کند، یا در صورت تنظیم نشدن آن، دستگیره‌های سرور را برای تمام ترابری‌های قابل مشاهده در فایل /etc/netconfig می‌سازد. نکته: ترابری‌ها در زمان اجرا انتخاب می‌شوند و نه در زمان کامپایل.

هنگامی که برای یک ناظر درگاه ساخته شود (rpcgen -I) و سرور به صورت مستقل آغاز به کار کند، به طور پیش‌فرض به پس‌زمینه می‌رود. یک نماد تعریف ویژه به نام RPC_SVC_FG می‌تواند برای اجرای فرایند سرور در پیش‌زمینه به کار رود.

دومین خلاصه دستور، قابلیت‌های ویژه‌ای را فراهم می‌کند که امکان ایجاد سرورهای پیشرفته‌تر RPC را می‌دهد. این قابلیت‌ها شامل پشتیبانی از #defineهای تعریف‌شده توسط کاربر و جدول‌های توزیع RPC است. مدخل‌های جدول توزیع RPC شامل موارد زیر است:

•
اشاره‌گرهایی به روال خدماتی مربوط به آن رویه،
•
یک اشاره‌گر به آرگومان‌های ورودی و خروجی
•
اندازهٔ این روال‌ها
یک سرور می‌تواند از جدول توزیع برای بررسی مجوزها و سپس اجرای روال سرویس استفاده کند؛ یک کتابخانه کلاینت ممکن است از آن برای رسیدگی به جزئیات مدیریت حافظه و تبدیل داده‌های XDR بهره ببرد.

سه خلاصه دستور دیگر که در بالا نشان داده شده‌اند، زمانی به کار می‌روند که کاربر نخواهد همهٔ فایل‌های خروجی را تولید کند، بلکه تنها یک فایل خاص مد نظر باشد. چند نمونه از کاربرد آن‌ها در بخش «مثال‌ها» در ادامه شرح داده شده است. هنگامی که rpcgen با گزینهٔ -s اجرا شود، سرورهایی را برای آن ردهٔ خاص از ترابری‌ها ایجاد می‌کند. هنگامی که با گزینهٔ -n اجرا شود، سروری را برای ترابری مشخص‌شده توسط netid ایجاد می‌کند. اگر infile مشخص نشده باشد، rpcgen ورودی استاندارد را می‌پذیرد.

پیش‌پردازندهٔ C، یعنی cc -E [نگاه کنید به cc(1)]، پیش از آن‌که فایل ورودی واقعاً توسط rpcgen تفسیر شود، بر روی آن اجرا می‌گردد. برای هر نوع فایل خروجی، rpcgen یک نماد پیش‌پردازندهٔ ویژه را برای استفادهٔ برنامه‌نویس rpcgen تعریف می‌کند:

هنگام کامپایل به فایل‌های سرایند (header) تعریف می‌شود
هنگام کامپایل به روال‌های XDR تعریف می‌شود
هنگام کامپایل به استاب‌های سمت سرور تعریف می‌شود
هنگام کامپایل به استاب‌های سمت کلاینت تعریف می‌شود.TP RPC_TBL هنگام کامپایل به جداول توزیع RPC تعریف می‌شود.

هر خطی که با `%' شروع شود، مستقیماً و بدون تفسیر توسط rpcgen به فایل خروجی منتقل می‌شود.

به‌ازای هر نوع داده‌ای که در infile به آن ارجاع داده شده است، rpcgen فرض می‌کند که روالی با پیشوند رشتهٔ xdr_ به ابتدای نام نوع داده وجود دارد. اگر این روال در کتابخانهٔ RPC/XDR وجود نداشته باشد، باید ارائه شود. ارائهٔ یک نوع دادهٔ تعریف‌نشده امکان سفارشی‌سازی روال‌های XDR را فراهم می‌کند.

گزینه‌های زیر در دسترس هستند:

تولید تمام فایل‌ها شامل کد نمونه برای سمت کلاینت و سرور.
این گزینه کد را به سبک SunOS4.1 برای rpc تولید می‌کند. این گزینه برای سازگاری با نسخه‌های پیشین است. این حالت پیش‌فرض است.
-5
این گزینه کد را به سبک SysVr4 برای rpc تولید می‌کند. این گزینه توسط Transport Independent RPC که در سامانه‌های Svr4 موجود است، استفاده می‌شود. به‌طور پیش‌فرض rpcgen کد را به سبک SunOS4.1 برای rpc تولید می‌کند.
کامپایل به روال‌های XDR.
تولید کد در استاندارد ANSI C. این گزینه همچنین کدی تولید می‌کند که می‌تواند توسط کامپایلر ++C کامپایل شود. این حالت پیش‌فرض است.
تولید کد در استاندارد K&R C. حالت پیش‌فرض ANSI C است.
تعریف یک نماد name. معادل با دستورالعمل #define در کد مبدأ. اگر هیچ valueای داده نشود، value برابر با 1 تعریف می‌شود. این گزینه ممکن است بیش از یک بار مشخص شود.
کامپایل به تعاریف داده‌ای C (یک فایل هدر). گزینهٔ -T می‌تواند همراه با آن استفاده شود تا فایل هدری تولید کند که از جداول توزیع RPC پشتیبانی می‌کند.
تولید سرویسی که بتواند از طریق inetd راه‌اندازی شود. پیش‌فرض این است که یک سرویس ایستا تولید شود که ترابری‌های انتخاب‌شده با -s را مدیریت کند. استفاده از -I امکان راه‌اندازی سرویس به هر یک از دو روش را فراهم می‌کند.
به‌طور پیش‌فرض، سرویس‌های ایجادشده با استفاده از rpcgen پس از پاسخ‌گویی به یک درخواست، پیش از خروج 120 ثانیه منتظر می‌مانند. این بازهٔ زمانی می‌تواند با استفاده از پرچم -K تغییر داده شود. برای ایجاد سروری که بلافاصله پس از پاسخ‌گویی به یک درخواست خارج شود، می‌توان از -K 0 استفاده کرد. برای ایجاد سروری که هرگز خارج نشود، آرگومان مناسب -K -1 است.
هنگام پایش سرور، برخی از پایشگران پورت مانند listen(1M)، همواره در پاسخ به یک درخواست سرویس، فرایند جدیدی ایجاد می‌کنند. اگر مشخص باشد که سرور همراه با چنین پایشگری استفاده خواهد شد، سرور باید بلافاصله پس از اتمام کار خارج شود. برای چنین سرورهایی، rpcgen باید با -K -1 استفاده شود.
کامپایل به استاب‌های سمت کلاینت.
کامپایل به استاب‌های سمت سرور، اما روال “main” را تولید نمی‌کند. این گزینه برای ایجاد روال‌های بازخوانی (callback-routines) و برای کاربرانی که برای انجام مقداردهی اولیه نیاز به نوشتن روال “main” خودشان دارند، مفید است.
تولید استاب‌های امن در برابر چندریسمانی (multithread-safe) برای انتقال آرگومان‌ها و نتایج بین کدهای تولیدشده با rpcgen و کدهای نوشته‌شده توسط کاربر. این گزینه برای کاربرانی که می‌خواهند از ریسمان‌ها در کدهای خود استفاده کنند مفید است.
کامپایل به استاب‌های سمت سرور برای ترابری مشخص‌شده توسط netid. باید مدخلی برای netid در پایگاه‌دادهٔ netconfig وجود داشته باشد. این گزینه ممکن است بیش از یک بار مشخص شود، تا سروری کامپایل شود که به چندین ترابری سرویس می‌دهد.
استفاده از سبک جدید (newstyle) در rpcgen. این به رویه‌ها اجازه می‌دهد چندین آرگومان داشته باشند. همچنین از سبک ارسال پارامتری استفاده می‌کند که بسیار شبیه به C است. بنابراین، هنگام ارسال آرگومان به یک رویهٔ راه دور نیازی نیست اشاره‌گری به آرگومان ارسال کنید، بلکه خود آرگومان را ارسال می‌کنید. این رفتار با سبک قدیمی (oldstyle) کدهای تولیدشده توسط rpcgen متفاوت است. سبک جدید به دلیل سازگاری با نسخه‌های پیشین، حالت پیش‌فرض نیست.
نام فایل خروجی را مشخص می‌کند. اگر هیچ فایلی مشخص نشود، از خروجی استاندارد استفاده می‌شود (تنها در حالت‌های -c، -h، -l، -m، -n، -s، -Sc، -Sm، -Ss و -t).
کامپایل به استاب‌های سمت سرور برای تمام ترابری‌های متعلق به کلاس nettype. کلاس‌های پشتیبانی‌شده عبارتند از netpath، visible، circuit_n، circuit_v، datagram_n، datagram_v، tcp و udp [برای معانی مرتبط با این کلاس‌ها rpc(3N) را ببینید]. این گزینه ممکن است بیش از یک بار مشخص شود. نکته: ترابری‌ها در زمان اجرا انتخاب می‌شوند و نه در زمان کامپایل.
تولید کد نمونه برای نشان دادن نحوهٔ استفاده از رویهٔ راه دور و چگونگی اتصال به سرور پیش از فراخوانی استاب‌های سمت کلاینتِ تولیدشده توسط rpcgen.
تولید یک Makefile نمونه که می‌تواند برای کامپایل برنامه استفاده شود.
تولید اسکلت کدها برای رویه‌های راه دور در سمت سرور. شما باید کدهای واقعی را برای رویه‌های راه دور تکمیل کنید.
کامپایل به جدول توزیع RPC.
تولید کدی که از جداول توزیع RPC پشتیبانی می‌کند..P گزینه‌های -c، -h، -l، -m، -s و -t تنها برای تولید نوع خاصی از فایل‌ها به کار می‌روند، در حالی که گزینه‌های -D و -T سراسری هستند و می‌توان آن‌ها را همراه با سایر گزینه‌ها به کار برد.

زبان RPC از ساختارهای تودرتو پشتیبانی نمی‌کند. به عنوان یک راهکار، می‌توان ساختارها را در بالاترین سطح اعلان کرد و از نام آن‌ها درون ساختارهای دیگر استفاده نمود تا همان نتیجه به دست آید.

هنگام استفاده از تعاریف برنامه، ممکن است تداخل نام رخ دهد، زیرا محدوده‌بندی (scoping) ظاهری در عمل اعمال نمی‌شود. از بیشتر این تداخل‌ها می‌توان با برگزیدن نام‌های یکتا برای برنامه‌ها، نسخه‌ها، رویه‌ها و نوع‌ها جلوگیری کرد.

کد سرور تولیدشده با گزینهٔ -n به بستر انتقال مشخص‌شده با netid اشاره دارد و از این رو بسیار وابسته به محیط پیاده‌سازی است.

مثال زیر:

$ rpcgen -T prot.x

این پنج فایل را تولید می‌کند: prot.h، prot_clnt.c، prot_svc.c، prot_xdr.c و prot_tbl.i.

مثال زیر تعاریف داده‌ای C (فایل سرآیند) را به خروجی استاندارد می‌فرستد.

$ rpcgen -h prot.x

برای ارسال نسخهٔ آزمایشی -DTEST از کدهای واسط (stubs) سمت سرور برای تمامی بسترهای انتقالِ متعلق به کلاس datagram_n به خروجی استاندارد، از این دستور استفاده کنید:

$ rpcgen -s datagram_n -DTEST prot.x

برای ایجاد کدهای واسط سمت سرور برای بستر انتقال مشخص‌شده توسط netid tcp، از دستور زیر استفاده کنید:

$ rpcgen -n tcp -o prot_svc.c prot.x

cc(1).